claude-code-swarm 0.3.4 → 0.3.5

package/e2e/vitest.config.e2e.mjs

@@ -12,7 +12,7 @@ export default defineConfig({
     maxForks: 1,
     server: {
       deps: {
-        external: ["openteams"],
+        external: ["openteams", "agent-inbox", "@multi-agent-protocol/sdk"],
       },
     },
   },

package/hooks/hooks.json

@@ -22,24 +22,31 @@
         ]
       }
     ],
-    "PreToolUse": [
+    "PostToolUse": [
       {
-        "matcher": "Task",
+        "matcher": "opentasks",
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" agent-spawning; fi"
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit((c.opentasks?.enabled||process.env.SWARM_OPENTASKS_ENABLED)&&(c.map?.enabled||c.map?.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED)?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" opentasks-mcp-used; fi"
           }
         ]
-      }
-    ],
-    "PostToolUse": [
+      },
+      {
+        "matcher": "TaskCreate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" native-task-created; fi"
+          }
+        ]
+      },
       {
-        "matcher": "Task",
+        "matcher": "TaskUpdate",
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" agent-completed; fi"
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" native-task-updated; fi"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {
@@ -18,15 +18,24 @@
     "swarm-generate-agents": "./scripts/generate-agents.mjs"
   },
   "dependencies": {
+    "agentic-mesh": "^0.2.0",
     "js-yaml": "^4.1.0"
   },
   "peerDependencies": {
     "@multi-agent-protocol/sdk": "*",
+    "agent-inbox": "*",
+    "opentasks": "*",
     "swarmkit": "*"
   },
   "peerDependenciesMeta": {
     "@multi-agent-protocol/sdk": {
       "optional": true
+    },
+    "agent-inbox": {
+      "optional": true
+    },
+    "opentasks": {
+      "optional": true
     }
   },
   "scripts": {
@@ -37,6 +46,7 @@
     "test:e2e:tier2": "vitest run --config e2e/vitest.config.e2e.mjs -t tier2",
     "test:e2e:tier3": "vitest run --config e2e/vitest.config.e2e.mjs -t tier3",
     "test:e2e:tier4": "vitest run --config e2e/vitest.config.e2e.mjs -t tier4",
+    "test:e2e:tier5": "vitest run --config e2e/vitest.config.e2e.mjs -t tier5",
     "version:patch": "npm version patch --no-git-tag-version && node scripts/sync-version.mjs",
     "version:minor": "npm version minor --no-git-tag-version && node scripts/sync-version.mjs",
     "version:major": "npm version major --no-git-tag-version && node scripts/sync-version.mjs"
@@ -45,6 +55,8 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
+    "@multi-agent-protocol/sdk": "^0.1.4",
+    "agent-inbox": "^0.1.7",
     "vitest": "^4.0.18",
     "ws": "^8.0.0"
   }

package/references/agent-inbox/CLAUDE.md

@@ -0,0 +1,151 @@
+# CLAUDE.md — Agent Guide for agent-inbox
+
+## What this repo is
+
+Agent Inbox is a MAP-native message router for multi-agent systems. It provides structured inbox/outbox semantics, threading, delivery tracking, and cross-system federation on top of MAP (Multi-Agent Protocol) transport.
+
+## Build and test
+
+```bash
+npm install           # Install dependencies
+npm run build         # TypeScript compile (tsc)
+npm test              # Run all tests (vitest)
+npm run test:watch    # Watch mode
+```
+
+All tests use vitest. Run the full suite before committing — there are 356 tests across 27 files. Tests run fast (<6s total).
+
+## Project layout
+
+```
+src/
+  index.ts                      Entry point — wires storage, router, federation, IPC, MCP, MAP
+  types.ts                      All type definitions (Message, Agent, Federation types, etc.)
+  storage/interface.ts          Storage interface (getAgent, putMessage, getInbox, etc.)
+  storage/memory.ts             InMemoryStorage — Map-based, used in all tests
+  storage/sqlite.ts             SQLiteStorage — persistent with FTS5 search
+  router/message-router.ts      Core routing: resolveRecipients, normalizeContent, routeMessage
+  federation/
+    connection-manager.ts       Manages MAP connections + federation peer links + queue flush
+    routing-engine.ts           Table/broadcast/hierarchical routing strategies
+    delivery-queue.ts           Offline message queue with TTL, retry, overflow policies
+    address.ts                  Parse "agent@system" addresses (parseAddress, isRemoteAddress)
+    trust.ts                    Allow-list federation trust (canConnect, canRoute stubs)
+  registry/warm-registry.ts     Agent lifecycle: active → away → expired with TTL timers
+  traceability/traceability.ts  Auto-create conversations/turns/threads from message events
+  ipc/ipc-server.ts             UNIX socket server (NDJSON protocol)
+  map/map-client.ts             MAP SDK wrapper (dynamic import, optional peer dependency)
+  mcp/mcp-server.ts             MCP tool server (send_message, check_inbox, read_thread, list_agents)
+  jsonrpc/mail-server.ts        MAP JSON-RPC mail methods
+  push/notifier.ts              Inbox file writes + inbox.message event emission
+  mesh/
+    mesh-transport.ts           MapConnection impl over agentic-mesh MessageChannel
+    mesh-connector.ts           Factory for creating MeshTransport connections (MapAgentConnectionClass)
+    delivery-bridge.ts          DeliveryHandler bridge — intercepts MAP delivery → inbox storage
+    type-mapper.ts              MAP Message ↔ Inbox Message bidirectional translation
+
+test/
+  federation/                   Federation tests (connection-manager, routing, queue, address, trust, integration, sdk-integration)
+  mesh/                         Mesh transport tests (mesh-transport, mesh-connector, federation-mesh, delivery-bridge, type-mapper, meshpeer-integration, e2e)
+  registry/                     Warm registry tests
+  *.test.ts                     Core tests (storage, router, traceability, IPC, mail-server, push)
+
+docs/
+  CLAUDE-CODE-SWARM-PROPOSAL.md   Proposal: replace claude-code-swarm's sidecar with embedded MeshPeer + agent-inbox
+```
+
+## Key architecture concepts
+
+### Message flow
+
+1. Message comes in via IPC socket, MCP tool, MAP connection, or MeshPeer delivery
+2. `MessageRouter.routeMessage()` resolves recipients, normalizes content, stores the message
+3. Local recipients: message stored in their inbox via storage
+4. Remote recipients (`agent@system`): delegated to `ConnectionManager.route()`
+5. Federation sends via FederationGateway (mesh), MAP SDK (WebSocket), or queues if peer is offline
+6. Traceability layer auto-creates conversations/threads from events
+
+### Federation addressing
+
+- `"bob"` — local agent
+- `"bob@system-2"` — agent on a federated system
+- `"@system-2"` — broadcast to system
+
+Parsed by `parseAddress()` in `src/federation/address.ts`.
+
+### Federation transports
+
+Two federation transport options, configurable per-peer:
+
+**WebSocket (MAP SDK):** Traditional MAP federation over WebSocket. Configure with `FederationPeerConfig.url`.
+
+**Mesh (agentic-mesh):** Encrypted P2P federation over agentic-mesh. Two integration levels:
+
+- **Phase 1 (raw channel):** `MeshTransport` wraps a `MessageChannel` behind `MapConnection`. Configure with `CreateOptions.mesh` + `FederationPeerConfig.meshPeerId`. Uses channel name `"proto:agent-inbox"`.
+
+- **Phase 2 (full MeshPeer):** Agent-inbox registers as an agent on the MeshPeer's MapServer. Uses `FederationGateway` for cross-mesh routing with envelope wrapping, hop counting, and loop detection. `DeliveryBridge` intercepts MAP message delivery → inbox storage. Configure with `CreateOptions.meshPeer`.
+
+Both transports can coexist — configure per-peer via `url` vs `meshPeerId`.
+
+### Storage interface
+
+All storage operations go through `Storage` interface (`src/storage/interface.ts`). Two implementations: `InMemoryStorage` (tests + ephemeral) and `SQLiteStorage` (persistent). Tests always use `InMemoryStorage`.
+
+### MAP SDK is optional
+
+The `@multi-agent-protocol/sdk` is a peer dependency loaded dynamically in `src/map/map-client.ts`. Agent Inbox works without it (IPC + MCP only, no MAP transport). The SDK class is injected into `ConnectionManager` when available.
+
+### Mesh transport (agentic-mesh) is optional
+
+[agentic-mesh](https://github.com/alexngai/agentic-mesh) is an optional peer dependency for encrypted P2P federation. When a `MeshPeer` is provided via `CreateOptions.meshPeer`, agent-inbox gets:
+
+- Direct P2P federation (no central MAP server required)
+- Encrypted tunnels (Nebula/Tailscale handle PKI and NAT traversal)
+- Federation with hop/loop detection via `FederationGateway`
+- Automatic agent discovery via MapServer registry
+- `_meta` field passthrough for inbox semantics (threading, importance, subjects)
+
+Key mesh components:
+- `MeshTransport` (`src/mesh/mesh-transport.ts`) — `MapConnection` over `MessageChannel`
+- `MeshConnector` (`src/mesh/mesh-connector.ts`) — factory implementing `MapAgentConnectionClass`
+- `DeliveryBridge` (`src/mesh/delivery-bridge.ts`) — intercepts MAP delivery for inbox storage
+- `TypeMapper` (`src/mesh/type-mapper.ts`) — bidirectional MAP ↔ Inbox message translation
+
+### Event-driven internals
+
+Components communicate via `EventEmitter`. Key events:
+- `message.created` — emitted by router, consumed by traceability and notifier
+- `inbox.message` — emitted per-recipient by notifier `{ agentId, recipientKind, message }`. Clients subscribe to implement delivery strategy.
+- `federation.route` — emitted when no transport, for testing
+- `federation.message.received` — incoming federation message
+- `federation.broadcast` — broadcast strategy fired
+- `routing.updated` — routing table changed
+
+## Conventions
+
+- **TypeScript strict mode**, ESM output
+- **vitest** for all tests — no jest
+- **No mocking frameworks** — tests use hand-rolled mocks and the `InMemoryStorage` directly
+- IDs generated with `ulid` or `crypto.randomUUID()`
+- Content normalization: string payloads auto-wrapped to `{ type: "text", text: "..." }`
+- Federation tests use `MockMapServer` (in-process broker) in `test/federation/sdk-integration.test.ts`
+- Mesh tests use `MockMeshContext` (linked pair) in `test/mesh/mock-mesh.ts`
+- Mesh channel name convention: protocol channels use `"proto:"` prefix (e.g., `"proto:agent-inbox"`)
+
+## Common tasks
+
+### Adding a new MCP tool
+1. Add tool definition in `src/mcp/mcp-server.ts`
+2. Implement handler that delegates to router/storage
+3. Add test in `test/` (currently no dedicated mcp test file — tools tested through integration)
+
+### Adding a new federation feature
+1. Types go in `src/types.ts`
+2. Logic in `src/federation/` (connection-manager, routing-engine, etc.)
+3. Unit test in `test/federation/`
+4. Integration test in `test/federation/integration.test.ts` or `test/federation/sdk-integration.test.ts`
+
+### Adding a new storage method
+1. Add to interface in `src/storage/interface.ts`
+2. Implement in both `memory.ts` and `sqlite.ts`
+3. Test in `test/storage.test.ts` and `test/sqlite-storage.test.ts`

package/references/agent-inbox/README.md

@@ -0,0 +1,238 @@
+# Agent Inbox
+
+A MAP-native message router for multi-agent systems. Provides structured inbox/outbox semantics, message threading, delivery tracking, and cross-system federation on top of the [Multi-Agent Protocol](https://github.com/anthropics/multi-agent-protocol) transport layer.
+
+Built to work with [claude-code-swarm](https://github.com/alexngai/claude-code-swarm) and any MAP-compatible agent framework. Optionally integrates with [agentic-mesh](https://github.com/alexngai/agentic-mesh) for encrypted P2P federation.
+
+## What it does
+
+- **Message routing** — Send messages between agents with `to`, `cc`, `bcc` semantics. Messages are stored in per-agent inboxes with delivery and read tracking.
+- **Threading** — Messages can be grouped by `thread_tag` and linked via `in_reply_to` for conversation threading.
+- **Traceability** — Auto-creates conversations, turns, and threads from messaging events following MAP's mail conventions.
+- **Federation** — Route messages across independent systems. Supports WebSocket (MAP SDK) and encrypted P2P mesh (agentic-mesh) transports, configurable per-peer. Routing strategies: table, broadcast, hierarchical.
+- **Multiple interfaces** — IPC (UNIX socket), MCP tools (stdio), MAP JSON-RPC, and event-based push via `inbox.message` events.
+
+## Architecture
+
+```
+Agent Runtime (Claude Code, OpenAI, etc.)
+  │
+  Adapter (~200 lines)
+  │
+  └── agent-inbox (routing, threading, storage, MCP tools)
+        │
+        ├── Local delivery (same system)
+        ├── Federation via MAP SDK (WebSocket)
+        └── Federation via agentic-mesh (encrypted P2P)
+              │
+              MeshPeer (MAP server, FederationGateway,
+                        agent discovery, hop/loop detection)
+```
+
+Agent Inbox can run standalone (IPC + MCP only), with a MAP server (WebSocket federation), or with an embedded agentic-mesh `MeshPeer` (encrypted P2P federation with full MAP protocol support).
+
+## Quick start
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `INBOX_SOCKET_PATH` | `~/.claude/agent-inbox/inbox.sock` | IPC socket path |
+| `INBOX_SCOPE` | `default` | Default message scope |
+| `INBOX_SYSTEM_ID` | auto-generated | System identity for federation |
+| `INBOX_MAP_ENABLED` | `false` | Enable MAP server connection |
+| `INBOX_MAP_SERVER` | — | MAP server URL |
+| `INBOX_SQLITE_PATH` | — | SQLite database path (enables persistent storage) |
+| `INBOX_HTTP_PORT` | `0` | HTTP port for JSON-RPC endpoint |
+
+### As an MCP tool server
+
+Agent Inbox exposes 4 MCP tools that agents can call directly:
+
+| Tool | Description |
+|------|-------------|
+| `send_message` | Send a message to one or more agents (supports replies via `inReplyTo`) |
+| `check_inbox` | Check an agent's inbox for unread messages (auto-registers the agent) |
+| `read_thread` | Read all messages in a thread by `threadTag` |
+| `list_agents` | List registered agents (local and optionally federated) |
+
+```bash
+# Run in MCP mode (stdio transport for Claude Code integration)
+npm start -- mcp
+```
+
+### IPC protocol
+
+NDJSON over UNIX socket. Commands:
+
+```json
+{"action": "send", "from": "alice", "to": "bob", "payload": "Hello"}
+{"action": "notify", "event": {"type": "agent.spawn", "agent": {...}}}
+{"action": "ping"}
+```
+
+### MAP JSON-RPC
+
+When connected to a MAP server, Agent Inbox registers JSON-RPC methods:
+
+- `mail/send` — Send a message
+- `mail/inbox` — Check inbox
+- `mail/thread` — Read a thread
+- `mail/ack` — Acknowledge a message
+- `mail/search` — Full-text search (requires SQLite storage)
+
+## Federation
+
+Agents on different systems can message each other using `agent@system` addressing:
+
+```
+alice@system-1  -->  bob@system-2
+```
+
+### Transports
+
+Two federation transport options, configurable per-peer:
+
+**WebSocket (MAP SDK)** — Traditional MAP federation. Requires a reachable MAP server endpoint.
+
+```typescript
+await createAgentInbox({
+  enableFederation: true,
+  config: {
+    federation: {
+      peers: [{ systemId: "partner", url: "ws://partner:3001" }]
+    }
+  }
+});
+```
+
+**Mesh (agentic-mesh)** — Encrypted P2P federation via Nebula/Tailscale tunnels. No central server required. Provides hop/loop detection, message buffering, and automatic agent discovery.
+
+```typescript
+import { MeshPeer } from "agentic-mesh";
+
+const peer = MeshPeer.createEmbedded({ peerId: "my-system" });
+await peer.start();
+
+await createAgentInbox({
+  meshPeer: peer,
+  enableFederation: true,
+  config: {
+    federation: {
+      peers: [{ systemId: "partner", meshPeerId: "partner-peer" }]
+    }
+  }
+});
+```
+
+Both transports can coexist — some peers use WebSocket, others use mesh.
+
+### Routing strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `table` (default) | In-memory routing table populated from peer exposure data. TTL-based expiry. |
+| `broadcast` | Forward to all connected peers. First responder wins. |
+| `hierarchical` | Local table first, then delegate to upstream hubs. Works with system-qualified addresses for indirect relay. |
+
+### Trust
+
+Federation connections are gated by an allow-list. Only systems in `allowedServers` can establish federation links.
+
+### Delivery queue
+
+Messages to offline peers are queued with configurable TTL, overflow policy, and retry strategy. Queues flush automatically on reconnect.
+
+## Storage
+
+Two storage backends:
+
+- **InMemoryStorage** — Default. Fast, no dependencies. Data lost on restart.
+- **SQLiteStorage** — Persistent storage with FTS5 full-text search. Requires `better-sqlite3`.
+
+## Project structure
+
+```
+src/
+  index.ts                      Entry point — wires all components
+  types.ts                      Core type definitions
+  storage/
+    interface.ts                Storage interface
+    memory.ts                   In-memory implementation
+    sqlite.ts                   SQLite implementation (persistent + FTS5)
+  router/
+    message-router.ts           Message routing: resolve recipients, local vs remote
+  federation/
+    connection-manager.ts       MAP connections + federation peer management
+    routing-engine.ts           Configurable routing (table/broadcast/hierarchical)
+    delivery-queue.ts           Offline message queue with TTL + retry
+    address.ts                  Parse/resolve agent@system addresses
+    trust.ts                    Federation trust policies (allow-list)
+  registry/
+    warm-registry.ts            Agent lifecycle: active/away/expired + TTL
+  traceability/
+    traceability.ts             Auto-create conversations/turns/threads
+  ipc/
+    ipc-server.ts               UNIX socket server (NDJSON protocol)
+  map/
+    map-client.ts               MAP SDK connection wrapper
+  mcp/
+    mcp-server.ts               MCP tool server (stdio transport)
+  jsonrpc/
+    mail-server.ts              MAP JSON-RPC mail methods
+  push/
+    notifier.ts                 Inbox file writes + inbox.message event emission
+  mesh/
+    mesh-transport.ts           MapConnection impl over agentic-mesh MessageChannel
+    mesh-connector.ts           Factory for MeshTransport connections
+    delivery-bridge.ts          DeliveryHandler bridge (MAP delivery → inbox storage)
+    type-mapper.ts              Bidirectional MAP ↔ Inbox message translation
+```
+
+## Testing
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+```
+
+357 tests across 27 test files covering:
+
+- Storage (in-memory + SQLite)
+- Message routing and content normalization
+- Traceability (auto-conversation/thread creation)
+- IPC server (NDJSON protocol, concurrent clients)
+- Federation (connection manager, routing engine, delivery queue, address parsing, trust)
+- Federation integration (end-to-end multi-system scenarios)
+- SDK integration (two-system tests with in-process mock MAP server)
+- MAP JSON-RPC mail methods
+- Warm agent registry lifecycle
+- Push model (inbox.message events + inbox file writes)
+- Mesh transport (MeshTransport, MeshConnector, federation-mesh integration)
+- Mesh Phase 2 (DeliveryBridge, TypeMapper, MeshPeer integration)
+- E2E with real agentic-mesh MeshPeer instances (bidirectional messaging, reply chains, concurrent load)
+
+## Development
+
+```bash
+npm run dev           # TypeScript watch mode
+npm test              # Run tests
+npm run build         # Production build
+```
+
+Requires Node.js >= 18.
+
+## Further reading
+
+- [docs/DESIGN.md](docs/DESIGN.md) — Detailed architecture and design decisions
+- [docs/CLAUDE-CODE-SWARM-PROPOSAL.md](docs/CLAUDE-CODE-SWARM-PROPOSAL.md) — Proposal: replace claude-code-swarm's sidecar with embedded MeshPeer + agent-inbox
+
+## License
+
+MIT

package/references/agent-inbox/docs/CLAUDE-CODE-SWARM-PROPOSAL.md

@@ -0,0 +1,137 @@
+# claude-code-swarm Migration Proposal: Embedded MeshPeer + agent-inbox
+
+**Author:** agent-inbox team
+**Date:** 2026-03-16
+**Status:** Proposal
+**Context:** agent-inbox has completed full agentic-mesh integration (Phase 1 + Phase 2). This document proposes migrating claude-code-swarm from its custom WebSocket sidecar to the shared agent-inbox + agentic-mesh stack.
+
+---
+
+## The Problem: Per-Agent-Runtime Reimplementation
+
+claude-code-swarm currently uses a custom WebSocket sidecar (~1500 lines) tightly coupled to Claude Code's hook system. It handles MAP connections, agent registration, and message routing. If we want to support a different agent runtime (e.g., OpenAI-based agents, AutoGen, standalone scripts), we'd have to reimplement the sidecar each time.
+
+## The Solution: Three-Layer Architecture
+
+```
+┌────────────────────────────────────────────────┐
+│  Agent-Specific Adapter  (~200 lines)          │
+│  (Claude Code hooks, or OpenAI plugin, etc.)   │
+├────────────────────────────────────────────────┤
+│  agent-inbox                                   │
+│  (inbox/outbox, threading, traceability, MCP)  │
+├────────────────────────────────────────────────┤
+│  agentic-mesh (MeshPeer)                       │
+│  (transport, encryption, MAP protocol,         │
+│   federation, discovery, CRDT sync)            │
+└────────────────────────────────────────────────┘
+```
+
+**agentic-mesh is the layer every agent shares.** It handles networking, encryption, peer discovery, and MAP protocol once. agent-inbox adds structured messaging on top. The per-agent adapter is just lifecycle translation (~200 lines).
+
+## What's Ready Today
+
+### agent-inbox + agentic-mesh integration (complete)
+
+| Capability | Status |
+|-----------|--------|
+| P2P message delivery over encrypted mesh | Working |
+| Offline queuing (both layers) | Working |
+| Agent discovery via MapServer registry | Working |
+| Full MAP scoped addressing | Working |
+| Federation with hop/loop detection | Working (FederationGateway) |
+| `_meta` field passthrough (threading, importance, subjects) | Verified end-to-end |
+| DeliveryHandler bridge (MAP → inbox storage) | Working |
+| MAP ↔ Inbox type translation | Working (18 tests) |
+| E2E with real MeshPeer instances | 13 tests passing |
+| Total mesh-related tests | 85 tests, all passing |
+
+### How agent-inbox consumes MeshPeer
+
+```typescript
+const inbox = await createAgentInbox({
+  meshPeer: myMeshPeer,  // Embedded MeshPeer, full MAP protocol
+  enableFederation: true,
+  config: {
+    federation: {
+      peers: [
+        { systemId: "system-b", meshPeerId: "system-b" }
+      ]
+    }
+  }
+});
+```
+
+This single call:
+1. Registers `agent-inbox` as an agent on the MeshPeer's MapServer
+2. Installs a `DeliveryBridge` to intercept MAP message delivery → inbox storage
+3. Wires `FederationGateway` for cross-mesh routing with envelope wrapping and loop detection
+4. Sets up all inbox semantics (threading, read tracking, traceability)
+
+## Proposed Migration Path for claude-code-swarm
+
+### Step 1: Replace the sidecar with embedded MeshPeer + agent-inbox
+
+The current sidecar handles:
+- MAP WebSocket connection management
+- Agent registration on connect/disconnect
+- Message routing between agents
+- Hook-based lifecycle (agent spawn/done events)
+
+All of these are now handled by MeshPeer + agent-inbox. The sidecar reduces to a thin adapter that:
+- Creates an embedded `MeshPeer` on startup
+- Passes it to `createAgentInbox({ meshPeer })`
+- Translates Claude Code hook events (agent spawn/done) into agent-inbox registry calls
+- Exposes MCP tools for agents to send/receive messages
+
+### Step 2: Claude Code hook adapter (~200 lines)
+
+```typescript
+// Pseudocode for the thin adapter
+import { MeshPeer } from "agentic-mesh";
+import { createAgentInbox } from "agent-inbox";
+
+// 1. Start embedded MeshPeer
+const peer = MeshPeer.createEmbedded({ peerId: "swarm-leader" });
+await peer.start();
+
+// 2. Create agent-inbox with MeshPeer
+const inbox = await createAgentInbox({ meshPeer: peer, enableFederation: true });
+
+// 3. Hook adapter: translate Claude Code events → inbox
+onAgentSpawn(({ agentId, name }) => {
+  inbox.registry.register(agentId, { name });
+});
+
+onAgentDone(({ agentId }) => {
+  inbox.registry.disconnect(agentId);
+});
+
+// 4. MCP tools are automatically available via inbox
+// Agents use send_message, check_inbox, read_thread, list_agents
+```
+
+### Step 3: Multi-runtime support
+
+With the sidecar replaced, supporting new agent runtimes is just writing a new ~200-line adapter:
+- OpenAI agent adapter: translates OpenAI function calls → inbox MCP tools
+- AutoGen adapter: maps AutoGen conversation patterns → inbox threading
+- Standalone script adapter: CLI wrapper around inbox IPC
+
+Each adapter only handles lifecycle translation. Messaging, routing, federation, and storage are all shared.
+
+## Benefits
+
+1. **~1300 fewer lines** in claude-code-swarm (1500 LOC sidecar → 200 LOC adapter)
+2. **No more MAP WebSocket management** — MeshPeer handles transport
+3. **Encrypted P2P** — Nebula/Tailscale tunnels instead of plain WebSocket
+4. **Federation with safety** — hop counting, loop detection, message buffering
+5. **Multi-runtime** — any agent runtime can join the mesh with a thin adapter
+6. **Structured messaging** — threading, read tracking, importance levels, traceability
+
+## Open Questions
+
+1. **Migration timeline** — Can this be done incrementally (sidecar + inbox side-by-side) or does it need a clean cutover?
+2. **Hook compatibility** — Are there Claude Code hook behaviors the adapter can't replicate?
+3. **Performance** — Does the extra indirection (hook → adapter → inbox → MeshPeer) add unacceptable latency for real-time agent coordination?
+4. **State migration** — Any persistent state in the current sidecar that needs migrating?