fix(events-shim): one inbox wakes one session, and says which

Merged
KH
3d ago
+871-147

Problem

This was found live. A person made one inbox on the webhook-inbox page and ran setup for both Claude Code and Codex on it, because every agent tab shows the same MCP URL.

  • serve linked the inbox's relay wake to the Codex session.
  • A brand-new Claude Code session never woke. Since 18.9.0 (#2194), listen --hook only listens in sessions whose transcript shows a webhooks tool call. Every hook listener also stands down while a relay wake link works.
  • The Claude session then called watch_webhooks, read wake: "linked" with "each post is injected into this session", and told the person the inbox was linked to it. That was false: the link targets Codex.
  • Setup still said "Start a new Claude Code session. Each post wakes it by itself".

One inbox wakes exactly one session, but nothing said which one, and the opt-in broke fresh Claude-only sessions.

Change

a. Claude wakes without opt-in, still one session. A per-inbox owner record (claude-owner-<digest>.json) names the Claude Code session that takes posts.

  • The SessionStart hook writes it: the most recently started session takes over. claude -p runs and compactions don't.
  • A webhooks MCP tool call found in the transcript since the last scan also takes over. This is the explicit way to move posts to an older session.
  • When the owner's claude process has exited, the record is vacant and the next hook to run takes it.
  • An older listener checks ownership in its loop and every 2 s during a wait. It cuts its wait off (a leased batch is released at once) and exits, so it never takes another post.

Kept from #2190, #2194 and #2211:

  • one listener per inbox (the inbox lock is unchanged);
  • no hook listener takes posts while a working relay wake link exists (now logged with the target agent);
  • leases and acks are untouched.

b. Truthful link reporting. WakeTarget.agent is new and optional.

  • link_relay_wake takes agent and answers linked_agent. It also answers replaced_agent and says "The inbox no longer wakes …" when it moves a link.
  • watch_webhooks reports linked_agent and linked_at, and its next steps say "linked to the Agent Relay agent "X" … Compare "X" with your own Agent Relay agent name. If it is not yours, the posts do not come to this session". It no longer says the posts go to this session.
  • An unnamed link reads linked_agent: null, with "unless you called link_relay_wake yourself in this conversation, assume the link wakes another session".
  • linkAgent (serve and link --codex-hook) passes the agent name.
  • The feed reports agent.wake_agent.
  • The skill text tells the agent to compare names.

c. Multi-CLI setup clarity, and per-agent inboxes that actually work.

  • Each CLI now keeps its own inbox (inboxes in webhooks.json). Before, every hook read the single mcpUrl, so a second inbox for a second agent on the same machine replaced the first one's.
  • serve, link and uninstall work per inbox.
  • Configs saved before this keep their known CLIs (core kinds, and Claude when its hook is installed) on their old inbox.
  • Setup refuses (exit 2, nothing written) to add a waking CLI to an inbox another CLI already uses, or to one linked to another agent. The message names the holder and points to making a separate inbox. --share-inbox overrides.
  • When CLIs share an inbox, setup prints "One inbox wakes one session, not one per agent. Claude Code, Codex share this inbox, so:", says who wins and how it switches, and points to an inbox per agent.

Tests

npx vitest run --root . packages/events-shim/src: 147 pass. Reverting only cli.ts, mcp.ts, types.ts and service.ts fails 11 of them:

  • fresh session wakes without a tool call; a non-owner takes nothing;
  • a newer session takes over and the older listener exits without a post (two concurrent listeners);
  • a closed owner is vacant; claude -p and compaction don't take over;
  • a tool call takes over (long transcript, chunked);
  • watch_webhooks / link_relay_wake name the agent, replaced_agent, and the unnamed-link text;
  • link passes the agent;
  • setup refuses or allows with --share-inbox and prints who wins;
  • setup refuses an inbox linked to a named agent;
  • Claude and Codex on separate inboxes wake independently;
  • legacy config migration;
  • the new setup copy.

Typecheck and build are clean.

Hosts

The hosted inbox stores the wake link in fixed columns. It shows linked_agent once it persists WakeTarget.agent (a follow-up in cloud). Until then links read as unnamed, and the tool text never claims the link for the reader.

Companion page PR in agentrelay.com: per-agent inboxes on the page (linked in a comment).

Live verification on a macOS machine: results will be posted as a comment.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.