claude-code-swarm 0.0.1 → 0.3.3

package/references/swarmkit/src/utils/ui.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import * as ui from "./ui.js";
+
+describe("utils/ui", () => {
+  let output: string[];
+
+  beforeEach(() => {
+    output = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      output.push(args.map(String).join(" "));
+    });
+  });
+
+  describe("heading", () => {
+    it("prints a blank line then the text", () => {
+      ui.heading("Test Heading");
+      expect(output).toHaveLength(2);
+      expect(output[0]).toBe("");
+      // Second line should contain the text (may have ANSI codes for bold)
+      expect(output[1]).toContain("Test Heading");
+    });
+  });
+
+  describe("success", () => {
+    it("prints with a checkmark prefix", () => {
+      ui.success("it worked");
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain("✓");
+      expect(output[0]).toContain("it worked");
+    });
+  });
+
+  describe("warn", () => {
+    it("prints with a warning prefix", () => {
+      ui.warn("careful");
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain("⚠");
+      expect(output[0]).toContain("careful");
+    });
+  });
+
+  describe("fail", () => {
+    it("prints with a cross prefix", () => {
+      ui.fail("broken");
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain("✗");
+      expect(output[0]).toContain("broken");
+    });
+  });
+
+  describe("info", () => {
+    it("prints indented text", () => {
+      ui.info("some info");
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain("some info");
+    });
+  });
+
+  describe("bullet", () => {
+    it("prints indented text", () => {
+      ui.bullet("a point");
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain("a point");
+    });
+  });
+
+  describe("blank", () => {
+    it("prints an empty line", () => {
+      ui.blank();
+      expect(output).toHaveLength(1);
+      expect(output[0]).toBe("");
+    });
+  });
+
+  describe("table", () => {
+    it("does nothing for empty rows", () => {
+      ui.table([]);
+      expect(output).toHaveLength(0);
+    });
+
+    it("prints rows with column alignment", () => {
+      ui.table([
+        ["short", "a"],
+        ["longer-name", "b"],
+      ]);
+      expect(output).toHaveLength(2);
+      // Both rows should start with indent (4 spaces default)
+      expect(output[0]).toMatch(/^ {4}/);
+      expect(output[1]).toMatch(/^ {4}/);
+    });
+
+    it("respects custom indent", () => {
+      ui.table([["cell"]], { indent: 8 });
+      expect(output).toHaveLength(1);
+      expect(output[0]).toMatch(/^ {8}/);
+    });
+
+    it("aligns columns correctly with plain text", () => {
+      ui.table([
+        ["ab", "x"],
+        ["abcd", "y"],
+      ]);
+      // First column width should be 4 (length of "abcd")
+      // "ab" should be padded to 4 chars
+      // With indent of 4 and 2-space gap between columns:
+      // "    ab    x"  and "    abcd  y"
+      expect(output[0]).toContain("ab");
+      expect(output[1]).toContain("abcd");
+      // Both "x" and "y" should start at the same column position
+      const xPos = output[0].indexOf("x");
+      const yPos = output[1].indexOf("y");
+      expect(xPos).toBe(yPos);
+    });
+  });
+});

package/references/swarmkit/src/utils/ui.ts

@@ -0,0 +1,62 @@
+import chalk from "chalk";
+
+export function heading(text: string): void {
+  console.log();
+  console.log(chalk.bold(text));
+}
+
+export function success(text: string): void {
+  console.log(chalk.green("  ✓") + " " + text);
+}
+
+export function warn(text: string): void {
+  console.log(chalk.yellow("  ⚠") + " " + text);
+}
+
+export function fail(text: string): void {
+  console.log(chalk.red("  ✗") + " " + text);
+}
+
+export function info(text: string): void {
+  console.log(chalk.dim("  " + text));
+}
+
+export function bullet(text: string): void {
+  console.log("  " + text);
+}
+
+export function blank(): void {
+  console.log();
+}
+
+export function table(
+  rows: string[][],
+  { indent = 4 }: { indent?: number } = {},
+): void {
+  if (rows.length === 0) return;
+
+  const colCount = Math.max(...rows.map((r) => r.length));
+  const colWidths: number[] = [];
+
+  for (let col = 0; col < colCount; col++) {
+    colWidths[col] = Math.max(
+      ...rows.map((r) => stripAnsi(r[col] ?? "").length),
+    );
+  }
+
+  const pad = " ".repeat(indent);
+  for (const row of rows) {
+    const cells = row.map((cell, i) => {
+      if (i === row.length - 1) return cell;
+      const visible = stripAnsi(cell).length;
+      return cell + " ".repeat(colWidths[i] - visible);
+    });
+    console.log(pad + cells.join("  "));
+  }
+}
+
+// Simple ANSI strip — covers the codes chalk produces
+function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}

