claude-code-swarm 0.3.7 → 0.3.9

package/src/mesh-connection.mjs

@@ -29,6 +29,10 @@
  * @param {object} [opts.transport] - Custom transport for P2P connectivity (optional).
  * @returns {Promise<{peer: object, connection: object}|null>}
  */
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("mesh");
+
 export async function createMeshPeer({ peerId, scope, systemId, onMessage, transport }) {
   try {
     const { MeshPeer } = await import("agentic-mesh");
@@ -54,15 +58,11 @@ export async function createMeshPeer({ peerId, scope, systemId, onMessage, trans
       connection.on("message", onMessage);
     }
 
-    process.stderr.write(
-      `[mesh] MeshPeer started as ${peerId}, agent ${agentName} in scope ${scope}\n`
-    );
+    log.info("MeshPeer started", { peerId, agent: agentName, scope });
 
     return { peer, connection };
   } catch (err) {
-    process.stderr.write(
-      `[mesh] agentic-mesh not available: ${err.message}\n`
-    );
+    log.warn("agentic-mesh not available", { error: err.message });
     return null;
   }
 }
@@ -107,14 +107,10 @@ export async function createMeshInbox({ meshPeer, scope, systemId, socketPath, i
     };
 
     const inbox = await createAgentInbox(opts);
-    process.stderr.write(
-      `[mesh] Agent Inbox started with MeshPeer on ${socketPath}\n`
-    );
+    log.info("Agent Inbox started with MeshPeer", { socketPath });
     return inbox;
   } catch (err) {
-    process.stderr.write(
-      `[mesh] Agent Inbox (mesh mode) not available: ${err.message}\n`
-    );
+    log.warn("Agent Inbox (mesh mode) not available", { error: err.message });
     return null;
   }
 }

package/src/opentasks-client.mjs

@@ -12,6 +12,9 @@
 
 import fs from "fs";
 import path from "path";
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("opentasks");
 import net from "net";
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
@@ -157,10 +160,10 @@ export async function ensureDaemon(config) {
     }
 
     if (stderr) {
-      process.stderr.write(`[opentasks-client] Daemon start stderr: ${stderr.trim()}\n`);
+      log.warn("daemon start stderr", { stderr: stderr.trim() });
     }
   } catch (err) {
-    process.stderr.write(`[opentasks-client] Failed to start daemon: ${err.message}\n`);
+    log.error("failed to start daemon", { error: err.message });
   }
 
   return false;

package/src/paths.mjs

@@ -5,11 +5,12 @@
  *
  * Path resolution priority:
  *   1. If .swarm/claude-swarm/ exists in CWD → use project-level paths
- *   2. Otherwise → use global paths at ~/.claude/claude-swarm/tmp/
+ *   2. Otherwise → use global paths at ~/.claude-swarm/tmp/
  *
  * Global layout:
- *   ~/.claude/claude-swarm/tmp/teams/<template>/   — shared template artifact cache
- *   ~/.claude/claude-swarm/tmp/map/<cwd-hash>/     — per-project MAP runtime state
+ *   ~/.claude-swarm/tmp/teams/<template>/   — shared template artifact cache
+ *   ~/.claude-swarm/tmp/map/<cwd-hash>/     — per-project MAP runtime state
+ *   ~/.claude-swarm/tmp/logs/<sessionId>.log — per-session log files
  *
  * Project layout (backward-compatible):
  *   .swarm/claude-swarm/config.json                — user config (always project-relative)
@@ -36,7 +37,7 @@ export const SESSIONLOG_DIR = path.join(".git", "sessionlog-sessions");
 
 // --- Global base directory ---
 
-const GLOBAL_BASE = path.join(os.homedir(), ".claude", "claude-swarm");
+const GLOBAL_BASE = GLOBAL_CONFIG_DIR;
 
 // --- Path resolution ---
 
