feat(composio): move Composio into the agent, behind one approval gate

[mxmzb]

Supersedes #66. Same feature, on the side of the boundary Tyler argued for.

Why this rather than #66

#66 put Composio in the Channel. The objection was that it defines agent
behaviour in the surface: the OpenTag agent, run on its own, had no Composio
capability at all.

The evidence that objection was right is in our own docs. setup.md on that
branch said Composio calls were "gated separately and differently" from Linear
and Notion writes — a second approval card, its own dial, and no graph to resume.
One product, two approval systems. That sentence made the case better than the
line count did.

The rule this settles on: capabilities belong to the agent; identity and
rendering belong to the surface.

What moved

The agent owns the Composio session, discovery, execution, effect
classification, and the approval decision. agent/composio_tools/.

The Channel keeps exactly two things it alone can do: knowing who pressed a
button, and putting something in front of one person.

Two things got better, not just relocated

One approval gate. A Composio call now pauses on the same confirm_write
card that already guards a Linear or Notion write. Because the graph resumes
after the decision, the model sees an approved call's result — #66 could not, and
said so in its own comments.

No classification cap. Effects are looked up per slug and cached, instead of
building the whole map up front under a fixed limit. A real slug past that limit
used to be unclassified through no fault of the model.

Identity

The agent reads who spoke from forwardedProps.channelActor, added in
CopilotKit#6826. It is never a tool argument the model fills, which is what made
agent-side Composio unsafe before: the model would have been choosing whose
mailbox to open.

Sessions key on platform and id together. That fixes a collision carried over
from #66, which keyed on the raw provider id — one deployment serving Slack and
Teams would have given U1 on either platform the same Composio identity, and
therefore each other's connected accounts.

A malformed or absent actor reads as an anonymous turn: shared toolkits still
work, personal ones are refused. Refusing personal access is the safe failure.

The connect flow, and the auth gap it exposed

A connect link is a bearer capability — whoever opens it binds their account to
the id it was minted for. So the card posted in the thread carries no link; the
link is minted on click, for the clicker, and delivered where only they can see
it.

Minting needs a route on the agent, and that route could not be added safely as
things stood: the runtime has always sent AGENT_AUTH_HEADER and this service
has always ignored it. Behind Railway's private domain that was survivable; in
front of a link-minting endpoint it is not. So the secret is now checked, on two
deliberately different rules:

• Ordinary traffic, only when a secret is configured — a local run has none, and
  enforcing unconditionally would take every existing deployment down on
  upgrade. Health stays open; the platform probe cannot send one.
• The connect route, always. With no secret it reports itself unavailable rather
  than serving. There is no configuration in which handing a capability to an
  unauthenticated caller is intended.

Compared with compare_digest, not ==.

Approvals, and who may answer

A call that runs in one person's own account names that person as its approver.
The agent can only say whose call it is; the surface knows who clicked, so it
enforces — refusing anyone else on both buttons, telling them privately, and
leaving the graph paused so the right person can still answer. Declining is
enforced too, since a colleague cancelling somebody else's action is the same
problem in reverse.

The test worth reading

agent/tests/test_composio_approval_resume.py. A resume is delivered as a resume
command and carries no forwarded properties, so the actor that decided whose
account a call runs in is not re-sent. An approval clicked twenty minutes later
still lands in the right account because the state schema declares the actor and
the checkpoint keeps it — verified by removing that declaration and watching the
personal call stop running.

Requires a released @copilotkit/channels

Personal toolkits depend on CopilotKit#6826 shipping. On an older pin the actor
never arrives, every turn reads as anonymous, and personal toolkits silently
offer nothing while shared ones keep working. setup.md says so where somebody
debugging would look.

Verification

• pnpm check-types clean.
• 261 TypeScript tests, 271 Python tests, 11 CDK tests — all passing.
• Mutation-checked, not just written: the unconditional personal-only dedup, the
  disabled sandbox, the toolkit-prefix routing, the mandatory error check, the
  fail-closed capability rule, the approver enforcement, and the resume identity
  were each broken deliberately to confirm a test catches it.
• Both packaging tests now derive from disk instead of hardcoded lists — either
  would have let a new package pass locally and crash the container on first
  import.
• railway IaC validation needs credentials and was not run.

Not moved

The operator connect script, because it runs outside a turn — it is now
uv run python -m composio_tools.connect_cli <toolkit>, where the session lives.