claude-code-swarm 0.3.3 → 0.3.5

package/src/sidecar-client.mjs

@@ -2,14 +2,47 @@
  * sidecar-client.mjs — UNIX socket client for communicating with the MAP sidecar
  *
  * Provides send, health check, and recovery logic used by hooks.
+ * Supports per-session sidecar instances via sessionId parameter.
  */
 
 import fs from "fs";
 import path from "path";
 import net from "net";
 import { spawn } from "child_process";
-import { SOCKET_PATH, PID_PATH, pluginDir } from "./paths.mjs";
-import { resolveScope, DEFAULTS } from "./config.mjs";
+import { SOCKET_PATH, PID_PATH, pluginDir, sessionPaths } from "./paths.mjs";
+import { resolveScope, resolveMapServer, DEFAULTS } from "./config.mjs";
+import { meshFireAndForget } from "./mesh-connection.mjs";
+
+/**
+ * Send a command to the agent-inbox IPC socket and return the response.
+ * Returns the parsed response or null on failure. Never throws.
+ */
+export function sendToInbox(command, socketPath) {
+  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);
+    }, 2000);
+  });
+}
 
 /**
  * Send a command to the sidecar via UNIX socket.
@@ -33,9 +66,9 @@ export function sendToSidecar(command, socketPath = SOCKET_PATH) {
 /**
  * Check if the sidecar process is alive via PID file.
  */
