@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/subagents/refs.mjs

@@ -0,0 +1,274 @@
+/**
+ * lib/subagents/refs.mjs — THE single sub-agent reference parser (§2.1).
+ *
+ * WHY THIS EXISTS. Two regexes for the same job shipped in this repo and they
+ * disagreed:
+ *
+ *   bin/maestro.mjs:2261            /^\s+agent:\s*([\w-]+)\b/gm
+ *   scripts/ci/check-docs-accuracy  /^\s*-?\s*agent:\s*([A-Za-z0-9][A-Za-z0-9_-]*)\s*(#.*)?$/gm
+ *
+ * The first REQUIRES leading whitespace (so a top-level `agent: foo` is invisible
+ * to `doctor`), uses `\b` (so `agent: foo bar` matches `foo` and hides the
+ * malformed value), and matches inside a trailing comment. The second is stricter
+ * but only ever ran in CI over `workflows/`. The result: `doctor` and CI reported
+ * DIFFERENT dangling-reference sets for the same repo, and neither looked at
+ * `teams/*.yaml` `members:` or `config/event-routing.yaml` handlers at all — the
+ * two places that actually decide whether a sub-agent is idle.
+ *
+ * One parser, one grammar, four keys (`agent`/`delegate`/`subagent`/`handler`).
+ * Both callers are rewired to this module; the gap detector uses the same output.
+ *
+ * WHY event-routing gets its own walker. `config/event-routing.yaml` routes carry
+ * `{event, handler, via}` where `via` is one of `standard-agent`/`workflow`/`skill`.
+ * A bare `handler:` regex therefore reports every WORKFLOW id as a dangling agent
+ * — which is precisely the false-positive class that made the existing doctor
+ * warning unactionable. We read `via` and only treat agent-backed handlers as
+ * agent references; the rest are returned tagged so a caller can still see them.
+ *
+ * Node builtins only. Pure over strings; the directory walk is fail-open I/O.
+ * ESM.
+ *
+ * @module lib/subagents/refs
+ */
+
+"use strict";
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+/**
+ * The reference grammar, as a source string so both the CLI and CI can quote it
+ * in an error message rather than re-deriving it.
+ *
+ * `^\s*-?\s*` — a mapping key at ANY indent, optionally the first key of a list
+ * item (`- agent: foo`). `[A-Za-z0-9][\w-]*` — a slug: starts alphanumeric, then
+ * word chars or hyphens. `\s*(#.*)?$` — anchored to end-of-line so `agent: foo bar`
+ * does NOT match (a malformed value must be invisible, not silently truncated to
+ * `foo`, which is what `\b` did).
+ * @type {string}
+ */
+export const AGENT_REF_PATTERN = "^\\s*-?\\s*(agent|delegate|subagent|handler):\\s*([A-Za-z0-9][\\w-]*)\\s*(#.*)?$";
+
+/** Build a FRESH global regex (a shared /g regex carries lastIndex between calls). */
+export function agentRefRegex() {
+  return new RegExp(AGENT_REF_PATTERN, "gm");
+}
+
+/**
+ * Sentinels that mean "the executing agent itself", not a roster slug. Excluding
+ * them is not cosmetic: `agent-self` appears in most generated workflows and
+ * would otherwise be reported as the single most-dangling reference in the fleet.
+ * @type {ReadonlySet<string>}
+ */
+export const SELF_SENTINELS = Object.freeze(new Set(["agent-self", "agent_self", "self"]));
+
+/**
+ * `via:` values in event-routing that denote a SUB-AGENT handler. Anything else
+ * (`workflow`, `skill`) names a different artifact and must not be reported as a
+ * dangling agent.
+ * @type {ReadonlySet<string>}
+ */
+export const AGENT_VIA = Object.freeze(new Set(["standard-agent", "role-agent", "agent", "sub-agent", "subagent"]));
+
+/**
+ * Parse every sub-agent reference out of a text blob.
+ *
+ * @param {string} text
+ * @param {{kind?:string, file?:string}} [opts] `kind` labels the source
+ *   ("workflow"|"team"|"event-routing"|…) and is carried through to the caller.
+ * @returns {Array<{ref:string, key:string, line:number, kind:string, file?:string}>}
+ */
+export function parseAgentRefs(text, opts = {}) {
+  if (typeof text !== "string" || !text) return [];
+  const kind = opts.kind || "unknown";
+  const re = agentRefRegex();
+  const out = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const ref = m[2];
+    if (SELF_SENTINELS.has(ref)) continue;
+    out.push({ ref, key: m[1], line: lineOf(text, m.index), kind, ...(opts.file ? { file: opts.file } : {}) });
+  }
+  return out;
+}
+
+/** 1-indexed line number of a character offset. */
+function lineOf(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === "\n") line++;
+  return line;
+}
+
+/**
+ * Parse a `teams/*.yaml` `members:` block into agent references.
+ *
+ * The team files use a bare block sequence under `members:` (`- desktop-operator
+ * # comment`) — there is no `agent:` key, so {@link parseAgentRefs} cannot see
+ * them, which is why team membership was never checked. We walk the block
+ * explicitly and stop at the first line that is not a deeper-indented list item,
+ * so a sibling key (`responsibilities:`) ends it.
+ *
+ * `lead:` is also a reference (a team's lead is a sub-agent slug).
+ *
+ * @param {string} yamlText
+ * @param {{file?:string}} [opts]
+ * @returns {Array<{ref:string, key:string, line:number, kind:string, file?:string}>}
+ */
+export function parseTeamRefs(yamlText, opts = {}) {
+  if (typeof yamlText !== "string" || !yamlText) return [];
+  const out = [];
+  const lines = yamlText.split("\n");
+  let membersIndent = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+
+    const lead = raw.match(/^(\s*)lead:\s*([A-Za-z0-9][\w-]*)\s*(#.*)?$/);
+    if (lead && !SELF_SENTINELS.has(lead[2])) {
+      out.push({ ref: lead[2], key: "lead", line: i + 1, kind: "team", ...(opts.file ? { file: opts.file } : {}) });
+      continue;
+    }
+
+    const open = raw.match(/^(\s*)members:\s*(#.*)?$/);
+    if (open) { membersIndent = open[1].length; continue; }
+
+    if (membersIndent >= 0) {
+      const item = raw.match(/^(\s*)-\s*([A-Za-z0-9][\w-]*)\s*(#.*)?$/);
+      if (item && item[1].length > membersIndent) {
+        if (!SELF_SENTINELS.has(item[2])) {
+          out.push({ ref: item[2], key: "members", line: i + 1, kind: "team", ...(opts.file ? { file: opts.file } : {}) });
+        }
+        continue;
+      }
+      // Any non-deeper line ends the members block.
+      membersIndent = -1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse `config/event-routing.yaml` routes into agent references, honouring
+ * `via:` so workflow/skill handlers are NOT reported as agents.
+ *
+ * The generated file is a flat list of `- event: … / handler: … / via: …` maps
+ * (see lib/capability.buildEventRouting), so a small line walker is both
+ * sufficient and immune to the ordering of the three keys within a route.
+ *
+ * @param {string} yamlText
+ * @param {{file?:string}} [opts]
+ * @returns {Array<{ref:string, key:string, line:number, kind:string, via:string, isAgent:boolean, file?:string}>}
+ */
+export function parseEventRoutingRefs(yamlText, opts = {}) {
+  if (typeof yamlText !== "string" || !yamlText) return [];
+  const lines = yamlText.split("\n");
+  const routes = [];
+  let cur = null;
+  const flush = () => { if (cur && cur.handler) routes.push(cur); cur = null; };
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+    // A list-item dash starts a new route regardless of which key follows it.
+    if (/^\s*-\s/.test(raw)) {
+      flush();
+      cur = { handler: "", via: "", line: i + 1 };
+    }
+    const h = raw.match(/^\s*-?\s*handler:\s*([A-Za-z0-9][\w-]*)\s*(#.*)?$/);
+    if (h) { if (!cur) cur = { handler: "", via: "", line: i + 1 }; cur.handler = h[1]; cur.line = i + 1; continue; }
+    const v = raw.match(/^\s*-?\s*via:\s*([A-Za-z0-9][\w-]*)\s*(#.*)?$/);
+    if (v) { if (!cur) cur = { handler: "", via: "", line: i + 1 }; cur.via = v[1]; continue; }
+  }
+  flush();
+
+  const file = opts.file;
+  return routes
+    .filter((r) => !SELF_SENTINELS.has(r.handler))
+    .map((r) => ({
+      ref: r.handler,
+      key: "handler",
+      line: r.line,
+      kind: "event-routing",
+      via: r.via || "",
+      // An absent `via` is treated as an agent handler: the four seed routes
+      // buildEventRouting emits always carry `via: standard-agent`, so a route
+      // WITHOUT one was hand-added and an agent is the likeliest intent.
+      isAgent: !r.via || AGENT_VIA.has(r.via),
+      ...(file ? { file } : {}),
+    }));
+}
+
+/** Recursively list files under `dir` whose name matches `test`. Fail-open. */
+function walk(dir, test, out = []) {
+  if (!existsSync(dir)) return out;
+  let names;
+  try { names = readdirSync(dir); } catch { return out; }
+  for (const name of names) {
+    if (name.startsWith(".") || name === "node_modules") continue;
+    const full = join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) walk(full, test, out);
+    else if (st.isFile() && test(name)) out.push(full);
+  }
+  return out;
+}
+
+const isYaml = (n) => /\.ya?ml$/.test(n);
+
+/**
+ * Scan an agent repo for every sub-agent reference: `workflows/**` (+ any extra
+ * dirs), `teams/*.yaml`, and `config/event-routing.yaml`.
+ *
+ * This is the input to the gap detector's "unrostered" and "idle" sets, so it
+ * must cover every place a reference can hide — the whole reason the previous
+ * workflow-only scan under-reported.
+ *
+ * Fail-open: an unreadable file is skipped, never fatal.
+ *
+ * @param {{agentRoot:string, dirs?:string[], includeNonAgentRouting?:boolean}} o
+ * @returns {Array<{ref:string, key:string, line:number, kind:string, file:string, via?:string}>}
+ */
+export function scanAgentRefs(o = {}) {
+  const agentRoot = o.agentRoot;
+  if (!agentRoot) return [];
+  const out = [];
+  const rel = (p) => relative(agentRoot, p) || p;
+  const readSafe = (p) => { try { return readFileSync(p, "utf8"); } catch { return ""; } };
+
+  for (const d of o.dirs || ["workflows"]) {
+    for (const f of walk(join(agentRoot, d), isYaml)) {
+      out.push(...parseAgentRefs(readSafe(f), { kind: "workflow", file: rel(f) }));
+    }
+  }
+
+  for (const f of walk(join(agentRoot, "teams"), isYaml)) {
+    out.push(...parseTeamRefs(readSafe(f), { file: rel(f) }));
+  }
+
+  const routing = join(agentRoot, "config", "event-routing.yaml");
+  if (existsSync(routing)) {
+    for (const r of parseEventRoutingRefs(readSafe(routing), { file: rel(routing) })) {
+      if (r.isAgent || o.includeNonAgentRouting) out.push(r);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Collapse a reference list into `slug → [{file,line,kind}]`. The gap report
+ * prints file:line for every accepted drop (§2.3: the section NEVER edits a
+ * workflow, it tells the operator exactly what to delete).
+ * @param {Array<object>} refs
+ * @returns {Map<string, Array<{file:string, line:number, kind:string}>>}
+ */
+export function groupRefs(refs) {
+  const m = new Map();
+  for (const r of refs || []) {
+    if (!r || !r.ref) continue;
+    if (!m.has(r.ref)) m.set(r.ref, []);
+    m.get(r.ref).push({ file: r.file || "", line: r.line || 0, kind: r.kind || "unknown" });
+  }
+  return m;
+}

package/lib/subagents/refs.test.mjs

@@ -0,0 +1,204 @@
+/**
+ * refs.test.mjs — THE single sub-agent reference parser (§2.1).
+ * Run: node --test lib/subagents/refs.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  AGENT_REF_PATTERN,
+  AGENT_VIA,
+  SELF_SENTINELS,
+  agentRefRegex,
+  groupRefs,
+  parseAgentRefs,
+  parseEventRoutingRefs,
+  parseTeamRefs,
+  scanAgentRefs,
+} from "./refs.mjs";
+
+/** The two regexes this module replaces, verbatim, so the fixes are provable. */
+const OLD_DOCTOR = () => /^\s+agent:\s*([\w-]+)\b/gm;
+
+function repo() {
+  const root = mkdtempSync(join(tmpdir(), "subagent-refs-"));
+  mkdirSync(join(root, "workflows"), { recursive: true });
+  mkdirSync(join(root, "teams"), { recursive: true });
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+const refsOf = (list) => list.map((r) => r.ref);
+
+// ---------------------------------------------------------------------------
+// parseAgentRefs — the grammar and the two bugs it fixes
+// ---------------------------------------------------------------------------
+
+test("parseAgentRefs: matches all four keys at any indent, including a list item", () => {
+  const text = [
+    "agent: top-level",
+    "  agent: indented",
+    "  - agent: in-a-list",
+    "  delegate: delegated",
+    "  subagent: subbed",
+    "  handler: handled",
+  ].join("\n");
+  assert.deepEqual(refsOf(parseAgentRefs(text, { kind: "workflow" })),
+    ["top-level", "indented", "in-a-list", "delegated", "subbed", "handled"]);
+});
+
+test("parseAgentRefs: a TOP-LEVEL `agent:` is visible (the old doctor regex missed it)", () => {
+  const text = "agent: top-level\n";
+  assert.equal(OLD_DOCTOR().exec(text), null, "sanity: the old regex really did miss it");
+  assert.deepEqual(refsOf(parseAgentRefs(text)), ["top-level"]);
+});
+
+test("parseAgentRefs: a malformed value is INVISIBLE, not silently truncated", () => {
+  // The old `\b` regex matched `agent: foo bar` and reported `foo`, hiding the
+  // malformation. Anchoring to end-of-line makes a bad value a non-match, which
+  // is what lets a caller trust the set it gets.
+  const text = "  agent: foo bar\n";
+  assert.equal(OLD_DOCTOR().exec(text)[1], "foo", "sanity: the old regex truncated");
+  assert.deepEqual(parseAgentRefs(text), []);
+});
+
+test("parseAgentRefs: a trailing comment is allowed and stripped", () => {
+  assert.deepEqual(refsOf(parseAgentRefs("  agent: alpha   # why\n")), ["alpha"]);
+});
+
+test("parseAgentRefs: self sentinels are skipped", () => {
+  const text = ["  agent: agent-self", "  agent: agent_self", "  agent: self", "  agent: real"].join("\n");
+  assert.deepEqual(refsOf(parseAgentRefs(text)), ["real"]);
+  for (const s of ["agent-self", "agent_self", "self"]) assert.equal(SELF_SENTINELS.has(s), true);
+});
+
+test("parseAgentRefs: reports 1-indexed line numbers and carries kind/file", () => {
+  const out = parseAgentRefs("x: 1\ny: 2\n  agent: alpha\n", { kind: "workflow", file: "workflows/a.yaml" });
+  assert.deepEqual(out, [{ ref: "alpha", key: "agent", line: 3, kind: "workflow", file: "workflows/a.yaml" }]);
+});
+
+test("agentRefRegex: a FRESH regex per call (a shared /g carries lastIndex)", () => {
+  const text = "  agent: alpha\n  agent: beta\n";
+  assert.deepEqual(refsOf(parseAgentRefs(text)), ["alpha", "beta"]);
+  assert.deepEqual(refsOf(parseAgentRefs(text)), ["alpha", "beta"], "second call must not resume mid-string");
+  assert.equal(agentRefRegex().source, AGENT_REF_PATTERN);
+  assert.equal(agentRefRegex().lastIndex, 0);
+});
+
+test("parseAgentRefs: non-string / empty input returns []", () => {
+  assert.deepEqual(parseAgentRefs(null), []);
+  assert.deepEqual(parseAgentRefs(""), []);
+  assert.deepEqual(parseAgentRefs(42), []);
+});
+
+// ---------------------------------------------------------------------------
+// teams/*.yaml — membership was never checked before
+// ---------------------------------------------------------------------------
+
+test("parseTeamRefs: reads `lead:` and the `members:` block sequence", () => {
+  const y = [
+    "id: growth",
+    "lead: growth-lead",
+    "members:",
+    "  - desktop-operator   # comment",
+    "  - research-analyst",
+    "responsibilities:",
+    "  - not-an-agent",
+  ].join("\n");
+  const out = parseTeamRefs(y, { file: "teams/growth.yaml" });
+  assert.deepEqual(refsOf(out), ["growth-lead", "desktop-operator", "research-analyst"]);
+  assert.equal(out.every((r) => r.kind === "team" && r.file === "teams/growth.yaml"), true);
+});
+
+test("parseTeamRefs: a sibling key ENDS the members block", () => {
+  const y = ["members:", "  - alpha", "other:", "  - beta"].join("\n");
+  assert.deepEqual(refsOf(parseTeamRefs(y)), ["alpha"]);
+});
+
+test("parseTeamRefs: skips self sentinels", () => {
+  assert.deepEqual(refsOf(parseTeamRefs("members:\n  - agent-self\n  - alpha\n")), ["alpha"]);
+});
+
+// ---------------------------------------------------------------------------
+// event-routing — `via:` is what stops every workflow id being reported
+// ---------------------------------------------------------------------------
+
+test("parseEventRoutingRefs: `via` decides whether a handler is an AGENT", () => {
+  const y = [
+    "routes:",
+    "  - event: inbox.received",
+    "    handler: triage-agent",
+    "    via: standard-agent",
+    "  - event: cadence.tick",
+    "    handler: daily-brief",
+    "    via: workflow",
+    "  - event: x.y",
+    "    handler: some-skill",
+    "    via: skill",
+  ].join("\n");
+  const out = parseEventRoutingRefs(y, { file: "config/event-routing.yaml" });
+  assert.deepEqual(out.map((r) => [r.ref, r.isAgent]), [
+    ["triage-agent", true],
+    ["daily-brief", false],
+    ["some-skill", false],
+  ]);
+});
+
+test("parseEventRoutingRefs: a route with NO `via` is treated as an agent handler", () => {
+  const out = parseEventRoutingRefs("  - event: e\n    handler: mystery\n");
+  assert.deepEqual(out.map((r) => [r.ref, r.isAgent, r.via]), [["mystery", true, ""]]);
+});
+
+test("parseEventRoutingRefs: key order within a route does not matter", () => {
+  const y = ["  - via: standard-agent", "    handler: alpha", "  - handler: beta", "    via: workflow"].join("\n");
+  assert.deepEqual(parseEventRoutingRefs(y).map((r) => [r.ref, r.isAgent]), [["alpha", true], ["beta", false]]);
+  for (const v of ["standard-agent", "role-agent", "agent"]) assert.equal(AGENT_VIA.has(v), true);
+});
+
+// ---------------------------------------------------------------------------
+// scanAgentRefs — all three sources in one pass
+// ---------------------------------------------------------------------------
+
+test("scanAgentRefs: covers workflows + teams + event-routing, and filters non-agent routes", () => {
+  const root = repo();
+  mkdirSync(join(root, "workflows", "nested"), { recursive: true });
+  writeFileSync(join(root, "workflows", "a.yaml"), "steps:\n  - agent: alpha\n  - agent: agent-self\n");
+  writeFileSync(join(root, "workflows", "nested", "b.yml"), "  agent: nested-one\n");
+  writeFileSync(join(root, "workflows", "notes.md"), "  agent: ignored-non-yaml\n");
+  writeFileSync(join(root, "teams", "t.yaml"), "members:\n  - team-member\n");
+  writeFileSync(join(root, "config", "event-routing.yaml"),
+    "  - event: e\n    handler: routed-agent\n    via: standard-agent\n  - event: f\n    handler: some-workflow\n    via: workflow\n");
+
+  const refs = scanAgentRefs({ agentRoot: root });
+  assert.deepEqual(refsOf(refs).sort(), ["alpha", "nested-one", "routed-agent", "team-member"]);
+  assert.deepEqual([...new Set(refs.map((r) => r.kind))].sort(), ["event-routing", "team", "workflow"]);
+  assert.equal(refs.every((r) => r.file && !r.file.startsWith("/")), true, "paths are agentRoot-relative");
+});
+
+test("scanAgentRefs: includeNonAgentRouting surfaces workflow/skill handlers too", () => {
+  const root = repo();
+  writeFileSync(join(root, "config", "event-routing.yaml"), "  - event: f\n    handler: some-workflow\n    via: workflow\n");
+  assert.deepEqual(refsOf(scanAgentRefs({ agentRoot: root })), []);
+  assert.deepEqual(refsOf(scanAgentRefs({ agentRoot: root, includeNonAgentRouting: true })), ["some-workflow"]);
+});
+
+test("scanAgentRefs: fail-open on a missing root / missing dirs", () => {
+  assert.deepEqual(scanAgentRefs({}), []);
+  assert.deepEqual(scanAgentRefs({ agentRoot: join(tmpdir(), "definitely-not-here-12345") }), []);
+});
+
+test("groupRefs: collapses to slug → locations", () => {
+  const m = groupRefs([
+    { ref: "alpha", file: "w/a.yaml", line: 2, kind: "workflow" },
+    { ref: "alpha", file: "w/b.yaml", line: 9, kind: "workflow" },
+    { ref: "beta", file: "t/t.yaml", line: 1, kind: "team" },
+    null,
+  ]);
+  assert.equal(m.get("alpha").length, 2);
+  assert.deepEqual(m.get("beta"), [{ file: "t/t.yaml", line: 1, kind: "team" }]);
+  assert.equal(m.size, 2);
+});