claude-code-swarm 0.3.4 → 0.3.6

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/opentasks-daemon.mjs

@@ -0,0 +1,149 @@
+/**
+ * Test helper: minimal opentasks daemon for e2e tests
+ *
+ * Creates a JSON-RPC 2.0 server on a Unix socket that implements the
+ * subset of opentasks daemon methods used by opentasks-client.mjs:
+ *   - ping → { pong: true }
+ *   - graph.create → stores node, returns { id, ...params }
+ *   - graph.update → updates stored node, returns updated node
+ *   - tools.link → stores edge, returns { ok: true }
+ *
+ * Uses in-memory storage. No persistence, no providers, no flush.
+ */
+
+import net from "net";
+import fs from "fs";
+import { randomUUID } from "crypto";
+
+/**
+ * Start a minimal opentasks daemon on a Unix socket.
+ * Returns { socketPath, stop(), nodes, edges }.
+ */
+export function startTestDaemon(socketPath) {
+  const nodes = new Map();
+  const edges = [];
+  let server;
+
+  return new Promise((resolve, reject) => {
+    // Remove stale socket
+    try { fs.unlinkSync(socketPath); } catch { /* ignore */ }
+
+    server = net.createServer((conn) => {
+      let buffer = "";
+
+      conn.on("data", (data) => {
+        buffer += data.toString();
+        const lines = buffer.split("\n");
+        buffer = lines.pop(); // Keep incomplete line
+
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const req = JSON.parse(line);
+            const result = handleRequest(req, nodes, edges);
+            conn.write(JSON.stringify(result) + "\n");
+          } catch (err) {
+            conn.write(JSON.stringify({
+              jsonrpc: "2.0",
+              id: null,
+              error: { code: -32700, message: "Parse error", data: err.message },
+            }) + "\n");
+          }
+        }
+      });
+    });
+
+    server.on("error", reject);
+
+    server.listen(socketPath, () => {
+      resolve({
+        socketPath,
+        nodes,
+        edges,
+        stop: () => new Promise((res) => {
+          server.close(() => {
+            try { fs.unlinkSync(socketPath); } catch { /* ignore */ }
+            res();
+          });
+          // Force close connections
+          server.unref();
+        }),
+      });
+    });
+  });
+}
+
+function handleRequest(req, nodes, edges) {
+  const { id, method, params } = req;
+
+  switch (method) {
+    case "ping":
+      return { jsonrpc: "2.0", id, result: { pong: true } };
+
+    case "graph.create": {
+      const nodeId = randomUUID();
+      const node = {
+        id: nodeId,
+        type: params?.type || "task",
+        title: params?.title || "",
+        status: params?.status || "open",
+        assignee: params?.assignee || null,
+        uri: params?.uri || null,
+        metadata: params?.metadata || {},
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+      nodes.set(nodeId, node);
+      return { jsonrpc: "2.0", id, result: node };
+    }
+
+    case "graph.update": {
+      const nodeId = params?.id;
+      if (!nodeId || !nodes.has(nodeId)) {
+        return {
+          jsonrpc: "2.0", id,
+          error: { code: -32602, message: `Node not found: ${nodeId}` },
+        };
+      }
+      const existing = nodes.get(nodeId);
+      const updated = {
+        ...existing,
+        ...(params.status !== undefined && { status: params.status }),
+        ...(params.title !== undefined && { title: params.title }),
+        ...(params.assignee !== undefined && { assignee: params.assignee }),
+        ...(params.metadata !== undefined && { metadata: { ...existing.metadata, ...params.metadata } }),
+        updatedAt: new Date().toISOString(),
+      };
+      nodes.set(nodeId, updated);
+      return { jsonrpc: "2.0", id, result: updated };
+    }
+
+    case "graph.query": {
+      const allNodes = Array.from(nodes.values());
+      const filtered = params?.type
+        ? allNodes.filter((n) => n.type === params.type)
+        : allNodes;
+      return { jsonrpc: "2.0", id, result: filtered };
+    }
+
+    case "tools.link": {
+      const edge = {
+        fromId: params?.fromId,
+        toId: params?.toId,
+        type: params?.type || "related",
+        metadata: params?.metadata || {},
+      };
+      edges.push(edge);
+      return { jsonrpc: "2.0", id, result: { ok: true } };
+    }
+
+    case "shutdown":
+      return { jsonrpc: "2.0", id, result: { ok: true } };
+
+    default:
+      return {
+        jsonrpc: "2.0", id,
+        error: { code: -32601, message: `Method not found: ${method}` },
+      };
+  }
+}

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" });