feat(arcade): Arcade as a second connected-app provider (PR 1)

[mxmzb]

Adds Arcade as a second connected-app provider beside Composio. One provider is active per deployment. Four changes are visible to Composio deployments too; see Changes Composio deployments will see below.

Changes Composio deployments will see

• Both COMPOSIO_API_KEY and ARCADE_API_KEY set with no OPENBOT_BROKER_PROVIDER: the server now refuses to start, with a message naming the variables. Before, the Composio key alone decided. Set OPENBOT_BROKER_PROVIDER=composio or unset the Arcade key.
• The Composio directory call now has a 10s deadline (VENDOR_CALL_TIMEOUT_MS), which a cold cache can hit; the page then shows a timeout instead of hanging.
• A migration backfills mcp_servers.account_mode = 'personal' on brokered apps (Composio included) that hold an account and have it null. Rows that already say shared are untouched.
• Tool names a refresh skips are a warning, not the app's last error. A name no model can be offered (a dotted MCP name, say) used to go into mcp_servers.last_error, which turned the app's row red on the Plugins list for good. The names now go in a new nullable column, skipped_tools (migration 0059), and the app's page names them.

What this gives a deployment

Arcade authorizes per action, so there is no Connect button. A person authorizes Gmail.ListEmails; OpenBot mints a consent for exactly that, binds the return leg to the attempt it started, and writes one connection row and one audit event — or writes nothing at all.

Two facts are measured and shown before anybody grants anything:

• Coverage — a toolkit whose listing classified nothing is flagged before enablement, because every action will be treated as a destructive write.
• Consent breadth — "this app uses N separate permissions across M actions", or "approving any action approves all N of them", grouped on the scopes the listing actually reports.

The headline the measurements took away

An earlier draft said "pick Arcade when a security team has to sign off." That is false as a general claim, and the numbers say so:

Provider	Scopes per action	One read consent authorized	Isolation
Google (Gmail)	gmail.readonly vs gmail.send	11 of 30	yes
GitHub (GitHub App)	none, for any action	43 of 43	no

On GitHub, consenting to Github.CountStargazers — a read — flipped all 43 actions to authorized, writes and the destructive one included. Least privilege is a property of (provider × how its OAuth app was registered), not of Arcade. No screen, doc or message in this PR claims otherwise; a test asserts the absence of a confinement promise across every sentence shape.

Shape

• The gate asks a declared property, not a vendor name. grantIsLocal — Composio's grant is held here, Arcade's is not, so an Arcade call goes out and the vendor's own refusal is the answer. store.ts records a defect where a gate and its exemption keyed on different things and failed open; a provider === "arcade" comparison inside a permission check is that same shape.
• One attempt in flight per actor, in a durable row. With one candidate there is nothing to guess, and interleaved flows are impossible by construction rather than handled.
• The callback is bound to the attempt, not merely the identity: confirm_user's auth_id must equal the one the mint recorded. Identity alone attributes a late read consent to a fresh send request.
• Completion is one transaction gated by a conditional UPDATE. Audit ids are random UUIDs, so a payload field enforces nothing.
• auth.status carries a live access token. The adapter returns { status, userId, scopes } and drops the rest inside the adapter — a narrowed return type rather than a rule, because the throwaway harness that proved this flow wrote the token to a file on its first run.

A live defect this found and fixed

connectionsFor compared the vendor's auth provider to the toolkit name. Those coincide only when an operator names the provider after the toolkit — which Github, Asana and Attio all do, and which every fixture in the tree uses. For any Google app, the filter matched nothing: isConnected false for a connected account, revoke answering "nothing there" instead of deleting, accountName null. Silent, and at the moment somebody presses Disconnect.

Fixed by putting authProviderOf on the seam and reading it from the listing the adapter already performs.

Verification

bun run test:ci   8155 pass / 0 fail / 75 skip   (705 files, merged with main at 12c3a694)
typecheck · typecheck:tests (baseline 241) · format · lint   all exit 0

bun test server/tests as a whole no longer runs: ~100 files open a module-scope pool against PostgreSQL's 100 max_connections, so it dies with sorry, too many clients already before reporting anything. That is a harness ceiling, never a regression. Run it sharded.

