claude-code-swarm 0.3.7 → 0.3.9

package/references/agent-inbox/README.md

@@ -1,238 +0,0 @@
-# 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

@@ -1,137 +0,0 @@
-# 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?