claude-code-swarm 0.3.23 → 0.3.25

package/src/skilltree-client.mjs

@@ -149,40 +149,137 @@ export function inferProfileFromRole(roleName) {
   return "";
 }
 
+// ────────────────────────────────────────────────────────────────
+// Openteams ↔ skill-tree bridge
+//
+// The bridge between openteams `loadout.skills` (SkillsConfig in the
+// schema) and skill-tree's LoadoutCriteria. skill-tree is the
+// *mechanism*; openteams is the *declaration layer* that dispatches
+// into it. See openhive's docs/LOADOUT_INTEGRATION.md for the model.
+//
+// Bridged fields are locked in by src/__tests__/loadout-schema-bridge.test.mjs
+// which cross-references this list against openteams' SkillsConfig schema.
+// Adding a field on either side without updating the other fails the test.
+// ────────────────────────────────────────────────────────────────
+
+/** Fields on openteams `loadout.skills` that the bridge maps into
+ * LoadoutCriteria. Order is the order they appear in openteams'
+ * `loadout.schema.json` $defs.SkillsConfig.properties. */
+export const OPENTEAMS_BRIDGED_FIELDS = Object.freeze([
+  "profile",
+  "include",
+  "exclude",
+  "max_tokens",
+]);
+
+/**
+ * Overlay an openteams `loadout.skills` block onto a skill-tree
+ * `LoadoutCriteria`. Pure function — returns a new object, does not
+ * mutate the input.
+ *
+ * Mapping:
+ *   profile     → criteria.profile     (replace if set)
+ *   include     → criteria.include     (union, deduped)
+ *   exclude     → criteria.exclude     (union, deduped)
+ *   max_tokens  → criteria.maxTokens   (replace if set)
+ *
+ * Passing null/undefined for `loadoutSkills` returns a shallow copy of
+ * the input criteria unchanged.
+ */
+export function mergeOpenteamsSkillsIntoCriteria(criteria, loadoutSkills) {
+  const merged = { ...(criteria ?? {}) };
+  if (!loadoutSkills) return merged;
+  if (loadoutSkills.profile) merged.profile = loadoutSkills.profile;
+  if (loadoutSkills.include?.length) {
+    merged.include = mergeUnique(merged.include, loadoutSkills.include);
+  }
+  if (loadoutSkills.exclude?.length) {
+    merged.exclude = mergeUnique(merged.exclude, loadoutSkills.exclude);
+  }
+  if (typeof loadoutSkills.max_tokens === "number") {
+    merged.maxTokens = loadoutSkills.max_tokens;
+  }
+  return merged;
+}
+
+/**
+ * Resolve the LoadoutCriteria for a single role. Pure function — no I/O.
+ * Returns null when no criteria can be derived (signals to the caller
+ * that the role should be skipped).
+ *
+ * Priority order:
+ *   1. team.yaml `skilltree:` extension defaults
+ *   2. team.yaml `skilltree:` extension per-role override (replaces step 1)
+ *   3. openteams `role.loadout.skills` overlay via mergeOpenteamsSkillsIntoCriteria
+ *      (this is the openteams ↔ skill-tree bridge — declarations dispatch
+ *      into the mechanism)
+ *   4. If no skill-bearing criteria exists yet:
+ *      a. config.defaultProfile, else
+ *      b. ROLE_PROFILE_MAP auto-inference from role name, else
+ *      c. return null (no criteria — caller skips this role)
+ *
+ * @param {string} roleName
+ * @param {object} manifest - Parsed team.yaml manifest
+ * @param {object} [config] - Plugin config (skilltree section)
+ * @param {object} [template] - Optional openteams ResolvedTemplate
+ * @returns {object|null} LoadoutCriteria or null when role has no criteria
+ */
+export function computeRoleCriteria(
+  roleName,
+  manifest,
+  config = {},
+  template = null,
+) {
+  const { defaults, roles: roleOverrides } = parseSkillTreeExtension(manifest);
+  const templateRoles = normalizeRolesMap(template?.roles);
+
+  // Step 1+2: skilltree extension defaults + per-role override
+  let roleCriteria = roleOverrides[roleName]
+    ? { ...defaults, ...roleOverrides[roleName] }
+    : { ...defaults };
+
+  // Step 3: openteams loadout.skills overlay (canonical bridge — openteams wins)
+  const loadoutSkills = templateRoles?.get(roleName)?.loadout?.skills;
+  roleCriteria = mergeOpenteamsSkillsIntoCriteria(roleCriteria, loadoutSkills);
+
+  // Step 4: fallback chain — only fires when nothing skill-bearing is set yet
+  if (
+    !roleCriteria.profile &&
+    !roleCriteria.tags &&
+    !roleCriteria.include &&
+    !roleCriteria.taskDescription
+  ) {
+    if (config?.defaultProfile) {
+      roleCriteria.profile = config.defaultProfile;
+    } else {
+      const inferred = inferProfileFromRole(roleName);
+      if (inferred) {
+        roleCriteria.profile = inferred;
+      } else {
+        return null;
+      }
+    }
+  }
+
+  return roleCriteria;
+}
+
 /**
- * Compile skill loadouts for all roles in a team manifest.
- * Reads the skilltree extension from the manifest, compiles loadouts per role.
- * Returns metadata alongside content for richer agent context.
+ * Compile skill loadouts for all roles in a team manifest. Thin
+ * orchestrator over `computeRoleCriteria` + `compileRoleLoadout`.
  *
  * @param {object} manifest - Parsed team.yaml manifest
  * @param {object} config - Plugin config (skilltree section)
+ * @param {object} [template] - Optional openteams ResolvedTemplate
  * @returns {Promise<object>} Map of roleName → { content, profile }
  */