Not done

• Live coverage is manual only. server/tests/arcade-live.test.ts ran once by hand on 2026-10-13: 9 passed and 3 failed, and all 3 failures were the suite's own mistakes, since fixed. It has not been re-run since. The app was also run locally against a live Arcade project, which found three defects, all now fixed. The last was the admin page offering a whole-app Connect under Arcade that always failed; 9c441b7d hides it. CI never dials Arcade. docs/plugins/arcade.md now says which of its facts came from which run.
• A dev database that ran an earlier draft of migrations 0057–0063 fails with a raw 42P07 relation "pending_authorizations" already exists instead of the migration guard's message. Nothing is corrupted. Recreate that dev database and migrate again.
• OFFERABLE_TOOL_NAME has no length limit, so with a long server id mcp__<serverId>__<name> can go over OpenAI's 64-character limit. Main already behaves this way, so it is left for a follow-up.
• The review loop has not converged. Fixes from the review findings landed in waves, but no confirmation round has run since round 2. The remaining findings are documented, not fixed.
• Each deployment needs setup by hand: its own Arcade project, an OAuth app per provider, and the verifier URL registered in Arcade's dashboard. The server now warns about the verifier at every startup, because nothing can check it.

Operator setup is in docs/plugins/arcade.md.

🤖 Generated with Claude Code

[davidmckayv]

You're right that this shouldn't merge as is. The design holds up well: the callback is bound to the attempt, one attempt per person, identity always from the session, no token leaks. Fixing things in the same PR is fine by me. Here's what needs fixing first.

Must fix

1. A demoted admin can wipe the team's shared grant. server/src/plugins/route-groups/connections.ts:2169. The return leg does if (fresh.refusal || !sameAccount(fresh.account, retired)) and then revokes retired. If an admin starts Authorize on a shared app and loses the admin role before finishing consent, brokeredAccountFor refuses with 403, and the code revokes the deployment's live shared account. That ends the shared grant for everyone and clears the sibling apps' rows. Only withdraw when the account really moved (!fresh.refusal && !sameAccount(...)). On a refusal, close the attempt without revoking.

2. One badly named tool now blocks a whole MCP server. server/src/plugins/plugin-store/model.ts:643. storableTools throws on any name outside [a-zA-Z0-9_-], for every transport. A custom MCP server with one dotted tool name (the MCP spec allows dots) now stores zero tools, and an existing server's tool list freezes. That isn't Arcade-only, so "Composio behaviour is unchanged" doesn't hold. Skip and record the bad name instead of refusing the whole listing.

3. Cancelling during the return leg reports success. completeAuthorizationAttempt in server/src/plugins/plugin-store/connections.ts (around 1236) returns when nothing was claimed, and the verify route then redirects to the success landing. If Cancel lands between confirmReturn and the conditional update, the person is told they're connected while the audit says cancelled, and the grant is live at Arcade (grantIsLocal: false). Have the store say whether it claimed the row. If it didn't, refuse and withdraw the grant at the vendor.

4. 0063 breaks a rolling deploy. server/drizzle/0063_mcp_tool_vendor_name.sql adds vendor_name NOT NULL and drops the default in the same release, so old replicas inserting mcp_tools rows fail mid-rollout. docs/development.md covers this case: ship it nullable with a separate backfill, and tighten it in a later release.

Also

• Squash 0057 to 0063 into one generated migration before merge. They're unreleased, and 0058 to 0062 all reshape a table 0057 creates. Keep one --custom file for the 0061 account_mode backfill, since that one touches existing Composio rows. 0060 also has a hand-written DELETE inside a generated file.
• Check or warn about the verifier. Nothing checks that the custom Arcade verifier is registered. If an operator leaves Arcade's default, consents complete at the vendor with no attempt binding, no row and no audit. At least warn at startup and in the docs.
• docs/plugins/arcade.md has claims the code doesn't back yet:
  • It says results were "measured… against the live API", but nothing has dialled Arcade.
  • It and the error at broker.ts:1180 point operators to a "sunset flow" that isn't built.
  • "Three refusals" is followed by four bullets.
