feat(session-relay): cross-session/cross-project + cross-tool (Codex↔Claude) agent message bus

[DocksDocks]

What

Adds session-relay, a second plugin in the docks marketplace: a cross-session, cross-project, cross-tool agent message bus. One agent can hand a message to — and get a reply from — an agent in another session, another project, or another tool (Claude Code ⇄ Codex), over a single shared on-disk store.

This PR folds two phases:

• v1 — the bus (Claude Code). A stdio MCP server (bus) exposing whoami/register/roster/send/inbox over a shared store, a SessionStart hook that auto-registers each session and drains its inbox into context, and a relay.mjs doorbell that wakes an idle recipient via headless claude -p --resume.
• v2 — cross-tool (Codex). The same store/registry/hook now serve Codex too: registry entries carry a tool field, the doorbell dispatches per-tool (claude -p --resume or codex exec resume), the SessionStart hook is shared (Codex's contract is byte-identical to Claude's), and a .codex-plugin/ manifest + Codex marketplace entry ship it to Codex.

Why

Native Claude Code has no general live session-to-session channel across projects (Agent Teams can't span sessions; Channels are single-session, research-preview). The session id is the routing key; the transport is built from three confirmed primitives — an MCP server over a shared store, a SessionStart hook for auto-register + inbox-drain, and a headless-resume doorbell to wake idle recipients. Codex exposes the same three primitives (codex exec resume, a matching SessionStart hook, codex mcp), so the bus spans both tools.

How it works

 project A (Claude)            shared store (~/.agent-relay/)         project B (Codex)
  SessionStart hook ──register──▶ registry.json {id→dir,name,tool} ◀──register── SessionStart hook
  bus.send(to=B) ───────────────▶ mailbox/<id>.jsonl ◀──────────────── relay.mjs send
        └────── doorbell: codex exec resume <id> (wake idle B) ──────────┘

Delivery is pull + event, never a live push: a recipient sees mail when it calls inbox or at its next SessionStart; send reaches an idle session only after the doorbell wakes it.

Verification

• node scripts/ci.mjs — green (adds a self-contained session-relay section with 5 Codex-parity checks; the rest of CI stays scoped to plugins/docks).
• node plugins/session-relay/test/selftest.mjs — 15 checks (store round-trip, MCP handshake, hook inject/drain, tool-field, doorbell dispatch selection, AGENT_RELAY_HOME precedence).
• Live bidirectional round-trip (codex 0.142.2 + claude): a real Codex session and a real Claude session registered on one store and exchanged message+reply both ways — Claude→Codex delivered an external message into the Codex session via its hook (agent replied MANGO); Codex→Claude had the Codex agent relay.mjs send a message that was delivered into the Claude session via its hook (echoed PAPAYA-FROM-CODEX).

Notes for reviewers

• The Claude-only path is behavior-preserving; v2 only adds a tool tag and a second doorbell branch.
• The bus is a privilege boundary: any local process that can write the store can inject a turn into a registered session. Inbound messages are treated as untrusted input; the skill says so explicitly.
• release.mjs is intentionally not extended — it stays scoped to plugins/docks; session-relay self-versions (its manifest triple is gated in ci.mjs).
• Full cold-handoff plan + the verified-research trail live in docs/plans/active/session-relay-cross-tool-bus.md.

Plan & completion review

Tracked end-to-end in docs/plans/active/session-relay-cross-tool-bus.md (11/11 steps done). An independent plan-review completion pass diffed planned_at_commit..HEAD against the goal and set review_status: passed — Goal met, no regressions to the Claude-only path, CI green. Its one follow-up (Claude-side manifests still said "Claude Code only") is resolved in this PR.

🤖 Generated with Claude Code