claude-code-swarm 0.3.4 → 0.3.5

package/scripts/map-sidecar.mjs

@@ -2,18 +2,28 @@
 /**
  * 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.
+ * Two-socket, one-process architecture:
+ * - Lifecycle socket: spawn/done/state/trajectory-checkpoint (existing protocol)
+ * - Inbox socket: agent-inbox IPC for messaging (send/check_inbox/notify)
+ *
+ * Transport modes:
+ * - Mesh (preferred): Embedded MeshPeer + agent-inbox Phase 2 integration.
+ *   MeshPeer handles transport, encryption, discovery. Agent-inbox handles
+ *   messaging, registry, federation. ~200 lines of adapter code.
+ * - WebSocket (fallback): Direct MAP SDK connection (legacy mode).
+ *   Used when agentic-mesh is not available.
  *
  * Usage: node map-sidecar.mjs --server ws://localhost:8080 --scope swarm:team --system-id system-id
+ *          [--session-id id] [--inbox-config json] [--inactivity-timeout ms]
+ *          [--mesh-peer-id id] [--mesh-enabled]
  */
 
 import fs from "fs";
 import path from "path";
-import { INBOX_PATH, SOCKET_PATH, PID_PATH } from "../src/paths.mjs";
+import { SOCKET_PATH, PID_PATH, INBOX_SOCKET_PATH, sessionPaths } from "../src/paths.mjs";
 import { connectToMAP } from "../src/map-connection.mjs";
+import { createMeshPeer, createMeshInbox } from "../src/mesh-connection.mjs";
 import { createSocketServer, createCommandHandler } from "../src/sidecar-server.mjs";
-import { writeToInbox } from "../src/inbox.mjs";
 
 // ── Parse CLI args ──────────────────────────────────────────────────────────
 
@@ -22,17 +32,43 @@ function getArg(name, defaultValue = "") {
   const idx = args.indexOf(`--${name}`);
   return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : defaultValue;
 }
-
+function hasFlag(name) {
+  return args.includes(`--${name}`);
+}
 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
+const SESSION_ID = getArg("session-id", "");
+const INACTIVITY_TIMEOUT_MS = parseInt(getArg("inactivity-timeout", ""), 10) || 30 * 60 * 1000;
+
+// Mesh transport args
+const MESH_ENABLED = hasFlag("mesh-enabled");
+const MESH_PEER_ID = getArg("mesh-peer-id", "");
+
+// Parse inbox config (passed as JSON blob from sidecar-client)
+let INBOX_CONFIG = null;
+const inboxConfigJson = getArg("inbox-config", "");
+if (inboxConfigJson) {
+  try {
+    INBOX_CONFIG = JSON.parse(inboxConfigJson);
+  } catch {
+    process.stderr.write("[sidecar] Warning: invalid --inbox-config JSON, inbox disabled\n");
+  }
+}
+
+// Resolve per-session or legacy paths
+const sPaths = SESSION_ID
+  ? sessionPaths(SESSION_ID)
+  : { socketPath: SOCKET_PATH, inboxSocketPath: INBOX_SOCKET_PATH, pidPath: PID_PATH };
 
 // ── State ───────────────────────────────────────────────────────────────────
 
 let connection = null;
+let meshPeer = null;
 let socketServer = null;
+let inboxInstance = null;
 let inactivityTimer = null;
+let transportMode = "websocket"; // "mesh" or "websocket"
 const registeredAgents = new Map();
 
 // ── Inactivity Timer ────────────────────────────────────────────────────────
@@ -51,15 +87,27 @@ async function shutdown() {
   process.stderr.write("[sidecar] Shutting down...\n");
 
   if (inactivityTimer) clearTimeout(inactivityTimer);
+
+  // Stop agent-inbox first (it borrows the connection/peer, doesn't own it)
+  if (inboxInstance) {
+    try { await inboxInstance.stop(); } catch { /* ignore */ }
+  }
+
   if (socketServer) socketServer.close();
 
-  try { fs.unlinkSync(SOCKET_PATH); } catch { /* ignore */ }
-  try { fs.unlinkSync(PID_PATH); } catch { /* ignore */ }
+  try { fs.unlinkSync(sPaths.socketPath); } catch { /* ignore */ }
+  try { fs.unlinkSync(sPaths.inboxSocketPath); } catch { /* ignore */ }
+  try { fs.unlinkSync(sPaths.pidPath); } catch { /* ignore */ }
 
   if (connection) {
     try { await connection.disconnect(); } catch { /* ignore */ }
   }
 
+  // Stop MeshPeer after disconnecting the connection that uses it
+  if (meshPeer) {
+    try { await meshPeer.stop(); } catch { /* ignore */ }
+  }
+
   process.exit(0);
 }
 
