claude-code-swarm 0.0.1 → 0.3.3

package/e2e/helpers/assertions.mjs

@@ -0,0 +1,162 @@
+/**
+ * assertions.mjs — Tool call extraction and assertion helpers for e2e tests
+ *
+ * Handles messages from --output-format stream-json (newline-delimited JSON).
+ * Each message is a JSON object with a `type` field. Common types:
+ *   - "system" (subtypes: "init", "hook_response", "hook_started")
+ *   - "assistant" (content array with "text" and "tool_use" blocks)
+ *   - "user" (content array with "tool_result" blocks)
+ *   - "result" (final result with cost and metadata)
+ */
+
+/**
+ * Extract all tool_use calls from the message stream.
+ * Returns array of { name, input, id } objects.
+ *
+ * Handles multiple message formats:
+ *   - Assistant messages: { type: "assistant", content: [{ type: "tool_use", ... }] }
+ *   - Content block events: { type: "content_block_start", content_block: { type: "tool_use", ... } }
+ */
+export function extractToolCalls(messages) {
+  const calls = [];
+  for (const msg of messages) {
+    // Standard assistant message with content array
+    if (msg.type === "assistant" && Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block.type === "tool_use") {
+          calls.push({
+            name: block.name,
+            input: block.input || {},
+            id: block.id,
+          });
+        }
+      }
+      continue;
+    }
+
+    // Content block start event (stream-json)
+    if (
+      msg.type === "content_block_start" &&
+      msg.content_block?.type === "tool_use"
+    ) {
+      calls.push({
+        name: msg.content_block.name,
+        input: msg.content_block.input || {},
+        id: msg.content_block.id,
+      });
+      continue;
+    }
+
+    // Nested message wrapper (some stream-json variants)
+    if (msg.message?.content && Array.isArray(msg.message.content)) {
+      for (const block of msg.message.content) {
+        if (block.type === "tool_use") {
+          calls.push({
+            name: block.name,
+            input: block.input || {},
+            id: block.id,
+          });
+        }
+      }
+    }
+  }
+  return calls;
+}
+
+/**
+ * Extract tool calls by name. Returns array of matching tool call inputs.
+ */
+export function findToolCalls(messages, toolName) {
+  return extractToolCalls(messages)
+    .filter((tc) => tc.name === toolName)
+    .map((tc) => tc.input);
+}
+
+/**
+ * Assert that a specific tool was called at least once.
+ * Returns the matching call inputs.
+ */
+export function expectToolCalled(messages, toolName) {
+  const calls = findToolCalls(messages, toolName);
+  expect(calls.length).toBeGreaterThan(0);
+  return calls;
+}
+
+/**
+ * Assert that a tool was called with specific input properties.
+ */
+export function expectToolCalledWith(messages, toolName, inputMatch) {
+  const calls = findToolCalls(messages, toolName);
+  expect(calls).toEqual(
+    expect.arrayContaining([expect.objectContaining(inputMatch)])
+  );
+  return calls;
+}
+
+/**
+ * Get the final result message.
+ */
+export function getResult(messages) {
+  return messages.find((m) => m.type === "result") || null;
+}
+
+/**
+ * Extract hook output text from system messages.
+ *
+ * Hook responses can appear in various forms:
+ *   - { type: "system", subtype: "hook_response", stdout: "...", output: "..." }
+ *   - { type: "system", subtype: "init", content: "..." }
+ *   - { type: "system", content: "..." } or { type: "system", content: [...] }
+ */
+export function getHookOutput(messages) {
+  return messages
+    .filter(
+      (m) =>
+        m.type === "system" &&
+        (m.subtype === "hook_response" ||
+          m.subtype === "hook_started" ||
+          m.subtype === "init")
+    )
+    .map((m) => {
+      const parts = [];
+
+      // Hook-specific fields
+      if (m.stdout) parts.push(m.stdout);
+      if (m.output) parts.push(m.output);
+
+      // Content field (string or array)
+      if (typeof m.content === "string") {
+        parts.push(m.content);
+      } else if (Array.isArray(m.content)) {
+        parts.push(
+          m.content
+            .map((c) => (typeof c === "string" ? c : c.text || ""))
+            .join("\n")
+        );
+      }
+
+      // If nothing else, stringify the whole message
+      if (parts.length === 0) {
+        parts.push(JSON.stringify(m));
+      }
+
+      return parts.join("\n");
+    })
+    .join("\n");
+}
+
+/**
+ * Concatenate all assistant text blocks into a single string.
+ * Handles both direct content and nested message.content (stream-json format).
+ */
+export function getAssistantText(messages) {
+  const texts = [];
+  for (const msg of messages) {
+    if (msg.type !== "assistant") continue;
+    const content = msg.content || msg.message?.content || [];
+    for (const block of content) {
+      if (block.type === "text") texts.push(block.text);
+    }
+  }
+  return texts.join("\n");
+}

