claude-code-swarm 0.3.24 → 0.3.26

package/src/loadout-materializer.mjs

@@ -0,0 +1,315 @@
+/**
+ * loadout-materializer.mjs — pure functions that convert openteams
+ * loadouts into Claude Code sub-agent frontmatter + sibling scope files.
+ *
+ * No filesystem writes in this module. All I/O is the caller's job.
+ * See docs/loadout-consumer-design.md for the full design.
+ *
+ * Inputs:
+ *   - role        — role object (at minimum: { name, description?, displayName? })
+ *   - loadout     — openteams ResolvedLoadout (may be undefined for loadout-less roles)
+ *   - template    — openteams ResolvedTemplate shape (mcpProviders as Map or plain object)
+ *   - options     — { teamName, projectPath, hookCommand, scopeFilePath, nativeTools, position }
+ *
+ * Output from materializeLoadout():
+ *   {
+ *     frontmatter: {...},    // YAML-serializable object for AGENT.md
+ *     scopeFile:   {...},    // JSON-serializable object for the scope-check hook
+ *     warnings:    [string], // non-fatal issues to surface to the user
+ *   }
+ */
+
+const MCP_TOOL_PREFIX = "mcp__";
+
+/**
+ * Build the full materialization result for a role.
+ */
+export function materializeLoadout({
+  role,
+  loadout,
+  template,
+  options = {},
+} = {}) {
+  if (!role || typeof role !== "object" || !role.name) {
+    throw new Error("materializeLoadout: role.name is required");
+  }
+  const warnings = [];
+  const teamName = options.teamName ?? template?.manifest?.name ?? "team";
+
+  const mcp = resolveMcpScope({
+    mcpScope: loadout?.mcpScope ?? [],
+    mcpInstalls: loadout?.mcpServers ?? [],
+    providers: toProviderMap(template?.mcpProviders),
+    warnings,
+    roleName: role.name,
+  });
+
+  const scopeFile = buildScopeFile({
+    role,
+    loadout,
+    mcp,
+    teamName,
+  });
+
+  const frontmatter = buildFrontmatter({
+    role,
+    loadout,
+    teamName,
+    mcp,
+    scopeFilePath: options.scopeFilePath,
+    hookCommand: options.hookCommand,
+    projectPath: options.projectPath,
+    nativeTools: options.nativeTools ?? defaultNativeTools(role, options),
+    position: options.position,
+  });
+
+  return { frontmatter, scopeFile, warnings };
+}
+
+// ────────────────────────────────────────────────────────────────
+// MCP scope resolution
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Normalize mcpScope (from openteams) + install-bearing mcpServers
+ * into the shapes we need:
+ *
+ *   mcpServers       — list of `string | inline` for frontmatter
+ *   disallowedTools  — list of `mcp__<server>__<tool>` for frontmatter
+ *   scope            — canonical scope list for the scope file
+ *                      (normalized server → tools?/exclude?)
+ *   refs             — symbolic refs the consumer should resolve later
+ */
+export function resolveMcpScope({
+  mcpScope = [],
+  mcpInstalls = [],
+  providers = new Map(),
+  warnings = [],
+  roleName = "",
+} = {}) {
+  const mcpServers = [];
+  const seenServers = new Set();
+  const refs = [];
+
+  // Install-bearing entries authored by the loadout itself.
+  // Inline install specs spawn a subprocess per agent invocation —
+  // we emit them verbatim but warn users about the cost.
+  for (const install of mcpInstalls) {
+    if (install && typeof install === "object" && "ref" in install) {
+      refs.push({ ref: install.ref, config: install.config });
+      // Refs resolve lazily — don't add to mcpServers until resolved.
+      continue;
+    }
+    if (install && typeof install === "object" && "name" in install) {
+      if (seenServers.has(install.name)) continue;
+      seenServers.add(install.name);
+      const inline = { [install.name]: toInlineSpec(install) };
+      mcpServers.push(inline);
+      warnings.push(
+        `Role "${roleName}": loadout inlines MCP server "${install.name}" — ` +
+          `each subagent spawn starts its own subprocess. Consider moving to ` +
+          `team.mcp_providers instead.`
+      );
+    }
+  }
+
+  // Pure-scope references. A string-ref entry gives the agent access to
+  // the named server from the session-level base set.
+  for (const entry of mcpScope) {
+    if (!entry || !entry.server) continue;
+    const name = entry.server;
+    if (!seenServers.has(name)) {
+      seenServers.add(name);
+      mcpServers.push(name);
+    }
+    // Advisory: flag if neither providers declare it nor it's inline.
+    if (!providers.has(name)) {
+      // We don't definitively know whether the consumer has this server
+      // installed externally — that's handled by the health-check step.
+      // We only warn when providers expressly omit it; the caller can
+      // downgrade or clear the warning after checking against the active set.
+      // For now, don't push — health-checker owns cross-referencing.
+    }
+  }
+
+  // Translate exclude lists into literal `mcp__<server>__<tool>` denies.
+  const disallowedTools = [];
+  for (const entry of mcpScope) {
+    if (!entry?.exclude?.length) continue;
+    for (const tool of entry.exclude) {
+      disallowedTools.push(`${MCP_TOOL_PREFIX}${entry.server}__${tool}`);
+    }
+  }
+
+  // Build the canonical scope list for the scope file (hook input).
+  const scope = mcpScope.map((entry) => {
+    const out = { server: entry.server };
+    if (entry.tools?.length) out.tools = [...entry.tools];
+    if (entry.exclude?.length) out.exclude = [...entry.exclude];
+    return out;
+  });
+
+  return { mcpServers, disallowedTools, scope, refs };
+}
+
+function toInlineSpec(install) {
+  const spec = {};
+  if (install.command) spec.command = install.command;
+  if (install.args) spec.args = [...install.args];
+  if (install.env) spec.env = { ...install.env };
+  if (install.type) spec.type = install.type;
+  return spec;
+}
+
+/**
+ * Accept either a Map (openteams native) or a plain object (cached JSON)
+ * and return a Map for consistent lookup.
+ */
+function toProviderMap(providers) {
+  if (!providers) return new Map();
+  if (providers instanceof Map) return providers;
+  return new Map(Object.entries(providers));
+}
+
+// ────────────────────────────────────────────────────────────────
+// Scope file (hook input)
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Build the JSON payload the scope-check hook reads at runtime.
+ * Includes scope declarations + loadout permissions for enforcement.
+ */
+export function buildScopeFile({ role, loadout, mcp, teamName }) {
+  const scopeFile = {
+    role: role.name,
+    team: teamName,
+    scope: mcp?.scope ?? [],
+    permissions: {
+      allow: loadout?.permissions?.allow ? [...loadout.permissions.allow] : [],
+      deny: loadout?.permissions?.deny ? [...loadout.permissions.deny] : [],
+      ask: loadout?.permissions?.ask ? [...loadout.permissions.ask] : [],
+    },
+  };
+  return scopeFile;
+}
+
+// ────────────────────────────────────────────────────────────────
+// Frontmatter assembly
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Assemble the frontmatter object for the AGENT.md file.
+ * Order of keys is deliberate for human readability when serialized.
+ */
+export function buildFrontmatter({
+  role,
+  loadout,
+  teamName,
+  mcp,
+  scopeFilePath,
+  hookCommand,
+  projectPath,
+  nativeTools,
+  position,
+}) {
+  const name = `${teamName}-${role.name}`;
+  const description =
+    role.description ||
+    loadout?.description ||
+    `${role.name} role for the ${teamName} team`;
+
+  const fm = {
+    name,
+    description,
+    team_name: teamName,
+    role: role.name,
+    generated_by: "claude-code-swarm",
+    generated_at: new Date().toISOString(),
+  };
+  if (projectPath) fm.project_path = projectPath;
+  if (position) fm.position = position;
+
+  if (nativeTools?.length) fm.tools = [...nativeTools];
+
+  if (mcp?.mcpServers?.length) fm.mcpServers = mcp.mcpServers;
+
+  if (mcp?.disallowedTools?.length) {
+    fm.disallowedTools = mcp.disallowedTools;
+  }
+
+  const needsHook = scopeNeedsHook(mcp, loadout);
+  if (needsHook && hookCommand && scopeFilePath) {
+    fm.hooks = buildHookDeclaration({
+      hookCommand,
+      scopeFilePath,
+      roleName: role.name,
+    });
+  }
+
+  if (loadout?.capabilities?.length) {
+    fm.capabilities = [...loadout.capabilities];
+  }
+
+  return fm;
+}
+
+/**
+ * We only emit a hook when there's something the hook can enforce that
+ * the static frontmatter can't — namely tool-level allowlists (no
+ * wildcard support in `tools:`) or non-empty permissions lists that
+ * aren't already materialized elsewhere.
+ */
+export function scopeNeedsHook(mcp, loadout) {
+  if (!mcp && !loadout) return false;
+  if (mcp?.scope?.some((s) => s.tools?.length)) return true;
+  if (
+    (loadout?.permissions?.allow?.length ?? 0) > 0 ||
+    (loadout?.permissions?.deny?.length ?? 0) > 0 ||
+    (loadout?.permissions?.ask?.length ?? 0) > 0
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function buildHookDeclaration({ hookCommand, scopeFilePath, roleName }) {
+  return {
+    PreToolUse: [
+      {
+        matcher: `${MCP_TOOL_PREFIX}.*`,
+        hooks: [
+          {
+            type: "command",
+            command: hookCommand,
+            env: {
+              SCOPE_FILE: scopeFilePath,
+              ROLE_NAME: roleName,
+            },
+          },
+        ],
+      },
+    ],
+  };
+}
+
+// ────────────────────────────────────────────────────────────────
+// Native tools defaulting
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Mirror the existing agent-generator.mjs behavior for default tools.
+ * Callers can override via options.nativeTools if they've already
+ * computed tools through another code path.
+ */
+function defaultNativeTools(role, options = {}) {
+  const tools = ["Read", "Glob", "Grep", "Bash"];
+  if (options.opentasksEnabled) {
+    tools.push("SendMessage");
+  } else {
+    tools.push("TaskList", "TaskUpdate", "SendMessage");
+    if (options.position === "root" || options.position === "companion") {
+      tools.push("TaskCreate");
+    }
+  }
+  return tools;
+}

package/src/map-events.mjs

@@ -63,12 +63,18 @@ export async function emitPayload(config, payload, meta, sessionId) {
 
 /**
  * Build a "spawn" sidecar command for a subagent.
+ *
+ * The agentId is derived from hookData.agent_id when available (stable,
+ * set by the spawning agent) or falls back to a timestamp-based ID.
+ * `inboxAgentId` is included in metadata so the hub can correlate MAP
+ * and inbox identities.
  */
 export function buildSubagentSpawnCommand(hookData, teamName) {
+  const agentId = hookData.agent_id || `${teamName}-subagent-${Date.now()}`;
   return {
     action: "spawn",
     agent: {
-      agentId: hookData.agent_id || `${teamName}-subagent-${Date.now()}`,
+      agentId,
       name: hookData.agent_type || "subagent",
       role: "subagent",
       scopes: [`swarm:${teamName}`],
@@ -76,6 +82,7 @@ export function buildSubagentSpawnCommand(hookData, teamName) {
         agentType: hookData.agent_type || "",
         sessionId: hookData.session_id || "",
         isTeamRole: false,
+        inboxAgentId: agentId,
       },
     },
   };

package/src/mcp-health-checker.mjs

@@ -0,0 +1,237 @@
+/**
+ * mcp-health-checker.mjs — compare declared MCP providers against the
+ * set of servers known to be installed, produce a report, and format it
+ * for human consumption.
+ *
+ * Two entry points:
+ *   checkMcpHealth({ providers, activeSet, scopeReferences }) — pure
+ *   discoverActiveSet({ projectPath, pluginPath, userPath }) — reads fs
+ *
+ * See docs/loadout-consumer-design.md for the non-invasive design.
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+/**
+ * Compare declared providers against the active set and return a report.
+ * Pure function — no I/O. Consumers supply the active-set via discoverActiveSet
+ * or their own logic (e.g. hive DB lookup).
+ *
+ * @param providers         Map<string, McpProviderSpec> or plain object from team.yaml
+ * @param activeSet         Map<string, { source, spec? }> of installed servers
+ * @param scopeReferences   [{ loadout, server }] — which loadouts reference which servers
+ * @returns {MCPHealthReport}
+ */
+export function checkMcpHealth({
+  providers,
+  activeSet = new Map(),
+  scopeReferences = [],
+} = {}) {
+  const providerMap = toMap(providers);
+  const activeMap = toMap(activeSet);
+
+  const ok = [];
+  const missing = [];
+  const disabled = [];
+  const refs = [];
+
+  for (const [name, spec] of providerMap) {
+    if (spec?.disabled) {
+      disabled.push({ name, spec });
+      continue;
+    }
+    if (spec?.ref) {
+      refs.push({ name, ref: spec.ref, spec });
+      continue;
+    }
+    const active = activeMap.get(name);
+    if (active) {
+      ok.push({ name, source: active.source, spec });
+    } else {
+      missing.push({ name, spec });
+    }
+  }
+
+  // Active servers that are NOT declared in providers — informational only.
+  // Useful for detecting plugin MCPs or user-installed servers the team
+  // template wasn't aware of but can still reference in scope.
+  const activeOnly = [];
+  for (const [name, active] of activeMap) {
+    if (!providerMap.has(name)) {
+      activeOnly.push({ name, source: active.source });
+    }
+  }
+
+  // Scope references that aren't backed by providers OR active servers.
+  // These are the "loadout X wants server Y but it's not available" cases.
+  const orphanedReferences = [];
+  const availableSet = new Set([...providerMap.keys(), ...activeMap.keys()]);
+  for (const ref of scopeReferences) {
+    if (!ref?.server) continue;
+    if (!availableSet.has(ref.server)) {
+      orphanedReferences.push({ loadout: ref.loadout, server: ref.server });
+    }
+  }
+
+  return {
+    ok,
+    missing,
+    disabled,
+    refs,
+    activeOnly,
+    orphanedReferences,
+  };
+}
+
+/**
+ * Collect the set of MCP servers known to be installed by reading the
+ * well-known Claude Code configuration paths.
+ *
+ * Priority order (later wins on conflict):
+ *   1. Plugin MCPs (.claude-plugin/plugin.json:mcpServers)
+ *   2. User MCPs (~/.claude/mcp.json:mcpServers or ~/.claude.json:mcpServers)
+ *   3. Project MCPs (.mcp.json:mcpServers)
+ *
+ * Returns a Map<string, { source, spec }> describing which server came
+ * from where. Silently skips files that don't exist or fail to parse —
+ * this is read-only observation, not config validation.
+ */
+export function discoverActiveSet({
+  projectPath = process.cwd(),
+  pluginPath,
+  userHome = os.homedir(),
+} = {}) {
+  const active = new Map();
+
+  // 1. Plugin MCPs — lowest priority
+  if (pluginPath) {
+    const pluginManifest = path.join(pluginPath, ".claude-plugin", "plugin.json");
+    mergeMcpServers(active, pluginManifest, "plugin");
+  }
+
+  // 2. User MCPs — middle priority
+  const userMcp = path.join(userHome, ".claude", "mcp.json");
+  mergeMcpServers(active, userMcp, "user");
+
+  // 3. Project MCPs — highest priority
+  const projectMcp = path.join(projectPath, ".mcp.json");
+  mergeMcpServers(active, projectMcp, "project");
+
+  return active;
+}
+
+/**
+ * Scan a loadouts map for every scope reference — useful input for
+ * checkMcpHealth's scopeReferences arg. Accepts either openteams' native
+ * Map<name, ResolvedLoadout> or a plain object of the same shape.
+ */
+export function collectScopeReferences(loadouts) {
+  const out = [];
+  const it = toMap(loadouts);
+  for (const [name, lo] of it) {
+    const scope = lo?.mcpScope ?? [];
+    for (const entry of scope) {
+      if (entry?.server) {
+        out.push({ loadout: name, server: entry.server });
+      }
+    }
+  }
+  return out;
+}
+
+// ────────────────────────────────────────────────────────────────
+// Formatting — human-readable report
+// ────────────────────────────────────────────────────────────────
+
+const STATUS = {
+  ok: "✓",
+  missing: "⚠",
+  refs: "◎",
+  disabled: "○",
+};
+
+/**
+ * Render a report as a text block suitable for terminal output.
+ * ASCII-only — no terminal-color escapes (callers can colorize).
+ */
+export function formatHealthReport(report, { teamName = "team" } = {}) {
+  const lines = [];
+  lines.push(`Team "${teamName}" MCP status`);
+  lines.push("─".repeat(40));
+
+  if (
+    report.ok.length === 0 &&
+    report.missing.length === 0 &&
+    report.refs.length === 0 &&
+    report.disabled.length === 0
+  ) {
+    lines.push("(no MCP providers declared; team may use installed servers)");
+  }
+
+  for (const e of report.ok) {
+    lines.push(`  ${STATUS.ok} ${e.name}  (${e.source})`);
+  }
+  for (const e of report.missing) {
+    lines.push(`  ${STATUS.missing} ${e.name}  (declared, not active)`);
+    lines.push(`      → /swarm mcp install ${e.name}`);
+  }
+  for (const e of report.refs) {
+    lines.push(`  ${STATUS.refs} ${e.name}  (ref: ${e.ref})`);
+    lines.push(`      → ref resolution deferred`);
+  }
+  for (const e of report.disabled) {
+    lines.push(`  ${STATUS.disabled} ${e.name}  (disabled)`);
+  }
+
+  if (report.orphanedReferences.length > 0) {
+    lines.push("");
+    lines.push("Loadout scope references not backed by any provider:");
+    for (const r of report.orphanedReferences) {
+      lines.push(`  - loadout "${r.loadout}" uses "${r.server}"`);
+    }
+  }
+
+  if (report.activeOnly.length > 0) {
+    lines.push("");
+    lines.push(`Active servers not declared: ${report.activeOnly.map((a) => a.name).join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ────────────────────────────────────────────────────────────────
+// Internals
+// ────────────────────────────────────────────────────────────────
+
+function toMap(input) {
+  if (!input) return new Map();
+  if (input instanceof Map) return input;
+  return new Map(Object.entries(input));
+}
+
+function mergeMcpServers(active, jsonPath, source) {
+  if (!fs.existsSync(jsonPath)) return;
+  let doc;
+  try {
+    doc = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
+  } catch {
+    return;
+  }
+  const mcp = doc?.mcpServers;
+  if (!mcp || typeof mcp !== "object") return;
+  for (const [name, spec] of Object.entries(mcp)) {
+    active.set(name, { source, spec });
+  }
+}
+
+/**
+ * @typedef {Object} MCPHealthReport
+ * @property {Array<{name: string, source: string, spec: object}>} ok
+ * @property {Array<{name: string, spec: object}>} missing
+ * @property {Array<{name: string, spec: object}>} disabled
+ * @property {Array<{name: string, ref: string, spec: object}>} refs
+ * @property {Array<{name: string, source: string}>} activeOnly
+ * @property {Array<{loadout: string, server: string}>} orphanedReferences
+ */

package/src/sidecar-server.mjs

@@ -99,6 +99,11 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
   const { inboxInstance, meshPeer, transportMode = "websocket" } = opts;
   const useMeshRegistry = transportMode === "mesh" && inboxInstance;
 
+  // Dispatch thread nudge state — set by x-dispatch/nudge notifications,
+  // consumed by the UserPromptSubmit hook via the check-nudge command.
+  // Keyed by dispatch_id → { conversation_id, received_at }.
+  const _pendingNudges = new Map();
+
   // Connection-ready gate: commands that need `conn` await this promise.
   // If connection is already available, resolves immediately.
   // When connection arrives later (via setConnection), resolves the pending promise.
@@ -474,6 +479,37 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
           break;
         }
 
+        // --- Dispatch thread nudge ---
+        // Set by x-dispatch/nudge MAP notifications, consumed by hooks.
+
+        case "nudge": {
+          // Called internally when the notification handler fires.
+          const { dispatch_id, conversation_id } = command;
+          if (dispatch_id) {
+            _pendingNudges.set(dispatch_id, {
+              conversation_id,
+              received_at: Date.now(),
+            });
+          }
+          respond(client, { ok: true });
+          break;
+        }
+
+        case "check-nudge": {
+          // Called by UserPromptSubmit hook. Returns and clears all
+          // pending nudges so the hook can inject a hint.
+          const nudges = [];
+          for (const [dispatchId, info] of _pendingNudges) {
+            nudges.push({
+              dispatch_id: dispatchId,
+              conversation_id: info.conversation_id,
+            });
+          }
+          _pendingNudges.clear();
+          respond(client, { ok: true, nudges });
+          break;
+        }
+
         default:
           respond(client, { ok: false, error: `Unknown action: ${action}` });
       }