package/references/swarmkit/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "references"]
+}

package/references/swarmkit/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    testTimeout: 10_000,
+    watch: false,
+  },
+});

package/scripts/bootstrap.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * bootstrap.mjs — SessionStart hook entry point
+ *
+ * Thin wrapper: delegates to src/bootstrap.mjs + src/context-output.mjs.
+ * Output goes to stdout → injected into Claude's context.
+ * Exit 0 always — never block the session.
+ */
+
+import { bootstrap } from "../src/bootstrap.mjs";
+import { formatBootstrapContext } from "../src/context-output.mjs";
+
+try {
+  const result = await bootstrap();
+  const output = formatBootstrapContext({
+    template: result.template,
+    mapStatus: result.mapEnabled ? result.mapStatus : null,
+    sessionlogStatus: result.sessionlogEnabled ? result.sessionlogStatus : null,
+    sessionlogSync: result.sessionlogSync,
+  });
+  process.stdout.write(output);
+} catch (err) {
+  process.stderr.write(`[bootstrap] Error: ${err.message}\n`);
+  // Still output something useful
+  process.stdout.write("## Claude Code Swarm\n\nUse `/swarm` to launch a team.\n");
+}

package/scripts/generate-agents.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * generate-agents.mjs — Bridge between openteams templates and Claude Code AGENT.md files
+ *
+ * Thin wrapper: delegates to src/agent-generator.mjs.
+ *
+ * Usage: node generate-agents.mjs <template-dir> [output-dir]
+ */
+
+import path from "path";
+import { generateAllAgents } from "../src/agent-generator.mjs";
+
+const templateDir = process.argv[2];
+const outputDir = process.argv[3] || path.join(process.cwd(), "agents");
+
+if (!templateDir) {
+  console.error("Usage: generate-agents.mjs <template-dir> [output-dir]");
+  process.exit(1);
+}
+
+const result = await generateAllAgents(templateDir, outputDir);
+
+if (!result.success) {
+  console.error(result.error);
+  process.exit(1);
+}
+
+console.log(`Generated ${result.roles.length} agent definitions:`);
+for (const role of result.roles) {
+  console.log(`  agents/${role}/AGENT.md`);
+}
+console.log(`\nDone. Agent definitions written to: ${path.resolve(outputDir)}`);

