@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/setup/sections/inventory.mjs

@@ -0,0 +1,178 @@
+/**
+ * sections/inventory.mjs — the CAPABILITY INVENTORY step.  (order 55)
+ *
+ * Registered the same way every other cross-workstream section is: by dropping
+ * this file into `lib/setup/sections/`. `runner.mjs` globs the directory and
+ * sorts by `order` — no dispatcher edit, no import to add.
+ *
+ * Order 55 sits between `tools` (50, which RECORDS what the operator selected)
+ * and `operating-model` (60, which GENERATES the cadence set). That position is
+ * the whole point: the operating model, and later the plan compiler at 78, must
+ * be built on capabilities that were actually PROBED, not on a wish-list. The
+ * law this section establishes and `lib/plan/compile.mjs` enforces:
+ *
+ *     an entry with `reachable:false` may not be cited by any obligation.
+ *
+ * What it discovers (SPEC §5.1), across four planes:
+ *   builtin — Claude Code's own tools
+ *   skill   — plugins/<plugin>/skills/*.md (with the marketplace + enabledPlugins
+ *             probe, and an optional REPAIR that registers them — rung 1 of the
+ *             execution ladder is a lie while 40-odd skill files are orphaned),
+ *             plus archetype workflows and the sub-agent roster
+ *   mcp     — .mcp.json cross-read with config/mcp-servers.yaml
+ *   org     — the curated Cohort protocol tools + granted integration tools
+ *
+ * Output: `config/capability-manifest.json` — tracked in git, so a capability
+ * appearing or disappearing is a reviewable diff, and queryable by every session,
+ * schedule and router that follows.
+ *
+ * Every hook is non-blocking under --headless; detect/apply/verify never read the
+ * TTY. apply() is idempotent. Degradations are recorded AND logged, never
+ * swallowed.
+ *
+ * @module lib/setup/sections/inventory
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import * as io from "../io.mjs";
+import { buildInventory, writeManifest, readManifest, MANIFEST_REL, MANIFEST_VERSION } from "../../capability/inventory.mjs";
+import { readAgentJson } from "../sot.mjs";
+
+/** Resolve { function, altitude } from the on-disk SoT (null when unset). */
+export function archetypeOf(agentRoot) {
+  try {
+    const cfg = readAgentJson(agentRoot) || {};
+    if (cfg.function && cfg.altitude) return { function: cfg.function, altitude: cfg.altitude };
+  } catch { /* fall through — the identity section owns this gap */ }
+  return null;
+}
+
+/**
+ * Post the manifest to hq (`mandate.declareCapability`). Fail-open and NEVER
+ * silent: an un-enrolled agent, an old server without the mandate family, or an
+ * unreachable network all degrade to a logged note — the local manifest is the
+ * authority for planning either way.
+ *
+ * @param {string} agentRoot @param {object} manifest
+ * @param {{callImpl?:Function, logImpl?:Function}} [deps]
+ * @returns {Promise<{posted:boolean, reason?:string}>}
+ */
+export async function declareCapability(agentRoot, manifest, deps = {}) {
+  const log = deps.logImpl || ((m) => io.note(m, { dim: true }));
+  try {
+    let call = deps.callImpl;
+    if (!call) {
+      const client = await import("../../org/client.mjs");
+      const cfg = client.loadOrgConfig(agentRoot);
+      if (!client.isEnabled(cfg)) {
+        log("[inventory] not enrolled in an org — capability manifest kept local only");
+        return { posted: false, reason: "not-enrolled" };
+      }
+      const o = client.configFromAgent(cfg);
+      call = (m, p) => client.call(m, p, o);
+    }
+    const body = (manifest.entries || []).map((e) => ({
+      id: e.id, plane: e.plane, kind: e.kind, reachable: e.reachable,
+      probedAt: e.probedAt, blastRadius: e.blastRadius, costHint: e.costHint,
+    }));
+    const r = await call("mandate.declareCapability", { version: manifest.schemaVersion, body });
+    if (r && r.ok) return { posted: true };
+    const reason = (r && r.error && r.error.code) || "unknown";
+    log(`[inventory] mandate.declareCapability not accepted (${reason}) — manifest kept local only`);
+    return { posted: false, reason };
+  } catch (e) {
+    log(`[inventory] mandate.declareCapability failed: ${e && e.message ? e.message : e} — manifest kept local only`);
+    return { posted: false, reason: "threw" };
+  }
+}
+
+export default {
+  id: "inventory",
+  label: "Capability inventory (skills, plugins, MCP, org tools)",
+  order: 55,
+
+  async detect(ctx) {
+    const m = readManifest(ctx.agentRoot);
+    if (!m) return { status: "unconfigured", missing: [MANIFEST_REL] };
+    if (m.schemaVersion !== MANIFEST_VERSION) {
+      return { status: "partial", summary: `manifest schema v${m.schemaVersion} (expected v${MANIFEST_VERSION})`, missing: ["stale manifest schema"] };
+    }
+    const total = Array.isArray(m.entries) ? m.entries.length : 0;
+    if (total === 0) return { status: "partial", summary: "manifest present but empty", missing: ["no capabilities discovered"] };
+    const c = m.counts || {};
+    return {
+      status: "complete",
+      summary: `${total} capabilities (${c.reachable ?? "?"} reachable) — builtin ${c.builtin ?? 0} · skill ${c.skill ?? 0} · mcp ${c.mcp ?? 0} · org ${c.org ?? 0}`,
+    };
+  },
+
+  async prompt(ctx) {
+    // One question only, and it is a REPAIR consent: registering the skill
+    // marketplaces writes to the plugin dirs and ~/.claude/settings.json.
+    const repair = await io.confirm(ctx, {
+      message: "Register maestro's skill marketplaces and enable them, so the agent's skills are actually invocable?",
+      key: "capabilityRepair",
+      default: true,
+    });
+    ctx.answers.capabilityRepair = repair;
+  },
+
+  async apply(ctx) {
+    const repair = ctx.answers && typeof ctx.answers.capabilityRepair === "boolean" ? ctx.answers.capabilityRepair : true;
+    const deps = (ctx.capabilityDeps && typeof ctx.capabilityDeps === "object") ? ctx.capabilityDeps : {};
+    const log = deps.logImpl || ((m) => io.note(m, { dim: true }));
+
+    const manifest = await buildInventory(
+      { agentRoot: ctx.agentRoot, maestroRoot: ctx.maestroRoot, archetype: archetypeOf(ctx.agentRoot), repair, env: (ctx.flags && ctx.flags.env) || process.env },
+      { ...deps, logImpl: log },
+    );
+    writeManifest(ctx.agentRoot, manifest, deps);
+
+    const c = manifest.counts || {};
+    io.note(`[inventory] ${c.reachable ?? 0}/${(manifest.entries || []).length} capabilities reachable — builtin ${c.builtin ?? 0} · skill ${c.skill ?? 0} · mcp ${c.mcp ?? 0} · org ${c.org ?? 0}`);
+    if ((manifest.degradations || []).length) {
+      io.note(`[inventory] ${manifest.degradations.length} degradation(s) recorded in ${MANIFEST_REL} — unreachable capabilities cannot back any obligation.`, { dim: true });
+    }
+
+    await declareCapability(ctx.agentRoot, manifest, { ...deps, logImpl: log });
+  },
+
+  async verify(ctx) {
+    const checks = [];
+    const m = readManifest(ctx.agentRoot);
+    checks.push({ name: `${MANIFEST_REL} present`, ok: !!m, remedy: m ? undefined : "run `maestro setup --only inventory`" });
+    if (!m) return { ok: false, checks };
+
+    const entries = Array.isArray(m.entries) ? m.entries : [];
+    const wellFormed = entries.every((e) => e && typeof e.id === "string" && typeof e.plane === "string" && typeof e.reachable === "boolean" && e.probedAt);
+    checks.push({ name: "every entry carries {id, plane, reachable, probedAt}", ok: wellFormed, remedy: wellFormed ? undefined : "re-run the inventory section" });
+
+    const anyReachable = entries.some((e) => e.reachable);
+    checks.push({ name: `at least one reachable capability (${(m.counts && m.counts.reachable) || 0})`, ok: anyReachable, remedy: anyReachable ? undefined : "no capability probed reachable — the agent cannot act" });
+
+    // SOFT checks: an un-enrolled agent or a laptop without MCP credentials is a
+    // legitimate state during init. Surface the remedy, never hard-fail setup —
+    // but say it out loud, because a silently empty plane is how rung 0/1 became
+    // a lie in the first place.
+    for (const plane of ["skill", "mcp", "org"]) {
+      const total = entries.filter((e) => e.plane === plane).length;
+      const reachable = entries.filter((e) => e.plane === plane && e.reachable).length;
+      checks.push({
+        name: `${plane} plane: ${reachable}/${total} reachable`,
+        ok: true,
+        remedy: total > 0 && reachable === 0 ? `nothing on the ${plane} plane is reachable — obligations may not cite it` : undefined,
+      });
+    }
+
+    const degraded = (m.degradations || []).length;
+    checks.push({ name: `degradations recorded: ${degraded}`, ok: true, remedy: degraded ? `see \`degradations\` in ${MANIFEST_REL}` : undefined });
+
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};
+
+/** Exported for the standalone init script + tests. */
+export { MANIFEST_REL, existsSync as _existsSync, join as _join };

package/lib/setup/sections/inventory.test.mjs

@@ -0,0 +1,198 @@
+/**
+ * inventory.test.mjs — the capability-inventory setup section (order 55).
+ * Run: node --test lib/setup/sections/inventory.test.mjs
+ *
+ * Also asserts the REGISTRATION mechanism itself: runner.loadSections() globs
+ * this directory, so the section must be discoverable and correctly ordered
+ * without any core edit.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import inventory, { archetypeOf, declareCapability } from "./inventory.mjs";
+import { loadSections } from "../runner.mjs";
+import { MANIFEST_REL } from "../../capability/inventory.mjs";
+import * as io from "../io.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+/**
+ * A tmp agent repo, a tmp HOME and a tmp MAESTRO_ROOT. The framework root is
+ * faked deliberately: `repair:true` writes marketplace manifests into the plugin
+ * dirs it scans, and a test must never mutate the real repo (or the operator's
+ * ~/.claude/settings.json).
+ */
+function tmpRoot({ archetype = true } = {}) {
+  const root = mkdtempSync(join(tmpdir(), "maestro-invsec-"));
+  const home = mkdtempSync(join(tmpdir(), "maestro-invhome-"));
+  const fakeMaestro = mkdtempSync(join(tmpdir(), "maestro-invfw-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify(
+    archetype ? { firstName: "Placeholder", function: "executive-operator", altitude: "c-suite" } : { firstName: "Placeholder" },
+  ));
+  mkdirSync(join(root, "plugins", "agent-skills", "skills"), { recursive: true });
+  writeFileSync(join(root, "plugins", "agent-skills", "skills", "morning-brief.md"), "# morning-brief\n");
+  writeFileSync(join(root, ".mcp.json"), JSON.stringify({ mcpServers: { cohort: { command: "cohort-mcp" } } }));
+  return { root, home, fakeMaestro };
+}
+
+function ctxFor(root, home, answers = {}, extra = {}) {
+  return {
+    agentRoot: root,
+    maestroRoot: extra.maestroRoot || MAESTRO_ROOT,
+    flags: { headless: true },
+    answers,
+    io,
+    capabilityDeps: {
+      homeDir: home,
+      now: () => "2026-08-11T09:00:00.000Z",
+      logImpl: () => {},
+      orgToolsImpl: async () => [
+        { name: "board_ready", access: "read", binding: { kind: "rpc" } },
+        { name: "task_create", access: "write", binding: { kind: "rpc" } },
+      ],
+      orgProbeImpl: async () => ({ ok: true, detail: "round-trip ok", mandateFamily: true }),
+      capabilitySurface: async () => ({ workflows: [{ id: "weekly-operating-review", cadence: "weekly" }] }),
+      wishlistImpl: async () => [],
+      callImpl: async () => ({ ok: true, result: {} }),
+      ...(extra.capabilityDeps || {}),
+    },
+  };
+}
+
+test("REGISTRATION: runner.loadSections() discovers `inventory` at order 55, between tools(50) and operating-model(60)", async () => {
+  const sections = await loadSections();
+  const ids = sections.map((s) => s.id);
+  assert.ok(ids.includes("inventory"), "section is auto-discovered by the directory glob — no dispatcher edit");
+  const idx = ids.indexOf("inventory");
+  assert.equal(sections[idx].order, 55);
+  assert.ok(ids.indexOf("tools") < idx, "runs after tools (50)");
+  assert.ok(ids.indexOf("operating-model") > idx, "runs before operating-model (60)");
+});
+
+test("section shape: id/order/hooks", () => {
+  assert.equal(inventory.id, "inventory");
+  assert.equal(inventory.order, 55);
+  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof inventory[h], "function");
+});
+
+test("detect: unconfigured → complete across apply()", async () => {
+  const { root, home, fakeMaestro } = tmpRoot();
+  const before = await inventory.detect(ctxFor(root, home, {}, { maestroRoot: fakeMaestro }));
+  assert.equal(before.status, "unconfigured");
+  assert.deepEqual(before.missing, [MANIFEST_REL]);
+
+  await inventory.apply(ctxFor(root, home, { capabilityRepair: false }, { maestroRoot: fakeMaestro }));
+  const after = await inventory.detect(ctxFor(root, home, {}, { maestroRoot: fakeMaestro }));
+  assert.equal(after.status, "complete");
+  assert.match(after.summary, /capabilities/);
+  assert.ok(existsSync(join(root, MANIFEST_REL)));
+});
+
+test("apply writes a durable, queryable manifest with all four planes", async () => {
+  const { root, home, fakeMaestro } = tmpRoot();
+  await inventory.apply(ctxFor(root, home, { capabilityRepair: false }, { maestroRoot: fakeMaestro }));
+  const m = JSON.parse(readFileSync(join(root, MANIFEST_REL), "utf8"));
+  assert.equal(m.schemaVersion, 1);
+  for (const plane of ["builtin", "skill", "mcp", "org"]) {
+    assert.ok(m.counts[plane] > 0, `${plane} plane inventoried`);
+  }
+  assert.ok(m.entries.some((e) => e.id === "skill:agent-skills:morning-brief"));
+  assert.ok(m.entries.some((e) => e.id === "workflow:weekly-operating-review"));
+  assert.ok(m.entries.some((e) => e.id === "mcp:cohort"));
+  assert.ok(m.entries.some((e) => e.id === "board_ready"));
+});
+
+test("apply is IDEMPOTENT — the checksum is stable across runs", async () => {
+  const { root, home, fakeMaestro } = tmpRoot();
+  await inventory.apply(ctxFor(root, home, { capabilityRepair: false }, { maestroRoot: fakeMaestro }));
+  const a = JSON.parse(readFileSync(join(root, MANIFEST_REL), "utf8")).checksum;
+  await inventory.apply(ctxFor(root, home, { capabilityRepair: false }, { maestroRoot: fakeMaestro }));
+  const b = JSON.parse(readFileSync(join(root, MANIFEST_REL), "utf8")).checksum;
+  assert.equal(a, b);
+});
+
+test("apply with repair registers the marketplace so the skills become reachable", async () => {
+  const { root, home, fakeMaestro } = tmpRoot();
+  await inventory.apply(ctxFor(root, home, { capabilityRepair: true }, { maestroRoot: fakeMaestro }));
+  const m = JSON.parse(readFileSync(join(root, MANIFEST_REL), "utf8"));
+  const skill = m.entries.find((e) => e.id === "skill:agent-skills:morning-brief");
+  assert.equal(skill.reachable, true);
+  assert.ok(existsSync(join(root, "plugins", "agent-skills", ".claude-plugin", "marketplace.json")));
+});
+
+test("verify: hard-fails only on a missing/empty manifest; plane emptiness is a SOFT remedy", async () => {
+  const { root, home, fakeMaestro } = tmpRoot();
+  const bad = await inventory.verify(ctxFor(root, home, {}, { maestroRoot: fakeMaestro }));
+  assert.equal(bad.ok, false);
+
+  await inventory.apply(ctxFor(root, home, { capabilityRepair: false }, { maestroRoot: fakeMaestro }));
+  const good = await inventory.verify(ctxFor(root, home, {}, { maestroRoot: fakeMaestro }));
+  assert.equal(good.ok, true, JSON.stringify(good.checks.filter((c) => !c.ok)));
+  const names = good.checks.map((c) => c.name);
+  assert.ok(names.some((n) => /every entry carries/.test(n)));
+  assert.ok(names.some((n) => /skill plane/.test(n)));
+  // The unregistered-marketplace state is reported (the archetype workflow IS
+  // reachable, the skill file is NOT), and it never hard-fails setup.
+  const skillCheck = good.checks.find((c) => /skill plane/.test(c.name));
+  assert.equal(skillCheck.ok, true);
+  assert.match(skillCheck.name, /skill plane: 1\/2 reachable/);
+  const degCheck = good.checks.find((c) => /degradations recorded/.test(c.name));
+  assert.equal(degCheck.ok, true);
+  assert.match(degCheck.remedy, /capability-manifest\.json/);
+});
+
+test("verify: a plane with ZERO reachable entries surfaces an explicit remedy (never silent)", async () => {
+  const { root, home, fakeMaestro } = tmpRoot();
+  await inventory.apply(ctxFor(root, home, { capabilityRepair: false }, { maestroRoot: fakeMaestro,
+    capabilityDeps: { orgProbeImpl: async () => ({ ok: false, detail: "org.cohort is not enabled", degraded: "org-not-enrolled", mandateFamily: false }) },
+  }));
+  const v = await inventory.verify(ctxFor(root, home, {}, { maestroRoot: fakeMaestro }));
+  const orgCheck = v.checks.find((c) => /org plane/.test(c.name));
+  assert.equal(orgCheck.ok, true, "an un-enrolled agent is a legitimate init state");
+  assert.match(orgCheck.remedy, /nothing on the org plane is reachable/);
+  assert.equal(v.ok, true);
+});
+
+test("archetypeOf reads the SoT and returns null when unset", () => {
+  const { root } = tmpRoot();
+  assert.deepEqual(archetypeOf(root), { function: "executive-operator", altitude: "c-suite" });
+  const { root: bare } = tmpRoot({ archetype: false });
+  assert.equal(archetypeOf(bare), null);
+});
+
+test("declareCapability fails OPEN and LOGS when hq rejects or is absent", async () => {
+  const { root } = tmpRoot();
+  const logs = [];
+  const rejected = await declareCapability(root, { schemaVersion: 1, entries: [] }, {
+    callImpl: async () => ({ ok: false, error: { code: "NOT_FOUND" } }),
+    logImpl: (m) => logs.push(m),
+  });
+  assert.equal(rejected.posted, false);
+  assert.equal(rejected.reason, "NOT_FOUND");
+  assert.ok(logs.some((l) => /kept local only/.test(l)), "the degradation is never silent");
+
+  const threw = await declareCapability(root, { schemaVersion: 1, entries: [] }, {
+    callImpl: async () => { throw new Error("ECONNREFUSED"); },
+    logImpl: (m) => logs.push(m),
+  });
+  assert.equal(threw.posted, false);
+  assert.ok(logs.some((l) => /ECONNREFUSED/.test(l)));
+});
+
+test("declareCapability sends ids + reachability only — never invocation details", async () => {
+  const { root } = tmpRoot();
+  let sent = null;
+  await declareCapability(root, {
+    schemaVersion: 1,
+    entries: [{ id: "board_ready", plane: "org", kind: "method_tool", reachable: true, probedAt: "t", blastRadius: "internal", costHint: "free", invocation: "board_ready", probe: { detail: "secret" } }],
+  }, { callImpl: async (m, p) => { sent = { m, p }; return { ok: true }; }, logImpl: () => {} });
+  assert.equal(sent.m, "mandate.declareCapability");
+  assert.deepEqual(Object.keys(sent.p.body[0]).sort(), ["blastRadius", "costHint", "id", "kind", "plane", "probedAt", "reachable"]);
+});