claude-code-swarm 0.3.23 → 0.3.25

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/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/opentasks-bridge.mjs

@@ -0,0 +1,140 @@
+/**
+ * opentasks-bridge.mjs — Opentasks MAP event bridge for the sidecar
+ *
+ * Attaches opentasks' `createMAPEventBridge` to the local daemon's watch
+ * stream so every graph change surfaces as a `task.*` / `context.*` MAP
+ * event over the shared MAP connection. The bridge is kind-agnostic for
+ * contexts — downstream consumers (e.g. OpenHive's hub) route by
+ * `metadata.kind` to classify specs vs plain contexts.
+ *
+ * This is the "Option A" daemon-wired path — no explicit `bridge-*`
+ * sidecar command is needed for contexts. For tasks, the existing
+ * PostToolUse(TaskCreate) → `bridge-task-*` command chain remains the
+ * active path (matches the filters in sidecar-server.mjs and avoids
+ * double-emission when both hooks and the watcher fire for the same
+ * change).
+ *
+ * Extracted from map-sidecar.mjs for testability.
+ */
+
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("opentasks-bridge");
+
+/**
+ * Start the opentasks MAP event bridge.
+ *
+ * Connects to the local opentasks daemon, subscribes to graph changes,
+ * and forwards every event through the MAP event bridge so connected
+ * observers (OpenHive hub, peer swarms) see them as standard MAP events.
+ *
+ * Safe to call when the daemon isn't running or when MAP connection is
+ * absent — returns `null` and logs at debug level.
+ *
+ * @param {object} conn - MAP connection (AgentConnection or MeshPeer connection)
+ * @param {object} options
+ * @param {string} options.scope - MAP scope (e.g. "swarm:gsd")
+ * @param {() => void} [options.onActivity] - Called on each bridged event
+ * @param {() => Promise<object>} [options.importOpentasks] - Override for `await import("opentasks")`
+ * @param {() => Promise<object>} [options.importOpentasksClient] - Override for `./opentasks-client.mjs` import
+ * @returns {Promise<{ stop: () => Promise<void> } | null>}
+ */
+export async function startOpenTasksEventBridge(conn, options = {}) {
+  if (!conn) return null;
+
+  const {
+    scope = "swarm:default",
+    onActivity,
+    importOpentasks,
+    importOpentasksClient,
+  } = options;
+
+  let opentasks;
+  try {
+    opentasks = importOpentasks
+      ? await importOpentasks()
+      : await import("opentasks");
+  } catch (err) {
+    log.debug("opentasks package not available", { error: err.message });
+    return null;
+  }
+
+  const { createMAPEventBridge, createIPCClient } = opentasks || {};
+  if (!createMAPEventBridge || !createIPCClient) {
+    log.debug("opentasks event-bridge exports missing");
+    return null;
+  }
+
+  let socketPath;
+  try {
+    const opentasksClient = importOpentasksClient
+      ? await importOpentasksClient()
+      : await import("./opentasks-client.mjs");
+    socketPath = opentasksClient.findSocketPath();
+  } catch (err) {
+    log.debug("could not resolve opentasks socket path", { error: err.message });
+    return null;
+  }
+
+  const client = createIPCClient(socketPath);
+  try {
+    await client.connect();
+  } catch (err) {
+    log.debug("opentasks daemon not reachable, bridge disabled", {
+      socketPath,
+      error: err.message,
+    });
+    return null;
+  }
+
+  const bridge = createMAPEventBridge({
+    connection: conn,
+    scope,
+    agentId: `${scope}-sidecar`,
+    // Suppress bridge task.* events — the sidecar's existing
+    // `bridge-task-*` command chain (driven by PostToolUse hooks) is the
+    // canonical path for tasks. Emitting here too would duplicate every
+    // task event. Contexts have no hook counterpart, so they only flow
+    // via this watcher.
+    filter: (type) => !type.startsWith("task."),
+  });
+
+  const offNotif = client.onNotification((method, params) => {
+    if (method !== "watch.event") return;
+    if (onActivity) onActivity();
+    log.debug("watch.event received", {
+      kind: params?.type,
+      nodeId: params?.nodeId,
+      nodeType: params?.node?.type,
+    });
+    try {
+      bridge.handleProviderChange("native", { kind: "node", event: params });
+    } catch (err) {
+      log.debug("bridge.handleProviderChange threw", { error: err.message });
+    }
+  });
+
+  try {
+    await client.request("watch.subscribe", {});
+  } catch (err) {
+    log.debug("watch.subscribe failed, bridge disabled", { error: err.message });
+    offNotif();
+    try { client.disconnect(); } catch { /* ignore */ }
+    return null;
+  }
+
+  log.info("opentasks event bridge active", { scope, socketPath });
+
+  return {
+    async stop() {
+      try {
+        await client.request("watch.unsubscribe", {});
+      } catch {
+        // ignore — we're shutting down anyway
+      }
+      offNotif();
+      bridge.stop();
+      try { client.disconnect(); } catch { /* ignore */ }
+    },
+  };
+}