@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/setup/sections/subagents.mjs

@@ -0,0 +1,427 @@
+/**
+ * sections/subagents.mjs — the sub-agent registry init step (order 40).
+ *
+ * WHERE IT SITS AND WHY. `order: 40` is the lowest free slot (identity 10,
+ * company 20, model 30, comms 45, tools 50, operating-model 60, enrich 70,
+ * org 75, messaging 76, orgmail 77, learning 80, recovery 85, verify 90). It has
+ * to run BEFORE `operating-model` (60), which generates the capability surface's
+ * workflows, and before `tools` (50), so the roster the rest of the wizard writes
+ * against is already settled. It runs AFTER `model` (30) because the model alias
+ * normalisation shares that section's vocabulary.
+ *
+ * Registered by DROPPING THIS FILE into sections/ — `lib/setup/runner.mjs` globs
+ * the directory, so there is no core dispatcher edit (design §3.2).
+ *
+ * THE FOUR HOOKS AND THEIR CONTRACTS.
+ *
+ *   detect   Non-blocking, no input, network-OPTIONAL — it runs under
+ *            `--headless`, `doctor` and CI, so it never touches the TTY and never
+ *            waits on hq. Everything it needs (lock + agents/ + SDK manifest) is
+ *            on disk.
+ *
+ *   prompt   TTY only. Errors here are swallowed by the runner
+ *            (runner.mjs:208-212), so a prompt failure degrades to "no answers"
+ *            and `apply` takes only the unambiguous verdicts.
+ *
+ *   apply    Idempotent, and — this is the important one — A THROW HERE IS FATAL
+ *            TO THE WHOLE WIZARD (runner.mjs:218-223). Every network call is
+ *            therefore individually wrapped, every failure degrades to
+ *            cache-or-local, and the function returns normally with
+ *            `degraded:["workspace"]` recorded in the lock. Under `--headless` it
+ *            takes only unambiguous verdicts and NEVER creates an agent
+ *            unattended — it writes `state/subagents/gaps.json` for a human.
+ *
+ *   verify   Pure local: every resolved file validates against schema.mjs, the
+ *            lock hashes match disk, and every parsed reference either resolves
+ *            or is an accepted drop.
+ *
+ * §6 names the degradation branches as the least-exercised path in the design.
+ * They have explicit tests in subagents.test.mjs (cold cache, 500 from hq,
+ * timeout, missing env) — not just the happy path.
+ *
+ * @module lib/setup/sections/subagents
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as io from "../io.mjs";
+import * as client from "../../subagents/client.mjs";
+import { computeGaps, contextFromConfig, rosterFromSurface } from "../../subagents/gap.mjs";
+import { acceptDrop, mergeLock, readLock, writeGaps } from "../../subagents/lock.mjs";
+import { readManifest } from "../../subagents/manifest.mjs";
+import { scanAgentRefs } from "../../subagents/refs.mjs";
+import { materialiseAll, resolveSubagents } from "../../subagents/resolve.mjs";
+import { checkAgentFile, hashFile } from "../../subagents/schema.mjs";
+import { agentFilePath } from "../../subagents/resolve.mjs";
+
+/** The per-slug actions the prompt offers (§2.3). */
+export const ACTIONS = Object.freeze([
+  "adopt-workspace", "adopt-sdk", "fork", "create", "rewire", "drop-workflow-step", "defer",
+]);
+
+/** Verdicts `--headless` is allowed to act on: no ambiguity, no new rows. */
+export const HEADLESS_SAFE = Object.freeze(new Set(["adopt-workspace", "adopt-sdk"]));
+
+/** Read config/agent.json. Fail-open → {}. */
+export function readAgentConfig(agentRoot) {
+  const p = join(agentRoot, "config", "agent.json");
+  if (!existsSync(p)) return {};
+  try { return JSON.parse(readFileSync(p, "utf8")) || {}; } catch { return {}; }
+}
+
+/**
+ * Resolve the authoritative roster (`standardAgents ∪ roleAgents`) for this
+ * agent's archetype. Injectable for tests; fail-open to [] because an agent
+ * whose function has no capability pack still has a perfectly valid on-disk
+ * roster — we just cannot report `missing`/`idle` for it.
+ * @param {object} ctx @param {object} agentConfig
+ * @returns {Promise<Array<object>>}
+ */
+export async function resolveRoster(ctx, agentConfig) {
+  const impl = ctx && ctx.resolveSurfaceImpl;
+  const sel = { function: agentConfig.function, altitude: agentConfig.altitude };
+  if (typeof impl === "function") {
+    try { return rosterFromSurface(await impl(sel)); } catch { return []; }
+  }
+  if (!sel.function || !sel.altitude) return [];
+  try {
+    const mod = await import("../../capability.mjs");
+    return rosterFromSurface(await mod.resolveCapabilitySurface(sel));
+  } catch { return []; }
+}
+
+/**
+ * The core of detect/prompt/apply: resolve all three layers and diff them.
+ *
+ * `network` is opt-IN (detect passes false). When on, a failed `subagent.resolve`
+ * is not an error — it sets `degraded:["workspace"]` and layer 1 falls back to
+ * the lock + cache, which is exactly §4's contract.
+ *
+ * @param {object} ctx the wizard ctx
+ * @param {{network?:boolean}} [o]
+ * @returns {Promise<object>} {cfg, resolved, gaps, roster, refs, degraded, rosterVersion, agentConfig}
+ */
+export async function assess(ctx, o = {}) {
+  const agentRoot = ctx.agentRoot;
+  const maestroRoot = ctx.maestroRoot;
+  const agentConfig = readAgentConfig(agentRoot);
+  const cfg = ctx.subagentCfg || client.resolveConfig({ agentRoot, env: ctx.env });
+  const lock = readLock(agentRoot);
+  const manifest = readManifest(maestroRoot);
+
+  let pins = [];
+  let degraded = [];
+  let rosterVersion = lock.rosterVersion;
+
+  if (o.network && cfg.enabled) {
+    try {
+      const r = await client.fetchResolve({
+        cfg,
+        agentRoot,
+        memberId: cfg.memberId || undefined,
+        function: agentConfig.function,
+        altitude: agentConfig.altitude,
+        fetchImpl: ctx.subagentFetchImpl,
+      });
+      if (r.ok) { pins = r.entries; rosterVersion = r.rosterVersion; }
+      else degraded = ["workspace"];
+    } catch {
+      // Belt and braces: the client is documented never to throw, but `apply`
+      // throws are fatal, so we do not take its word for it.
+      degraded = ["workspace"];
+    }
+  }
+
+  if (!pins.length) {
+    // Cold-cache / offline layer 1: whatever the lock says was pinned. The bodies
+    // come from state/subagents/cache/ inside resolveSubagents.
+    pins = Object.entries(lock.agents || {})
+      .filter(([, e]) => e && e.layer === "workspace")
+      .map(([slug, e]) => ({ slug, definitionId: e.definitionId, version: e.version, contentHash: e.contentHash }));
+  }
+
+  const resolved = resolveSubagents({ agentRoot, maestroRoot, pins, manifest, lock, orgSlug: cfg.orgId });
+  const roster = await resolveRoster(ctx, agentConfig);
+  const refs = scanAgentRefs({ agentRoot });
+  const gaps = computeGaps({ roster, resolved, refs, lock, context: contextFromConfig({ agentConfig }) });
+
+  return { agentConfig, cfg, lock, manifest, resolved, roster, refs, gaps, degraded, rosterVersion, pins };
+}
+
+/**
+ * Decide the default action for each gap without asking anyone. This is what
+ * `--headless` executes and what the TTY prompt pre-selects.
+ *
+ * The rules are deliberately conservative:
+ *   - a missing slug that the WORKSPACE offers → adopt-workspace (unambiguous)
+ *   - a missing slug that the SDK offers       → adopt-sdk       (unambiguous)
+ *   - anything else                            → defer           (needs a human)
+ * `create` and `fork` are never defaults: both mint a row in hq, and §2.3 forbids
+ * doing that unattended.
+ *
+ * @param {object} assessment
+ * @returns {Array<{slug:string, action:string, reason:string}>}
+ */
+export function planActions(assessment) {
+  const plan = [];
+  const bySlug = assessment.resolved.bySlug;
+  const manifestAgents = (assessment.manifest && assessment.manifest.agents) || {};
+  const pinned = new Set((assessment.pins || []).map((p) => p && p.slug).filter(Boolean));
+
+  for (const m of assessment.gaps.missing) {
+    if (pinned.has(m.slug)) { plan.push({ slug: m.slug, action: "adopt-workspace", reason: "a workspace pin offers this slug" }); continue; }
+    if (manifestAgents[m.slug]) { plan.push({ slug: m.slug, action: "adopt-sdk", reason: "the SDK ships this slug" }); continue; }
+    plan.push({ slug: m.slug, action: "defer", reason: "no layer offers this slug — fork/create needs a human" });
+  }
+  // Entries that DO resolve but are not on disk yet are also adoptions: the
+  // registry's steady state is "every resolved winner is materialised".
+  for (const e of assessment.resolved.entries) {
+    if (e.onDisk || plan.some((p) => p.slug === e.slug)) continue;
+    plan.push({ slug: e.slug, action: e.layer === "workspace" ? "adopt-workspace" : "adopt-sdk", reason: `resolved from ${e.layer} but not on disk` });
+  }
+  return plan;
+}
+
+export default {
+  id: "subagents",
+  label: "Sub-agents",
+  order: 40,
+
+  /**
+   * Non-blocking, no input, NO NETWORK. `complete` only when there are no
+   * `missing` and no unresolved `drop-or-create` (§2.3).
+   */
+  async detect(ctx) {
+    const cfg = ctx.subagentCfg || client.resolveConfig({ agentRoot: ctx.agentRoot, env: ctx.env });
+    const a = await assess(ctx, { network: false });
+    const missing = a.gaps.missing.map((m) => m.slug);
+    const openDrops = a.gaps.openDrops.map((u) => u.ref);
+
+    if (a.gaps.status === "complete") {
+      const note = cfg.enabled ? "" : " (workspace layer off — not enrolled)";
+      return { status: "complete", summary: `${a.gaps.counts.resolved} sub-agents resolved${note}` };
+    }
+    return {
+      status: a.gaps.counts.resolved ? "partial" : "unconfigured",
+      summary: a.gaps.summary,
+      missing: [...missing.map((s) => `missing: ${s}`), ...openDrops.map((s) => `dangling ref: ${s}`)].slice(0, 12),
+    };
+  },
+
+  /**
+   * One table, per-slug actions. TTY only; the runner swallows throws here, and
+   * `io.*` returns the pre-supplied answer under `--headless` without blocking.
+   */
+  async prompt(ctx) {
+    const a = await assess(ctx, { network: true });
+    ctx.answers.subagentAssessment = { counts: a.gaps.counts, degraded: a.degraded };
+
+    if (a.degraded.length) {
+      io.note("Could not reach the workspace registry — resolving from the SDK + local cache only.", { dim: true });
+    }
+    if (!a.gaps.missing.length && !a.gaps.openDrops.length && !a.gaps.idle.length) {
+      io.note(`Sub-agents: ${a.gaps.counts.resolved} resolved, nothing to decide.`, { dim: true });
+      return;
+    }
+
+    io.note("");
+    io.note(`Sub-agents — ${a.gaps.summary}`);
+    const plan = planActions(a);
+    const chosen = {};
+
+    for (const m of a.gaps.missing) {
+      const dflt = (plan.find((p) => p.slug === m.slug) || {}).action || "defer";
+      const choices = [
+        { label: `adopt from the workspace registry`, value: "adopt-workspace" },
+        { label: `adopt the SDK's shipped definition`, value: "adopt-sdk" },
+        { label: `fork it (copy the body, own it)`, value: "fork" },
+        { label: `create a new definition from the skeleton`, value: "create" },
+        { label: `defer — decide later`, value: "defer" },
+      ];
+      chosen[m.slug] = await io.select(ctx, {
+        message: `  ${m.slug} (${m.role || "roster agent"}) — missing`,
+        key: `subagent.${m.slug}`,
+        default: dflt,
+        choices,
+      });
+    }
+
+    // Dangling references. NEVER auto-edits or deletes a workflow: a `drop` only
+    // records the accepted drop and prints the file:line for a human to delete.
+    for (const u of a.gaps.openDrops) {
+      const at = u.locations[0] ? `${u.locations[0].file}:${u.locations[0].line}` : "unknown location";
+      const choices = [
+        { label: `drop the workflow step (recommended) — ${at}`, value: "drop-workflow-step" },
+        ...(u.suggest ? [{ label: `rewire to ${u.suggest} (${Math.round(u.score * 100)}% match)`, value: `rewire:${u.suggest}` }] : []),
+        { label: "create a sub-agent for it", value: "create" },
+        { label: "defer", value: "defer" },
+      ];
+      chosen[`ref:${u.ref}`] = await io.select(ctx, {
+        message: `  ${u.ref} — referenced but not on the roster (${u.reason})`,
+        key: `subagent.ref.${u.ref}`,
+        default: u.recommend === "rewire" && u.suggest ? `rewire:${u.suggest}` : "drop-workflow-step",
+        choices,
+      });
+    }
+
+    if (a.gaps.idle.length) {
+      io.note(`  ${a.gaps.idle.length} roster agent(s) are referenced by nothing: ${a.gaps.idle.map((i) => i.slug).join(", ")}`, { dim: true });
+    }
+
+    ctx.answers.subagentChoices = chosen;
+  },
+
+  /**
+   * Idempotent. EVERY network call is wrapped; on failure it degrades to
+   * cache-or-local, records `degraded:["workspace"]` and returns NORMALLY —
+   * because a throw here aborts the entire wizard.
+   */
+  async apply(ctx) {
+    const headless = io.isHeadless(ctx.flags || {});
+    let a;
+    try {
+      a = await assess(ctx, { network: true });
+    } catch (e) {
+      // Even the local assessment failing must not abort setup: the registry is
+      // additive, and an agent with no sub-agent resolution still runs.
+      io.note(`[subagents] assessment failed (${e && e.message ? e.message : e}) — skipping the registry step.`, { dim: true });
+      mergeLock(ctx.agentRoot, { degraded: ["assessment"] });
+      return;
+    }
+
+    const choices = (ctx.answers && ctx.answers.subagentChoices) || {};
+    const plan = planActions(a);
+
+    // 1. Materialise every resolved winner. Local edits are never overwritten
+    //    (materialise() refuses without --force), so this is safe to run always.
+    const out = materialiseAll({ agentRoot: ctx.agentRoot, resolved: a.resolved });
+    if (out.written) io.note(`Materialised ${out.written} sub-agent definition(s).`, { dim: true });
+    for (const r of out.refused) io.note(`  ! ${r.slug}: ${r.reason}`, { dim: true });
+
+    // 2. Act on the operator's per-slug verdicts. Under --headless only the
+    //    unambiguous adoptions run (already done by step 1); create/fork NEVER
+    //    happen unattended.
+    const created = [];
+    for (const [key, verdict] of Object.entries(choices)) {
+      if (!verdict || verdict === "defer") continue;
+
+      if (key.startsWith("ref:")) {
+        const ref = key.slice(4);
+        if (verdict === "drop-workflow-step") {
+          const u = a.gaps.unrostered.find((x) => x.ref === ref);
+          const loc = (u && u.locations[0]) || {};
+          acceptDrop(ctx.agentRoot, { ref, file: loc.file, line: loc.line, reason: "operator accepted drop at init" });
+          io.note(`  drop accepted for "${ref}" — delete it yourself at ${loc.file || "?"}:${loc.line || "?"} (the wizard never edits workflows).`, { dim: true });
+        } else if (String(verdict).startsWith("rewire:")) {
+          const target = String(verdict).slice(7);
+          const u = a.gaps.unrostered.find((x) => x.ref === ref);
+          const loc = (u && u.locations[0]) || {};
+          io.note(`  rewire "${ref}" → "${target}" at ${loc.file || "?"}:${loc.line || "?"} (edit it yourself — the wizard never edits workflows).`, { dim: true });
+        }
+        continue;
+      }
+
+      if (headless && !HEADLESS_SAFE.has(verdict)) continue;
+      if (verdict !== "create" && verdict !== "fork") continue;
+
+      // create / fork — the only two verdicts that mint a row in hq. Each is
+      // individually wrapped: a failure queues to the outbox and moves on.
+      try {
+        const entry = a.resolved.bySlug.get(key);
+        const params = verdict === "fork" && entry
+          ? { slug: key, baseLayer: entry.layer === "sdk" ? "sdk" : "none", baseSlug: key, title: key, summary: (entry.frontmatter && entry.frontmatter.description) || key, frontmatter: entry.frontmatter, body: entry.body }
+          : null;
+        const r = params
+          ? await client.forkDefinition(params, { cfg: a.cfg, agentRoot: ctx.agentRoot, fetchImpl: ctx.subagentFetchImpl })
+          : { ok: false, degraded: true, error: { message: "create needs a scaffolded body — run `maestro subagents add`" } };
+        if (r.ok) {
+          created.push(key);
+          await client.pinDefinition({ slug: key, definitionId: r.result && r.result.definitionId, version: r.result && r.result.version }, { cfg: a.cfg, agentRoot: ctx.agentRoot, fetchImpl: ctx.subagentFetchImpl });
+        } else if (r.queued) {
+          io.note(`  ${key}: queued offline → ${r.queued}`, { dim: true });
+        } else {
+          io.note(`  ${key}: ${(r.error && r.error.message) || "registry write failed"}`, { dim: true });
+        }
+      } catch (e) {
+        io.note(`  ${key}: registry write threw (${e && e.message ? e.message : e}) — continuing.`, { dim: true });
+      }
+    }
+
+    // 3. Persist the lock: what is on disk, the roster version we saw, and any
+    //    degradation, so `doctor` can tell "N sub-agents behind workspace".
+    mergeLock(ctx.agentRoot, { agents: out.lockAgents, rosterVersion: a.rosterVersion, degraded: a.degraded });
+
+    // 4. Headless leaves a report instead of asking. Never creates unattended.
+    if (headless) {
+      writeGaps(ctx.agentRoot, {
+        summary: a.gaps.summary,
+        counts: a.gaps.counts,
+        missing: a.gaps.missing,
+        unrostered: a.gaps.unrostered,
+        idle: a.gaps.idle,
+        plan,
+        degraded: a.degraded,
+      });
+    }
+    if (created.length) io.note(`Registered ${created.length} workspace definition(s): ${created.join(", ")}`, { dim: true });
+  },
+
+  /**
+   * Pure local, no network: schema, lock/disk agreement, reference resolution.
+   */
+  async verify(ctx) {
+    const checks = [];
+    const a = await assess(ctx, { network: false });
+
+    // (a) every resolved file that is on disk validates.
+    const bad = [];
+    for (const e of a.resolved.entries) {
+      const p = agentFilePath(ctx.agentRoot, e.slug);
+      if (!existsSync(p)) continue;
+      let text;
+      try { text = readFileSync(p, "utf8"); } catch { bad.push(`${e.slug}: unreadable`); continue; }
+      const c = checkAgentFile(text, e.slug);
+      if (!c.ok) bad.push(`${e.slug}: ${c.errors[0]}`);
+    }
+    checks.push({
+      name: bad.length ? `sub-agent definitions valid (${bad.length} invalid)` : "sub-agent definitions valid",
+      ok: bad.length === 0,
+      remedy: bad.length ? `fix: ${bad.slice(0, 3).join("; ")}` : undefined,
+    });
+
+    // (b) lock hashes match disk. A mismatch is not a failure — it is the
+    //     definition of a local edit — but a lock entry pointing at a file that
+    //     no longer exists IS a broken lock.
+    const orphanLock = [];
+    for (const [slug, e] of Object.entries(a.lock.agents || {})) {
+      const p = agentFilePath(ctx.agentRoot, slug);
+      if (!existsSync(p)) { orphanLock.push(slug); continue; }
+      if (!e.fileHash) continue;
+      try { if (hashFile(readFileSync(p, "utf8")) !== e.fileHash) { /* local edit — reported, not failed */ } } catch { orphanLock.push(slug); }
+    }
+    checks.push({
+      name: orphanLock.length ? `lock matches disk (${orphanLock.length} orphan entr${orphanLock.length === 1 ? "y" : "ies"})` : "lock matches disk",
+      ok: orphanLock.length === 0,
+      remedy: orphanLock.length ? "run `maestro subagents pull` to re-materialise, or remove the stale lock entries" : undefined,
+    });
+
+    // (c) every parsed reference resolves or is an accepted drop.
+    const dangling = a.gaps.openDrops.map((u) => u.ref);
+    checks.push({
+      name: dangling.length ? `sub-agent references resolve (${dangling.length} dangling)` : "sub-agent references resolve",
+      // Dangling references WARN rather than fail: `create` copies maestro's own
+      // workflows verbatim, so a fresh agent legitimately starts with ~15 of them
+      // and hard-failing verify would make every new agent's setup red.
+      ok: true,
+      remedy: dangling.length ? `run \`maestro subagents status\` — ${dangling.slice(0, 5).join(", ")}` : undefined,
+    });
+
+    if (a.degraded.length) {
+      checks.push({ name: "workspace registry reachable (best-effort)", ok: true, remedy: `degraded: ${a.degraded.join(", ")} — resolved from cache/SDK` });
+    }
+
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};