claude-code-swarm 0.3.3 → 0.3.5

package/README.md

@@ -58,6 +58,71 @@ npm install -g openteams
 openteams editor
 ```
 
+## Configuration
+
+### Config resolution
+
+Configuration is resolved with tiered fallthrough — each level overrides the one below:
+
+```
+SWARM_* env vars  >  project config  >  global config  >  defaults
+```
+
+### Project config
+
+Lives in your project directory at `.swarm/claude-swarm/config.json` (or `.claude-swarm/config.json` with `--no-prefix`):
+
+```json
+{
+  "template": "get-shit-done",
+  "map": {
+    "scope": "my-project",
+    "systemId": "my-project-swarm"
+  }
+}
+```
+
+Project config is typically committed to the repo or gitignored per preference.
+
+### Global config
+
+Lives at `~/.claude-swarm/config.json`. Created by `swarmkit init` or manually. Sets user-wide defaults that apply to all projects unless overridden:
+
+```json
+{
+  "map": {
+    "server": "ws://my-map-server:8080",
+    "sidecar": "session",
+    "auth": {
+      "token": "my-token"
+    }
+  },
+  "sessionlog": {
+    "enabled": true,
+    "sync": "metrics"
+  }
+}
+```
+
+This is useful for settings you don't want to repeat in every project — MAP server address, auth tokens, sidecar mode, sessionlog preferences. Fields like `template` and `map.scope` are typically project-specific and belong in the project config.
+
+### Environment variable overrides
+
+All config values can be overridden via `SWARM_*` environment variables:
+
+| Config field | Environment variable |
+|---|---|
+| `template` | `SWARM_TEMPLATE` |
+| `map.server` | `SWARM_MAP_SERVER` |
+| `map.enabled` | `SWARM_MAP_ENABLED` |
+| `map.scope` | `SWARM_MAP_SCOPE` |
+| `map.systemId` | `SWARM_MAP_SYSTEM_ID` |
+| `map.sidecar` | `SWARM_MAP_SIDECAR` |
+| `map.auth.token` | `SWARM_MAP_AUTH_TOKEN` |
+| `map.auth.param` | `SWARM_MAP_AUTH_PARAM` |
+| `sessionlog.enabled` | `SWARM_SESSIONLOG_ENABLED` |
+| `sessionlog.sync` | `SWARM_SESSIONLOG_SYNC` |
+
 ## How it works
 
 1. **SessionStart hook** ensures `openteams` is installed and reads your team configuration

package/e2e/helpers/cleanup.mjs

@@ -19,11 +19,25 @@ export function killByPidFile(pidPath) {
 
 /**
  * Clean up generated artifacts and sidecar processes in a workspace.
+ * Kills both default and per-session sidecar processes.
  */
 export function cleanupWorkspace(dir) {
-  // Kill MAP sidecar if running
-  const pidPath = path.join(dir, ".swarm", "claude-swarm", "tmp", "map", "sidecar.pid");
-  killByPidFile(pidPath);
+  const mapDir = path.join(dir, ".swarm", "claude-swarm", "tmp", "map");
+
+  // Kill default MAP sidecar if running
+  killByPidFile(path.join(mapDir, "sidecar.pid"));
+
+  // Kill all per-session sidecars
+  const sessionsDir = path.join(mapDir, "sessions");
+  try {
+    if (fs.existsSync(sessionsDir)) {
+      for (const entry of fs.readdirSync(sessionsDir)) {
+        killByPidFile(path.join(sessionsDir, entry, "sidecar.pid"));
+      }
+    }
+  } catch {
+    // ignore
+  }
 
   // Remove all generated/tmp artifacts
   const tmpDir = path.join(dir, ".swarm", "claude-swarm", "tmp");

package/e2e/helpers/map-mock-server.mjs

@@ -1,23 +1,41 @@
 /**
- * map-mock-server.mjs — Minimal mock MAP WebSocket server for e2e tests
+ * map-mock-server.mjs — Protocol-compliant mock MAP WebSocket server for e2e tests
  *
- * Records all received messages and handles basic MAP protocol handshakes
- * so the sidecar doesn't crash on connection.
+ * Speaks enough of the MAP JSON-RPC protocol for the SDK's AgentConnection.connect()
+ * to succeed: handles map/connect, map/agents/register, map/agents/spawn,
+ * map/agents/unregister, map/agents/update, map/send, and trajectory/checkpoint.
+ *
+ * Also supports:
+ * - Sending inbound messages to connected clients
+ * - Configurable response delays for resilience testing
+ * - Method-specific message tracking
  */
 
 import { WebSocketServer } from "ws";
 
+let _counter = 0;
+function nextId() {
+  return `mock-${++_counter}`;
+}
+
 export class MockMapServer {
   constructor() {
     this.wss = null;
     this.port = 0;
-    this.receivedMessages = [];
     this.connections = [];
+    this.receivedMessages = [];
+    this.responseDelayMs = 0;
+    this.trajectorySupported = false;
+
+    // Method-specific tracking
+    this.spawnedAgents = [];
+    this.sentMessages = [];
+    this.callExtensions = [];
+    this.stateUpdates = [];
   }
 
   /**
    * Start the mock server on a random available port.
-   * Returns a promise that resolves with the assigned port.
    */
   start() {
     return new Promise((resolve, reject) => {
@@ -38,7 +56,6 @@ export class MockMapServer {
             });
             this._handleMessage(ws, msg);
           } catch {
-            // Invalid JSON, record raw
             this.receivedMessages.push({
               timestamp: Date.now(),
               raw: data.toString(),
@@ -56,30 +73,168 @@ export class MockMapServer {
   }
 
   /**
-   * Handle incoming MAP protocol messages with minimal responses.
+   * Handle incoming MAP protocol messages with method-specific responses.
    */
-  _handleMessage(ws, msg) {
-    // JSON-RPC style: respond with result if there's an id
-    if (msg.id !== undefined) {
-      ws.send(
-        JSON.stringify({
-          jsonrpc: "2.0",
-          id: msg.id,
-          result: { ok: true, agentId: msg.params?.name || "mock-agent" },
-        })
-      );
-      return;
+  async _handleMessage(ws, msg) {
+    if (this.responseDelayMs > 0) {
+      await new Promise((r) => setTimeout(r, this.responseDelayMs));
     }
 
-    // MAP connect message
-    if (msg.type === "connect" || msg.method === "connect") {
-      ws.send(
-        JSON.stringify({
+    const { id, method, params } = msg;
+
+    // Non-RPC messages (no id) — legacy compat
+    if (id === undefined) {
+      if (msg.type === "connect" || msg.method === "connect") {
+        ws.send(JSON.stringify({
           type: "connected",
           agentId: msg.name || "mock-agent",
-        })
-      );
+        }));
+      }
+      return;
     }
+
+    // JSON-RPC dispatch by method
+    switch (method) {
+      case "map/connect": {
+        this._respond(ws, id, {
+          sessionId: `session-${nextId()}`,
+          capabilities: {},
+          protocolVersion: "1.0",
+        });
+        break;
+      }
+
+      case "map/agents/register": {
+        const agent = {
+          id: params?.agentId || params?.name || nextId(),
+          state: "idle",
+          name: params?.name || "agent",
+          role: params?.role || "agent",
+        };
+        this._respond(ws, id, { agent });
+        break;
+      }
+
+      case "map/agents/spawn": {
+        const agent = {
+          id: params?.agentId || nextId(),
+          state: "idle",
+          name: params?.name || "spawned",
+          role: params?.role || "agent",
+        };
+        this.spawnedAgents.push({ ...params, _timestamp: Date.now() });
+        this._respond(ws, id, { agent });
+        break;
+      }
+
+      case "map/agents/unregister": {
+        this.callExtensions.push({
+          method: "map/agents/unregister",
+          params,
+          _timestamp: Date.now(),
+        });
+        this._respond(ws, id, { ok: true });
+        break;
+      }
+
+      case "map/agents/update": {
+        this.stateUpdates.push({ ...params, _timestamp: Date.now() });
+        this._respond(ws, id, { ok: true });
+        break;
+      }
+
+      case "map/send": {
+        this.sentMessages.push({ ...params, _timestamp: Date.now() });
+        this._respond(ws, id, { messageId: nextId() });
+        break;
+      }
+
+      case "trajectory/checkpoint": {
+        if (this.trajectorySupported) {
+          this._respond(ws, id, { ok: true });
+        } else {
+          this._respondError(ws, id, -32601, "Method not found: trajectory/checkpoint");
+        }
+        break;
+      }
+
+      default: {
+        // Check if it's a callExtension-style method
+        if (method) {
+          this.callExtensions.push({ method, params, _timestamp: Date.now() });
+          this._respond(ws, id, { ok: true });
+        } else {
+          this._respondError(ws, id, -32601, `Unknown method: ${method}`);
+        }
+      }
+    }
+  }
+
+  _respond(ws, id, result) {
+    try {
+      ws.send(JSON.stringify({ jsonrpc: "2.0", id, result }));
+    } catch { /* client gone */ }
+  }
+
+  _respondError(ws, id, code, message) {
+    try {
+      ws.send(JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        error: { code, message },
+      }));
+    } catch { /* client gone */ }
+  }
+
+  /**
+   * Send a MAP message notification to all connected clients.
+   * Simulates an external agent sending a message into the scope.
+   */
+  sendToAll(payload, meta = {}) {
+    const notification = this._buildMessageNotification(payload, meta);
+    for (const ws of this.connections) {
+      try {
+        ws.send(notification);
+      } catch { /* ignore */ }
+    }
+  }
+
+  /**
+   * Send a MAP message notification to a specific client.
+   */
+  sendToClient(ws, payload, meta = {}) {
+    try {
+      ws.send(this._buildMessageNotification(payload, meta));
+    } catch { /* ignore */ }
+  }
+
+  /**
+   * Build a MAP message notification in the exact JSON-RPC 2.0 format
+   * the SDK expects: no top-level `id` (notification, not request),
+   * method "map/message", params.message with id/from/to/timestamp/payload/meta.
+   */
+  _buildMessageNotification(payload, meta = {}) {
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      method: "map/message",
+      params: {
+        message: {
+          id: nextId(),
+          from: meta.from || "external-agent",
+          to: meta.to || { scope: "default" },
+          timestamp: new Date().toISOString(),
+          payload,
+          meta,
+        },
+      },
+    });
+  }
+
+  /**
+   * Set response delay for resilience testing.
+   */
+  setResponseDelay(ms) {
+    this.responseDelayMs = ms;
   }
 
   /**
@@ -95,8 +250,19 @@ export class MockMapServer {
     );
   }
 
+  /**
+   * Get received messages filtered by JSON-RPC method.
+   */
+  getByMethod(method) {
+    return this.receivedMessages.filter((m) => m.data?.method === method);
+  }
+
   clearMessages() {
     this.receivedMessages = [];
+    this.spawnedAgents = [];
+    this.sentMessages = [];
+    this.callExtensions = [];
+    this.stateUpdates = [];
   }
 
   /**
@@ -104,15 +270,25 @@ export class MockMapServer {
    */
   stop() {
     return new Promise((resolve) => {
+      // Force-terminate all connections immediately to prevent
+      // auto-reconnecting clients from keeping the server alive.
       for (const ws of this.connections) {
         try {
-          ws.close();
+          ws.terminate();
         } catch {
           // ignore
         }
       }
+      this.connections = [];
+
       if (this.wss) {
+        // Reject any new connections that arrive during shutdown
+        this.wss.on("connection", (ws) => {
+          try { ws.terminate(); } catch { /* ignore */ }
+        });
         this.wss.close(() => resolve());
+        // Safety timeout — resolve after 3s even if wss.close() hangs
+        setTimeout(resolve, 3000);
       } else {
         resolve();
       }

package/e2e/helpers/sidecar.mjs

@@ -0,0 +1,222 @@
+/**
+ * sidecar.mjs — Test helper for starting/stopping real sidecar processes
+ *
+ * Spawns the actual map-sidecar.mjs as a detached child process,
+ * waits for sockets to appear, and provides cleanup.
+ */
+
+import fs from "fs";
+import path from "path";
+import net from "net";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_DIR = path.resolve(__dirname, "../..");
+const SIDECAR_SCRIPT = path.join(PLUGIN_DIR, "scripts", "map-sidecar.mjs");
+
+/**
+ * Send a command to a UNIX socket and return the parsed response.
+ * Longer timeout than production (5s) for test reliability.
+ */
+export function sendCommand(socketPath, command, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const client = net.createConnection(socketPath, () => {
+      client.write(JSON.stringify(command) + "\n");
+    });
+    let buffer = "";
+    client.on("data", (data) => {
+      buffer += data.toString();
+      const idx = buffer.indexOf("\n");
+      if (idx !== -1) {
+        const line = buffer.slice(0, idx);
+        client.end();
+        try {
+          resolve(JSON.parse(line));
+        } catch {
+          resolve(null);
+        }
+      }
+    });
+    client.on("error", () => resolve(null));
+    setTimeout(() => {
+      client.destroy();
+      resolve(null);
+    }, timeoutMs);
+  });
+}
+
+/**
+ * Wait for a condition to become true, polling at intervalMs.
+ */
+async function waitFor(predicate, timeoutMs = 10000, intervalMs = 200) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await predicate()) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+/**
+ * Compute the expected socket paths for a sidecar running in a workspace.
+ * Mirrors the path resolution in src/paths.mjs when .swarm/claude-swarm/ exists.
+ */
+function getSocketPaths(workspaceDir, sessionId) {
+  // Resolve symlinks (macOS: /tmp -> /private/tmp) so paths match the sidecar's process.cwd()
+  const realDir = fs.realpathSync(workspaceDir);
+  const mapDir = path.join(realDir, ".swarm", "claude-swarm", "tmp", "map");
+  if (sessionId) {
+    const dir = path.join(mapDir, "sessions", sessionId);
+    return {
+      socketPath: path.join(dir, "sidecar.sock"),
+      inboxSocketPath: path.join(dir, "inbox.sock"),
+      pidPath: path.join(dir, "sidecar.pid"),
+      mapDir,
+    };
+  }
+  return {
+    socketPath: path.join(mapDir, "sidecar.sock"),
+    inboxSocketPath: path.join(mapDir, "inbox.sock"),
+    pidPath: path.join(mapDir, "sidecar.pid"),
+    mapDir,
+  };
+}
+
+/**
+ * Start the real sidecar process for testing.
+ *
+ * @param {object} options
+ * @param {string} options.workspaceDir - workspace with .swarm/claude-swarm/ directory
+ * @param {number} options.mockServerPort - port of the mock MAP server
+ * @param {string} [options.scope] - MAP scope (default: "swarm:test")
+ * @param {string} [options.systemId] - system ID (default: "system-test")
+ * @param {string} [options.sessionId] - per-session sidecar ID
+ * @param {object} [options.inboxConfig] - inbox config object (passed as --inbox-config JSON)
+ * @param {number} [options.inactivityTimeoutMs] - inactivity timeout override
+ * @returns {Promise<object>} handle with socketPath, pid, cleanup, etc.
+ */
+export async function startTestSidecar(options) {
+  const {
+    workspaceDir,
+    mockServerPort,
+    scope = "swarm:test",
+    systemId = "system-test",
+    sessionId,
+    inboxConfig,
+    inactivityTimeoutMs,
+  } = options;
+
+  const paths = getSocketPaths(workspaceDir, sessionId);
+
+  // Ensure map directory exists
+  fs.mkdirSync(path.dirname(paths.pidPath), { recursive: true });
+
+  // Build CLI args
+  const args = [
+    SIDECAR_SCRIPT,
+    "--server", `ws://localhost:${mockServerPort}`,
+    "--scope", scope,
+    "--system-id", systemId,
+  ];
+  if (sessionId) {
+    args.push("--session-id", sessionId);
+  }
+  if (inboxConfig) {
+    args.push("--inbox-config", JSON.stringify(inboxConfig));
+  }
+  if (inactivityTimeoutMs) {
+    args.push("--inactivity-timeout", String(inactivityTimeoutMs));
+  }
+
+  // Spawn detached
+  const child = spawn("node", args, {
+    detached: true,
+    stdio: ["ignore", "ignore", "pipe"],
+    cwd: workspaceDir,
+  });
+  child.unref();
+
+  // Collect stderr for debugging
+  let stderr = "";
+  child.stderr.on("data", (data) => {
+    stderr += data.toString();
+  });
+
+  // Write PID file
+  fs.writeFileSync(paths.pidPath, String(child.pid));
+
+  // Wait for lifecycle socket to appear and respond to ping
+  const lifecycleReady = await waitFor(async () => {
+    if (!fs.existsSync(paths.socketPath)) return false;
+    const resp = await sendCommand(paths.socketPath, { action: "ping" });
+    return resp?.ok === true;
+  }, 15000);
+
+  if (!lifecycleReady) {
+    // Try to clean up
+    try { process.kill(child.pid, "SIGTERM"); } catch { /* ignore */ }
+    throw new Error(
+      `Sidecar lifecycle socket not ready after 15s.\nStderr: ${stderr}`
+    );
+  }
+
+  // If inbox is configured, wait for inbox socket too
+  let inboxReady = false;
+  if (inboxConfig) {
+    inboxReady = await waitFor(
+      () => fs.existsSync(paths.inboxSocketPath),
+      10000
+    );
+  }
+
+  return {
+    pid: child.pid,
+    child,
+    stderr: () => stderr,
+    ...paths,
+    inboxReady,
+    cleanup: () => stopTestSidecar({ pid: child.pid, ...paths }),
+  };
+}
+
+/**
+ * Stop a test sidecar and clean up.
+ */
+export async function stopTestSidecar(handle) {
+  const { pid, socketPath, inboxSocketPath, pidPath } = handle;
+
+  // Send SIGTERM
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // Already dead
+  }
+
+  // Wait for process to die
+  await waitFor(() => {
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch {
+      return true;
+    }
+  }, 5000);
+
+  // Clean up files
+  for (const f of [socketPath, inboxSocketPath, pidPath]) {
+    try { fs.unlinkSync(f); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Check if a process is alive.
+ */
+export function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/e2e/helpers/workspace.mjs

@@ -17,9 +17,10 @@ export function createWorkspace(options = {}) {
     config = undefined,
     gitInit = true,
     files = {},
+    tmpdir = os.tmpdir(),
   } = options;
 
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  const dir = fs.mkdtempSync(path.join(tmpdir, prefix));
 
   if (gitInit) {
     execSync("git init -q", { cwd: dir, stdio: "ignore" });