package/scripts/map-hook.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * map-hook.mjs — Hook helper for claude-code-swarm MAP integration
+ *
+ * Thin wrapper: reads action + stdin, dispatches to src/ modules.
+ * Uses MAP SDK primitives via the sidecar (spawn/done/state) for agent
+ * lifecycle, and typed message payloads for task lifecycle.
+ * No custom swarm.* event types.
+ *
+ * Actions:
+ *   inject          — Read inbox, format as markdown, output to stdout
+ *   agent-spawning  — Spawn agent in MAP + emit task.dispatched payload
+ *   agent-completed — Done agent in MAP + emit task.completed payload
+ *   turn-completed  — Update sidecar state to idle
+ *   sessionlog-sync — Sync sessionlog state to MAP
+ *   subagent-start  — Spawn subagent in MAP
+ *   subagent-stop   — Done subagent in MAP
+ *   teammate-idle   — Update teammate state to idle
+ *   task-completed  — Emit task.completed payload
+ *
+ * Usage: node map-hook.mjs <action>
+ *        Hook event data is read from stdin (JSON).
+ */
+
+import { readConfig, resolveTeamName } from "../src/config.mjs";
+import { readRoles, matchRole } from "../src/roles.mjs";
+import { readInbox, clearInbox, formatInboxAsMarkdown } from "../src/inbox.mjs";
+import {
+  sendCommand,
+  emitPayload,
+  buildSpawnCommand,
+  buildDoneCommand,
+  buildSubagentSpawnCommand,
+  buildSubagentDoneCommand,
+  buildStateCommand,
+  buildTaskDispatchedPayload,
+  buildTaskCompletedPayload,
+  buildTaskStatusPayload,
+} from "../src/map-events.mjs";
+import { syncSessionlog } from "../src/sessionlog.mjs";
+
+const action = process.argv[2];
+
+// ── Stdin reader ──────────────────────────────────────────────────────────────
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", () => {
+      try { resolve(JSON.parse(data)); }
+      catch { resolve({}); }
+    });
+    if (process.stdin.readableEnded) resolve({});
+    setTimeout(() => resolve({}), 1000);
+  });
+}
+
+// ── Action handlers ───────────────────────────────────────────────────────────
+
+async function handleInject() {
+  const messages = readInbox();
+  if (!messages.length) return;
+  clearInbox();
+  const output = formatInboxAsMarkdown(messages);
+  if (output) process.stdout.write(output);
+}
+
+async function handleAgentSpawning() {
+  const config = readConfig();
+  const hookData = await readStdin();
+  const roles = readRoles();
+
+  const agentName = hookData.tool_input?.name || hookData.tool_input?.description || "";
+  const matchedRole = matchRole(agentName, roles);
+  const teamName = resolveTeamName(config);
+
+  // Spawn agent in MAP via sidecar (server auto-emits agent_registered)
+  if (matchedRole) {
+    await sendCommand(config, buildSpawnCommand(agentName, matchedRole, teamName, hookData));
+  }
+
+  // Emit task.dispatched as a regular MAP message
+  await emitPayload(config, buildTaskDispatchedPayload(hookData, teamName, matchedRole, agentName));
+}
+
+async function handleAgentCompleted() {
+  const config = readConfig();
+  const hookData = await readStdin();
+  const roles = readRoles();
+
+  const agentName = hookData.tool_input?.name || hookData.tool_input?.description || "";
+  const matchedRole = matchRole(agentName, roles);
+  const teamName = resolveTeamName(config);
+
+  // Mark agent done in MAP via sidecar (server auto-emits agent_unregistered)
+  if (matchedRole) {
+    await sendCommand(config, buildDoneCommand(agentName, matchedRole, teamName));
+  }
+
+  // Emit task.completed as a regular MAP message
+  await emitPayload(config, buildTaskCompletedPayload(hookData, teamName, matchedRole, agentName));
+}
+
+async function handleTurnCompleted() {
+  const config = readConfig();
+  const hookData = await readStdin();
+
+  // Update sidecar state to idle (server auto-emits agent_state_changed)
+  const stopReason = hookData.stop_reason || "end_turn";
+  await sendCommand(config, buildStateCommand(null, "idle", { lastStopReason: stopReason }));
+}
+
+async function handleSessionlogSync() {
+  const config = readConfig();
+  await syncSessionlog(config);
+}
+
+async function handleSubagentStart() {
+  const config = readConfig();
+  const hookData = await readStdin();
+  const teamName = resolveTeamName(config);
+
+  // Spawn subagent in MAP (server auto-emits agent_registered)
+  await sendCommand(config, buildSubagentSpawnCommand(hookData, teamName));
+}
+
+async function handleSubagentStop() {
+  const config = readConfig();
+  const hookData = await readStdin();
+  const teamName = resolveTeamName(config);
+
+  // Mark subagent done (server auto-emits agent_unregistered)
+  await sendCommand(config, buildSubagentDoneCommand(hookData, teamName));
+}
+
+async function handleTeammateIdle() {
+  const config = readConfig();
+  const hookData = await readStdin();
+  const roles = readRoles();
+  const teamName = resolveTeamName(config);
+
+  const teammateName = hookData.teammate_name || "";
+  const matchedRole = matchRole(teammateName, roles);
+
+  // Update teammate state to idle (server auto-emits agent_state_changed)
+  const agentId = matchedRole ? `${teamName}-${matchedRole}` : null;
+  await sendCommand(config, buildStateCommand(agentId, "idle"));
+}
+
+async function handleTaskCompleted() {
+  const config = readConfig();
+  const hookData = await readStdin();
+  const roles = readRoles();
+  const teamName = resolveTeamName(config);
+
+  const teammateName = hookData.teammate_name || "";
+  const matchedRole = matchRole(teammateName, roles);
+
+  // Emit task.completed as a regular MAP message
+  await emitPayload(config, buildTaskStatusPayload(hookData, teamName, matchedRole));
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  try {
+    switch (action) {
+      case "inject": await handleInject(); break;
+      case "agent-spawning": await handleAgentSpawning(); break;
+      case "agent-completed": await handleAgentCompleted(); break;
+      case "turn-completed": await handleTurnCompleted(); break;
+      case "sessionlog-sync": await handleSessionlogSync(); break;
+      case "subagent-start": await handleSubagentStart(); break;
+      case "subagent-stop": await handleSubagentStop(); break;
+      case "teammate-idle": await handleTeammateIdle(); break;
+      case "task-completed": await handleTaskCompleted(); break;
+      default:
+        process.stderr.write(`[map-hook] Unknown action: ${action}\n`);
+    }
+  } catch (err) {
+    process.stderr.write(`[map-hook] Error in ${action}: ${err.message}\n`);
+  }
+}
+
+main();

