feat(composio): optional Composio tool integration, shared or per-user

[mxmzb]

Adds an optional Composio integration so a self-hoster can connect third-party
apps by setting an environment variable, instead of hand-writing an MCP block
per app.

Verified end to end in a live Slack workspace, including the approval gate, and
wired into both deployments. Details at the bottom, along with the four commits
that live run produced.

What it does

Two paths, independently configurable:

COMPOSIO_API_KEY=ak_...
COMPOSIO_TOOLKITS=linear,jira               # one shared team identity
COMPOSIO_USER_TOOLKITS=gmail,googlecalendar # each person's own account

Shared toolkits run as a single identity everyone in Slack reaches.
Personal toolkits run as whoever is asking — "what's on my calendar" uses
your Google account, and your colleague's question uses theirs. People connect
their own accounts from a card in the thread.

With no COMPOSIO_API_KEY, none of it loads: no client, no tools, no log noise.

Approvals

COMPOSIO_APPROVALS is off, destructive (default), or writes. The default
gates deletes and lets creates and updates through — measured against the live
API, that is 9 of gmail's 63 tools, 3 of linear's 47, and 8 of googlecalendar's
49.

Managed Channels cannot block a tool handler on a user's choice
(supportsBlockingChoice: false), so a gated call posts a card, registers the
pending call under a token, and ends the turn. The Approve handler executes and
rewrites the card in place.

Design notes worth reviewing

It lives entirely in the TypeScript runtime. @copilotkit/channels-core has
no forwardedProps, so there is no way to hand a structured, LLM-proof user id
to the Python agent — identity reaches it only as prompt text, which cannot
scope credentials. ChannelToolContext does carry a platform-verified actor.
Identity exists in TypeScript and nowhere else, so the code that needs identity
lives there.

We wrap the SDK rather than exposing Composio's own router tools. Their
hosted executor sends calls from the model straight to Composio, bypassing our
approval card entirely. Wrapping is what makes the gate un-bypassable.

Sessions always pass workbench: { enable: false }. A default Composio
session hands the agent COMPOSIO_REMOTE_BASH_TOOL and
COMPOSIO_REMOTE_WORKBENCH — remote shell and Python — with no opt-in. OpenTag
already has a sandbox behind separate credentials; a second ungated one arriving
as a side effect of naming a toolkit is a surprise, not a feature.

Composio's telemetry is disabled. Enabled by default, it registers its own
SIGINT/SIGTERM handlers that flush over the network and then re-raise via
process.kill. Against server.ts's async drain that truncates graceful
shutdown — and SIGTERM is how Railway and ECS stop a container.

A connect link is never posted to a channel. A Composio link binds whoever
completes it to the user_id it was minted for, so a link for one person in a
shared channel lets someone else attach their mailbox to that identity. The card
carries a button; the link is minted for whoever clicks and delivered privately.

An unmapped tool slug is treated as destructive. Tools are classified from
Composio's MCP behaviour tags, fetched with limit: 300. A slug past that cap,
hallucinated, or injected would otherwise be treated as a plain write — and a
plain write is not gated in the default mode.

Shared toolkits need one terminal step

pnpm composio:connect <toolkit> mints a link bound to the identity shared
calls actually run as. The Composio dashboard's own "Connect my account" button
binds a different user id, so it does not work for this — connections are
strictly scoped per user id, verified live.

Personal toolkits skip this; each person connects their own from a thread.

Verification

Check	Result
pnpm check-types	clean
pnpm test	431 passed, 36 files
cd agent && uv run pytest	180 passed
cd deployment/aws && pnpm test	14 passed
Railway IaC	diagnostics: []
Live Slack workspace	connect flow and all four approval checks verified

Behaviour here was measured against the live API rather than taken from
published documentation, which was wrong on several counts worth knowing if you
review this against Composio's docs:

• tool_router.create_session does not exist — it is sessions.create, and
  tool_router is a deprecated alias.
