claude-code-swarm 0.3.3 → 0.3.5

package/references/agent-inbox/docs/DESIGN.md

@@ -0,0 +1,1156 @@
+# Agent Inbox: MAP-Native Agent Message Router
+
+## Problem Statement
+
+Multi-agent coding workflows (like [claude-code-swarm](https://github.com/alexngai/claude-code-swarm)) need structured inter-agent messaging that works across process and federation boundaries. Today, agents within a swarm coordinate via native team primitives (SendMessage, TaskCreate) for in-process communication, and use MAP sidecars for external observability. But there's a gap:
+
+1. **Cross-process messaging** — Agents in different Claude Code sessions (different repos, different machines) can't message each other. The MAP sidecar broadcasts events but doesn't provide structured inbox/routing.
+
+2. **Structured message handling** — MAP provides transport (WebSocket, scopes, send/receive), but doesn't define inbox semantics, message threading, read tracking, or delivery guarantees. Agents need more than raw message passing.
+
+3. **Federation** — Different swarm instances, potentially on different networks, need to exchange messages with identity resolution and trust.
+
+**Agent Inbox** fills this gap: a MAP-native message router that provides structured inbox/outbox semantics on top of MAP's transport and identity primitives. It connects to MAP servers (like the one in agentic-mesh or claude-code-swarm's sidecar) and adds the routing, threading, and delivery layer that agents need for real coordination.
+
+---
+
+## Design Goals
+
+1. **MAP-native**: Built on MAP's agent identity, scoping, and messaging primitives — not a parallel system
+2. **Federation-first**: Cross-process and cross-instance messaging is the primary use case, not an afterthought
+3. **Structured messaging**: Inboxes, threading, read tracking, delivery confirmation — beyond raw MAP send/receive
+4. **Agent-friendly interface**: MCP tools that any coding agent can call naturally
+5. **Traceability via MAP conventions**: Conversations, turns, and threads follow MAP's mail spec for observability
+6. **Progressive complexity**: Simple send/receive works immediately; threading, conversations, and federation are opt-in
+
+---
+
+## Architecture Overview
+
+Agent Inbox and the MAP sidecar are **independent services**, each with its own MAP connection and its own responsibilities. The **plugin layer** (`map-events.mjs` in claude-code-swarm) acts as the router — dispatching lifecycle commands to the sidecar and messaging commands to Agent Inbox. No event bus is needed.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Local System (one machine)                           │
+│                                                                             │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                    Claude Code Session                                │  │
+│  │                                                                       │  │
+│  │   Hooks (SessionStart, PreToolUse, PostToolUse, etc.)                │  │
+│  │     │                                                                 │  │
+│  │     └─ Plugin (map-hook.mjs / map-events.mjs)                        │  │
+│  │          │                                                            │  │
+│  │          ├─ spawn/done/state/trajectory ──► sendToSidecar()           │  │
+│  │          │                                                            │  │
+│  │          └─ send/emit (messaging) ────────► sendToInbox()             │  │
+│  └───────────┬──────────────────────────────────────┬────────────────────┘  │
+│              │                                       │                      │
+│   ┌──────────▼──────────┐                 ┌──────────▼──────────────┐      │
+│   │    MAP Sidecar       │                 │     Agent Inbox          │      │
+│   │                      │                 │                          │      │
+│   │  Receives from       │                 │  Receives from           │      │
+│   │  plugin:             │                 │  plugin:                 │      │
+│   │   spawn/done/state   │                 │   send (messaging)      │      │
+│   │   trajectory         │                 │   agent notifications    │      │
+│   │   ping               │                 │     (spawn/done events)  │      │
+│   │                      │                 │                          │      │
+│   │  Owns:               │                 │  Owns:                   │      │
+│   │   Hook IPC (UNIX)    │                 │   Inbox/outbox mgmt     │      │
+│   │   Agent lifecycle    │                 │   Message routing        │      │
+│   │   Trajectory sync    │                 │   Threading              │      │
+│   │   Process mgmt       │                 │   Delivery tracking      │      │
+│   │                      │                 │   Traceability           │      │
+│   │                      │                 │   Federation             │      │
+│   │                      │                 │   MCP tools interface    │      │
+│   │                      │                 │   MAP JSON-RPC           │      │
+│   └──────────┬───────────┘                 └──────────┬───────────────┘      │
+│              │                                         │                     │
+│         MAP Connection                           MAP Connection(s)           │
+│         (local server)                           (local + remote)            │
+│              │                                         │                     │
+└──────────────┼─────────────────────────────────────────┼─────────────────────┘
+               │                                         │
+        ┌──────▼──────┐                    ┌─────────────▼─────────────┐
+        │ MAP Server   │                    │ MAP Server(s)             │
+        │ (local)      │                    │ (local + remote/federated)│
+        └─────────────┘                    └───────────────────────────┘
+```
+
+### Plugin-as-Router Pattern
+
+The claude-code-swarm plugin (`map-events.mjs`) already dispatches commands by type. Today, all commands go to the sidecar. With Agent Inbox, the plugin gains a second dispatch target:
+
+```
+Hooks → Plugin (map-hook.mjs / map-events.mjs)
+          │
+          ├─ spawn/done/state/trajectory → sendToSidecar() → Sidecar → MAP (lifecycle)
+          │
+          └─ send/emit (messaging) ──────→ sendToInbox() → Agent Inbox → MAP (messaging)
+```
+
+The plugin also notifies Agent Inbox about agent lifecycle events (spawn/done) so it can maintain its agent registry. This is a lightweight notification — not a bus subscription — just a `sendToInbox({ action: "notify", event: ... })` alongside the existing `sendToSidecar()` call.
+
+```typescript
+// In map-events.mjs — sendCommand() gains a second dispatch path
+
+export async function sendCommand(config, command, sessionId) {
+  const sPaths = sessionPaths(sessionId);
+
+  if (command.action === "send" || command.action === "emit") {
+    // Messaging commands → Agent Inbox
+    const sent = await sendToInbox(command, inboxSocketPath(sessionId));
+    if (!sent) {
+      // Fall back to sidecar (existing behavior)
+      await sendToSidecar(command, sPaths.socketPath);
+    }
+    return;
+  }
+
+  // Lifecycle commands → Sidecar (existing behavior)
+  const sent = await sendToSidecar(command, sPaths.socketPath);
+  if (!sent) {
+    const recovered = await ensureSidecar(config, sessionId);
+    if (recovered) {
+      await sendToSidecar(command, sPaths.socketPath);
+    } else if (command.action === "emit") {
+      await fireAndForget(config, command.event);
+    }
+  }
+
+  // Also notify Agent Inbox about lifecycle events (for registry)
+  if (command.action === "spawn" || command.action === "done") {
+    await sendToInbox(
+      { action: "notify", event: { type: `agent.${command.action}`, ...command } },
+      inboxSocketPath(sessionId)
+    );
+  }
+}
+```
+
+### Why Two MAP Connections? Concern-Based Split
+
+The sidecar and Agent Inbox each maintain their own MAP connection(s) because the **nature of their traffic is fundamentally different**:
+
+**Sidecar's MAP connection — lifecycle & observability:**
+- `conn.spawn()` / `conn.done()` — agent registration/unregistration
+- `conn.updateState()` — idle/active state changes
+- `conn.send({ scope }, payload)` — broadcast task lifecycle events (`task.dispatched`, `task.completed`, `task.sync`)
+- `conn.callExtension("trajectory/checkpoint")` — trajectory reporting
+- These are **fire-and-forget observability events**. If they fail, the swarm keeps working. The sidecar already has fallback logic for this (fire-and-forget via ephemeral connections).
+
+**Agent Inbox's MAP connection(s) — messaging & mail:**
+- `conn.send(target, message)` — routed message delivery to specific agents
+- Receiving incoming messages addressed to local agents
+- MAP `mail/*` operations (conversations, turns, threads)
+- Federation connections to remote MAP servers
+- These are **structured communications that need tracking**. Delivery matters. Messages are stored, threaded, and tracked.
+
+| | Sidecar traffic | Agent Inbox traffic |
+|---|---|---|
+| **Pattern** | Broadcast / fire-and-forget | Targeted / tracked delivery |
+| **Failure mode** | Silently drop | Queue and retry |
+| **Recipients** | Scope (all observers) | Specific agent(s) |
+| **Persistence** | Ephemeral | Stored in inbox |
+| **Threading** | None | Conversations, reply chains |
+| **Federation** | No | Yes (remote MAP servers) |
+
+Two connections to the same local MAP server is fine — they're doing different things. Agent Inbox additionally connects to **remote** MAP servers for federation, which the sidecar has no involvement in.
+
+### MAP Connection Ownership Summary
+
+```
+Sidecar MAP connection:         Agent Inbox MAP connection(s):
+  conn.spawn()                    conn.send(target, message)  ← message delivery
+  conn.done()                     conn.onMessage()            ← message receiving
+  conn.updateState()              mail/* operations
+  conn.send({ scope }, event)     Federation to remote servers
+  conn.callExtension(trajectory)
+```
+
+### Standalone Mode
+
+Agent Inbox also works **without a sidecar** — for non-swarm use cases, direct MCP tool usage, or testing. It has its own MAP connection and its own MCP tools interface. The sidecar is an integration point for Claude Code hooks, not a dependency.
+
+### How Agent Inbox Learns About Agents
+
+Without an event bus, Agent Inbox needs another way to know which agents exist. Two complementary mechanisms:
+
+1. **Plugin notifications**: The plugin sends lightweight `notify` commands to Agent Inbox on `spawn`/`done` events. Agent Inbox updates its agent registry.
+
+2. **MAP server query** (startup hydration): On startup, Agent Inbox can query the MAP server for currently registered agents to hydrate its registry. This handles the case where Agent Inbox starts after agents are already spawned.
+
+3. **Auto-registration**: Agents are automatically registered on their first `check_inbox` call or via the `SessionStart` hook (`hooks/register-hook.mjs`), which is the primary path for non-swarm use cases.
+
+```typescript
+// Agent Inbox command handler for lifecycle notifications from the plugin
+case "notify":
+  if (command.event.type === "agent.spawn") {
+    await storage.putAgent({
+      agent_id: command.event.agent.agentId,
+      display_name: command.event.agent.name,
+      scope: command.event.agent.scopes?.[0],
+      status: "active",
+      metadata: command.event.agent.metadata,
+      registered_at: new Date().toISOString(),
+      last_active_at: new Date().toISOString(),
+    });
+  } else if (command.event.type === "agent.done") {
+    const agent = await storage.getAgent(command.event.agentId);
+    if (agent) {
+      agent.status = "offline";
+      await storage.putAgent(agent);
+    }
+  }
+  break;
+```
+
+### How Agent Inbox Processes Messages
+
+```typescript
+// Agent Inbox receives messaging commands from the plugin via UNIX socket
+case "send":
+  // 1. Create a Message record with tracking metadata
+  const message = await storage.putMessage({
+    id: ulid(),
+    scope: command.scope || defaultScope,
+    sender_id: command.from || sidecarAgentId,
+    recipients: resolveRecipients(command.to),
+    content: normalizeContent(command.payload),
+    thread_tag: command.threadTag,
+    in_reply_to: command.inReplyTo,
+    created_at: new Date().toISOString(),
+  });
+
+  // 2. Route to recipients via Agent Inbox's OWN MAP connection
+  for (const recipient of message.recipients) {
+    if (isLocal(recipient.agent_id)) {
+      await mapConn.send(recipient.agent_id, {
+        messageId: message.id,
+        from: message.sender_id,
+        content: message.content,
+        threadTag: message.thread_tag,
+        conversationId: message.conversation_id,
+      });
+      recipient.delivered_at = new Date().toISOString();
+    } else {
+      // Remote delivery via federated MAP connection
+      await federatedConn.send(recipient.agent_id, message);
+    }
+  }
+
+  // 3. Record in traceability layer
+  traceability.recordTurn(message);
+  break;
+
+// Agent Inbox also receives messages on its MAP connection (from other agents/servers)
+mapConn.onMessage(async (msg) => {
+  // Store in recipient's inbox
+  const message = await storage.putMessage(normalizeIncoming(msg));
+
+  // Write to the local inbox.jsonl for Claude's context injection
+  writeToInbox({
+    from: message.sender_id,
+    payload: message.content,
+    timestamp: message.created_at,
+    messageId: message.id,
+    conversationId: message.conversation_id,
+  }, inboxPath);
+
+  // Record in traceability
+  traceability.recordTurn(message);
+});
+```
+
+---
+
+## Relationship to MAP
+
+Agent Inbox is **not** a MAP server. It's a MAP **client** that connects to one or more MAP servers and provides higher-level messaging semantics.
+
+```
+MAP Server          = transport + identity + scoping + raw send/receive
+Agent Inbox         = inbox routing + threading + delivery + traceability
+```
+
+| Concern | Handled by MAP Server | Handled by Agent Inbox |
+|---------|----------------------|----------------------|
+| Agent identity & registration | Yes (spawn, agentId) | Uses MAP's identity primitives |
+| Scoping / namespaces | Yes (scopes) | Maps scopes to workspaces |
+| Raw message send/receive | Yes (conn.send) | Wraps with inbox/routing semantics |
+| Message threading | No | Yes (thread_tag, in_reply_to, conversations) |
+| Inbox / read tracking | No | Yes (per-agent inbox, read_at, ack_at) |
+| Delivery confirmation | No | Yes (delivered_at, read receipts) |
+| Cross-server routing | No (single server) | Yes (connected to multiple MAP servers) |
+| Traceability (mail/*) | Partial (events) | Full (conversations, turns, threads, replay) |
+| Message persistence | No (ephemeral) | Yes (in-memory or SQLite) |
+
+### MAP Identity Primitives
+
+Agent Inbox uses MAP's agent identity system rather than inventing its own:
+
+- **agentId**: MAP's unique agent identifier — used as the primary identity
+- **Scopes**: MAP's namespace mechanism — used as workspace equivalent
+- **spawn/unregister**: MAP's agent lifecycle — Agent Inbox observes these
+- **Display names**: Optional memorable names layered on top of MAP agentIds for human readability
+
+Identity persistence is left to the connecting client. A client can reconnect with the same `agentId` to reclaim its inbox, or register fresh. Agent Inbox doesn't force a persistence model.
+
+---
+
+## Data Model
+
+### Messaging Entities
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                       Agent                                       │
+│  agent_id: string               ← MAP agentId                    │
+│  display_name?: string          (memorable, e.g. "GreenCastle")  │
+│  program?: string               (e.g. "claude-code", "codex")    │
+│  model?: string                 (e.g. "claude-opus-4-6")         │
+│  scope: string                  ← MAP scope (workspace equiv)    │
+│  status: active | idle | offline                                  │
+│  metadata: Record<string, unknown>                                │
+│  registered_at: timestamp                                         │
+│  last_active_at: timestamp                                        │
+└──────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────┐
+│                      Message                                      │
+│  id: string (ulid)                                                │
+│  scope: string                  ← MAP scope                      │
+│  sender_id: string              ← MAP agentId                    │
+│  recipients: Recipient[]                                          │
+│  subject?: string                                                 │
+│  content: MessageContent        (see Message Format below)        │
+│  thread_tag?: string            (user-defined grouping)           │
+│  in_reply_to?: string           (message id)                      │
+│  importance: low | normal | high | urgent                         │
+│  metadata: Record<string, unknown>                                │
+│  created_at: timestamp                                            │
+└──────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────┐
+│                     Recipient                                     │
+│  agent_id: string               ← MAP agentId                    │
+│  kind: to | cc | bcc                                              │
+│  delivered_at?: timestamp                                         │
+│  read_at?: timestamp                                              │
+│  ack_at?: timestamp                                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Traceability Entities (MAP mail conventions)
+
+These follow MAP's mail specification. Agent Inbox auto-creates and maintains them from messaging events, following MAP convention: a message with a `conversationId` is added to that conversation; without one, the server groups by thread context or auto-creates.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    Conversation                                   │
+│  id: string ("conv-{ulid}")     ← MAP mail format                │
+│  scope: string                  ← MAP scope                      │
+│  subject?: string                                                 │
+│  status: active | completed | archived                            │
+│  participants: Participant[]                                      │
+│  metadata: Record<string, unknown>                                │
+│  created_at: timestamp                                            │
+│  updated_at: timestamp                                            │
+└──────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────┐
+│                       Turn                                        │
+│  id: string ("turn-{ulid}")     ← MAP mail format                │
+│  conversation_id: string                                          │
+│  participant_id: string         ← MAP agentId                    │
+│  source_message_id?: string     ← links to Message               │
+│  content_type: text | data | event | reference | x-*              │
+│  content: TurnContent                                             │
+│  thread_id?: string                                               │
+│  in_reply_to?: string           (turn id)                         │
+│  created_at: timestamp                                            │
+└──────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────┐
+│                      Thread                                       │
+│  id: string ("thread-{ulid}")   ← MAP mail format                │
+│  conversation_id: string                                          │
+│  root_turn_id: string                                             │
+│  parent_thread_id?: string                                        │
+│  subject?: string                                                 │
+│  created_at: timestamp                                            │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### How the Layers Connect
+
+| Messaging Event | Traceability Record |
+|-----------------|---------------------|
+| Message sent with `conversationId` | Turn added to that Conversation |
+| Message sent with `thread_tag`, no `conversationId` | Turn added to Conversation auto-created for that thread_tag + scope |
+| Message sent with neither | Turn added to a catch-all Conversation for that scope |
+| Reply (message with `in_reply_to`) | Turn with `in_reply_to` in same Thread (auto-created from reply chain) |
+| Agent registers (observed via MAP) | Participant added to scope's active Conversations |
+
+The traceability layer **derives** its state from messaging events. It follows MAP's convention: if a message includes a `conversationId`, it's placed there; otherwise the server groups intelligently.
+
+---
+
+## Message Format
+
+Messages use a **structured content model** inspired by MAP's content types, with a convenient plain-text shorthand for simple cases.
+
+### Content Structure
+
+```typescript
+type MessageContent =
+  | { type: "text"; text: string }                    // Markdown text
+  | { type: "data"; schema?: string; data: unknown }  // Structured data (JSON)
+  | { type: "event"; event: string; data?: unknown }  // Lifecycle/coordination event
+  | { type: "reference"; uri: string; label?: string } // Reference to external resource
+  | { type: string; [key: string]: unknown }          // Extension types (x-*)
+```
+
+### MCP Tool Shorthand
+
+When agents use MCP tools, they can pass a plain markdown string as the body. The service layer wraps it:
+
+```
+Agent calls: send_message(body="Here's the API contract...")
+Stored as:   { type: "text", text: "Here's the API contract..." }
+```
+
+For structured payloads (task assignments, status updates, etc.), agents can pass the full content object:
+
+```
+Agent calls: send_message(content={ type: "data", schema: "task-assignment", data: { task: "...", assignee: "..." } })
+Stored as-is
+```
+
+### Extension Content Types
+
+For coordination-specific payloads, use `x-*` prefixed types:
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| `x-task-dispatched` | Task delegation | `{ type: "x-task-dispatched", task: "...", assignee: "..." }` |
+| `x-task-completed` | Task completion | `{ type: "x-task-completed", task: "...", summary: "..." }` |
+| `x-status-update` | Agent status change | `{ type: "x-status-update", status: "idle", reason: "..." }` |
+
+This aligns with claude-code-swarm's existing payload types (`task.dispatched`, `task.completed`, `task.sync`) — Agent Inbox just structures them as typed content.
+
+### Conversation Threading
+
+Threading works at two levels:
+
+1. **thread_tag** (lightweight): A user-defined string (e.g., `"auth-sprint-1"`) that groups messages. The traceability layer auto-creates a Conversation for each unique thread_tag + scope combination. Agents just tag messages; the server handles the rest.
+
+2. **in_reply_to** (structural): A message references another message's ID, creating a reply chain. The traceability layer auto-creates Threads within a Conversation from reply chains. Multiple reply chains in the same Conversation become separate Threads.
+
+3. **Explicit conversations**: Agents can also create conversations directly via `mail/create` and reference the `conversationId` in messages, giving full control when needed.
+
+---
+
+## Messaging Patterns
+
+### 1. Local Messaging (same MAP server / same scope)
+
+Agents connected through the same MAP server, in the same scope.
+
+```
+AgentA → send_message(to="AgentB", body="...")
+  → Agent Inbox routes locally (both in same scope on same MAP server)
+  → Message appears in AgentB's inbox
+AgentB → check_inbox() → sees message
+AgentB → reply(in_reply_to=msg_id, body="...")
+```
+
+This is the claude-code-swarm intra-team case. Today the sidecar broadcasts via `conn.send({ scope }, payload)`. With Agent Inbox, messages are routed to specific recipients with inbox tracking.
+
+### 2. Cross-Scope Messaging (same MAP server, different scopes)
+
+Agents in different scopes (workspaces/teams) on the same MAP server.
+
+```
+AgentA (scope: "frontend") → send_message(
+    to="AgentB",
+    to_scope="backend",
+    body="..."
+)
+```
+
+Agent Inbox resolves the target agent in the target scope and routes via the shared MAP server.
+
+### 3. Cross-Server Messaging (federation)
+
+Agents on different MAP servers — different machines, different networks. Uses MAP's native `federation/connect` and `federation/route` protocol.
+
+```
+AgentA (system: "frontend-team") → send_message(
+    to="AgentC@backend-team",
+    body="..."
+)
+```
+
+Agent Inbox parses the `@backend-team` address, resolves it to the federation peer link, and forwards via `federation/route`. The remote Agent Inbox receives, stores, and delivers to AgentC.
+
+**Via hub (typical deployment):**
+```
+┌─────────────┐      ┌──────────────┐                     ┌──────────────┐      ┌─────────────┐
+│  MAP Server  │      │ Agent Inbox  │  federation/route   │  Central Hub │      │             │
+│  (frontend)  │◄────►│ (gateway)    │◄───────────────────►│  Agent Inbox │      │             │
+│              │      │              │                     │  (router)    │      │             │
+│  AgentA ─────┼─────►│  resolve @   │────────────────────►│  relay ──────┼─────►│  Agent      │
+│  AgentB      │      │  backend-team│                     │              │      │  Inbox      │
+└─────────────┘      └──────────────┘                     └──────┬───────┘      │  (gateway)  │
+                                                                  │              │             │
+                                                                  │              │  ──► AgentC │
+                                                                  │              │      AgentD │
+                                                           ┌──────▼──────┐      └──────┬──────┘
+                                                           │  MAP Server  │◄────────────┘
+                                                           │  (backend)   │
+                                                           └─────────────┘
+```
+
+**Direct peer (alternative):**
+```
+┌─────────────┐      ┌──────────────┐  federation/connect  ┌──────────────┐      ┌─────────────┐
+│  MAP Server  │      │ Agent Inbox  │◄───────────────────►│ Agent Inbox  │      │  MAP Server  │
+│  (frontend)  │◄────►│ (gateway)    │  federation/route   │ (gateway)    │◄────►│  (backend)   │
+│              │      │              │                     │              │      │              │
+│  AgentA ─────┼─────►│  route ──────┼────────────────────►│  deliver ────┼─────►│  ──► AgentC  │
+└─────────────┘      └──────────────┘                     └──────────────┘      └─────────────┘
+```
+
+---
+
+## MCP Tools Interface
+
+### Agent-Facing Tools
+
+The MCP interface is intentionally minimal — 4 tools that cover all common agent messaging needs:
+
+| Tool | Description |
+|------|-------------|
+| `send_message` | Send a message to one or more agents. Supports replies (`inReplyTo`), threading (`threadTag`), and federated addressing (`agent@system`). |
+| `check_inbox` | Fetch unread messages for an agent. Auto-registers the agent on first call. Auto-marks messages as read. |
+| `read_thread` | Read all messages in a thread by `threadTag`. |
+| `list_agents` | List agents registered locally and optionally from federated peers. |
+
+Previously-separate tools were consolidated: `reply` is now `send_message` with `inReplyTo`, `register_agent` is handled automatically by `check_inbox`, and `acknowledge` happens implicitly on read. Conversation management tools (start_conversation, get_conversation, etc.) were removed from the agent-facing MCP interface — the traceability layer handles them internally, and they remain accessible via the MAP JSON-RPC interface for dashboards and debugging tools.
+
+---
+
+## MAP JSON-RPC Interface
+
+A JSON-RPC 2.0 endpoint implementing MAP's `mail/*` methods for traceability clients (dashboards, debuggers, audit tools).
+
+Methods:
+- `mail/create`, `mail/get`, `mail/list`, `mail/close`
+- `mail/join`, `mail/leave`, `mail/invite`
+- `mail/turn`, `mail/turns/list`
+- `mail/thread/create`, `mail/thread/list`
+- `mail/summary`, `mail/replay`
+- `map/subscribe` with event filtering
+
+This interface reads from the traceability layer. It can also write (e.g., a MAP client adding a turn), which flows back as a message to the target agent's inbox.
+
+---
+
+## claude-code-swarm Integration
+
+### Current Architecture
+
+```
+Claude Code Session
+  │
+  ├─ Native team primitives (SendMessage, TaskCreate)  ← in-process coordination
+  │
+  └─ Hooks (lifecycle events)
+       │
+       └─ UNIX Socket IPC
+            │
+            └─ MAP Sidecar
+                 │
+                 ├─ conn.spawn() / conn.send() / conn.updateState()  ← MAP SDK
+                 │
+                 └─ WebSocket ──► MAP Server
+                                    │
+                                    └─ broadcasts to scope
+```
+
+**Key sidecar commands**: `spawn`, `done`, `state`, `emit` (broadcast to scope), `send` (to target), `trajectory-checkpoint`, `ping`
+
+**Message injection**: Incoming MAP messages → `inbox.jsonl` → UserPromptSubmit hook → injected into agent context as markdown
+
+### Proposed Architecture (plugin-as-router)
+
+The plugin layer (`map-events.mjs`) gains a second dispatch target. Lifecycle commands continue going to the sidecar. Messaging commands go to Agent Inbox. The plugin also sends lightweight lifecycle notifications to Agent Inbox so it can maintain its agent registry.
+
+```
+Claude Code Session
+  │
+  ├─ Native team primitives           ← unchanged
+  │
+  └─ Hooks
+       │
+       └─ Plugin (map-hook.mjs / map-events.mjs)
+            │
+            ├─ spawn/done/state/trajectory
+            │       │
+            │       ├─► Sidecar → MAP Server (lifecycle, via sidecar's own conn)
+            │       │
+            │       └─► Agent Inbox (notify: agent.spawn / agent.done)
+            │                └─► updates agent registry
+            │
+            └─ send/emit (messaging)
+                    │
+                    ├─► Agent Inbox (primary)
+                    │       │
+                    │       ├─► store in inbox, track delivery
+                    │       ├─► route via its own MAP connection
+                    │       └─► write to inbox.jsonl for context injection
+                    │
+                    └─► Sidecar (fallback, if Agent Inbox unavailable)
+                            └─► direct MAP send (existing behavior)
+```
+
+### What Changes in claude-code-swarm
+
+**map-events.mjs** — the routing layer:
+
+1. `sendCommand()` gains routing logic: messaging commands (`send`, `emit`) go to Agent Inbox first, with fallback to sidecar
+2. `spawn`/`done` commands send a lightweight notification to Agent Inbox alongside the existing sidecar dispatch
+3. New `sendToInbox()` function (same UNIX socket IPC pattern as `sendToSidecar()`)
+
+```typescript
+// New: Agent Inbox UNIX socket client (same pattern as sidecar-client.mjs)
+export function sendToInbox(command, socketPath) {
+  return new Promise((resolve) => {
+    const client = net.createConnection(socketPath, () => {
+      client.write(JSON.stringify(command) + "\n");
+      client.end();
+      resolve(true);
+    });
+    client.on("error", () => resolve(false));
+    setTimeout(() => { client.destroy(); resolve(false); }, 500);
+  });
+}
+```
+
+**sidecar-server.mjs** — minimal changes:
+
+1. The `send` command handler becomes a fallback path (only used when Agent Inbox is unavailable)
+2. No bus client needed — the plugin handles routing
+
+**inbox.mjs** — minor change:
+
+1. `writeToInbox()` now receives richer data from Agent Inbox (message ID, conversation ID)
+2. `formatInboxAsMarkdown()` can display threading context
+
+**map-connection.mjs** — `connectToMAP()`'s `onMessage` handler becomes a fallback only. When Agent Inbox is active, incoming messages are received by Agent Inbox on its own MAP connection, stored, and written to `inbox.jsonl` directly.
+
+### What Stays the Same
+
+- Hook architecture (SessionStart, PreToolUse, PostToolUse, etc.)
+- UNIX socket IPC protocol (NDJSON over UNIX socket)
+- Native team primitives for in-process coordination
+- Sidecar process lifecycle (startup, stale cleanup, auto-terminate)
+- UserPromptSubmit injection pattern
+- Fire-and-forget fallback for broadcast-only operations
+
+### Graceful Degradation
+
+Agent Inbox is an enhancement, not a hard dependency. If it's unavailable, the plugin falls back to the sidecar for everything — the existing behavior:
+
+```typescript
+// In map-events.mjs — sendCommand() with graceful fallback
+export async function sendCommand(config, command, sessionId) {
+  if (command.action === "send" || command.action === "emit") {
+    // Try Agent Inbox first
+    const sent = await sendToInbox(command, inboxSocketPath(sessionId));
+    if (sent) return;
+    // Fall through to sidecar (existing behavior)
+  }
+
+  // Lifecycle commands → sidecar, or messaging fallback
+  const sPaths = sessionPaths(sessionId);
+  const sent = await sendToSidecar(command, sPaths.socketPath);
+  if (!sent) {
+    const recovered = await ensureSidecar(config, sessionId);
+    if (recovered) {
+      await sendToSidecar(command, sPaths.socketPath);
+    } else if (command.action === "emit") {
+      await fireAndForget(config, command.event);
+    }
+  }
+
+  // Notify Agent Inbox about lifecycle events (best-effort)
+  if (command.action === "spawn" || command.action === "done") {
+    sendToInbox(
+      { action: "notify", event: { type: `agent.${command.action}`, ...command } },
+      inboxSocketPath(sessionId)
+    ).catch(() => {}); // fire-and-forget notification
+  }
+}
+```
+
+### Multi-Session Support
+
+Multiple Claude Code sessions can run simultaneously, each with its own sidecar. All sessions' plugins dispatch messaging commands to the **same** Agent Inbox instance:
+
+```
+Session 1 Plugin ──┐
+                    ├──► Agent Inbox (shared)
+Session 2 Plugin ──┘
+
+Agent Inbox routes messages to the right agent regardless of which
+session originated them. The messageId + recipient agentId determine
+routing, not the session.
+```
+
+Each session's sidecar remains independent — handling only its own lifecycle events.
+
+---
+
+## Technology Stack
+
+| Component | Choice | Rationale |
+|-----------|--------|-----------|
+| Language | TypeScript | Same as claude-code-swarm and agentic-mesh; direct integration |
+| MAP Client | `@multi-agent-protocol/sdk` | Same SDK used by claude-code-swarm's sidecar |
+| MCP Server | `@modelcontextprotocol/sdk` | Standard MCP server for agent-facing tools |
+| Storage (default) | In-memory (Map/Array) | Zero-config, good for development and testing |
+| Storage (optional) | SQLite via `better-sqlite3` | Persistence, full-text search |
+| ID Generation | ULID | Sortable, unique, MAP convention |
+| IPC | UNIX socket (NDJSON) | Same protocol as sidecar; proven pattern |
+| Internal events | Node.js EventEmitter | In-process pub/sub for internal components |
+
+---
+
+## Storage Layer
+
+### Interface
+
+```typescript
+interface Storage {
+  // Agents
+  getAgent(agentId: string): Agent | undefined;
+  putAgent(agent: Agent): void;
+  listAgents(scope: string): Agent[];
+
+  // Messages
+  getMessage(id: string): Message | undefined;
+  putMessage(message: Message): void;
+  getInbox(agentId: string, opts?: { unreadOnly?: boolean }): Message[];
+  getThread(threadTag: string, scope: string): Message[];
+  searchMessages(query: string, scope: string): Message[];
+
+  // Conversations (traceability)
+  getConversation(id: string): Conversation | undefined;
+  putConversation(conversation: Conversation): void;
+  listConversations(scope: string): Conversation[];
+  addTurn(turn: Turn): void;
+  getTurns(conversationId: string): Turn[];
+}
+```
+
+### Implementations
+
+1. **InMemoryStorage** (default): Maps and arrays. Fast, zero-config. Data lost on restart. Good for development, testing, and ephemeral swarm sessions.
+
+2. **SQLiteStorage** (optional): Persistent storage with indexes and full-text search (FTS5). For long-running inbox instances or when message history matters.
+
+Both implement the same `Storage` interface — swap via configuration.
+
+---
+
+## Federation Model
+
+Federation is the primary use case. Agent Inbox acts as a **gateway agent** in MAP's federation model — connecting to MAP servers and peer Agent Inbox instances to route messages across system boundaries. Federation uses MAP's native `federation/connect` and `federation/route` protocol rather than inventing a parallel system.
+
+### MAP Federation Primitives
+
+Agent Inbox builds on MAP's existing federation spec:
+
+| MAP Federation Concept | Agent Inbox Role |
+|---|---|
+| Gateway agent | Agent Inbox instance (with routing logic) |
+| `federation/connect` | Connection Manager establishing peer links with auth + exposure |
+| `federation/route` / `federation/send` | Message Router forwarding to remote systems |
+| `MAPFederationExposure` | Trust policy controlling what agents are visible remotely |
+| `systemId` | Unique identity for each Agent Inbox instance |
+| `{ system, agent }` address | Federated addressing for cross-system routing |
+
+### System ID — Tiered Resolution
+
+Each Agent Inbox instance needs a stable `systemId` for federation. Resolved in order of precedence:
+
+```typescript
+function resolveSystemId(config: InboxConfig, mapSystemInfo?: SystemInfo): string {
+  if (config.systemId) return config.systemId;           // 1. Explicit config (INBOX_SYSTEM_ID)
+  if (mapSystemInfo?.name) return mapSystemInfo.name;     // 2. Derived from MAP server's systemInfo.name
+  return `inbox-${randomId(4)}`;                          // 3. Auto-generated fallback
+}
+```
+
+The MAP server's `map/connect` response includes `systemInfo?: { name?: string; version?: string }` which can provide the system identity when no explicit config is set.
+
+**Stability considerations:**
+- **Hub/federation mode**: Should require or strongly recommend explicit `systemId` — peers reference it in their config
+- **Local/standalone mode**: Auto-generated is fine since no one addresses it remotely
+- **Derived mode**: Stable as long as the MAP server's `systemInfo.name` is stable
+- **Persistence**: The resolved ID is persisted on first run so auto-generated IDs survive restarts
+
+### Agent Registry — Warm Model
+
+Agents are ephemeral (spun up/down frequently) but should be resilient to brief disconnections. The registry uses a **warm model** with TTL and grace period:
+
+```
+Agent connects       → status: "active"   (routable, fully live)
+Agent disconnects    → status: "away"     (still routable for grace period, messages queued)
+Grace period expires → status: "expired"  (not routable, retained for audit)
+Explicitly removed   → deleted from registry
+```
+
+**Configurable knobs:**
+
+```typescript
+interface AgentRegistryConfig {
+  gracePeriodMs: number;        // Time after disconnect before away → expired (default: 60000)
+  retainExpiredMs: number;      // How long to keep expired entries for audit (default: 3600000)
+  requeueOnReconnect: boolean;  // Flush queued messages when agent reconnects (default: true)
+}
+```
+
+**Federation implications** — when a peer asks "do you have agent-X?":
+- **"active"** → route immediately
+- **"away"** → accept the message, queue it, agent will likely reconnect
+- **"expired" / unknown** → reject with "not found" error
+
+Ephemerality is about **routability, not identity**. An agent's ID persists in the registry after disconnect — it just stops being a valid routing target after the grace period.
+
+**Self-registration**: Agents are auto-registered on their first `check_inbox` call, or via MAP spawn events or the `SessionStart` hook. First-wins on ID conflicts — if an ID is already taken by an active/away agent, the registration is rejected.
+
+### Addressing
+
+**String shorthand** (used in MCP tools):
+```
+agent-id              → local resolution only
+agent-id@system-id    → federated: route to specific system
+@system-id            → broadcast to all exposed agents on that system (or scope)
+```
+
+**Structured form** (used internally and in MAP federation messages):
+```typescript
+interface FederatedAddress {
+  system?: string;   // target system ID
+  agent?: string;    // target agent ID
+  scope?: string;    // optional scope qualifier
+}
+```
+
+**Resolution order:**
+1. **No `@`** → `"AgentB"` → find in local registry (same scope, then all scopes)
+2. **With `@`** → `"AgentB@backend-team"` → look up `backend-team` in connection manager, forward via `federation/route`
+3. **Explicit scope** → `"AgentB"` + `to_scope="backend"` → find in specified scope (local or remote)
+
+**Server connection mapping**: MAP server connections are identified by URL (`ws://host:port`). For federation, system aliases map to URLs via configuration:
+
+```typescript
+interface FederationPeerConfig {
+  systemId: string;         // human-friendly alias: "backend-team"
+  url: string;              // MAP server URL: "ws://10.0.1.5:3001"
+  auth?: FederationAuth;    // authentication for federation/connect
+  exposure?: ExposurePolicy; // what we expose to this peer
+}
+```
+
+### Connection Manager
+
+```typescript
+interface ConnectionManager {
+  // Connect to a MAP server (local or remote)
+  connect(serverUrl: string, opts: ConnectionOpts): Promise<MAPConnection>;
+
+  // Establish federation with a peer (uses MAP federation/connect)
+  federate(peer: FederationPeerConfig): Promise<FederationLink>;
+
+  // Route a message to the right connection
+  route(message: Message): Promise<DeliveryResult>;
+
+  // Resolve an agent address to a connection + agentId
+  resolve(address: string | FederatedAddress): ResolvedTarget | undefined;
+
+  // List all connections (MAP servers + federation peers)
+  connections(): ConnectionInfo[];
+
+  // List all federation peers
+  peers(): FederationPeer[];
+}
+
+interface FederationLink {
+  peerId: string;          // remote system ID
+  sessionId: string;       // federation session
+  status: 'connected' | 'disconnected' | 'authenticating';
+  exposure: ExposurePolicy; // what the remote exposes to us
+}
+```
+
+### Federation Topology
+
+Both hub and direct-peer topologies are supported — same code, different configuration.
+
+**Hub topology** (typical deployment — central router between swarms):
+
+```
+┌─────────────┐      ┌──────────────┐      ┌──────────────────┐
+│ Agent Team A │──────│ Agent Inbox  │──────│  Central Hub     │
+│ (MAP Server) │      │ (gateway)    │      │  Agent Inbox     │
+└─────────────┘      └──────────────┘      │  (router only,   │
+                                            │   no local agents)│
+┌─────────────┐      ┌──────────────┐      │                  │
+│ Agent Team B │──────│ Agent Inbox  │──────│                  │
+│ (MAP Server) │      │ (gateway)    │      └──────────────────┘
+└─────────────┘      └──────────────┘
+```
+
+Each team's Agent Inbox connects to its local MAP server and federates with the central hub. The hub has no local agents — it just routes between peers via `federation/route`.
+
+**Direct peer topology** (teams connect directly):
+
+```
+┌─────────────┐      ┌──────────────┐  federation/connect  ┌──────────────┐      ┌─────────────┐
+│ Agent Team A │──────│ Agent Inbox  │◄────────────────────►│ Agent Inbox  │──────│ Agent Team B │
+│ (MAP Server) │      │ (gateway)    │                      │ (gateway)    │      │ (MAP Server) │
+└─────────────┘      └──────────────┘                      └──────────────┘      └─────────────┘
+```
+
+Same Agent Inbox code. The difference is only in the federation peer config:
+- **Hub mode**: Each edge inbox has one peer (the hub). The hub has N peers (the edges).
+- **Peer mode**: Each inbox federates directly with the others it needs to talk to.
+
+The addressing format `agent-id@system-id` works identically in both topologies — the connection manager resolves `system-id` to whichever peer holds that system, whether it's a direct link or a hub that will relay.
+
+### Routing Engine
+
+The routing engine determines how to deliver messages to agents on unknown or disconnected peers. Strategy is configurable:
+
+```typescript
+interface FederationRoutingConfig {
+  strategy: 'table' | 'broadcast' | 'hierarchical';
+
+  // For 'table' strategy (default)
+  tableTTL?: number;           // how long routing entries live in ms (default: 300000)
+  refreshOnMiss?: boolean;     // re-query peers on cache miss before failing (default: true)
+
+  // For 'broadcast' strategy
+  broadcastTimeout?: number;   // ms to wait for first responder (default: 5000)
+
+  // For 'hierarchical' strategy
+  upstream?: string[];         // system IDs of upstream hubs to delegate to
+}
+```
+
+| Strategy | Behavior | Best for |
+|---|---|---|
+| **`table`** | Maintain in-memory routing table from `federation/connect` exposure data. Route to known agents. On miss, optionally query peers. | Default — fast, predictable |
+| **`broadcast`** | Forward to all connected peers, first responder wins. | Small clusters, highly dynamic agents |
+| **`hierarchical`** | Check local table first, then delegate to upstream hub(s) if unknown. | Multi-tier topologies |
+
+**Routing table population**: When `federation/connect` completes, the peer's exposure policy advertises available agents/scopes. The gateway stores this as an in-memory routing table:
+
+```
+routing table (in-memory, short-lived):
+  "agent-alpha" → peer "backend-team" (last seen: 2s ago, status: active)
+  "agent-beta"  → peer "backend-team" (last seen: 2s ago, status: active)
+  "agent-gamma" → peer "ml-team"      (last seen: 15s ago, status: away)
+```
+
+Entries expire after `tableTTL`. Refreshed passively (peer sends updated exposure) or actively (on-miss query or periodic poll). Short-lived agents naturally age out.
+
+### Delivery Queue
+
+Messages to offline or unreachable peers are queued for later delivery. All parameters are configurable:
+
+```typescript
+interface DeliveryQueueConfig {
+  persistence: 'memory' | 'sqlite';     // where to buffer (default: 'memory')
+  maxTTL: number;                        // max age before dropping in ms (default: 86400000 / 24h)
+  maxQueueSize: number;                  // max messages per destination (default: 10000)
+  retryStrategy: 'exponential' | 'fixed'; // retry pattern (default: 'exponential')
+  retryBaseInterval: number;             // base retry interval in ms (default: 1000)
+  retryMaxAttempts: number;              // max retries, 0 = unlimited until TTL (default: 0)
+  flushOnReconnect: boolean;             // drain queue when connection restored (default: true)
+  overflow: 'drop-oldest' | 'drop-newest' | 'reject-new'; // when queue is full (default: 'drop-oldest')
+}
+```
+
+Follows MAP's federation failure handling spec: configurable queue duration, size, and overflow policy.
+
+### Trust Policies
+
+Trust policies control federation access. All layers are supported; complexity can be deferred by starting with allow-list only and stubbing the rest.
+
+```typescript
+interface FederationTrustPolicy {
+  // Layer 1: Server allow-list (implemented first)
+  allowedServers: string[];              // system IDs or URLs allowed to connect
+
+  // Layer 2: Scope-based permissions (stub initially)
+  scopePermissions: Record<string, string[]>; // local scope → allowed remote scopes
+
+  // Layer 3: Token-based auth (stub initially)
+  requireAuth: boolean;                  // require tokens for cross-server delivery
+  authMethod?: 'bearer' | 'api-key' | 'mtls' | 'did:wba'; // MAP-supported auth methods
+  authTokens?: Record<string, string>;   // system ID → token
+}
+```
+
+**Exposure control** follows MAP's `MAPFederationExposure` model:
+- **`none`**: No agents visible to this peer
+- **`gateway`**: Only the gateway agent (Agent Inbox itself) is visible — peers must address messages explicitly
+- **`tagged`**: Only agents with specific tags/scopes are visible
+- **`all`**: All registered agents are visible to this peer
+
+### Cross-Server Conversation Ownership
+
+Each side maintains its own view. When Agent Inbox A forwards a message to Agent Inbox B:
+
+1. A stores the outbound message in its local storage
+2. B receives it via `federation/route` and stores it in its own local storage
+3. Each side tracks `in_reply_to` chains, threads, and conversations independently
+4. No sync protocol or CRDT needed
+
+Trade-off: no global "conversation view" across servers. Each system sees its own perspective. This is acceptable for agent-to-agent messaging and avoids sync complexity.
+
+---
+
+## Implementation Plan
+
+### Phase 1: Core Messaging + Single MAP Connection
+
+- TypeScript project setup
+- Storage interface + InMemoryStorage
+- Agent registry (backed by MAP identity)
+- Message send/receive/reply with inbox tracking
+- Thread tags (user-defined grouping)
+- Single MAP server connection
+- UNIX socket IPC server (same NDJSON protocol as sidecar)
+- MCP tools: `send_message`, `check_inbox`, `read_thread`, `list_agents`
+- Internal EventEmitter for component coordination
+- Basic traceability (auto-create conversations from thread_tags)
+
+### Phase 2: Traceability + MAP Mail
+
+- Full traceability layer: conversations, turns, threads
+- MAP JSON-RPC endpoint (`mail/*` methods)
+- MAP mail auto-grouping (conversationId, thread_tag fallback, catch-all)
+- `map/subscribe` for real-time event streaming
+- SQLiteStorage implementation
+- Full-text search
+
+### Phase 3: Federation + Multi-Server
+
+**3a: Core Federation Infrastructure**
+- System ID tiered resolution (config → MAP systemInfo → auto-generated)
+- Agent registry warm model (active/away/expired with configurable grace period)
+- Federated addressing: `agent-id@system-id` string shorthand + `{ system, agent, scope }` structured form
+- Self-registration with first-wins ID conflict resolution
+- Connection Manager: connect to multiple MAP servers + federation peers
+- Implement MAP `federation/connect` handshake (auth, exposure exchange)
+- Implement MAP `federation/route` / `federation/send` for cross-system messaging
+
+**3b: Routing + Delivery**
+- Routing engine with configurable strategy (`table` / `broadcast` / `hierarchical`)
+- In-memory routing table populated from federation exposure data (with TTL)
+- Delivery queue for offline peers (configurable persistence, TTL, overflow, retry)
+- Flush-on-reconnect for queued messages
+- Cross-server conversation ownership: each side maintains its own view
+
+**3c: Topology + Trust**
+- Hub topology support (central router Agent Inbox with no local agents)
+- Direct peer topology support (Agent Inbox ↔ Agent Inbox federation)
+- Trust policies: server allow-list (implemented), scope permissions + token auth (stubbed)
+- Exposure control following MAP's model (`none` / `gateway` / `tagged` / `all`)
+
+**Deferred: agentic-mesh integration** — kept in plans as optional transport layer, but not in Phase 3 scope
+
+---
+
+## Key Design Decisions
+
+### 1. Plugin-as-router (no event bus)
+
+The claude-code-swarm plugin (`map-events.mjs`) already dispatches commands by type. Rather than introducing a separate event bus for sidecar ↔ Agent Inbox coordination, the plugin routes directly: lifecycle commands to the sidecar, messaging commands to Agent Inbox. This eliminates an entire infrastructure layer (bus socket, pub/sub protocol, subscription management, bus lifecycle) while achieving the same routing outcome. Agent Inbox learns about agent lifecycle via lightweight notifications from the plugin, not bus subscriptions.
+
+### 2. Concern-based MAP connection split
+
+The sidecar and Agent Inbox each own their MAP connection(s) for their respective domains. The sidecar's connection handles lifecycle and observability (spawn, state, trajectory) — fire-and-forget traffic. Agent Inbox's connection(s) handle messaging and mail — tracked, routed delivery. This avoids routing unrelated traffic through either system. Agent Inbox also works standalone without a sidecar.
+
+### 3. MAP-native, not a parallel system
+
+Agent Inbox builds on MAP rather than reimplementing transport and identity. MAP servers handle the "pipe" — Agent Inbox adds inbox semantics, threading, and routing on top.
+
+### 4. Federation as primary concern
+
+Cross-process and cross-server messaging is the reason Agent Inbox exists. Local in-process coordination (SendMessage, TaskCreate) already works in claude-code-swarm. Agent Inbox adds the cross-boundary layer.
+
+### 5. Graceful degradation
+
+The plugin falls back to the sidecar for messaging if Agent Inbox is unavailable. Agent Inbox is an enhancement, not a hard dependency. This preserves the sidecar's existing reliability guarantees.
+
+### 6. Structured content with plain-text shorthand
+
+Messages store structured content (typed with schema), but MCP tools accept plain markdown for convenience. The service layer wraps simple text; agents can pass full structured content when they need machine-readable payloads.
+
+### 7. Traceability follows MAP mail conventions
+
+Conversations, turns, and threads are created automatically from messaging events following MAP's conventions. Agents can also create them explicitly. The traceability layer observes and records — it never blocks messaging.
+
+### 8. Identity delegated to MAP + client
+
+Agent Inbox uses MAP's `agentId` as the primary identity. Persistence is the client's responsibility — reconnect with the same ID to reclaim your inbox, or don't. The inbox doesn't enforce a persistence model.
+
+### 9. Storage is pluggable
+
+In-memory for development and ephemeral sessions. SQLite for persistence. Same interface, swap via config.
+
+### 10. TypeScript for ecosystem alignment
+
+Same language as claude-code-swarm, agentic-mesh, and the MAP SDK. Direct integration without language bridges or sidecars.
+
+---
+
+## Open Questions
+
+### Resolved
+
+1. ~~**Sidecar integration depth**~~: **Resolved — plugin-as-router.** The plugin layer dispatches lifecycle commands to the sidecar and messaging commands to Agent Inbox. No event bus needed. The sidecar owns lifecycle; Agent Inbox owns messaging. See Architecture Overview.
+
+2. ~~**File reservations**~~: **Deferred — not in scope.** File reservation support removed from current design.
+
+3. ~~**REST/SSE interface**~~: **Dropped.** Only MCP Tools + MAP JSON-RPC interfaces.
+
+4. ~~**Identity model**~~: **Resolved — use MAP identity primitives.** `agentId` + scopes. Persistence left to clients.
+
+5. ~~**Traceability auto-grouping**~~: **Resolved — follow MAP conventions.** Messages with `conversationId` go there; without, server groups by `thread_tag`/reply chain; catch-all for untagged.
+
+6. ~~**Event deduplication**~~: **Resolved — concern-based split eliminates the problem.** The sidecar handles lifecycle via its MAP connection; Agent Inbox handles messaging via its own MAP connection. No duplicate paths since each system only touches its own concern.
+
+7. ~~**Event bus architecture**~~: **Resolved — eliminated.** The plugin already routes by command type, making a dedicated bus unnecessary. Agent Inbox learns about agents via plugin notifications and MAP server queries.
+
+### Open
+
+1. **MCP notification support**: Can we push new messages to agents, or must they poll with `check_inbox`? For now, poll-only for agents; real-time for MAP JSON-RPC clients via `map/subscribe`.
+
+2. **MAP server dependency**: Should Agent Inbox run without a MAP server (embedded mode for testing/dev), or always require at least one?
+
+3. ~~**Cross-server conversation ownership**~~: **Resolved — each side maintains its own view.** When a message crosses federation boundaries, both the sending and receiving Agent Inbox instances store their own copy. Each side tracks threads, conversations, and reply chains independently. No sync protocol needed.
+
+4. **Message format evolution**: Should `x-*` extension content types be registered/discoverable, or purely convention-based?
+
+5. **Startup ordering**: If the plugin sends a messaging command before Agent Inbox is ready, it falls back to the sidecar. Should Agent Inbox replay missed messages from the MAP server on startup?
+
+6. **Transitive federation routing**: If system A is federated with hub H, and system B is also federated with H, can A send to B through H? The hierarchical routing strategy supports this, but the trust implications need further thought.
+
+7. **Federation discovery**: MAP spec mentions `.well-known` discovery and `did:wba` for domain-anchored identity. Should Agent Inbox support automatic peer discovery, or require explicit configuration? For now, explicit config only.