claude-code-swarm 0.3.24 → 0.3.26

package/src/__tests__/sidecar-nudge.test.mjs

@@ -0,0 +1,137 @@
+/**
+ * Tests for dispatch thread nudge commands on the sidecar command handler.
+ *
+ * Covers Phase 7 of dispatch-inbox-threads:
+ * - nudge command stores nudge state
+ * - check-nudge returns and clears pending nudges
+ * - Multiple nudges accumulate independently
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { createCommandHandler, respond } from "../sidecar-server.mjs";
+
+function createTestHandler() {
+  const registeredAgents = new Map();
+  return createCommandHandler(null, "swarm:test", registeredAgents, {
+    transportMode: "websocket",
+  });
+}
+
+function createFakeClient() {
+  let lastResponse = null;
+  return {
+    write(data) {
+      try {
+        lastResponse = JSON.parse(data.replace(/\n$/, ""));
+      } catch {
+        lastResponse = data;
+      }
+    },
+    writable: true,
+    getResponse() {
+      return lastResponse;
+    },
+  };
+}
+
+describe("sidecar nudge commands", () => {
+  let handler;
+
+  beforeEach(() => {
+    handler = createTestHandler();
+  });
+
+  it("check-nudge returns empty array when no nudges pending", async () => {
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.ok).toBe(true);
+    expect(resp.nudges).toEqual([]);
+  });
+
+  it("nudge stores state, check-nudge returns and clears it", async () => {
+    const fakeClient = { write: () => {}, writable: true };
+
+    // Store a nudge
+    await handler(
+      { action: "nudge", dispatch_id: "d1", conversation_id: "conv-d1" },
+      fakeClient,
+    );
+
+    // Check nudge should return it
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.ok).toBe(true);
+    expect(resp.nudges).toHaveLength(1);
+    expect(resp.nudges[0]).toEqual({
+      dispatch_id: "d1",
+      conversation_id: "conv-d1",
+    });
+
+    // Second check should be empty (cleared)
+    const client2 = createFakeClient();
+    await handler({ action: "check-nudge" }, client2);
+
+    const resp2 = client2.getResponse();
+    expect(resp2.nudges).toEqual([]);
+  });
+
+  it("accumulates multiple nudges for different dispatches", async () => {
+    const fakeClient = { write: () => {}, writable: true };
+
+    await handler(
+      { action: "nudge", dispatch_id: "d1", conversation_id: "conv-d1" },
+      fakeClient,
+    );
+    await handler(
+      { action: "nudge", dispatch_id: "d2", conversation_id: "conv-d2" },
+      fakeClient,
+    );
+
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.nudges).toHaveLength(2);
+    const ids = resp.nudges.map((n) => n.dispatch_id).sort();
+    expect(ids).toEqual(["d1", "d2"]);
+  });
+
+  it("overwrites nudge for same dispatch_id (latest wins)", async () => {
+    const fakeClient = { write: () => {}, writable: true };
+
+    await handler(
+      { action: "nudge", dispatch_id: "d1", conversation_id: "conv-old" },
+      fakeClient,
+    );
+    await handler(
+      { action: "nudge", dispatch_id: "d1", conversation_id: "conv-new" },
+      fakeClient,
+    );
+
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.nudges).toHaveLength(1);
+    expect(resp.nudges[0].conversation_id).toBe("conv-new");
+  });
+
+  it("ignores nudge with no dispatch_id", async () => {
+    const fakeClient = { write: () => {}, writable: true };
+
+    await handler(
+      { action: "nudge", conversation_id: "conv-x" },
+      fakeClient,
+    );
+
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.nudges).toEqual([]);
+  });
+});

package/src/__tests__/skilltree-client.test.mjs

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { parseSkillTreeExtension, inferProfileFromRole } from "../skilltree-client.mjs";
+import {
+  parseSkillTreeExtension,
+  inferProfileFromRole,
+  computeRoleCriteria,
+} from "../skilltree-client.mjs";
 
 describe("skilltree-client", () => {
   describe("parseSkillTreeExtension", () => {
@@ -123,4 +127,184 @@ describe("skilltree-client", () => {
       expect(inferProfileFromRole("quick-flow-dev")).toBe("implementation");
     });
   });
+
+  describe("computeRoleCriteria — priority chain", () => {
+    const baseManifest = { name: "t", roles: ["worker"] };
+
+    it("uses skilltree extension defaults when no per-role override", () => {
+      const out = computeRoleCriteria("worker", {
+        ...baseManifest,
+        skilltree: { defaults: { profile: "implementation", maxSkills: 4 } },
+      });
+      expect(out).toEqual({ profile: "implementation", maxSkills: 4 });
+    });
+
+    it("merges per-role override over defaults", () => {
+      const out = computeRoleCriteria("worker", {
+        ...baseManifest,
+        skilltree: {
+          defaults: { profile: "implementation", maxSkills: 4 },
+          roles: { worker: { profile: "code-review" } },
+        },
+      });
+      expect(out.profile).toBe("code-review");
+      expect(out.maxSkills).toBe(4);
+    });
+
+    it("openteams loadout.skills overlays on top of skilltree extension", () => {
+      const template = {
+        roles: new Map([
+          ["worker", { loadout: { skills: { profile: "security" } } }],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        {
+          ...baseManifest,
+          skilltree: { defaults: { profile: "implementation" } },
+        },
+        {},
+        template,
+      );
+      // openteams wins on profile (replace-if-set)
+      expect(out.profile).toBe("security");
+    });
+
+    it("openteams include unions with skilltree extension include", () => {
+      const template = {
+        roles: new Map([
+          [
+            "worker",
+            { loadout: { skills: { include: ["b", "c"] } } },
+          ],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        {
+          ...baseManifest,
+          skilltree: {
+            roles: { worker: { profile: "x", include: ["a", "b"] } },
+          },
+        },
+        {},
+        template,
+      );
+      expect([...out.include].sort()).toEqual(["a", "b", "c"]);
+    });
+
+    it("openteams max_tokens renames to maxTokens and replaces", () => {
+      const template = {
+        roles: new Map([
+          ["worker", { loadout: { skills: { max_tokens: 30000 } } }],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        {
+          ...baseManifest,
+          skilltree: { defaults: { profile: "x", maxTokens: 8000 } },
+        },
+        {},
+        template,
+      );
+      expect(out.maxTokens).toBe(30000);
+    });
+
+    it("falls back to config.defaultProfile when no skill-bearing criteria", () => {
+      const out = computeRoleCriteria(
+        "novel-role",
+        baseManifest,
+        { defaultProfile: "documentation" },
+      );
+      expect(out.profile).toBe("documentation");
+    });
+
+    it("falls back to inferProfileFromRole when no defaultProfile", () => {
+      const out = computeRoleCriteria("verifier", baseManifest);
+      expect(out.profile).toBe("testing");
+    });
+
+    it("returns null when no criteria can be derived", () => {
+      const out = computeRoleCriteria("brand-new-role-xyz", baseManifest);
+      expect(out).toBeNull();
+    });
+
+    it("does not invoke fallback chain when criteria already has tags", () => {
+      const out = computeRoleCriteria("worker", {
+        ...baseManifest,
+        skilltree: { defaults: { tags: ["typescript"] } },
+      });
+      expect(out.tags).toEqual(["typescript"]);
+      expect(out.profile).toBeUndefined();
+    });
+
+    it("does not invoke fallback chain when openteams provided include", () => {
+      const template = {
+        roles: new Map([
+          ["worker", { loadout: { skills: { include: ["x"] } } }],
+        ]),
+      };
+      const out = computeRoleCriteria("worker", baseManifest, {}, template);
+      expect(out.include).toEqual(["x"]);
+      // No fallback profile assigned
+      expect(out.profile).toBeUndefined();
+    });
+
+    it("accepts template.roles as a plain object (not just Map)", () => {
+      const template = {
+        roles: { worker: { loadout: { skills: { profile: "security" } } } },
+      };
+      const out = computeRoleCriteria("worker", baseManifest, {}, template);
+      expect(out.profile).toBe("security");
+    });
+
+    it("openteams overlay precedes fallback (no defaultProfile applied if openteams set profile)", () => {
+      const template = {
+        roles: new Map([
+          ["worker", { loadout: { skills: { profile: "security" } } }],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        baseManifest,
+        { defaultProfile: "implementation" },
+        template,
+      );
+      expect(out.profile).toBe("security");
+    });
+
+    it("preserves criteria fields openteams does not declare", () => {
+      const template = {
+        roles: new Map([
+          [
+            "worker",
+            { loadout: { skills: { profile: "security" } } },
+          ],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        {
+          ...baseManifest,
+          skilltree: {
+            roles: {
+              worker: {
+                profile: "x",
+                tags: ["typescript"],
+                keywords: ["frontend"],
+                maxSkills: 6,
+              },
+            },
+          },
+        },
+        {},
+        template,
+      );
+      expect(out.profile).toBe("security");
+      expect(out.tags).toEqual(["typescript"]);
+      expect(out.keywords).toEqual(["frontend"]);
+      expect(out.maxSkills).toBe(6);
+    });
+  });
 });

package/src/agent-generator.mjs

@@ -7,7 +7,16 @@
 
 import fs from "fs";
 import path from "path";
+import yaml from "js-yaml";
 import { buildCapabilitiesContext } from "./context-output.mjs";
+import { materializeLoadout } from "./loadout-materializer.mjs";
+
+/**
+ * Default command path for the scope-check PreToolUse hook.
+ * Claude Code expands ${CLAUDE_PLUGIN_ROOT} at runtime.
+ */
+const DEFAULT_HOOK_COMMAND =
+  "${CLAUDE_PLUGIN_ROOT}/scripts/scope-check.mjs";
 
 /**
  * Parse team.yaml without js-yaml dependency (basic YAML subset).
@@ -43,6 +52,67 @@ export function parseBasicYaml(content) {
   return result;
 }
 
+/**
+ * Build the frontmatter lines for an AGENT.md file.
+ *
+ * When `loadout` is provided, uses the loadout-materializer to produce
+ * enriched frontmatter (mcpServers, disallowedTools, hooks, capabilities).
+ * Otherwise falls back to the minimal legacy shape (name, description,
+ * model, tools).
+ *
+ * Returns an array of lines (no leading/trailing `---`).
+ */
+export function buildAgentFrontmatterLines({
+  roleName,
+  teamName,
+  description,
+  model,
+  tools,
+  loadout,
+  template,
+  hookCommand,
+  scopeFilePath,
+  projectPath,
+  position,
+}) {
+  if (!loadout) {
+    // Legacy minimal frontmatter — preserved verbatim for back-compat.
+    const lines = [];
+    lines.push(`name: ${teamName}-${roleName}`);
+    lines.push(`description: "${(description ?? "").replace(/"/g, '\\"')}"`);
+    if (model) lines.push(`model: ${model}`);
+    if (tools && tools.length > 0) {
+      lines.push(`tools: [${tools.join(", ")}]`);
+    }
+    return lines;
+  }
+
+  // Loadout-enriched frontmatter via materializer.
+  const { frontmatter } = materializeLoadout({
+    role: { name: roleName, description },
+    loadout,
+    template,
+    options: {
+      teamName,
+      hookCommand,
+      scopeFilePath,
+      projectPath,
+      nativeTools: tools,
+      position,
+    },
+  });
+  if (model) frontmatter.model = model;
+
+  // Serialize via js-yaml and split into lines so the caller can emit
+  // them between `---` fences.
+  const dumped = yaml.dump(frontmatter, {
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: false,
+  });
+  return dumped.replace(/\n+$/, "").split("\n");
+}
+
 /**
  * Determine which tools an agent needs based on role name, manifest, and position.
  */