package/e2e/helpers/cleanup.mjs

@@ -0,0 +1,48 @@
+/**
+ * cleanup.mjs — Process and file cleanup utilities for e2e tests
+ */
+
+import fs from "fs";
+import path from "path";
+
+/**
+ * Kill a process by PID file. Silent on failure.
+ */
+export function killByPidFile(pidPath) {
+  try {
+    const pid = parseInt(fs.readFileSync(pidPath, "utf-8").trim());
+    if (pid > 0) process.kill(pid, "SIGTERM");
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Clean up generated artifacts and sidecar processes in a workspace.
+ */
+export function cleanupWorkspace(dir) {
+  // Kill MAP sidecar if running
+  const pidPath = path.join(dir, ".swarm", "claude-swarm", "tmp", "map", "sidecar.pid");
+  killByPidFile(pidPath);
+
+  // Remove all generated/tmp artifacts
+  const tmpDir = path.join(dir, ".swarm", "claude-swarm", "tmp");
+  try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Wait for a condition with timeout.
+ * Returns true if predicate passed, false if timed out.
+ */
+export async function waitFor(predicate, timeoutMs = 5000, 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;
+}

package/e2e/helpers/cli.mjs

@@ -0,0 +1,327 @@
+/**
+ * cli.mjs — Claude CLI invocation helper for e2e tests
+ *
+ * Uses --output-format stream-json which produces newline-delimited JSON
+ * (one JSON object per line) containing the full message stream including
+ * system messages, assistant tool_use blocks, and the final result.
+ *
+ * IMPORTANT: Uses spawn with stdio: ['ignore', 'pipe', 'pipe'] to close
+ * stdin immediately. Without this, claude -p hangs waiting for stdin EOF.
+ *
+ * All CLI invocations are logged to e2e/logs/<timestamp>-<label>.log
+ * for post-run debugging. Feed these back to diagnose failures.
+ */
+
+import { spawn, execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const PLUGIN_DIR = path.resolve(__dirname, "../..");
+export const DEFAULT_MODEL = process.env.E2E_MODEL || "sonnet";
+export const DEFAULT_BUDGET = process.env.E2E_BUDGET || "0.50";
+
+const LOG_DIR = path.resolve(__dirname, "..", "logs");
+
+// Preflight: check if claude CLI is available
+export let CLI_AVAILABLE = false;
+try {
+  execSync("which claude", { stdio: "ignore" });
+  CLI_AVAILABLE = true;
+} catch {
+  CLI_AVAILABLE = false;
+}
+
+/**
+ * Build a clean environment for the child claude process.
+ * Strips env vars from any parent Claude Code session that would
+ * confuse the child into thinking it's already inside a session.
+ */
+function cleanEnv() {
+  const env = { ...process.env };
+
+  // Remove vars that tell claude it's inside an existing session
+  const stripPrefixes = ["CLAUDECODE", "CLAUDE_CODE_", "CLAUDE_SESSION", "CLAUDE_CONVERSATION"];
+  for (const key of Object.keys(env)) {
+    if (stripPrefixes.some((p) => key.startsWith(p))) {
+      delete env[key];
+    }
+  }
+
+  // Re-add only the ones we explicitly want
+  env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1";
+
+  return env;
+}
+
+/** Ensure log directory exists. */
+function ensureLogDir() {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+}
+
+/** Sanitize a string for use as a filename. */
+function sanitizeLabel(s) {
+  return s
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .replace(/_+/g, "_")
+    .slice(0, 80);
+}
+
+/**
+ * Write a log file for a CLI invocation.
+ * Returns the log file path.
+ */
+function writeLog(label, { args, exitCode, stdout, stderr, error, messages, result, durationMs }) {
+  ensureLogDir();
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const filename = `${ts}-${sanitizeLabel(label)}.log`;
+  const logPath = path.join(LOG_DIR, filename);
+
+  const sections = [
+    `# E2E Log: ${label}`,
+    `# Timestamp: ${new Date().toISOString()}`,
+    `# Duration: ${durationMs}ms`,
+    "",
+    "## Command",
+    `claude ${args.join(" ")}`,
+    "",
+    "## Exit Code",
+    String(exitCode),
+    "",
+  ];
+
+  if (error) {
+    sections.push("## Error", String(error), "");
+  }
+
+  sections.push(
+    "## Stderr",
+    stderr || "(empty)",
+    "",
+    "## Parsed Messages Summary",
+    `Total messages: ${messages?.length ?? 0}`,
+  );
+
+  if (messages?.length > 0) {
+    const typeCounts = {};
+    for (const m of messages) {
+      const key = m.subtype ? `${m.type}/${m.subtype}` : m.type;
+      typeCounts[key] = (typeCounts[key] || 0) + 1;
+    }
+    sections.push(`Message types: ${JSON.stringify(typeCounts)}`);
+
+    // Tool calls (handles both direct content and nested message.content)
+    const toolCalls = [];
+    for (const m of messages) {
+      const content = (m.type === "assistant" && Array.isArray(m.content))
+        ? m.content
+        : (m.type === "assistant" && Array.isArray(m.message?.content))
+          ? m.message.content
+          : null;
+      if (content) {
+        for (const b of content) {
+          if (b.type === "tool_use") toolCalls.push(b.name);
+        }
+      }
+      if (m.type === "content_block_start" && m.content_block?.type === "tool_use") {
+        toolCalls.push(m.content_block.name);
+      }
+    }
+    if (toolCalls.length > 0) {
+      sections.push(`Tool calls: ${toolCalls.join(", ")}`);
+    }
+  }
+
+  if (result) {
+    sections.push(
+      "",
+      "## Result",
+      JSON.stringify(result, null, 2),
+    );
+  }
+
+  sections.push(
+    "",
+    "## Raw Stdout",
+    stdout || "(empty)",
+  );
+
+  fs.writeFileSync(logPath, sections.join("\n"), "utf-8");
+  return logPath;
+}
+
+/**
+ * Parse newline-delimited JSON (stream-json format).
+ * Each line is a separate JSON object.
+ */
+function parseStreamJson(stdout) {
+  const messages = [];
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      messages.push(JSON.parse(trimmed));
+    } catch {
+      // skip non-JSON lines
+    }
+  }
+  return messages;
+}
+
+/**
+ * Spawn claude with stdin closed (/dev/null).
+ * Returns { exitCode, stdout, stderr, killed }.
+ *
+ * This is critical: execFile leaves stdin as an open pipe, and claude -p
+ * hangs waiting for stdin EOF. Using spawn with stdio 'ignore' connects
+ * stdin to /dev/null which provides immediate EOF.
+ */
+function spawnClaude(args, options = {}) {
+  const { cwd, timeout = 180_000, env } = options;
+
+  return new Promise((resolve) => {
+    const child = spawn("claude", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: env || cleanEnv(),
+    });
+
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let killed = false;
+
+    child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+    child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill("SIGTERM");
+    }, timeout);
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode: killed ? 143 : (code || 0),
+        stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+        killed,
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode: 1,
+        stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+        stderr: err.message,
+        killed: false,
+      });
+    });
+  });
+}
+
+/**
+ * Invoke the claude CLI in non-interactive print mode.
+ * Returns { messages, result, exitCode, stderr, stdout, logFile }.
+ *
+ * Uses stream-json format to capture the full message stream including
+ * tool calls, system messages, and the final result.
+ */
+export function runClaude(prompt, options = {}) {
+  const {
+    cwd,
+    model = DEFAULT_MODEL,
+    maxBudgetUsd = DEFAULT_BUDGET,
+    maxTurns,
+    timeout = 180_000,
+    label = prompt.slice(0, 40),
+    extraArgs = [],
+  } = options;
+
+  const args = [
+    "-p", prompt,
+    "--output-format", "stream-json",
+    "--verbose",
+    "--plugin-dir", PLUGIN_DIR,
+    "--model", model,
+    "--max-budget-usd", String(maxBudgetUsd),
+    "--no-session-persistence",
+    "--dangerously-skip-permissions",
+  ];
+
+  if (maxTurns !== undefined) {
+    args.push("--max-turns", String(maxTurns));
+  }
+
+  args.push(...extraArgs);
+
+  const startTime = Date.now();
+
+  return spawnClaude(args, { cwd, timeout }).then(({ exitCode, stdout, stderr, killed }) => {
+    const durationMs = Date.now() - startTime;
+    let messages = [];
+    let result = null;
+
+    // stream-json: newline-delimited JSON objects
+    messages = parseStreamJson(stdout);
+
+    // Find the result message
+    result = messages.find((m) => m.type === "result") || null;
+
+    const logFile = writeLog(label, {
+      args, exitCode, stdout, stderr,
+      error: killed ? "Process killed by timeout" : null,
+      messages, result, durationMs,
+    });
+
+    return {
+      messages,
+      result,
+      exitCode,
+      stderr,
+      stdout,
+      logFile,
+    };
+  });
+}
+
+/**
+ * Run only initialization hooks (no LLM call).
+ * Uses --init-only to trigger SessionStart hooks and exit.
+ * Returns { exitCode, stderr, stdout, logFile }.
+ */
+export function runInitOnly(options = {}) {
+  const {
+    cwd,
+    timeout = 30_000,
+    label = "init-only",
+    extraArgs = [],
+  } = options;
+
+  const args = [
+    "--init-only",
+    "--plugin-dir", PLUGIN_DIR,
+    "--dangerously-skip-permissions",
+    ...extraArgs,
+  ];
+
+  const startTime = Date.now();
+
+  return spawnClaude(args, { cwd, timeout }).then(({ exitCode, stdout, stderr, killed }) => {
+    const durationMs = Date.now() - startTime;
+
+    const logFile = writeLog(label, {
+      args, exitCode, stdout, stderr,
+      error: killed ? "Process killed by timeout" : null,
+      messages: [], result: null, durationMs,
+    });
+
+    return {
+      exitCode,
+      stderr,
+      stdout,
+      logFile,
+    };
+  });
+}

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

