Reach a person's own Gmail, Slack or Linear through Composio

[mxmzb]

What this adds

Composio becomes a fourth way a connector is reached, alongside MCP, the Google Drive REST adapter, and Routines.

An app an operator enables is an ordinary mcp_servers row marked provenance = "composio" with url composio://<toolkit>. A new transport dials it, and each call runs in the asking person's own account: the deployment holds one key for the broker, and which person's Gmail or Slack it opens is decided entirely by the user id sent alongside that key — taken from their authenticated session, never from anything a model supplied.

Everything downstream is untouched. The permission check, the rule engine and the audit row work exactly as they do for Drive and Notion.

Read this first: steps 1 and 2 only, deliberately

Nothing in the shipped product installs a Composio client, reads COMPOSIO_API_KEY, enables an app, or creates a connection row. That is intended for this change and it has a visible consequence: the "you have not connected this app" refusal is reachable, while the thing it tells you to go and do does not exist yet.

Concretely, so nobody has to discover it:

• useComposioClient has no caller under server/src, so on any real deployment the client is null and every Composio path answers empty or refuses.
• @composio/core is therefore in devDependencies, not dependencies — only the opt-in live test imports it. Step 3 must move that one line back and re-run bun install the moment a file under server/src imports the SDK. Watch for that import; it is the trigger.
• No COMPOSIO_API_KEY entry was added to .env.example. An entry there is a promise the running product reads the variable, and nothing does. .env.example is byte-identical to main.
• When step 3 lands, docker-compose.yml, charts/openbot/templates/_helpers.tpl and docs/configuration.md all need the key forwarding, and @composio/client resolves to an alpha (0.1.0-alpha.76, pinned by @composio/core) which will then enter the production image. Exact text for all four is in the review ledger.

The guarantee, and how it is held

The branch's central claim is that three previously independent derivations — which protocol dials a row, whose credential it spends, whose name the audit trail records — plus a fourth nobody had noticed (which app at the broker a row is) are now resolved once, in access.ts, and read as fields everywhere else.

Each of these is gated by a test that fails when the guarantee fails, verified by mutating the source and watching the test die rather than by the suite being green:

• The id sent to the vendor is the asker's. Send the bot's instead and two tests fail naming both ids.
• A __version in the model's own arguments cannot stand in for a recorded one, and cannot choose which revision of an action runs.
• A brokered call is refused when nobody is attributed, and when the asker has not connected the app — including when a colleague has. Drop the actor term from that gate and it becomes "has anybody connected this", handing the broker a stranger's id.
• A curated catalogue entry cannot be shadowed into a broker by a tampered provenance column, and a brokered row whose id collides with a curated slug is refused rather than dialled at the curated vendor on the wrong credential.
• A recorded effect may narrow what a bot may do and may never widen it: a reviewed write list outranks a value in a vendor column, and an unrecognised or empty value is a write.

Behaviour changes outside Composio

Two, both small and both corrections:

An MCP server's declared effect is now believed. The MCP specification defines annotations.destructiveHint, servers publish it, and the listing code was dropping it — so a tool its own vendor called destructive classified as a read wherever a hand-written write list omitted it. That hint is now read. readOnlyHint is deliberately not read: the SDK's own types warn against making tool decisions from annotations sent by untrusted servers, and honouring it would let anyone who can add a server by URL declare everything read-only and be believed. Drive is unaffected by construction — it never enters that code path. For Notion the only cell that changes is a destructive-declared tool absent from the reviewed list; nothing can move toward read.

A failed query no longer carries its statement onward. Several call sites copied a database error's message into last_error and into the audit payload, which meant a failed query put its SQL and parameters in both. Deployment faults are now recognised by shape and raised rather than relayed.

Migration

0029_composio — a composio_connections table and three columns on mcp_tools (effect, destructive, version).

It was 0028 until this rebase; main had already taken that number. The snapshot is regenerated rather than renamed, because a rename alone would have left the newest snapshot describing a database missing the two columns main's own 0028 adds — which would make the next schema generation emit commands to drop them. That was reproduced before being fixed, and the drift probe is clean now.

composio_connections.user_id has no foreign key, by design. The row must outlive the person so offboarding can find it; that is the whole reason the table exists rather than reusing the existing credential join. Offboarding now deletes those rows and audits each one — note it shuts the gate this deployment owns and does not revoke at Composio, which the vendorRevoked: false field records honestly.

Review

Two full unbiased review rounds, then a targeted fix cycle.

Round one produced thirty mandatory findings, all fixed. Round two — the byte-identical confirmation round — produced about twenty-five, roughly half of them gaps in round one's own fixes, and the correctness half of those is fixed here. Its most consequential finding is worth naming, because it is the kind only a second round catches: the first round fixed a data-loss bug where an empty listing wiped every tool row, and a later fix made the transport throw instead of returning empty. Both were correct. Together they routed the first round's tests around the guard, so it could be deleted outright with the suite still green. It is genuinely gated now.

Two recurring causes account for most of the rest, and both are worth knowing when reading this diff: a comment asserting something the code or the dependency does not do, with code then written to match the comment; and a test that passes regardless of the behaviour it names. One false sentence in an interface's own documentation produced both a real bug and the two test stubs that could not catch it.

The remaining test-quality tail is deliberately deferred and listed in full in the review ledger — assertions comparing a value to itself, loops that pass vacuously on an empty set, and pre-existing debt in the files this branch happens to touch.

Known and deliberately not fixed here

• A brokered row's app is resolved from its url, but the vendor's own API has no field for it — the call identifies the app by the action slug alone. Our seam now passes app and action as a named pair so they cannot silently transpose, and states the obligation to refuse a mismatch for whoever writes the real adapter.
• A run nobody can be identified for records initiator_kind: "person" beside actor: "unattributed". Not a contradiction: one field says what set the run in motion, the other whose account it reached. Recording it as deployment would assert the call went out on the deployment's credential when it never went out at all. Main's DEPLOYMENT_INITIATOR documentation claims that case and nothing sends it there, so the overlap is in the prose; narrowing that sentence is not this branch's call.
• Delete-and-recreate restores permissions in three other places — MCP servers, skills, and bot-to-bot grants. Real, out of this subject, and written up for follow-up.

Verification

• bun test server/tests — 2071 pass, 4 skip, 0 fail across 136 files. The 4 skips are the live vendor suite, which needs an API key. Test count accounts exactly: 1841 at the merge base, +83 from main, +151 from this branch.
• typecheck, format:check, lint clean.
• drizzle-kit check clean; the CI drift probe reports no unwritten migration.
• The migration applies cleanly on top of main's own 0028 on a scratch database, landing both sets of columns.

🤖 Generated with Claude Code

https://claude.ai/code/session_01P2mm9gARmD13tnasEztb4x