@@ -71,34 +119,138 @@ process.on("uncaughtException", (err) => {
   process.stderr.write(`[sidecar] Uncaught exception: ${err.message}\n`);
   shutdown();
 });
+process.on("unhandledRejection", (reason) => {
+  const msg = reason instanceof Error ? reason.message : String(reason);
+  process.stderr.write(`[sidecar] Unhandled rejection: ${msg}\n`);
+  // Don't shutdown — log and continue. The rejection is likely from a
+  // non-critical SDK operation (e.g. scope-based send, state update).
+});
 
-// ── Main ────────────────────────────────────────────────────────────────────
-
-async function main() {
-  // Ensure directories exist
-  fs.mkdirSync(path.dirname(INBOX_PATH), { recursive: true });
+// ── Transport Setup ─────────────────────────────────────────────────────────
 
-  // Derive team name from scope
+/**
+ * Try to start with MeshPeer transport (preferred).
+ * Returns true if mesh transport was established.
+ */
+async function tryMeshTransport() {
   const teamName = MAP_SCOPE.replace("swarm:", "");
+  const peerId = MESH_PEER_ID || `${teamName}-sidecar`;
 
-  // Connect to MAP server
+  const result = await createMeshPeer({
+    peerId,
+    scope: MAP_SCOPE,
+    systemId: SYSTEM_ID,
+    mapServer: MAP_SERVER !== "ws://localhost:8080" ? MAP_SERVER : undefined,
+    onMessage: () => resetInactivityTimer(),
+  });
+
+  if (!result) return false;
+
+  meshPeer = result.peer;
+  connection = result.connection;
+  transportMode = "mesh";
+
+  // Start agent-inbox with MeshPeer (Phase 2 integration)
+  if (INBOX_CONFIG || true) {
+    // Always try mesh inbox — it handles agent registry + messaging
+    inboxInstance = await createMeshInbox({
+      meshPeer: result.peer,
+      scope: MAP_SCOPE,
+      systemId: SYSTEM_ID,
+      socketPath: sPaths.inboxSocketPath,
+      inboxConfig: INBOX_CONFIG || {},
+    });
+  }
+
+  return true;
+}
+
+/**
+ * Start with direct MAP SDK WebSocket transport (fallback).
+ */
+async function startWebSocketTransport() {
   connection = await connectToMAP({
     server: MAP_SERVER,
     scope: MAP_SCOPE,
     systemId: SYSTEM_ID,
-    onMessage: (message) => {
+    onMessage: () => {
       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) => {
+  transportMode = "websocket";
+
+  // Start agent-inbox with MAP connection (legacy mode)
+  if (INBOX_CONFIG && connection) {
+    inboxInstance = await startLegacyAgentInbox(connection);
+  }
+}
+
+/**
+ * Start agent-inbox in legacy mode (shared MAP connection, no MeshPeer).
+ */
+async function startLegacyAgentInbox(mapConnection) {
+  if (!INBOX_CONFIG) return null;
+
+  try {
+    const { createAgentInbox } = await import("agent-inbox");
+
+    const peers = INBOX_CONFIG.federation?.peers || [];
+    const federationConfig = peers.length > 0
+      ? {
+          systemId: SYSTEM_ID,
+          peers,
+          routing: INBOX_CONFIG.federation?.routing,
+          trust: INBOX_CONFIG.federation?.trust,
+        }
+      : undefined;
+
+    const opts = {
+      connection: mapConnection,
+      config: {
+        socketPath: sPaths.inboxSocketPath,
+        scope: MAP_SCOPE,
+        federation: federationConfig,
+      },
+      enableFederation: peers.length > 0,
+      sqlitePath: INBOX_CONFIG.sqlite || undefined,
+      httpPort: INBOX_CONFIG.httpPort || 0,
+      webhooks: INBOX_CONFIG.webhooks?.length ? INBOX_CONFIG.webhooks : undefined,
+    };
+
+    const inbox = await createAgentInbox(opts);
+    process.stderr.write(`[sidecar] Agent Inbox started (websocket mode) on ${sPaths.inboxSocketPath}\n`);
+    return inbox;
+  } catch (err) {
+    process.stderr.write(`[sidecar] Agent Inbox not available: ${err.message}\n`);
+    return null;
+  }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  // Ensure directories exist
+  fs.mkdirSync(path.dirname(sPaths.pidPath), { recursive: true });
+
+  // Try mesh transport first, fall back to WebSocket
+  if (MESH_ENABLED) {
+    const meshOk = await tryMeshTransport();
+    if (!meshOk) {
+      process.stderr.write("[sidecar] Mesh transport unavailable, falling back to WebSocket\n");
+      await startWebSocketTransport();
+    }
+  } else {
+    await startWebSocketTransport();
+  }
+
+  // Start lifecycle UNIX socket server
+  const onCommand = createCommandHandler(connection, MAP_SCOPE, registeredAgents, {
+    inboxInstance,
+    meshPeer,
+    transportMode,
+  });
+  socketServer = createSocketServer(sPaths.socketPath, (command, client) => {
     resetInactivityTimer();
     onCommand(command, client);
   });
@@ -106,7 +258,9 @@ async function main() {
   // Start inactivity timer
   resetInactivityTimer();
 
-  process.stderr.write("[sidecar] Ready\n");
+  const modeLabel = transportMode === "mesh" ? "mesh" : "websocket";
+  const inboxLabel = inboxInstance ? " [inbox active]" : "";
+  process.stderr.write(`[sidecar] Ready (${modeLabel})${SESSION_ID ? ` (session: ${SESSION_ID})` : ""}${inboxLabel}\n`);
 }
 
 main().catch((err) => {

package/scripts/team-loader.mjs

@@ -3,26 +3,21 @@
  * 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.
+ * writes roles.json, outputs context.
  *
- * Usage: node team-loader.mjs [template-name-or-path] [plugin-dir]
+ * Usage: node team-loader.mjs [template-name-or-path]
  */
 
-import fs from "fs";
 import { readConfig } from "../src/config.mjs";
 import {
-  resolveTemplatePath,
+  loadTeam,
   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] || "";
 
@@ -43,45 +38,21 @@ if (!templateName) {
   process.exit(0);
 }
 
-// ── Resolve template path ───────────────────────────────────────────────────
+// ── Load team (resolve, generate/cache, write roles.json) ─────────────────
 
-const templatePath = resolveTemplatePath(templateName);
+const result = await loadTeam(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) {
+if (!result.success) {
+  if (!result.templatePath) {
+    process.stdout.write(formatTemplateNotFoundMessage(templateName));
+  } else {
     process.stdout.write(
-      `## Claude Code Swarm\n\nWARNING: Failed to generate team artifacts from ${templatePath}\n${result.error || ""}\n`
+      `## Claude Code Swarm\n\nWARNING: Failed to generate team artifacts from ${result.templatePath}\n${result.error || ""}\n`
     );
-    process.exit(0);
   }
+  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));
+process.stdout.write(formatTeamLoadedContext(result.outputDir, result.templatePath, result.teamName));

package/skills/swarm/SKILL.md

@@ -1,71 +1,135 @@
 ---
 name: swarm
-description: Launch an agent team from an openteams topology template. Creates a native Claude Code team and spawns a coordinator agent.
+description: Launch an agent team from an openteams topology template. Creates a native Claude Code team and spawns all agents directly.
 user_invocable: true
 argument: optional
 ---
 
 # /swarm — Launch a Team Topology
 
-You are the **swarm launcher** for the claude-code-swarm plugin. Your job is to launch a coordinated agent team from an openteams YAML topology template using Claude Code's native team features.
+You are the **swarm orchestrator** for the claude-code-swarm plugin. Your job is to launch and coordinate an agent team from an openteams YAML topology template using Claude Code's native team features.
+
+**Important**: Only the main agent (you) can spawn teammates. Spawned teammates cannot spawn other teammates — this is a Claude Code limitation. You must act as the orchestrator: spawn all agents, create tasks, and coordinate the team directly.
 
 ## What to do
 
 Follow these steps in order. Be efficient — do not debug or retry failed commands, just proceed to the next step.
 
-### Step 1: Find the plugin directory and generate artifacts
+### Step 1: Locate team artifacts
 
-The plugin directory is listed in the system init message under `plugins` (look for `claude-code-swarm` and use its `path`). If you cannot find it there, run:
+Check the session init context for **"Team artifacts ready"** — the bootstrap hook pre-loads the configured template and outputs the artifact paths (SKILL.md and agent prompts directory).
 
-```bash
-find ~/.claude/plugins -name "plugin.json" -path "*/claude-code-swarm/*" -exec dirname {} \; 2>/dev/null | head -1 | xargs dirname 2>/dev/null
-```
+If the artifact paths are already shown in the init context, skip to **Step 2** using those paths.
 
-The template name comes from `$ARGUMENTS` (e.g. `gsd`). If none provided, ask the user. Templates available via openteams: **gsd**, **bmad-method**, **bug-fix-pipeline**, **docs-sync**, **security-audit** (and more).
+If no artifacts are shown (e.g. the user specified a different template via `$ARGUMENTS`, or no template was configured), generate them:
 
-Generate artifacts with the team-loader script (this handles dependency resolution, artifact generation, and roles.json):
+1. Find the plugin directory from the system init message under `plugins` (look for `claude-code-swarm` and use its `path`). Fallback:
+   ```bash
+   find ~/.claude/plugins -name "plugin.json" -path "*/claude-code-swarm/*" -exec dirname {} \; 2>/dev/null | head -1 | xargs dirname 2>/dev/null
+   ```
 
-```bash
-node "$PLUGIN_DIR/scripts/team-loader.mjs" "<template-name>"
-```
+2. The template name comes from `$ARGUMENTS` (e.g. `gsd`). If none provided, ask the user. Templates available via openteams: **gsd**, **bmad-method**, **bug-fix-pipeline**, **docs-sync**, **security-audit** (and more).
+
+3. Run the team-loader:
+   ```bash
+   node "$PLUGIN_DIR/scripts/team-loader.mjs" "<template-name>"
+   ```
+   The output contains the artifact paths.
 
 ### Step 2: Read the generated artifacts
 
-1. Read `.swarm/claude-swarm/tmp/teams/<template-name>/SKILL.md` — the team catalog overview
-2. Read `.swarm/claude-swarm/tmp/teams/<template-name>/agents/<root-role>.md` — the root agent's prompt (the root role is typically `orchestrator` for gsd, `master` for bmad-method)
+1. Read the **SKILL.md** from the artifact path — this is the team catalog overview (topology, roles, relationships)
+2. Read agent prompts from the `agents/` subdirectory (e.g. `agents/<role>.md`) as needed before spawning each role
+
+Use the SKILL.md to understand the topology: which roles exist, the root role, companions, and spawn rules. You don't need to read every agent prompt upfront — read them as needed before spawning each agent.
 
 ### Step 3: Create the native team
 
 ```
 TeamCreate(
   team_name="<template-name>",
-  description="<description from team-loader output>"
+  description="<description from SKILL.md>"
 )
 ```
 
-### Step 4: Spawn the coordinator agent
+### Step 4: Create tasks based on the user's goal
+
+Break down the user's goal into tasks using `TaskCreate`. Consider the topology's structure:
+- Which roles are needed for this goal?
+- What's the logical order of work (dependencies)?
+- Which tasks can run in parallel?
+
+Create tasks with clear descriptions and set up dependencies with `addBlockedBy` where needed.
 
-Build a coordinator prompt combining the root role's agent.md content, coordinator instructions, and the user's goal. Then spawn:
+### Step 5: Spawn agents and assign tasks
+
+For each role needed, read its agent prompt and spawn it as a teammate:
 
 ```
 Agent(
-  name="<root-role-name>",
+  name="<role-name>",
   team_name="<template-name>",
-  prompt="<coordinator prompt>"
+  prompt="<agent prompt content + assigned task context>"
 )
 ```
 
-The coordinator prompt should tell the agent to:
-- Spawn companion agents (with `team_name`) by reading their `.swarm/claude-swarm/tmp/teams/<template-name>/agents/<role>.md`
-- Create tasks via `TaskCreate` based on the user's goal
-- Spawn additional agents on-demand per spawn_rules (always with `team_name`)
-- Coordinate via `SendMessage` and track progress via `TaskList`/`TaskUpdate`
+Spawn agents in parallel where possible (multiple Agent calls in one message). Include in each agent's prompt:
+- The content from their `.md` agent file
+- Which task(s) they should work on
+- Any relevant context from the user's goal
+
+After spawning, assign tasks to agents via `TaskUpdate(owner="<role-name>")`.
+
+### Step 6: Coordinate the team
+
+As the orchestrator, you are responsible for:
+- **Monitoring progress** via `TaskList` — check what's completed, what's blocked
+- **Spawning additional agents** on demand as new work is identified
+- **Relaying information** between agents via `SendMessage` when needed
+- **Unblocking work** — if a task is blocked, check if the dependency is met and update accordingly
+- **Synthesizing results** — when all tasks are complete, summarize outcomes for the user
+
+Respond to teammate messages as they come in. When teammates finish and go idle, check if there's more work to assign or if the team's goal is met.
+
+### Step 7: Clean up
 
-**Stop here.** The coordinator handles everything from this point.
+When all work is complete:
+1. Send shutdown requests to all teammates
+2. Clean up the team with `TeamDelete`
+3. Summarize the results to the user
 
 ## Important Notes
 
+- **You are the only agent that can spawn teammates** — do not instruct agents to spawn other agents
 - **openteams is config-only** — used only for artifact generation, NOT for runtime coordination
 - **Use Claude Code native teams** for all runtime: `TeamCreate`, `TaskCreate`, `TaskUpdate`, `SendMessage`
 - All agents must be spawned with `team_name` so they share the team's task list
 - If MAP is enabled in `.swarm/claude-swarm/config.json`, lifecycle events are handled automatically by hooks
+- Start with the most critical roles first — you don't need to spawn all roles from the topology at once
+- Keep team size manageable (3-5 agents) — spawn more only when genuinely needed
+
+## When minimem is enabled
+
+If minimem is configured (check init context for "Memory: ready"):
+- All agents have access to **minimem MCP tools** for searching and storing memories
+- Use `minimem__memory_search` to find relevant past decisions, patterns, and context
+- Use `minimem__knowledge_search` to search with domain or entity filters
+- Memories are shared team-wide — all agents search the same memory store
+- Instruct agents to search memory before starting major work for relevant prior context
+
+## When skill-tree is enabled
+
+If skill-tree is configured (check init context for "Skills: ready"):
+- Per-role skill loadouts are compiled from the team.yaml `skilltree:` extension and embedded in agent prompts
+- Agents receive their role-appropriate skills automatically in their AGENT.md — no runtime action needed
+- Skills are cached per template alongside other artifacts
+- To update loadouts, delete the template cache directory and reload
+
+## When opentasks is enabled
+
+If opentasks is configured (check init context for "Opentasks: connected"):
+- Use **opentasks MCP tools** instead of native `TaskCreate`/`TaskUpdate`/`TaskList`
+- `opentasks__create_task` to create tasks
+- `opentasks__update_task` to assign and update status
+- `opentasks__list_tasks` to check progress
+- Native task tools may be unavailable — opentasks provides richer task management (links, annotations, cross-provider queries)

package/src/__tests__/agent-generator.test.mjs

@@ -57,19 +57,19 @@ describe("agent-generator", () => {
       expect(tools).toContain("SendMessage");
     });
 
-    it("adds Write, Edit, Agent, TaskCreate for root position", () => {
+    it("adds Write, Edit, TaskCreate for root position (no Agent)", () => {
       const tools = determineTools("lead", minManifest, "root");
       expect(tools).toContain("Write");
       expect(tools).toContain("Edit");
-      expect(tools).toContain("Agent");
       expect(tools).toContain("TaskCreate");
+      expect(tools).not.toContain("Agent");
     });
 
-    it("adds Write, Edit, Agent, TaskCreate for companion position", () => {
+    it("adds Write, Edit, TaskCreate for companion position (no Agent)", () => {
       const tools = determineTools("helper", minManifest, "companion");
       expect(tools).toContain("Write");
-      expect(tools).toContain("Agent");
       expect(tools).toContain("TaskCreate");
+      expect(tools).not.toContain("Agent");
     });
 
     it("does not add Write for regular spawned position", () => {
@@ -78,17 +78,10 @@ describe("agent-generator", () => {
       expect(tools).not.toContain("Edit");
     });
 
-    it("adds Agent when spawn_rules allow spawning", () => {
+    it("does not add Agent for spawn_rules (teammates cannot spawn)", () => {
       const manifest = { topology: { spawn_rules: { planner: ["executor"] } } };
       const tools = determineTools("planner", manifest, "spawned");
-      expect(tools).toContain("Agent");
-    });
-
-    it("does not duplicate Agent if already present for root", () => {
-      const manifest = { topology: { spawn_rules: { lead: ["dev"] } } };
-      const tools = determineTools("lead", manifest, "root");
-      const agentCount = tools.filter((t) => t === "Agent").length;
-      expect(agentCount).toBe(1);
+      expect(tools).not.toContain("Agent");
     });
 
     it("adds Write, Edit for executor role", () => {