@@ -51,7 +52,7 @@ function cwdHash() {
 /**
  * Resolve the base tmp directory.
  * If .swarm/claude-swarm/ exists in CWD, use project-level paths.
- * Otherwise, use global paths at ~/.claude/claude-swarm/tmp/.
+ * Otherwise, use global paths at ~/.claude-swarm/tmp/.
  */
 function resolveBaseTmpDir() {
   if (fs.existsSync(SWARM_DIR)) {
@@ -94,13 +95,15 @@ export const PID_PATH = path.join(_mapDir, "sidecar.pid");
 export const ROLES_PATH = path.join(_mapDir, "roles.json");
 export const SESSIONLOG_STATE_PATH = path.join(_mapDir, "sessionlog-state.json");
 export const SIDECAR_LOG_PATH = path.join(_mapDir, "sidecar.log");
+export const LOG_PATH = path.join(GLOBAL_CONFIG_DIR, "tmp", "logs", "swarm.log");
+export const LOGS_DIR = path.join(GLOBAL_CONFIG_DIR, "tmp", "logs");
 
 // opentasks runtime state
 export const OPENTASKS_DIR = path.join(_tmpDir, "opentasks");
 export const OPENTASKS_SYNC_STATE_PATH = path.join(_tmpDir, "opentasks", "sync-state.json");
 
 /**
- * Whether paths resolved to global (~/.claude/claude-swarm/tmp/) vs project-level.
+ * Whether paths resolved to global (~/.claude-swarm/tmp/) vs project-level.
  */
 export const IS_GLOBAL_PATHS = _isGlobal;
 
@@ -109,7 +112,7 @@ export const IS_GLOBAL_PATHS = _isGlobal;
 /**
  * Get the per-template team directory.
  * E.g. teamDir("gsd") → ".swarm/claude-swarm/tmp/teams/gsd" or
- *      "~/.claude/claude-swarm/tmp/teams/gsd"
+ *      "~/.claude-swarm/tmp/teams/gsd"
  */
 export function teamDir(templateName) {
   return path.join(TEAMS_DIR, templateName);
@@ -118,7 +121,7 @@ export function teamDir(templateName) {
 /**
  * Ensure the necessary directories exist.
  * - Project-level: creates .swarm/claude-swarm/ with .gitignore for tmp/
- * - Global: creates ~/.claude/claude-swarm/tmp/ (no .gitignore needed)
+ * - Global: creates ~/.claude-swarm/tmp/ (no .gitignore needed)
  */
 export function ensureSwarmDir() {
   if (_isGlobal) {

package/src/roles.mjs

@@ -9,6 +9,9 @@ import fs from "fs";
 import path from "path";
 import { createRequire } from "module";
 import { ROLES_PATH } from "./paths.mjs";
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("roles");
 
 const require = createRequire(import.meta.url);
 
@@ -64,9 +67,7 @@ export function writeRoles(templatePath, outputPath = ROLES_PATH) {
     fs.writeFileSync(outputPath, JSON.stringify(roles, null, 2));
     return roles;
   } catch (err) {
-    process.stderr.write(
-      `Warning: could not write roles.json: ${err.message}\n`
-    );
+    log.warn("could not write roles.json", { error: err.message });
     return null;
   }
 }

package/src/sessionlog.mjs

@@ -2,14 +2,15 @@
  * sessionlog.mjs — Sessionlog integration for claude-code-swarm
  *
  * Detects active sessionlog sessions, builds trajectory checkpoints,
- * and syncs session data to MAP via the trajectory protocol.
+ * syncs session data to MAP via the trajectory protocol, and annotates
+ * sessions with swarm metadata for cross-session correlation.
  */
 
 import fs from "fs";
 import path from "path";
 import { execSync } from "child_process";
 import { SESSIONLOG_DIR, SESSIONLOG_STATE_PATH, sessionPaths } from "./paths.mjs";
-import { resolveTeamName } from "./config.mjs";
+import { resolveTeamName, resolveScope } from "./config.mjs";
 import { sendToSidecar, ensureSidecar } from "./sidecar-client.mjs";
 import { fireAndForgetTrajectory } from "./map-connection.mjs";
 
@@ -164,3 +165,38 @@ export async function syncSessionlog(config, sessionId) {
     // Non-critical
   }
 }
+
+/**
+ * Annotate the current sessionlog session with swarm metadata.
+ * Uses sessionlog's store.annotate() for atomic merge.
+ * Best-effort — never throws.
+ */
+export async function annotateSwarmSession(config, sessionId) {
+  if (!sessionId) return;
+
+  let createSessionStore;
+  try {
+    ({ createSessionStore } = await import("sessionlog"));
+  } catch {
+    // sessionlog not available as a module
+    return;
+  }
+
+  const teamName = resolveTeamName(config);
+  const scope = resolveScope(config);
+
+  const annotations = {
+    swarmId: `${teamName}-${sessionId}`,
+    teamName,
+    template: config.template || "",
+    scope,
+  };
+
+  try {
+    const store = createSessionStore();
+    if (typeof store.annotate !== "function") return; // requires sessionlog >=0.0.6
+    await store.annotate(sessionId, annotations);
+  } catch {
+    // Non-critical — session may not exist yet or annotate failed
+  }
+}

package/src/sidecar-client.mjs

@@ -12,6 +12,9 @@ import { spawn } from "child_process";
 import { SOCKET_PATH, PID_PATH, pluginDir, sessionPaths } from "./paths.mjs";
 import { resolveScope, resolveMapServer, DEFAULTS } from "./config.mjs";
 import { meshFireAndForget } from "./mesh-connection.mjs";
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("sidecar-client");
 
 /**
  * Send a command to the agent-inbox IPC socket and return the response.
@@ -87,7 +90,7 @@ export async function startSidecar(config, pluginDirOverride, sessionId) {
   const sidecarPath = path.join(dir, "scripts", "map-sidecar.mjs");
   const sPaths = sessionPaths(sessionId);
 
-  const server = resolveMapServer(config);
+  const server = resolveMapServer(config, sessionId);
   const scope = resolveScope(config);
   const systemId = config.map?.systemId || DEFAULTS.mapSystemId;
 
@@ -98,9 +101,17 @@ export async function startSidecar(config, pluginDirOverride, sessionId) {
     if (sessionId) {
       args.push("--session-id", sessionId);
     }
+    // Pass auth credential for server-driven auth negotiation
+    const credential = config.map?.auth?.credential;
+    if (credential) {
+      args.push("--credential", credential);
+    }
     if (config.inbox?.enabled) {
       args.push("--inbox-config", JSON.stringify(config.inbox));
     }
+    if (config.map?.reconnectIntervalMs && config.map.reconnectIntervalMs !== DEFAULTS.mapReconnectIntervalMs) {
+      args.push("--reconnect-interval", String(config.map.reconnectIntervalMs));
+    }
     if (config.mesh?.enabled) {
       args.push("--mesh-enabled");
       if (config.mesh.peerId) {
@@ -124,7 +135,7 @@ export async function startSidecar(config, pluginDirOverride, sessionId) {
       }
     }
   } catch (err) {
-    process.stderr.write(`[sidecar-client] Start failed: ${err.message}\n`);
+    log.error("start failed", { error: err.message });
   }
 
   return false;

package/src/sidecar-server.mjs

@@ -12,6 +12,9 @@
 
 import fs from "fs";
 import net from "net";
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("sidecar");
 
 /**
  * Create a UNIX socket server that accepts NDJSON commands.
@@ -45,14 +48,10 @@ export function createSocketServer(socketPath, onCommand) {
           // Must await the async handler to catch SDK errors;
           // without this, rejections become uncaught and crash the process.
           onCommand(command, client).catch((err) => {
-            process.stderr.write(
-              `[sidecar] Async command error (${command.action}): ${err.message}\n`
-            );
+            log.error("async command error", { action: command.action, error: err.message });
           });
         } catch (err) {
-          process.stderr.write(
-            `[sidecar] Invalid command: ${err.message}\n`
-          );
+          log.warn("invalid command", { error: err.message });
         }
       }
     });
@@ -63,13 +62,11 @@ export function createSocketServer(socketPath, onCommand) {
   });
 
   server.listen(socketPath, () => {
-    process.stderr.write(`[sidecar] Listening on ${socketPath}\n`);
+    log.info("listening", { socketPath });
   });
 
   server.on("error", (err) => {
-    process.stderr.write(
-      `[sidecar] Socket server error: ${err.message}\n`
-    );
+    log.error("socket server error", { error: err.message });
   });
 
   return server;
@@ -160,9 +157,7 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
 
               respond(client, { ok: true, agent: { agentId, name, role } });
             } catch (err) {
-              process.stderr.write(
-                `[sidecar] spawn (mesh) failed: ${err.message}\n`
-              );
+              log.error("spawn (mesh) failed", { error: err.message });
               respond(client, { ok: false, error: err.message });
             }
           } else if (conn) {
@@ -193,9 +188,7 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
 
               respond(client, { ok: true, agent: result });
             } catch (err) {
-              process.stderr.write(
-                `[sidecar] spawn failed: ${err.message}\n`
-              );
+              log.error("spawn failed", { error: err.message });
               respond(client, { ok: false, error: err.message });
             }
           } else {
@@ -235,8 +228,6 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
                 // Best-effort
               }
             }
-
-            registeredAgents.delete(agentId);
           } else if (conn) {
             // WebSocket mode: use MAP SDK
             try {
@@ -261,9 +252,12 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
                 });
               } catch { /* best-effort */ }
             }
-
-            registeredAgents.delete(agentId);
           }
+
+          // Always clean up local tracking — even if conn is null (during
+          // an outage), we want to remove the agent so it isn't
+          // re-registered when the connection is restored.
+          registeredAgents.delete(agentId);
           respond(client, { ok: true });
           break;
         }
@@ -276,9 +270,7 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
               });
               respond(client, { ok: true, method: "trajectory" });
             } catch (err) {
-              process.stderr.write(
-                `[sidecar] trajectory/checkpoint not supported, falling back to broadcast: ${err.message}\n`
-              );
+              log.warn("trajectory/checkpoint not supported, falling back to broadcast", { error: err.message });
               await conn.send(
                 { scope },
                 {
@@ -409,9 +401,7 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
           respond(client, { ok: false, error: `Unknown action: ${action}` });
       }
     } catch (err) {
-      process.stderr.write(
-        `[sidecar] Command error (${action}): ${err.message}\n`
-      );
+      log.error("command error", { action, error: err.message });
       respond(client, { ok: false, error: err.message });
     }
   };