package/scripts/map-sidecar.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * map-sidecar.mjs — MAP sidecar process for claude-code-swarm
+ *
+ * Thin wrapper: parses CLI args, delegates to src/ modules for connection,
+ * socket server, and command handling.
+ *
+ * Usage: node map-sidecar.mjs --server ws://localhost:8080 --scope swarm:team --system-id system-id
+ */
+
+import fs from "fs";
+import path from "path";
+import { INBOX_PATH, SOCKET_PATH, PID_PATH } from "../src/paths.mjs";
+import { connectToMAP } from "../src/map-connection.mjs";
+import { createSocketServer, createCommandHandler } from "../src/sidecar-server.mjs";
+import { writeToInbox } from "../src/inbox.mjs";
+
+// ── Parse CLI args ──────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+function getArg(name, defaultValue = "") {
+  const idx = args.indexOf(`--${name}`);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : defaultValue;
+}
+
+const MAP_SERVER = getArg("server", "ws://localhost:8080");
+const MAP_SCOPE = getArg("scope", "swarm:default");
+const SYSTEM_ID = getArg("system-id", "system-claude-swarm");
+const INACTIVITY_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+
+// ── State ───────────────────────────────────────────────────────────────────
+
+let connection = null;
+let socketServer = null;
+let inactivityTimer = null;
+const registeredAgents = new Map();
+
+// ── Inactivity Timer ────────────────────────────────────────────────────────
+
+function resetInactivityTimer() {
+  if (inactivityTimer) clearTimeout(inactivityTimer);
+  inactivityTimer = setTimeout(() => {
+    process.stderr.write("[sidecar] Inactivity timeout reached, shutting down\n");
+    shutdown();
+  }, INACTIVITY_TIMEOUT_MS);
+}
+
+// ── Shutdown ────────────────────────────────────────────────────────────────
+
+async function shutdown() {
+  process.stderr.write("[sidecar] Shutting down...\n");
+
+  if (inactivityTimer) clearTimeout(inactivityTimer);
+  if (socketServer) socketServer.close();
+
+  try { fs.unlinkSync(SOCKET_PATH); } catch { /* ignore */ }
+  try { fs.unlinkSync(PID_PATH); } catch { /* ignore */ }
+
+  if (connection) {
+    try { await connection.disconnect(); } catch { /* ignore */ }
+  }
+
+  process.exit(0);
+}
+
+// ── Signal Handlers ─────────────────────────────────────────────────────────
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+process.on("uncaughtException", (err) => {
+  process.stderr.write(`[sidecar] Uncaught exception: ${err.message}\n`);
+  shutdown();
+});
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Ensure directories exist
+  fs.mkdirSync(path.dirname(INBOX_PATH), { recursive: true });
+
+  // Derive team name from scope
+  const teamName = MAP_SCOPE.replace("swarm:", "");
+
+  // Connect to MAP server
+  connection = await connectToMAP({
+    server: MAP_SERVER,
+    scope: MAP_SCOPE,
+    systemId: SYSTEM_ID,
+    onMessage: (message) => {
+      resetInactivityTimer();
+      try {
+        writeToInbox(message);
+      } catch (err) {
+        process.stderr.write(`[sidecar] Failed to write inbox: ${err.message}\n`);
+      }
+    },
+  });
+
+  // Start UNIX socket server
+  const onCommand = createCommandHandler(connection, MAP_SCOPE, registeredAgents);
+  socketServer = createSocketServer(SOCKET_PATH, (command, client) => {
+    resetInactivityTimer();
+    onCommand(command, client);
+  });
+
+  // Start inactivity timer
+  resetInactivityTimer();
+
+  process.stderr.write("[sidecar] Ready\n");
+}
+
+main().catch((err) => {
+  process.stderr.write(`[sidecar] Fatal: ${err.message}\n`);
+  process.exit(1);
+});