@@ -79,6 +149,11 @@ export function determineTools(roleName, manifest, position, options = {}) {
 
 /**
  * Generate a Claude Code AGENT.md file content for a single role.
+ *
+ * When `loadout` is provided, the frontmatter is enriched via the
+ * loadout-materializer — adds mcpServers, disallowedTools, hooks,
+ * capabilities, and generator marker fields. When omitted, falls back
+ * to the legacy minimal frontmatter shape.
  */
 export function generateAgentMd({
   roleName,
@@ -103,19 +178,30 @@ export function generateAgentMd({
   mapEnabled,
   mapStatus,
   sessionlogSync,
+  // Loadout materialization (all optional — fall back to legacy frontmatter if absent)
+  loadout,
+  template,
+  hookCommand,
+  scopeFilePath,
+  projectPath,
 }) {
   const lines = [];
 
   // Claude Code AGENT.md frontmatter
   lines.push("---");
-  lines.push(`name: ${teamName}-${roleName}`);
-  lines.push(`description: "${description.replace(/"/g, '\\"')}"`);
-  if (model) {
-    lines.push(`model: ${model}`);
-  }
-  if (tools && tools.length > 0) {
-    lines.push(`tools: [${tools.join(", ")}]`);
-  }
+  lines.push(...buildAgentFrontmatterLines({
+    roleName,
+    teamName,
+    description,
+    model,
+    tools,
+    loadout,
+    template,
+    hookCommand: hookCommand || DEFAULT_HOOK_COMMAND,
+    scopeFilePath,
+    projectPath,
+    position,
+  }));
   lines.push("---");
   lines.push("");
 
@@ -292,6 +378,41 @@ export async function generateAllAgents(templateDir, outputDir, options = {}) {
 
       const tools = determineTools(roleName, manifest, position, options);
 
+      // Compute the scope file path the per-agent hook will read at runtime.
+      // Default: sibling of the agents output dir (<output>/../scope/<role>.json).
+      // When the role has a loadout, we ALSO write the scope file there so
+      // the frontmatter's SCOPE_FILE path always resolves at runtime.
+      const scopeDirAbs = options.scopeBasePath
+        ? path.resolve(options.scopeBasePath)
+        : path.resolve(absOutputDir, "..", "scope");
+      const scopeFileAbs = path.join(scopeDirAbs, `${roleName}.json`);
+      const scopeFilePath = options.projectPath
+        ? path.relative(options.projectPath, scopeFileAbs)
+        : scopeFileAbs;
+
+      if (role?.loadout) {
+        try {
+          const { scopeFile: scopeFileContent } = materializeLoadout({
+            role: {
+              name: roleName,
+              description: role.description,
+              displayName: role.displayName,
+            },
+            loadout: role.loadout,
+            template,
+            options: { teamName, scopeFilePath },
+          });
+          fs.mkdirSync(scopeDirAbs, { recursive: true });
+          fs.writeFileSync(
+            scopeFileAbs,
+            JSON.stringify(scopeFileContent, null, 2),
+            "utf-8"
+          );
+        } catch {
+          // Non-fatal — frontmatter still references the path; hook fails open
+        }
+      }
+
       const agentMd = generateAgentMd({
         roleName,
         teamName,
@@ -301,6 +422,12 @@ export async function generateAllAgents(templateDir, outputDir, options = {}) {
         tools,
         skillContent: roleSkill.content,
         manifest,
+        // Loadout integration (only kicks in when role.loadout is set in openteams)
+        loadout: role?.loadout,
+        template,
+        scopeFilePath,
+        projectPath: options.projectPath,
+        hookCommand: options.hookCommand,
         opentasksEnabled: options.opentasksEnabled,
         opentasksStatus: options.opentasksStatus,
         minimemEnabled: options.minimemEnabled,

package/src/bootstrap.mjs

@@ -244,16 +244,22 @@ async function startSessionSidecar(config, scope, dir, sessionId) {
 
   const ok = await startSidecar(config, dir, sessionId);
   if (ok) {
-    // Register the main Claude Code session agent with the MAP server
+    // Register the main Claude Code session agent with the MAP server.
+    // Use the inbox-derived ID (`${teamName}-main`) as the canonical agentId
+    // so MAP and inbox identities are unified — the hub can correlate a MAP
+    // agent with its inbox participant without a separate lookup table.
+    // The ephemeral sessionId is preserved in metadata for trajectory
+    // correlation and session storage.
     const teamName = resolveTeamName(config);
+    const inboxAgentId = `${teamName}-main`;
     sendCommand(config, {
       action: "spawn",
       agent: {
-        agentId: sessionId,
-        name: `${teamName}-main`,
+        agentId: inboxAgentId,
+        name: inboxAgentId,
         role: "orchestrator",
         scopes: [scope],
-        metadata: { isMain: true, sessionId },
+        metadata: { isMain: true, sessionId, inboxAgentId },
       },
     }, sessionId).catch(() => {});
 
@@ -307,9 +313,11 @@ export async function backgroundInit(config, scope, dir, sessionId) {
       }
     }
 
-    // Inbox registration
+    // Inbox registration — uses the same stable ID as the MAP registration
+    // above so both systems share a single canonical agent identity.
     if (config.map.enabled && config.inbox?.enabled) {
-      const teamName = resolveTeamName(config);
+      const inboxTeamName = resolveTeamName(config);
+      const inboxId = `${inboxTeamName}-main`;
       const sPaths = sessionId
         ? (await import("./paths.mjs")).sessionPaths(sessionId)
         : { inboxSocketPath: (await import("./paths.mjs")).INBOX_SOCKET_PATH };
@@ -319,11 +327,11 @@ export async function backgroundInit(config, scope, dir, sessionId) {
           event: {
             type: "agent.spawn",
             agent: {
-              agentId: `${teamName}-main`,
-              name: `${teamName}-main`,
+              agentId: inboxId,
+              name: inboxId,
               role: "orchestrator",
               scopes: [scope],
-              metadata: { isMain: true, sessionId },
+              metadata: { isMain: true, sessionId, inboxAgentId: inboxId },
             },
           },
         }, sPaths.inboxSocketPath).catch(() => {})

package/src/context-output.mjs

@@ -7,6 +7,8 @@
  */
 
 import fs from "fs";
+import path from "path";
+import { formatHealthReport } from "./mcp-health-checker.mjs";
 
 // ── Capabilities context (shared between main agent + spawned agents) ────────
 
@@ -259,6 +261,36 @@ export function formatBootstrapContext({
 
     lines.push(`Agent prompts: \`${team.outputDir}/agents/<role>.md\``);
     lines.push("");
+
+    // MCP health report (from loadout-aware caching) — non-blocking, informational.
+    // Only surface when the team declared providers or any loadout referenced
+    // a server; otherwise skip silently to avoid noise in non-loadout templates.
+    try {
+      const healthPath = path.join(team.outputDir, "mcp-health.json");
+      if (fs.existsSync(healthPath)) {
+        const report = JSON.parse(fs.readFileSync(healthPath, "utf-8"));
+        const anything =
+          (report.ok?.length ?? 0) +
+          (report.missing?.length ?? 0) +
+          (report.refs?.length ?? 0) +
+          (report.disabled?.length ?? 0) +
+          (report.orphanedReferences?.length ?? 0);
+        if (anything > 0) {
+          const rendered = formatHealthReport(report, { teamName: team.teamName });
+          lines.push(rendered);
+          lines.push("");
+          if (report.missing?.length > 0 || report.orphanedReferences?.length > 0) {
+            lines.push(
+              "Run `/swarm-mcp check` for details or `/swarm-mcp install <name>` " +
+                "to explicitly add a declared provider to your `.mcp.json`."
+            );
+            lines.push("");
+          }
+        }
+      }
+    } catch {
+      // Non-fatal — health is informational, never blocks bootstrap.
+    }
   }
 
   lines.push(