• Refusal text in the docs doesn't match. The quoted text in docs/deployment.md:184 and docs/development.md:107 doesn't match the real message in migration-reach.ts:218.
• Drop agent-mastra/bun.lock. It came back in merge 1686607 after you untracked it in a116c75.
• Mention the Composio-visible changes in the description:
  • With both COMPOSIO_API_KEY and ARCADE_API_KEY set and no OPENBOT_BROKER_PROVIDER, the broker is now off.
  • The Composio directory call now has a 10s deadline, which a cold cache can hit.
  • 0061 backfills account_mode.
• Typecheck baseline: keying it by file:line means moving any line in a baselined test fails CI. Key it by message, like mutation-register.ts does.

[mxmzb]

@davidmckayv thanks. Every item is addressed and pushed as of 90ee6838. bun run test:ci is green locally on the branch merged with current main (8072 pass, 0 fail). In three places I did something different from what you suggested; the reasons are inline.

Must fix

1. Demoted admin, shared grant (8b0d26b2). A refusal no longer revokes. The literal !fresh.refusal && !sameAccount(...) broke 8 existing tests, though. In those tests a person's consent is finished after the app switched to Shared; that also refuses with a 403, but their retired personal grant really did move and should still be withdrawn. So on a refusal the route resolves the account again without the admin requirement:

   • Different account: it really moved, so the grant is withdrawn as before.
   • Same account, or none: the attempt is closed unreconciled with no revoke, and the person gets a new refusal code, not-permitted.

   There's a test for your exact case: no vendor revoke, and the team's rows for the app and its siblings stay intact.

2. One bad tool name blocks a whole server (d860b916). storableTools now skips any name a model can't be offered and returns it in skipped. refreshTools stores the rest, names the skipped ones in lastError (the field the old throw message used) and logs a warning. One extra rule: if every name in a listing is skipped, the tools already stored are kept instead of being replaced with nothing.

3. Cancel during the return leg (6aadc579). completeAuthorizationAttempt now returns { claimed }.

   • Lost to a rival callback: the person still sees success, which is right.
   • Lost to a cancel: the route refuses with cancelled and withdraws the grant at Arcade.

   I went further than you asked in one way. An Arcade revoke ends the whole connection for that identity and auth provider. So the route skips the revoke, and logs arcade-cancelled-grant-left-live, when the account already held this app, when other apps share the connection, or when the shared apps can't be worked out. Otherwise an admin pressing Cancel on a Shared app would cause the same harm as item 1.

4. 0063 and rolling deploys (23d616c0). vendor_name ships nullable, with the backfill in a separate step, and every reader goes through vendorNameOf() → coalesce(vendor_name, name). I checked it against a database at main's 0056: an insert without the column, as an old replica would do, succeeds and reads back as the name. The NOT NULL change belongs to a later release.

Also

• Squash: 0057–0063 are now 0057_arcade_provider (generated) plus 0058_arcade_provider_backfill (--custom: the account_mode backfill and the vendor_name backfill). Running drizzle-kit generate again reports no changes. 0060's DELETE is gone: it only cleaned a table no released version has, and the table is now created with its foreign keys. Any dev database that already ran the old 0057+ needs a reset.
• Verifier: neither Arcade's SDK (2.4.1) nor its API can read a project's verifier setting, so the server now warns at every startup with Arcade active, naming the exact URL to register (237c7ddf). I corrected "no row and no audit" in the docs: at the default, our verify route is never called, but the connected-accounts page later writes both without the identity check. In practice Arcade's built-in verifier rejects user ids that aren't project members, which ours never are, so nobody can connect at the default. The docs now say both.
• arcade.md claims (35f5650f, 0ad11fe0):
  • "Measured": each claim now says which of two sources it came from, a throwaway script run before the page was written or the one manual arcade-live run on 2026-10-13, and that CI runs neither. The PR description's "nothing has dialled Arcade" was stale; I've corrected it too.
  • Sunset flow: the references are gone. The docs, broker.ts and provider-wiring.ts now name the real path: keep the old provider active, then end its connections the normal ways (each person disconnects, an admin disconnects a Shared app or removes the app, or the person is offboarded). There is no bulk action.
  • "Three refusals": now "four".