package/scripts/sync-version.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * sync-version.mjs — Sync version from package.json to plugin.json and marketplace.json
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8")).version;
+
+const files = [
+  path.join(root, ".claude-plugin", "plugin.json"),
+  path.join(root, ".claude-plugin", "marketplace.json"),
+];
+
+for (const file of files) {
+  const json = JSON.parse(fs.readFileSync(file, "utf-8"));
+  json.version = version;
+  fs.writeFileSync(file, JSON.stringify(json, null, 2) + "\n");
+  console.log(`Updated ${path.relative(root, file)} → ${version}`);
+}

package/scripts/team-loader.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * team-loader.mjs — Team loading script for claude-code-swarm
+ *
+ * Thin wrapper: resolves template, generates artifacts (with per-template caching),
+ * writes roles.json, outputs context. Replaces team-loader.sh.
+ *
+ * Usage: node team-loader.mjs [template-name-or-path] [plugin-dir]
+ */
+
+import fs from "fs";
+import { readConfig } from "../src/config.mjs";
+import {
+  resolveTemplatePath,
+  listAvailableTemplates,
+  generateTeamArtifacts,
+  readTeamManifest,
+} from "../src/template.mjs";
+import { writeRoles } from "../src/roles.mjs";
+import {
+  formatTeamLoadedContext,
+  formatNoTemplateMessage,
+  formatTemplateNotFoundMessage,
+} from "../src/context-output.mjs";
+import { teamDir } from "../src/paths.mjs";
+
+const argTemplate = process.argv[2] || "";
+
+// ── Determine template name ─────────────────────────────────────────────────
+
+let templateName = argTemplate;
+
+// Fall back to config file
+if (!templateName) {
+  const config = readConfig();
+  templateName = config.template;
+}
+
+// If no template, show available templates
+if (!templateName) {
+  const templates = listAvailableTemplates();
+  process.stdout.write(formatNoTemplateMessage(templates));
+  process.exit(0);
+}
+
+// ── Resolve template path ───────────────────────────────────────────────────
+
+const templatePath = resolveTemplatePath(templateName);
+
+if (!templatePath) {
+  process.stdout.write(formatTemplateNotFoundMessage(templateName));
+  process.exit(0);
+}
+
+// ── Generate team artifacts (per-template cache) ──────────────────────────
+
+const outputDir = teamDir(templateName);
+
+// Check cache: skip generation if SKILL.md already exists for this template
+const cached = fs.existsSync(`${outputDir}/SKILL.md`);
+
+if (!cached) {
+  const result = generateTeamArtifacts(templatePath, outputDir);
+
+  if (!result.success) {
+    process.stdout.write(
+      `## Claude Code Swarm\n\nWARNING: Failed to generate team artifacts from ${templatePath}\n${result.error || ""}\n`
+    );
+    process.exit(0);
+  }
+}
+
+// ── Write roles.json for MAP hook integration ───────────────────────────────
+
+writeRoles(templatePath);
+
+// ── Output context ──────────────────────────────────────────────────────────
+
+let teamName = templateName;
+try {
+  const manifest = readTeamManifest(templatePath);
+  teamName = manifest.name || teamName;
+} catch {
+  // Use template name as fallback
+}
+
+process.stdout.write(formatTeamLoadedContext(outputDir, templatePath, teamName));

package/settings.json

@@ -0,0 +1,13 @@
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(openteams *)",
+      "Bash(npm install -g openteams)",
+      "Bash(npm install -g @multi-agent-protocol/sdk)",
+      "Bash(node *)"
+    ]
+  }
+}