@@ -0,0 +1,121 @@
+/**
+ * map-mock-server.mjs — Minimal 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.
+ */
+
+import { WebSocketServer } from "ws";
+
+export class MockMapServer {
+  constructor() {
+    this.wss = null;
+    this.port = 0;
+    this.receivedMessages = [];
+    this.connections = [];
+  }
+
+  /**
+   * Start the mock server on a random available port.
+   * Returns a promise that resolves with the assigned port.
+   */
+  start() {
+    return new Promise((resolve, reject) => {
+      this.wss = new WebSocketServer({ port: 0 }, () => {
+        this.port = this.wss.address().port;
+        resolve(this.port);
+      });
+
+      this.wss.on("connection", (ws) => {
+        this.connections.push(ws);
+
+        ws.on("message", (data) => {
+          try {
+            const msg = JSON.parse(data.toString());
+            this.receivedMessages.push({
+              timestamp: Date.now(),
+              data: msg,
+            });
+            this._handleMessage(ws, msg);
+          } catch {
+            // Invalid JSON, record raw
+            this.receivedMessages.push({
+              timestamp: Date.now(),
+              raw: data.toString(),
+            });
+          }
+        });
+
+        ws.on("close", () => {
+          this.connections = this.connections.filter((c) => c !== ws);
+        });
+      });
+
+      this.wss.on("error", reject);
+    });
+  }
+
+  /**
+   * Handle incoming MAP protocol messages with minimal 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;
+    }
+
+    // MAP connect message
+    if (msg.type === "connect" || msg.method === "connect") {
+      ws.send(
+        JSON.stringify({
+          type: "connected",
+          agentId: msg.name || "mock-agent",
+        })
+      );
+    }
+  }
+
+  /**
+   * Get received messages, optionally filtered by event type.
+   */
+  getMessages(eventType = null) {
+    if (!eventType) return this.receivedMessages;
+    return this.receivedMessages.filter(
+      (m) =>
+        m.data?.type === eventType ||
+        m.data?.event?.type === eventType ||
+        m.data?.params?.type === eventType
+    );
+  }
+
+  clearMessages() {
+    this.receivedMessages = [];
+  }
+
+  /**
+   * Stop the mock server and close all connections.
+   */
+  stop() {
+    return new Promise((resolve) => {
+      for (const ws of this.connections) {
+        try {
+          ws.close();
+        } catch {
+          // ignore
+        }
+      }
+      if (this.wss) {
+        this.wss.close(() => resolve());
+      } else {
+        resolve();
+      }
+    });
+  }
+}