• One related gap: a deployment that somehow holds connections at both vendors cannot start, because every way of naming a provider is refused. The activation refusal should stop that state from ever happening. In case it does, the startup message now gives the manual way out.
• Refusal text: docs/deployment.md and docs/development.md now quote migration-reach.ts exactly (e94c8825).
• agent-mastra/bun.lock: untracked again (5a0c6186).
• Composio-visible changes: these are now a section of the description. One correction: with both keys set and no OPENBOT_BROKER_PROVIDER, the broker isn't simply off; the server refuses to start, with a message naming the variables.
• Typecheck baseline: now keyed by file, error code and message, counting duplicates, with no line numbers (a0d973af). I checked it: blank lines added at the top of a baselined file still pass, a new error or a third copy of a baselined one fails, and a missing baseline gives a clear message instead of 267 "NEW" errors.

[davidmckayv]

Thanks, this is a solid round. I checked each fix against the code rather than the reply. For each one I reverted the fix in a scratch copy and confirmed the new tests fail. I also ran the migrations on a throwaway database: an upgrade from 0056, a fresh install, an old replica inserting mid-rollout, and 500k rows. All four must-fix items hold, and so does the "also" list. The ratchet moves are within their own rules.

A few things are left before I approve.

Must fix

1. A mode flip mid-consent deletes the team's live shared row. accountRow in server/src/plugins/plugin-store/context.ts:345 matches a deployment row on provider, app and holder, but not vendor_user_id. So when the withdraw branch clears the retired shared identity (route-groups/connections.ts:2349), it deletes whichever deployment row the app has. Here's how to reproduce it:

   • An admin starts consent on Shared identity A.
   • The app goes Shared, then Personal, then Shared again, which mints identity B.
   • Someone connects B, and then the admin returns.

   The vendor revoke correctly targets A, but B's row is deleted. The app then reads as disconnected while B is still live at Arcade. A mode switch doesn't close open attempts, so this is reachable. Add vendorUserId to the deployment half of accountRow. This was already there before the last round; fix 1 didn't cause it.

2. Pin each skip-revoke guard on its own. Removing just the sibling guard (connections.ts:2531) leaves all 50 verify tests passing. So does removing just the already-held check (:2518). Only removing both fails a test. The test at arcade-verify.test.ts:1837, which is meant to cover already-held, actually passes through the sibling guard: the default authProviderAnswer of "google" turns the earlier rows into siblings. This is the Shared-app protection you called out, so each guard needs its own test.

3. Add a regression test for the rolling-deploy fix. Nothing inserts an mcp_tools row without vendor_name and reads it back through a reader, so a future raw vendorName read would pass CI. One test that does what an old replica does would cover it.

4. Show skipped tool names where the admin refreshes. $key.tsx:1038 and $key_.bots.$agentId.tsx:421 only show lastError when the app has zero tools. The refresh mutation also drops the response, so after a partial refresh the admin sees nothing, even though the comment at model.ts:637 says the names are reported on the app's page. Meanwhile admin/plugins/index.tsx:184 turns the whole row red. For a server that keeps listing a dotted name, that never clears. Show the skipped names as a warning on the app's page, and don't render a partial refresh as an error on the list.

Should fix

• A cancelled action can stay live. When a cancel takes the already-held path, the revoke is skipped and the person is told "cancelled", but the extra scope stays on the Arcade token. Calls are gated only by Arcade's tool_authorization_required, so the Bot can still do the action they cancelled. On a Shared app, it does so as the team. This is rare, but two things should change:
  • the notice at connected-accounts/index.tsx:155 should say the action may still be allowed, and how to remove it;
  • the trail should record more than authorization_cancelled.
• A probe failure after a cancel logs nothing (connections.ts:2510). Write the arcade-cancelled-grant-left-live line there too.
• Don't baseline this PR's own type errors. 25 of the 267 baseline entries are in 10 test files this PR adds. That includes 14 copies of one TS2322 in routes-vendor-vocabulary.test.ts and 8 across the arcade-*-engine tests. The baseline's own header says new code shouldn't add lines, so fix them and drop the entries.

Small