-export function isSidecarAlive() {
+export function isSidecarAlive(pidPath = PID_PATH) {
   try {
-    const pid = parseInt(fs.readFileSync(PID_PATH, "utf-8").trim());
+    const pid = parseInt(fs.readFileSync(pidPath, "utf-8").trim());
     process.kill(pid, 0);
     return true;
   } catch {
@@ -46,35 +79,47 @@ export function isSidecarAlive() {
 /**
  * Start the sidecar as a detached background process.
  * Writes PID file and waits for socket to appear (up to 2s).
+ * When sessionId is provided, the sidecar uses per-session paths.
  * Returns true if sidecar is ready.
  */
-export async function startSidecar(config, pluginDirOverride) {
+export async function startSidecar(config, pluginDirOverride, sessionId) {
   const dir = pluginDirOverride || pluginDir();
   const sidecarPath = path.join(dir, "scripts", "map-sidecar.mjs");
+  const sPaths = sessionPaths(sessionId);
 
-  const server = config.map?.server || DEFAULTS.mapServer;
+  const server = resolveMapServer(config);
   const scope = resolveScope(config);
   const systemId = config.map?.systemId || DEFAULTS.mapSystemId;
 
   try {
-    fs.mkdirSync(path.dirname(PID_PATH), { recursive: true });
-
-    const child = spawn(
-      "node",
-      [sidecarPath, "--server", server, "--scope", scope, "--system-id", systemId],
-      {
-        detached: true,
-        stdio: ["ignore", "ignore", "ignore"],
+    fs.mkdirSync(path.dirname(sPaths.pidPath), { recursive: true });
+
+    const args = [sidecarPath, "--server", server, "--scope", scope, "--system-id", systemId];
+    if (sessionId) {
+      args.push("--session-id", sessionId);
+    }
+    if (config.inbox?.enabled) {
+      args.push("--inbox-config", JSON.stringify(config.inbox));
+    }
+    if (config.mesh?.enabled) {
+      args.push("--mesh-enabled");
+      if (config.mesh.peerId) {
+        args.push("--mesh-peer-id", config.mesh.peerId);
       }
-    );
+    }
+
+    const child = spawn("node", args, {
+      detached: true,
+      stdio: ["ignore", "ignore", "ignore"],
+    });
     child.unref();
-    fs.writeFileSync(PID_PATH, String(child.pid));
+    fs.writeFileSync(sPaths.pidPath, String(child.pid));
 
     // Wait for socket to appear (up to 2s)
     for (let i = 0; i < 8; i++) {
       await new Promise((r) => setTimeout(r, 250));
-      if (fs.existsSync(SOCKET_PATH)) {
-        const ok = await sendToSidecar({ action: "ping" });
+      if (fs.existsSync(sPaths.socketPath)) {
+        const ok = await sendToSidecar({ action: "ping" }, sPaths.socketPath);
         if (ok) return true;
       }
     }
@@ -87,21 +132,28 @@ export async function startSidecar(config, pluginDirOverride) {
 
 /**
  * Kill an existing sidecar process (for session restart).
+ * When sessionId is provided, kills only that session's sidecar.
  */
-export function killSidecar() {
+export function killSidecar(sessionId) {
+  const sPaths = sessionPaths(sessionId);
   try {
-    const pid = parseInt(fs.readFileSync(PID_PATH, "utf-8").trim());
+    const pid = parseInt(fs.readFileSync(sPaths.pidPath, "utf-8").trim());
     process.kill(pid);
   } catch {
     // Process already dead or PID file missing
   }
   try {
-    fs.unlinkSync(PID_PATH);
+    fs.unlinkSync(sPaths.pidPath);
+  } catch {
+    // ignore
+  }
+  try {
+    fs.unlinkSync(sPaths.socketPath);
   } catch {
     // ignore
   }
   try {
-    fs.unlinkSync(SOCKET_PATH);
+    fs.unlinkSync(sPaths.inboxSocketPath);
   } catch {
     // ignore
   }
@@ -111,21 +163,23 @@ export function killSidecar() {
  * Ensure the sidecar is running. If not, attempt recovery.
  * Returns true if sidecar is available after this call.
  */
-export async function ensureSidecar(config) {
+export async function ensureSidecar(config, sessionId) {
+  const sPaths = sessionPaths(sessionId);
+
   // 1. Try pinging
-  const alive = await sendToSidecar({ action: "ping" });
+  const alive = await sendToSidecar({ action: "ping" }, sPaths.socketPath);
   if (alive) return true;
 
   // 2. Only attempt recovery in session mode
   if (config.map?.sidecar === "persistent") return false;
 
   // 3. Check PID
-  if (isSidecarAlive()) {
+  if (isSidecarAlive(sPaths.pidPath)) {
     // Process exists but socket not ready — wait briefly
     await new Promise((r) => setTimeout(r, 500));
-    return sendToSidecar({ action: "ping" });
+    return sendToSidecar({ action: "ping" }, sPaths.socketPath);
   }
 
   // 4. Restart sidecar
-  return startSidecar(config);
+  return startSidecar(config, undefined, sessionId);
 }

package/src/sidecar-server.mjs

@@ -3,6 +3,11 @@
  *
  * Provides the socket server that hooks communicate with, and the command
  * dispatch logic for all sidecar operations.
+ *
+ * Supports two transport modes:
+ * - "mesh": Uses inbox registry for agent lifecycle (spawn/done), MeshPeer
+ *   connection for task bridge events and trajectory.
+ * - "websocket": Uses MAP SDK primitives directly (legacy mode).
  */
 
 import fs from "fs";
@@ -37,7 +42,13 @@ export function createSocketServer(socketPath, onCommand) {
         if (!line.trim()) continue;
         try {
           const command = JSON.parse(line);
-          onCommand(command, client);
+          // Must await the async handler to catch SDK errors;
+          // without this, rejections become uncaught and crash the process.
+          onCommand(command, client).catch((err) => {
+            process.stderr.write(
+              `[sidecar] Async command error (${command.action}): ${err.message}\n`
+            );
+          });
         } catch (err) {
           process.stderr.write(
             `[sidecar] Invalid command: ${err.message}\n`
@@ -67,19 +78,27 @@ export function createSocketServer(socketPath, onCommand) {
 /**
  * Create a command handler for the sidecar socket server.
  *
- * Uses MAP SDK primitives: conn.spawn() for agent registration (server
- * auto-emits agent_registered), conn.updateState() for state changes
- * (server auto-emits agent_state_changed), and conn.send() only for
- * typed message payloads (task lifecycle). No custom swarm.* event types.
+ * In mesh mode, agent lifecycle (spawn/done) is delegated to the inbox
+ * registry when available, providing structured agent management. Task
+ * bridge events and other MAP primitives still go through the connection.
  *
- * @param {object|null} connection - MAP AgentConnection (or null if disconnected)
+ * In websocket mode, all operations use MAP SDK primitives directly
+ * (conn.spawn, conn.updateState, conn.send, etc.).
+ *
+ * @param {object|null} connection - MAP AgentConnection or MeshPeer connection
  * @param {string} scope - MAP scope name
  * @param {Map} registeredAgents - Map of agentId → spawn metadata
+ * @param {object} [opts] - Additional options
+ * @param {object} [opts.inboxInstance] - Agent-inbox instance (mesh mode)
+ * @param {object} [opts.meshPeer] - MeshPeer instance (mesh mode, for agent registration)
+ * @param {string} [opts.transportMode] - "mesh" or "websocket"
  * @returns {Function} async (command, client) => void
  */
-export function createCommandHandler(connection, scope, registeredAgents) {
+export function createCommandHandler(connection, scope, registeredAgents, opts = {}) {
   // Use a getter pattern so the connection ref can be updated
   let conn = connection;
+  const { inboxInstance, meshPeer, transportMode = "websocket" } = opts;
+  const useMeshRegistry = transportMode === "mesh" && inboxInstance;
 
   const handler = async (command, client) => {
     const { action } = command;
@@ -106,12 +125,48 @@ export function createCommandHandler(connection, scope, registeredAgents) {
           break;
         }
 
-        // --- SDK-native agent lifecycle ---
+        // --- Agent lifecycle ---
+        // In mesh mode: delegate to inbox registry
+        // In websocket mode: use MAP SDK primitives
 
         case "spawn": {
-          if (conn) {
-            const { agentId, name, role, scopes: agentScopes, metadata } =
-              command.agent;
+          const { agentId, name, role, scopes: agentScopes, metadata } =
+            command.agent;
+
+          if (useMeshRegistry) {
+            // Mesh mode: register via inbox registry + MeshPeer MapServer
+            try {
+              // Register in inbox storage for message routing
+              if (inboxInstance.storage) {
+                inboxInstance.storage.putAgent({
+                  agent_id: agentId,
+                  scope,
+                  status: "active",
+                  metadata: { name, role, ...metadata },
+                  registered_at: new Date().toISOString(),
+                  last_active_at: new Date().toISOString(),
+                });
+              }
+              registeredAgents.set(agentId, { name, role, metadata });
+
+              // Also register on the MeshPeer's MapServer for observability
+              if (meshPeer) {
+                try {
+                  await meshPeer.createAgent({ agentId, name, role, metadata });
+                } catch {
+                  // Best-effort — agent may already exist
+                }
+              }
+
+              respond(client, { ok: true, agent: { agentId, name, role } });
+            } catch (err) {
+              process.stderr.write(
+                `[sidecar] spawn (mesh) failed: ${err.message}\n`
+              );
+              respond(client, { ok: false, error: err.message });
+            }
+          } else if (conn) {
+            // WebSocket mode: use MAP SDK
             try {
               const result = await conn.spawn({
                 agentId,
@@ -135,8 +190,40 @@ export function createCommandHandler(connection, scope, registeredAgents) {
         }
 
         case "done": {
-          if (conn) {
-            const { agentId, reason } = command;
+          const { agentId, reason } = command;
+
+          if (useMeshRegistry) {
+            // Mesh mode: disconnect via inbox registry + MeshPeer MapServer
+            try {
+              // Remove from inbox storage
+              if (inboxInstance.storage) {
+                try {
+                  inboxInstance.storage.putAgent({
+                    agent_id: agentId,
+                    scope,
+                    status: "disconnected",
+                    metadata: {},
+                    registered_at: new Date().toISOString(),
+                    last_active_at: new Date().toISOString(),
+                  });
+                } catch { /* best-effort */ }
+              }
+            } catch {
+              // Agent may already be gone
+            }
+
+            // Also unregister from MeshPeer's MapServer
+            if (meshPeer) {
+              try {
+                meshPeer.server.unregisterAgent(agentId);
+              } catch {
+                // Best-effort
+              }
+            }
+
+            registeredAgents.delete(agentId);
+          } else if (conn) {
+            // WebSocket mode: use MAP SDK
             try {
               await conn.callExtension("map/agents/unregister", {
                 agentId,
@@ -184,12 +271,84 @@ export function createCommandHandler(connection, scope, registeredAgents) {
           break;
         }
 
+        // --- Task event bridge (opentasks → MAP) ---
+        // These emit task events over the shared connection using
+        // the opentasks event bridge pattern. Works identically in
+        // both mesh and websocket modes.
+
+        case "bridge-task-created": {
+          if (conn) {
+            try {
+              await conn.send({ scope }, {
+                type: "task.created",
+                task: command.task,
+                _origin: command.agentId || "opentasks",
+              }, { relationship: "broadcast" });
+            } catch { /* best effort */ }
+          }
+          respond(client, { ok: true });
+          break;
+        }
+
+        case "bridge-task-status": {
+          if (conn) {
+            try {
+              await conn.send({ scope }, {
+                type: "task.status",
+                taskId: command.taskId,
+                previous: command.previous || "open",
+                current: command.current,
+                _origin: command.agentId || "opentasks",
+              }, { relationship: "broadcast" });
+              // Also emit task.completed for terminal states
+              if (command.current === "completed" || command.current === "closed") {
+                await conn.send({ scope }, {
+                  type: "task.completed",
+                  taskId: command.taskId,
+                  _origin: command.agentId || "opentasks",
+                }, { relationship: "broadcast" });
+              }
+            } catch { /* best effort */ }
+          }
+          respond(client, { ok: true });
+          break;
+        }
+
+        case "bridge-task-assigned": {
+          if (conn) {
+            try {
+              await conn.send({ scope }, {
+                type: "task.assigned",
+                taskId: command.taskId,
+                agentId: command.assignee,
+                _origin: command.agentId || "opentasks",
+              }, { relationship: "broadcast" });
+            } catch { /* best effort */ }
+          }
+          respond(client, { ok: true });
+          break;
+        }
+
         case "state": {
           if (conn) {
             try {
               if (command.agentId) {
-                // State update for a specific child agent — update via metadata
-                const existing = registeredAgents.get(command.agentId);
+                // State update for a specific child agent
+                let agentKey = command.agentId;
+                let existing = registeredAgents.get(agentKey);
+                if (!existing) {
+                  // Extract role from fallback ID (e.g. "gsd-coordinator" → "coordinator")
+                  const fallbackRole = command.agentId.includes("-")
+                    ? command.agentId.split("-").slice(1).join("-")
+                    : command.agentId;
+                  for (const [id, entry] of registeredAgents) {
+                    if (entry.role === fallbackRole || id.endsWith(`/${fallbackRole}`)) {
+                      agentKey = id;
+                      existing = entry;
+                      break;
+                    }
+                  }
+                }
                 if (existing) {
                   existing.lastState = command.state;
                   if (command.metadata) {
@@ -212,7 +371,7 @@ export function createCommandHandler(connection, scope, registeredAgents) {
         }
 
         case "ping": {
-          respond(client, { ok: true, pid: process.pid });
+          respond(client, { ok: true, pid: process.pid, transport: transportMode });
           break;
         }
 

package/src/skilltree-client.mjs

@@ -0,0 +1,173 @@
+/**
+ * skilltree-client.mjs — Skill-tree loadout compilation for claude-code-swarm
+ *
+ * Compiles per-role skill loadouts from team.yaml skilltree extension.
+ * Uses skill-tree's SkillBank + SkillGraphServer programmatically.
+ * Results are cached per template alongside generated AGENT.md files.
+ *
+ * Never throws — returns empty results on any error (best-effort pattern).
+ */
+
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+import { getGlobalNodeModules } from "./swarmkit-resolver.mjs";
+
+const require = createRequire(import.meta.url);
+
+let _skillTree = undefined;
+
+/**
+ * Load the skill-tree module. Returns null if not available.
+ * Tries local require first, then falls back to global node_modules.
+ */
+function loadSkillTree() {
+  if (_skillTree !== undefined) return _skillTree;
+
+  // 1. Local require (works if skill-tree is in node_modules or NODE_PATH)
+  try {
+    _skillTree = require("skill-tree");
+    return _skillTree;
+  } catch {
+    // Not locally available
+  }
+
+  // 2. Global node_modules fallback (where swarmkit installs it)
+  const globalNm = getGlobalNodeModules();
+  if (globalNm) {
+    const globalPath = path.join(globalNm, "skill-tree");
+    if (fs.existsSync(globalPath)) {
+      try {
+        _skillTree = require(globalPath);
+        return _skillTree;
+      } catch {
+        // require failed
+      }
+    }
+  }
+
+  _skillTree = null;
+  return null;
+}
+
+/**
+ * Parse the skilltree extension namespace from a team.yaml manifest.
+ * Returns { defaults, roles } where defaults is a LoadoutCriteria
+ * and roles is a map of roleName → LoadoutCriteria.
+ *
+ * team.yaml example:
+ *   skilltree:
+ *     defaults:
+ *       profile: implementation
+ *       maxSkills: 6
+ *     roles:
+ *       orchestrator:
+ *         profile: code-review
+ *       executor:
+ *         profile: implementation
+ *         tags: [development]
+ *       verifier:
+ *         profile: testing
+ */
+export function parseSkillTreeExtension(manifest) {
+  const ext = manifest?.skilltree;
+  if (!ext) return { defaults: {}, roles: {} };
+
+  return {
+    defaults: ext.defaults || {},
+    roles: ext.roles || {},
+  };
+}
+
+/**
+ * Compile a skill loadout for a single role.
+ * Creates a temporary SkillBank, sets the loadout via criteria or profile,
+ * and returns the rendered markdown string.
+ *
+ * @param {string} roleName - Role name (for logging)
+ * @param {object} criteria - LoadoutCriteria (profile, tags, maxSkills, etc.)
+ * @param {object} config - Plugin config (skilltree section)
+ * @returns {Promise<string>} Rendered loadout markdown, or empty string on failure
+ */
+export async function compileRoleLoadout(roleName, criteria, config) {
+  const st = loadSkillTree();
+  if (!st?.createSkillBank) return "";
+
+  try {
+    // Determine skill bank base path
+    const basePath = config?.basePath || ".swarm/skill-tree";
+
+    // Only attempt if the base path exists
+    if (!fs.existsSync(basePath)) return "";
+
+    const bank = st.createSkillBank({
+      storage: { basePath },
+    });
+    await bank.initialize();
+
+    try {
+      const { server } = await bank.createServingLayer({
+        outputFormat: "markdown",
+      });
+
+      // Set loadout from profile or criteria
+      if (criteria.profile) {
+        try {
+          await server.setLoadoutFromProfile(criteria.profile);
+        } catch {
+          // Profile not found — skip this role
+          return "";
+        }
+      } else if (criteria.tags || criteria.include || criteria.taskDescription) {
+        await server.setLoadout(criteria);
+      } else {
+        // No criteria specified
+        return "";
+      }
+
+      return server.renderSystemPrompt();
+    } finally {
+      await bank.shutdown();
+    }
+  } catch (err) {
+    process.stderr.write(`[skilltree] Warning: loadout compilation failed for ${roleName}: ${err.message}\n`);
+    return "";
+  }
+}
+
+/**
+ * Compile skill loadouts for all roles in a team manifest.
+ * Reads the skilltree extension from the manifest, compiles loadouts per role.
+ *
+ * @param {object} manifest - Parsed team.yaml manifest
+ * @param {object} config - Plugin config (skilltree section)
+ * @returns {Promise<object>} Map of roleName → loadout markdown
+ */
+export async function compileAllRoleLoadouts(manifest, config) {
+  const { defaults, roles: roleOverrides } = parseSkillTreeExtension(manifest);
+  const allRoles = manifest.roles || [];
+  const result = {};
+
+  for (const roleName of allRoles) {
+    // Merge defaults with role-specific overrides
+    const roleCriteria = roleOverrides[roleName]
+      ? { ...defaults, ...roleOverrides[roleName] }
+      : defaults;
+
+    // Apply config-level default profile as final fallback
+    if (!roleCriteria.profile && !roleCriteria.tags && !roleCriteria.include && !roleCriteria.taskDescription) {
+      if (config?.defaultProfile) {
+        roleCriteria.profile = config.defaultProfile;
+      } else {
+        continue; // No criteria at all — skip
+      }
+    }
+
+    const loadout = await compileRoleLoadout(roleName, roleCriteria, config);
+    if (loadout) {
+      result[roleName] = loadout;
+    }
+  }
+
+  return result;
+}