package/src/skilltree-client.mjs

@@ -12,6 +12,9 @@ import fs from "fs";
 import path from "path";
 import { createRequire } from "module";
 import { getGlobalNodeModules } from "./swarmkit-resolver.mjs";
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("skilltree");
 
 const require = createRequire(import.meta.url);
 
@@ -130,7 +133,7 @@ export async function compileRoleLoadout(roleName, criteria, config) {
       await bank.shutdown();
     }
   } catch (err) {
-    process.stderr.write(`[skilltree] Warning: loadout compilation failed for ${roleName}: ${err.message}\n`);
+    log.warn("loadout compilation failed", { role: roleName, error: err.message });
     return "";
   }
 }

package/src/swarmkit-resolver.mjs

@@ -19,17 +19,33 @@ let _globalPrefix = undefined;
 let _swarmkit = undefined;
 
 /**
- * Get the global npm prefix path (cached).
+ * Get the global npm prefix path (cached in-memory + on disk).
+ * The disk cache avoids a ~70ms execSync('npm prefix -g') on every startup.
  * Returns null if npm is not available.
  */
 export function getGlobalPrefix() {
   if (_globalPrefix !== undefined) return _globalPrefix;
+
+  // Try disk cache first (stable across sessions — only changes if npm is reinstalled)
+  const cacheFile = path.join(pluginDir(), "node_modules", ".npm-prefix-cache");
+  try {
+    const cached = fs.readFileSync(cacheFile, "utf-8").trim();
+    if (cached && fs.existsSync(cached)) {
+      _globalPrefix = cached;
+      return _globalPrefix;
+    }
+  } catch {
+    // Cache miss — fall through
+  }
+
   try {
     _globalPrefix = execSync("npm prefix -g", {
       encoding: "utf-8",
       timeout: 5000,
       stdio: ["ignore", "pipe", "ignore"],
     }).trim();
+    // Persist to disk cache (best-effort)
+    try { fs.writeFileSync(cacheFile, _globalPrefix); } catch {}
   } catch {
     _globalPrefix = null;
   }

package/src/template.mjs

@@ -12,6 +12,9 @@ import { createRequire } from "module";
 import { getGlobalNodeModules } from "./swarmkit-resolver.mjs";
 import { teamDir } from "./paths.mjs";
 import { writeRoles } from "./roles.mjs";
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("template");
 import { readConfig } from "./config.mjs";
 
 const require = createRequire(import.meta.url);
@@ -161,7 +164,7 @@ export async function loadTeam(templateName) {
           fs.writeFileSync(loadoutsPath, JSON.stringify(loadouts, null, 2), "utf-8");
         }
       } catch (err) {
-        process.stderr.write(`[template] Warning: skill loadout compilation failed: ${err.message}\n`);
+        log.warn("skill loadout compilation failed", { error: err.message });
       }
     }
   }

package/vitest.config.mjs

@@ -4,6 +4,10 @@ export default defineConfig({
   test: {
     globals: true,
     environment: "node",
+    env: {
+      SWARM_LOG_FILE: "/dev/null",
+      SWARM_LOG_STDERR: "false",
+    },
     include: ["src/__tests__/**/*.test.mjs"],
     watch: false,
     testTimeout: 10000,

package/references/agent-inbox/CLAUDE.md

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