• session.tools() returns a fixed six-tool router, not a toolkit's tools.
• session.execute never throws on tool failure; it returns
  { data, error, logId } either way, so a try/catch alone reads every failed
  write as a success.
• thread.awaitChoice rejects outright on managed Channels and never posts.
• The session tags filter takes a bare array; the { enabled: [...] } shape
  in the API reference is rejected.

Deploy config

Both deployments carry the Composio variables and the two Slack tokens now, so
the feature is no longer local-only.

Railway takes all of them as preserve(): absent COMPOSIO_API_KEY nothing is
constructed, so a deployment that sets none of them behaves as it does today.

AWS splits them the way that stack already splits everything — non-secret
settings as CDK context on the runtime container, COMPOSIO_API_KEY as a field
in the JSON application secret. Naming a toolkit is what admits that field,
which is one knob rather than a flag that can disagree with the toolkit lists,
and slackDirectDelivery=true admits the two token fields. They are conditional
rather than always-present-and-empty because ECS fails a task whose secret is
missing a named field: a deployment using neither integration must not name
them.

Everything lands on the runtime container only. Identity reaches Composio's
tools there and nowhere else.

That work also fixes the Railway start command, which was pnpm runtime — pnpm
11 added a built-in command by that name that shadows the script and exits
non-zero, so the service would have failed to boot the first time the pinned
pnpm crossed that major.

Unrelated issue noticed

package.json pins rxjs: ^7.8.2 under pnpm.overrides, and pnpm 10.33 prints
"The 'pnpm' field in package.json is no longer read by pnpm." That pin has
been silently inert. Not touched here.

Added after review, during live Slack verification

Three commits land on top of the Composio work, in the order a live run
surfaced them.

Direct Slack delivery when both Slack tokens are set. The connect flow has
to hand one person a link nobody else in the thread can open, because a connect
link binds whoever opens it to the identity it was minted for. Intelligence's
managed adapter declares supportsEphemeral: false, so setting
SLACK_BOT_TOKEN and SLACK_APP_TOKEN together attaches a direct adapter that
supports postEphemeral. Both or neither — one alone cannot start a Socket Mode
adapter, so it fails at boot rather than falling back silently. Unset, which
stays the normal case, nothing changes.

One connect card per person and toolkit. The tool's "stop here" return
string is only advice. Without a guard the agent searched, was told truthfully
that the app is not connected, posted a card, searched again, and posted
another — a dozen identical cards in one turn until the graph's step limit cut
it off.

Answer a mention once, not once per revision. A single "@Roger say hi"
produced about fifty identical answers in eight seconds. Slack re-announces a
message as changed for reasons unrelated to anybody editing its text — adding a
reply to its thread is enough — and every announcement arrived as a fresh
mention with a new revision id, which the ingress dedup (keyed on that id)
cannot collapse. Answering one posted a reply, the reply revised the message
again, and the loop fed itself. An instrumented run showed one original message
and ten revisions of it among eleven turns. Verified after the fix: one mention,
one agent run, one reply.

The last one is a workaround for an upstream bug — @copilotkit/channels-slack
should not turn parent-metadata changes into mention turns at all. Worth fixing
in the monorepo so no Channels app needs this guard.

Verified end to end in Slack

The approval gate, in the same workspace:

Call	Effect Composio reports	What happened
Fetch inbox	read	ran, no card
Move to trash	write	ran, no card — see below
Batch delete	destructive	carded, turn ended, ran only after Approve
Batch delete, runtime restarted before the click	destructive	card reported itself expired

Trashing a message is not gated in the default mode, because Composio tags it as
an ordinary write rather than destructive. That reads as reasonable — trash is
recoverable, permanent delete is not — and COMPOSIO_APPROVALS=writes gates it
for anyone who disagrees.

Asking Roger for the last three Gmail messages posted exactly one Connect Gmail
card, the button handed out a link private to whoever clicked it, and after
connecting, the same question returned three real inbox messages. The card
itself stays in the thread on purpose — anyone else there can click it to
connect their own account — and only the link behind the button is per-person,
which is the part that needs postEphemeral.