-export async function compileAllRoleLoadouts(manifest, config) {
-  const { defaults, roles: roleOverrides } = parseSkillTreeExtension(manifest);
+export async function compileAllRoleLoadouts(manifest, config, template = null) {
   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 };
-
-    // Fallback chain for profile selection
-    if (!roleCriteria.profile && !roleCriteria.tags && !roleCriteria.include && !roleCriteria.taskDescription) {
-      if (config?.defaultProfile) {
-        roleCriteria.profile = config.defaultProfile;
-      } else {
-        // Auto-infer from role name
-        const inferred = inferProfileFromRole(roleName);
-        if (inferred) {
-          roleCriteria.profile = inferred;
-        } else {
-          continue; // No criteria at all — skip
-        }
-      }
-    }
+    const roleCriteria = computeRoleCriteria(roleName, manifest, config, template);
+    if (!roleCriteria) continue;
 
     const loadout = await compileRoleLoadout(roleName, roleCriteria, config);
     if (loadout) {
@@ -195,3 +292,17 @@ export async function compileAllRoleLoadouts(manifest, config) {
 
   return result;
 }
+
+function normalizeRolesMap(roles) {
+  if (!roles) return null;
+  if (roles instanceof Map) return roles;
+  if (typeof roles === "object") return new Map(Object.entries(roles));
+  return null;
+}
+
+function mergeUnique(a, b) {
+  const out = new Set();
+  for (const x of a ?? []) out.add(x);
+  for (const x of b ?? []) out.add(x);
+  return [...out];
+}

package/src/template.mjs

@@ -13,6 +13,12 @@ import { getGlobalNodeModules } from "./swarmkit-resolver.mjs";
 import { teamDir } from "./paths.mjs";
 import { writeRoles } from "./roles.mjs";
 import { createLogger } from "./log.mjs";
+import { materializeLoadout } from "./loadout-materializer.mjs";
+import {
+  checkMcpHealth,
+  collectScopeReferences,
+  discoverActiveSet,
+} from "./mcp-health-checker.mjs";
 
 const log = createLogger("template");
 import { readConfig } from "./config.mjs";
@@ -151,7 +157,10 @@ export async function loadTeam(templateName) {
     // Use template name as fallback
   }
 
-  // Compile skill-tree loadouts if enabled (cached alongside template artifacts)
+  // Compile skill-tree loadouts if enabled (cached alongside template artifacts).
+  // When openteams is available, we also pass the full ResolvedTemplate so
+  // compileAllRoleLoadouts can read `role.loadout.skills` (first-class) in
+  // addition to the legacy `skilltree:` extension.
   const config = readConfig();
   if (config.skilltree?.enabled) {
     const loadoutsPath = path.join(outputDir, "skill-loadouts.json");
@@ -159,7 +168,20 @@ export async function loadTeam(templateName) {
       try {
         const { compileAllRoleLoadouts } = await import("./skilltree-client.mjs");
         const manifest = readTeamManifest(templatePath);
-        const loadouts = await compileAllRoleLoadouts(manifest, config.skilltree);
+        let template = null;
+        const ot = loadOpenteams();
+        if (ot?.TemplateLoader) {
+          try {
+            template = ot.TemplateLoader.load(templatePath);
+          } catch (err) {
+            log.warn("template load for skill-tree failed", { error: err.message });
+          }
+        }
+        const loadouts = await compileAllRoleLoadouts(
+          manifest,
+          config.skilltree,
+          template
+        );
         if (Object.keys(loadouts).length > 0) {
           fs.writeFileSync(loadoutsPath, JSON.stringify(loadouts, null, 2), "utf-8");
         }
@@ -169,9 +191,143 @@ export async function loadTeam(templateName) {
     }
   }
 
+  // Cache openteams loadout artifacts (per-role scope + providers + health report).
+  // Always regenerates on loadTeam — fresh active-set discovery each session.
+  try {
+    cacheLoadoutArtifacts({ templatePath, outputDir, templateName, teamName });
+  } catch (err) {
+    log.warn("loadout artifact caching failed", { error: err.message });
+  }
+
   return { success: true, templateName, templatePath, outputDir, teamName, cached };
 }
 
+/**
+ * Materialize per-role loadout artifacts + team MCP state to the
+ * per-template cache directory. Side-effecting; only writes under
+ * `outputDir`. Best-effort — errors are logged but don't fail loadTeam.
+ *
+ * Written outputs (all under `outputDir`):
+ *   loadouts/<role>.json   — openteams LoadoutArtifacts (inspection + debug)
+ *   scope/<role>.json      — runtime scope file read by the scope-check hook
+ *   mcp-providers.json     — team.mcp_providers as a plain object (when non-empty)
+ *   mcp-health.json        — health report: ok / missing / refs / orphaned
+ */
+export function cacheLoadoutArtifacts({
+  templatePath,
+  outputDir,
+  templateName,
+  teamName,
+} = {}) {
+  const ot = loadOpenteams();
+  if (!ot?.TemplateLoader) return;
+
+  let template;
+  try {
+    template = ot.TemplateLoader.load(templatePath);
+  } catch (err) {
+    log.warn("template load failed during loadout caching", { error: err.message });
+    return;
+  }
+
+  const loadouts = template?.roles ?? new Map();
+  const providers = template?.mcpProviders ?? new Map();
+  const name = teamName || template?.manifest?.name || templateName;
+
+  // Per-role artifacts
+  const loadoutsDir = path.join(outputDir, "loadouts");
+  const scopeDir = path.join(outputDir, "scope");
+
+  // Short-circuit if there are no loadouts at all — avoid creating empty dirs.
+  const rolesWithLoadouts = [];
+  for (const [roleName, role] of loadouts) {
+    if (role?.loadout) rolesWithLoadouts.push([roleName, role]);
+  }
+
+  if (rolesWithLoadouts.length > 0) {
+    fs.mkdirSync(loadoutsDir, { recursive: true });
+    fs.mkdirSync(scopeDir, { recursive: true });
+
+    for (const [roleName, role] of rolesWithLoadouts) {
+      // Dump openteams' artifact view for debugging/observability.
+      if (ot.generateLoadoutArtifacts) {
+        try {
+          const artifacts = ot.generateLoadoutArtifacts(role.loadout);
+          fs.writeFileSync(
+            path.join(loadoutsDir, `${roleName}.json`),
+            JSON.stringify(artifacts, null, 2),
+            "utf-8"
+          );
+        } catch (err) {
+          log.warn("generateLoadoutArtifacts failed", {
+            role: roleName,
+            error: err.message,
+          });
+        }
+      }
+
+      // Scope file — consumed at runtime by scripts/scope-check.mjs
+      const scopeFilePath = path.join(scopeDir, `${roleName}.json`);
+      try {
+        const { scopeFile, warnings } = materializeLoadout({
+          role: {
+            name: roleName,
+            description: role.description,
+            displayName: role.displayName,
+          },
+          loadout: role.loadout,
+          template,
+          options: { teamName: name, scopeFilePath },
+        });
+        fs.writeFileSync(
+          scopeFilePath,
+          JSON.stringify(scopeFile, null, 2),
+          "utf-8"
+        );
+        for (const w of warnings) log.warn(w);
+      } catch (err) {
+        log.warn("scope-file materialization failed", {
+          role: roleName,
+          error: err.message,
+        });
+      }
+    }
+  }
+
+  // Team-level providers map
+  const providersObj =
+    providers instanceof Map ? Object.fromEntries(providers) : providers || {};
+  if (Object.keys(providersObj).length > 0) {
+    fs.writeFileSync(
+      path.join(outputDir, "mcp-providers.json"),
+      JSON.stringify(providersObj, null, 2),
+      "utf-8"
+    );
+  }
+
+  // Health report — regenerated each session against current active set
+  try {
+    const pluginPath = process.env.CLAUDE_PLUGIN_ROOT;
+    const activeSet = discoverActiveSet({
+      projectPath: process.cwd(),
+      pluginPath,
+    });
+    const scopeReferences = collectScopeReferences(template.loadouts ?? new Map());
+    const report = checkMcpHealth({
+      providers,
+      activeSet,
+      scopeReferences,
+    });
+    fs.writeFileSync(
+      path.join(outputDir, "mcp-health.json"),
+      JSON.stringify(report, null, 2),
+      "utf-8"
+    );
+  } catch (err) {
+    log.warn("mcp health check failed", { error: err.message });
+  }
+}
+
 /**
  * Generate team artifacts (SKILL.md + agent prompts) using openteams.
  * Prefers programmatic API (generateSkillMd + generateAgentPrompts),