fix(events-shim): give each agent tab its own webhook inbox
Why
On /mcp-events-shim a visitor makes one inbox and then picks an agent tab. Every tab showed setup '<the same MCP URL>' --<flag>, which reads as "one inbox per agent". It isn't: one inbox wakes exactly one agent session. Running setup for both Claude Code and Codex on one inbox meant the Codex wake link took every post and the fresh Claude Code session never woke.
Companion: AgentWorkforce/relay events-shim per-CLI inbox PR (linked in a comment once open). That PR keeps a separate inbox per agent CLI on one machine, makes setup refuse to add a second waking CLI to an inbox unless --share-inbox is passed, and adds an optional agent.wake_agent to GET /shims/current. This PR treats wake_agent as optional, because hosts may not send it yet.
What changes
- Each agent tab has its own inbox. A map
agentId -> { manageToken, mcpUrl }is kept in localStorage underagent-relay-events-shim-inboxes, along with the last selected tab. The old singleagent-relay-events-shiminbox is moved under the tab that is active on restore (default Claude Code), and the old key is removed, so existing users keep their inbox. An inbox lives under one tab only. - Inboxes are created lazily. A tab with no inbox shows a one-click Get a webhook for button. Nothing is created just by opening a tab. The create API allows 10 inboxes per hour per IP, so clicking through all nine tabs must not use up that limit. A code comment explains this.
- Everything follows the selected tab's inbox: post URL, secrets, rotate, bearer token, Live feed, relayfile commands and Keep this inbox (remounted per inbox). Only the selected inbox is polled. A 404 clears only that tab's inbox, and only if the tab still holds that inbox.
- The page link carries the tab:
#k=…&m=…&a=codex. A shared or bookmarked link opens that inbox on its tab, and a link with noaopens on the default tab. TheisSession/isOurMcpUrlvalidation is unchanged (it moved toweb/lib/events-shim-inboxes.ts), so a crafted link still can't make the page show someone else's command. - Copy. Every tab gets a callout next to the setup command:
- Claude Code: "This inbox wakes one Claude Code session: the one started most recently. An older session takes the posts back when you tell it “watch for webhooks”."
- Codex / opencode / Grok / Devin: "This inbox wakes one session: the newest open one."
- Cursor / Gemini CLI: "This inbox wakes one session." Muse, which is not woken yet: "This inbox is for one Muse session."
- Any MCP client: "This inbox is for one MCP client and one session. Give each other client its own inbox."
- Every tab also says: "Each agent here has its own inbox and webhook URL. To wake two agents, set each one up from its own tab."
- The hero lead no longer says "One MCP server, one webhook URL". Section ii is now "Post to 's webhook URL", and the relayfile copy names the agent.
- Status line. When
wake === 'linked'andwake_agentis present, it reads "Agent connected · posts wake , even when idle". Withoutwake_agentit reads "… posts wake its linked session, even when idle", which doesn't name a specific session. - Keep this inbox. On return from sign-up (
?keep=1) the inbox is kept once. The flag is then dropped from the URL, so switching tabs doesn't also keep other tabs' inboxes. - Persistence and fragment updates run in an effect, not inside a state updater, because Next routes
history.replaceState.
Tests
- New
web/lib/test/events-shim-inboxes.test.tscovers validation, fragment round-trip and crafted links, store parsing, one-inbox-per-tab, scoped expiry, legacy migration (default tab, active tab, old link plus legacy, link vs. a different legacy inbox, no free slot, unreadable data), shared links and the last selected tab. npm run lintpassed (warnings that were already there only),npm run typecheckpassed,npm run testpassed (web 56 files / 633 tests, router 12 / 319), andnpm run buildpassed.- Checked in headless Chromium against
next dev, with the events-shim API mocked through Playwright route interception (fake tokens only, no real inbox created):- A legacy inbox migrates to Claude Code.
- Clicking through all nine tabs created only the one inbox that was asked for.
- Claude Code keeps inbox A after Codex gets inbox B.
- Only the selected inbox is polled, and a 404 on Codex clears only Codex and shows the expiry message.
- A crafted link (foreign MCP URL,
a=grok) opens Grok with no inbox and nothing from the link rendered. - No console errors.
Screenshots
Taken locally with fake values (…FAKE-not-a-real-token…, local mock API). They aren't committed because the repo has no convention for that.
- Before, Claude Code and Codex tabs: both show the same
esm_DEMO-inbox-A…command, and the status says "posts wake it". - After, Claude Code: the one-session callout, inbox A, and the status "posts wake demo-claude-session".
- After, Codex (new): the callout and a Get a webhook for Codex button, with no command until clicked.
- After, Codex (created): its own inbox B command and webhook URL, with the status falling back to "posts wake its linked session".
- After, Any MCP client: the one-client callout and the create button.
🤖 Generated with Claude Code
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.
Summary by cubic
Fixes the events-shim page so each agent tab has its own webhook inbox, since one inbox wakes exactly one agent session. Every tab previously showed the same inbox's setup command; setting up Claude Code and Codex on one inbox meant the Codex wake link took every post and the new Claude Code session never woke.
- Each tab's inbox lives in a per-agent localStorage map; the old single
agent-relay-events-shiminbox migrates under the tab active on restore, and the old key stays when a shared link displaces the migrated copy. - Inboxes are created lazily per tab with a "Get a webhook for
<Agent>" button, so browsing tabs doesn't spend the API's 10-per-hour create limit. - Post URL, secrets, rotate, feed polling and relayfile commands follow the selected tab; a 404 clears only that tab's inbox, and a secret save finishing after a tab switch can't clear the newly selected tab's draft.
- A generated bearer token stays scoped to the inbox that produced it, and inbox-map changes merge across windows so an earlier window can't overwrite a newer inbox.
- The page link carries the tab (
#a=codex) so shared and bookmarked links open on the right tab, and existing validation blocks crafted links from showing someone else's command. - The status line names the woken agent when the feed sends
wake_agent, treated as optional for hosts that don't send it yet. - Keep this inbox auto-keeps once on return from sign-up rather than once per tab.
- New tests cover validation, legacy migration, one-inbox-per-tab, cross-window merging and shared-link behavior.