• A dev database that ran the old 0057 to 0063 gets a raw 42P07 relation "pending_authorizations" already exists instead of the guard's message. Nothing is corrupted. A line in the description is enough, or the guard could refuse when applied migrations are missing from the folder.
• The description's "Not done" section still says the admin page offers a whole-app Connect that always fails. 9c441b7d already hides that button.
• The comments at broker.ts:552 and arcade-adapter.ts:233/852/1080 still say "Measured against the live API", without the source and date the docs now give.
• Optional, since main already behaves this way: OFFERABLE_TOOL_NAME has no length limit. With a 40-character server id, mcp__<serverId>__<name> can pass OpenAI's 64-character limit.

Once 1 to 4 land, I'm happy to approve.

[mxmzb]

All of it is in, up to 289ef458. bun run test:ci, merged with main at 12c3a694: 8155 pass, 0 fail.

Must fix

1. Mode flip deleting the live row (dfce0efd). accountRow's deployment half now matches vendor_user_id. New test in arcade-verify.test.ts: Shared A attempt, app now Shared B with B's row connected, admin returns. The test checks that A is revoked, B's row survives, nothing goes on the trail, and the attempt is withdrawn. It fails without the fix.
   One knock-on you should know about: recordBrokeredConnection's only re-check write goes through accountRow too. A re-check made under a different deployment identity now answers wrote: false and leaves the row alone, where before it stamped its verdict on A's row. The probe tested B, so it says nothing about A. shared-brokered-store.integration.test.ts is updated to match.
2. Each skip-revoke guard pinned on its own. The already-held case now gets an auth provider of its own, so no earlier row can be a sibling. There's also a new sibling-only case: the app isn't held, and a sibling on the same provider is. I checked both by mutation: with only the already-held check removed, the already-held test fails; with only the sibling guard removed, the sibling test fails.
3. Rolling-deploy regression (1d322a71). store-vendor-vocabulary.test.ts inserts an mcp_tools row with no vendor_name, as a pre-0057 replica does. It reads the row back through serverPublishesAction and probeActionFor. Both tests fail if vendorNameOf becomes a raw column read.
4. Skipped tool names (11b56f3e). They now go in a new nullable column, mcp_servers.skipped_tools (migration 0059), not last_error. A partial refresh clears last_error, so the list row no longer goes red. The app page and the Bot's grant page show the names as an amber role="status" warning, whether or not the app has other tools. The refresh mutation already invalidates the page query, so the warning appears straight after Refresh. One case is unchanged: when every listed name is skipped, nothing new is stored, so that refresh still records last_error as well. The client field is optional, because an older replica won't send it mid-rollout.

Should fix

• Cancelled action left live. That branch now answers its own code, cancelled-left-live. Its notice says the vendor may still allow the cancelled action, and to remove it by disconnecting the app (which ends the whole connection) and reconnecting. The plain cancelled notice now says the grant was withdrawn, which is the only way that code is reached. The trail also gets a new mcp.cancelled_grant_left_live row beside mcp.authorization_cancelled, with the action, holder, why and siblings. If filing it fails, that is logged; it doesn't change the answer.
• Probe failure after a cancel now writes arcade-cancelled-grant-left-live, with why saying the ending couldn't be read. It has its own test.
• Baseline (cf4a4390). Fixed the 25 errors rather than baselining them. I also completed plugin-routes' ServerRecord fixture, whose baselined message would otherwise have changed with the new field. 267 → 241 entries, deletions only. After merging main, the gate caught one more: main's Open the Bot's screen only when there is something to watch, and offer an unconnected app in the conversation #798 added HeldConnection.revoked. Fixed in 289ef458.

Small

• 0057–0063 dev databases: added a line to the description.
• The "Not done" entry about the whole-app Connect is removed; the description now credits 9c441b7d.
• broker.ts and the three arcade-adapter.ts comments now say how and when each was measured: the 2026-10-13 live-suite run, the 2026-10-12 hand script, and the 2026-10-14 directory measurement. Each also says nothing in CI re-checks it.
• OFFERABLE_TOOL_NAME length: not done. Main behaves the same way, so I listed it in the description as a follow-up.