Skip to content

Installation page: connect proxy platforms, and no proxy calls without one (#1700) - #1733

Closed
michielbdejong wants to merge 1 commit into
claude/page-runtimesfrom
claude/installation-connect
Closed

michielbdejong wants to merge 1 commit into
claude/page-runtimesfrom
claude/installation-connect

Conversation

@michielbdejong

@michielbdejong michielbdejong commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #1729. Part of #1700 (flow a, answer 3).

Connect a platform on an Installation

For each platform the pinned release's manifest declares in proxy: [...] (#1725), the Installation page shows a row under Connections. A platform that is no longer declared but is still recorded also gets a row.

  • Not connected: "Connect " and, when the user already has a connection for that platform at the proxy, "Use existing connection".
  • Either button opens a consent step first: the proxy origin, and that the plugin may use the connection until you disconnect it. The consent bar is now a shared ProxyConsentBar, also used by AppFrame, with AppFrame's text unchanged.
  • Both paths reuse helpers/proxyConnections.ts (Plugin frames: integration-proxy capabilities instead of the relay (ontola/atomic-plugins#54) #1697):
    • /connect;
    • the signed redeem;
    • POST /connections/{id}/agents {agent: integrationAppAgent}.
  • After success: integrationConnections[platform] = connection_id (Installation app ids, published node agents and delegated connections for the integration proxy (#1700, answers 1-3) #1710, a JSON object) is written onto the Installation in a commit signed by the user.
    • For /connect, the return (ProxyConnectReturn → new finishProxyReturn) records it. It only does this for handoffs started from an Installation (recordOnInstallation in the pending scope). A connect started by an app frame writes nothing.
    • "Use existing connection" also triggers runtime registration in the background.
  • Disconnect: DELETE /connections/{id}/agents/{app} at the proxy (a 404 counts as already gone), then the key is removed. The property is dropped once it's empty. If the proxy refuses, the key stays.
  • Connected state: shown per platform, with the connection id.
  • Who sees it: only people who can write the Installation see the section. It isn't shown once the Installation is revoked.
  • Traffic notice: Say which integration proxy carries a connection's traffic #1724's ProxyTrafficNotice isn't on this base. There's a TODO(#1724) where it goes.

No proxy calls without a reason

The page only calls the proxy (GET /connections, runtime registration) when the manifest declares proxy or the Installation already has integrationConnections. The check runs in two places:

  • the page, which gates useInstallationRuntimes and the connections list;
  • registerInstallationRuntimes, so app frames that call it get the same check.

A plain Installation makes no request to the proxy's origin. #1729 listed this as a follow-up: one GET /connections per page load, plus a toast when the default proxy was down.

Tests (vitest)

  • helpers/installationConnections.test.ts, against a fake proxy:
    • connect (/connect → signed redeem → delegation to the app id) writes integrationConnections, and a frame-started connect writes nothing;
    • use-existing delegates and records, keeping other platforms;
    • disconnect calls DELETE …/agents/{app} and removes the key or the whole property;
    • the key is kept when the proxy refuses;
    • no app id → refused before any proxy call;
    • zero fetches to the proxy for a plain Installation, on the real fetch path the page uses. Two control cases show that declaring proxy, or having a recorded connection, does lead to proxy calls.
  • views/Installation/InstallationConnections.test.tsx:
    • hidden for non-writers;
    • the Connect and Use existing buttons;
    • the consent step names the proxy;
    • the connected state and Disconnect.
  • Existing tests updated for the extra finish() fields and the gating.
  • data-browser typecheck is clean; vitest for src/helpers, src/chunks/AppPage and src/views/Installation passes (70 files, 560 tests).

Checked in a running app against a server built from this branch and a stub proxy. A plain Installation made 0 requests to the proxy. For a proxy: ["demo"] Installation, "Use existing connection" wrote {"demo":"demo-conn-1"}, and Disconnect removed it.

.po

The catalogs were settled by running vite once after rm -rf src/locales/.wuchale, and I read the diff by hand. It only adds entries (the new strings, plus references to existing ones such as Cancel, Continue, Disconnect, Not connected and Connections). AppFrame's entries are unchanged. An earlier attempt passed the consent text as a prop holding JSX, and wuchale silently dropped AppFrame's strings. That's why ProxyConsentBar is a plain styled container with children.

Screenshots

Unconnected, the consent step and connected, at desktop and mobile width. They were captured locally and shared in the review chat; they still need uploading here. The [i18n-404:2152] after "Pinned to …" is already on the base: the committed catalog has no entry for the nested "from …" message in InstallationPage, and this PR doesn't touch it.

Not done

🤖 Generated with Claude Code

#1700)

Flow a, answer 3: the Installation page shows a Connections section for
each platform the pinned release's manifest declares in `proxy: [...]`
(plus any still recorded). Per platform, "Connect <platform>" and, when
the user already has one, "Use existing connection"; both go through a
consent step (the shared ProxyConsentBar, also used by AppFrame), then
reuse helpers/proxyConnections.ts: /connect, the signed redeem, and
POST /connections/{id}/agents {agent: integrationAppAgent}. After that,
integrationConnections[platform] = connection_id is written onto the
Installation in a commit signed by the user (the /connect return records
it in ProxyConnectReturn via finishProxyReturn). Disconnect removes the
delegation at the proxy (404 counts as gone) and the key, dropping the
property once empty. Only people who can write the Installation see the
controls. TODO for #1724's ProxyTrafficNotice, which is not on this base.

Don't contact the proxy for nothing: GET /connections and runtime
registration only run when the manifest declares `proxy` or the
Installation already has integrationConnections, both on the page and in
registerInstallationRuntimes (which app frames call too).

Tests: the connect flow writes integrationConnections; use-existing
delegates and records; disconnect calls the proxy and removes the key
(kept when the proxy refuses); zero fetches to the proxy for a plain
Installation; controls hidden for non-writers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@michielbdejong

Copy link
Copy Markdown
Contributor Author

Merge-risk triage (2026-09-28). This is a read-only review of this PR's own diff. The rule it applies: nothing that works today may break for existing users or clients, and new behaviour is added alongside the old. The stack is being rebased onto develop as one chain before merging, so line references are against the current stacked base.

Verdict: SAFE (merge together with #1729)

Frontend only. The gate means an Installation that declares no platform and has no recorded connection never contacts the proxy. The Connect UI only shows for writers.

Note: This gate is what makes #1729 safe.

🤖 Generated with Claude Code

@michielbdejong

Copy link
Copy Markdown
Contributor Author

Closing as part of the plugin-host stack cleanup (Q-101): not needed by atomic-plugins now. See the inventory at #1726 (comment). The branch is kept, and pin candidates are unaffected. Closed by Claude (VPS coordinator) on behalf of Michiel.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request plugin Should probably be an Atomic Plugin

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant