@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/subagents/schema.mjs

@@ -0,0 +1,467 @@
+/**
+ * lib/subagents/schema.mjs — the repo's first sub-agent frontmatter parser +
+ * validator (Sub-Agent Registry v1 §2.1).
+ *
+ * WHY THIS EXISTS. Until now nothing in maestro parsed `agents/<slug>/agent.md`.
+ * `doctor` only grepped for `agent:` references and checked that a DIRECTORY
+ * existed — so an empty `agents/foo/` passed, and a generated agent.md whose
+ * `model:` said `sonnet` while every shipped one said `claude-sonnet-4-6` drifted
+ * silently for months. The registry cannot distribute prose it cannot validate,
+ * so the validator is the first thing built and it is the SAME rule set the hq
+ * handler (`src/server/subagents/validate.ts`) applies server-side. A body that
+ * fails here is refused at materialisation; a body that fails there is refused at
+ * publish. Two gates, one rule set.
+ *
+ * WHY A HAND-ROLLED PARSER RATHER THAN js-yaml. Three reasons, in order:
+ *   1. `resolve()`, `verify()` and `doctor` must be SYNCHRONOUS and must run with
+ *      zero I/O beyond the file read. Every other yaml consumer in this repo does
+ *      `await import("js-yaml")`, which would make the whole resolution path
+ *      async for no benefit.
+ *   2. The frontmatter grammar is genuinely tiny and CLOSED: `key: scalar`,
+ *      `key: [a, b]` (flow sequence, quoted or bare) and a block sequence of
+ *      `- item` lines. Every shipped agent.md and every generated one uses only
+ *      those. A closed grammar we can refuse outside of is safer than a general
+ *      parser that will happily accept an anchor/alias/merge-key we then have to
+ *      round-trip byte-exactly into hq.
+ *   3. The registry has to WRITE frontmatter back (provenance stamping), and a
+ *      full YAML emitter reformats the whole block — which would change the file
+ *      hash of every managed file on every materialisation and make local-edit
+ *      detection (§3 rule 1) permanently wrong.
+ * Anything outside the grammar is an ERROR, never a silent mis-parse.
+ *
+ * Node builtins only (node:crypto). Pure — no I/O. ESM.
+ *
+ * @module lib/subagents/schema
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+import { KNOWN_TOKENS, collectTokens } from "../render.mjs";
+
+/**
+ * Model alias → the full Anthropic id the runtime actually dispatches on.
+ *
+ * This map is the place the shipped-vs-generated drift dies. `agents/*.md` that
+ * shipped with the SDK all say `claude-sonnet-4-6`; `generate-capability.mjs`
+ * emitted the bare alias `sonnet`. Both are accepted on INPUT and both normalise
+ * to the same full id on OUTPUT, so a fork of a shipped agent and a freshly
+ * generated one are byte-comparable. Full ids map to themselves so normalisation
+ * is idempotent (critical: it runs on every materialisation, and a
+ * non-idempotent normalisation would change the file hash every pass).
+ *
+ * Ids match lib/model-router/resolve.mjs (`claude-opus-4-8` / `claude-sonnet-4-6`
+ * / `claude-haiku-4-5`). Extend deliberately and in lockstep with hq's
+ * `validate.ts` — a divergence here means hq stores a model id the agent refuses.
+ * @type {Readonly<Record<string,string>>}
+ */
+export const MODEL_ALIASES = Object.freeze({
+  opus: "claude-opus-4-8",
+  sonnet: "claude-sonnet-4-6",
+  haiku: "claude-haiku-4-5",
+  "claude-opus-4-8": "claude-opus-4-8",
+  "claude-sonnet-4-6": "claude-sonnet-4-6",
+  "claude-haiku-4-5": "claude-haiku-4-5",
+  // `inherit` is Claude Code's "use the parent session's model" sentinel. It is
+  // a legitimate value, not an alias, so it passes through untouched.
+  inherit: "inherit",
+});
+
+/**
+ * Frontmatter keys the registry OWNS. They are stamped at materialisation and
+ * stripped before a body is published back, so a round-trip
+ * (publish → resolve → materialise) is stable and never accumulates provenance.
+ * @type {readonly string[]}
+ */
+export const PROVENANCE_KEYS = Object.freeze(["layer", "source", "version", "contentHash"]);
+
+/** The authored keys, in the canonical emit order. */
+export const AUTHORED_KEYS = Object.freeze(["name", "description", "model", "tools", "tokens"]);
+
+/** sha256 hex of a string. The one hashing primitive the registry uses. */
+function sha256(s) {
+  return createHash("sha256").update(String(s), "utf8").digest("hex");
+}
+
+/**
+ * sha256 of a version BODY — the identity hq stores as
+ * `SubagentVersion.contentHash`. Used for dedupe and for "is my pinned version
+ * still the one the roster says". NOT used for local-edit detection.
+ * @param {string} body
+ * @returns {string}
+ */
+export function hashBody(body) {
+  return sha256(body == null ? "" : body);
+}
+
+/**
+ * sha256 of a whole agent.md FILE (frontmatter + body, exact bytes).
+ *
+ * This — not {@link hashBody} — is what local-edit detection (§3 rule 1) and the
+ * SDK manifest compare, because what is on disk is the whole file including the
+ * provenance stamp. The spec's rule 1 says "sha256(file) ≠ lock[slug].contentHash";
+ * we keep BOTH hashes in the lock (`fileHash` for the disk comparison,
+ * `contentHash` for the hq body identity) rather than conflating two different
+ * preimages under one name, which would make every stamped file look locally
+ * edited the moment it was written.
+ * @param {string} text
+ * @returns {string}
+ */
+export function hashFile(text) {
+  return sha256(text == null ? "" : text);
+}
+
+/**
+ * Split an agent.md into its frontmatter text and body.
+ *
+ * Requires the document to OPEN with `---` on line 1 (Claude Code's own rule) and
+ * close with a `---` line. A file without frontmatter is an error, not an empty
+ * frontmatter — silently treating a prose-only file as valid is how an empty
+ * `agents/foo/` directory used to pass doctor.
+ *
+ * @param {string} text
+ * @returns {{ok:boolean, frontmatterText:string, body:string, error?:string}}
+ */
+export function splitFrontmatter(text) {
+  const src = typeof text === "string" ? text : "";
+  // Tolerate a UTF-8 BOM and CRLF line endings — both show up in files that have
+  // been round-tripped through an editor on a shared drive.
+  const clean = src.replace(/^/, "").replace(/\r\n/g, "\n");
+  if (!clean.startsWith("---\n")) {
+    return { ok: false, frontmatterText: "", body: clean, error: "missing opening --- frontmatter fence" };
+  }
+  const end = clean.indexOf("\n---", 3);
+  if (end === -1) {
+    return { ok: false, frontmatterText: "", body: clean, error: "unterminated frontmatter (no closing ---)" };
+  }
+  const frontmatterText = clean.slice(4, end + 1);
+  // Body starts after the closing fence's own newline (or EOF if it is last).
+  const afterFence = clean.indexOf("\n", end + 1);
+  const body = afterFence === -1 ? "" : clean.slice(afterFence + 1);
+  return { ok: true, frontmatterText, body };
+}
+
+/**
+ * Parse the closed frontmatter grammar into a plain object.
+ *
+ * Grammar (anything else is an error):
+ *   key: scalar                  → string (quotes stripped, `#` comment stripped
+ *                                  ONLY when unquoted and preceded by a space)
+ *   key: [a, "b", 'c']           → string[]
+ *   key:                         → string[] built from following `- item` lines
+ *     - a
+ *     - b
+ *
+ * @param {string} frontmatterText
+ * @returns {{ok:boolean, value:Object, errors:string[]}}
+ */
+export function parseFrontmatter(frontmatterText) {
+  const out = {};
+  const errors = [];
+  const lines = String(frontmatterText || "").split("\n");
+  let pendingListKey = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!raw.trim()) continue;
+    if (/^\s*#/.test(raw)) continue;
+
+    // Block-sequence item belonging to the previous `key:` with an empty value.
+    const item = raw.match(/^\s+-\s+(.*)$/);
+    if (item) {
+      if (!pendingListKey) {
+        errors.push(`line ${i + 1}: list item with no owning key ("${raw.trim()}")`);
+        continue;
+      }
+      out[pendingListKey].push(unquote(stripComment(item[1])));
+      continue;
+    }
+
+    const kv = raw.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!kv) {
+      errors.push(`line ${i + 1}: not a "key: value" pair ("${raw.trim()}") — nested maps are outside the frontmatter grammar`);
+      pendingListKey = null;
+      continue;
+    }
+    const key = kv[1];
+    const rest = kv[2];
+
+    if (rest.trim() === "") {
+      // `key:` with nothing after it opens a block sequence.
+      out[key] = [];
+      pendingListKey = key;
+      continue;
+    }
+    pendingListKey = null;
+
+    const flow = rest.trim();
+    if (flow.startsWith("[")) {
+      if (!flow.endsWith("]")) {
+        errors.push(`line ${i + 1}: unterminated flow sequence for "${key}"`);
+        continue;
+      }
+      out[key] = splitFlowSeq(flow.slice(1, -1));
+      continue;
+    }
+    out[key] = unquote(stripComment(rest));
+  }
+
+  return { ok: errors.length === 0, value: out, errors };
+}
+
+/**
+ * Split the inside of a `[...]` flow sequence on commas that are not inside
+ * quotes. A naive `.split(",")` breaks on `tools: ["Read, maybe"]` — unlikely but
+ * the registry round-trips these bytes into a database, so "unlikely" is not a
+ * licence to corrupt.
+ * @param {string} inner
+ * @returns {string[]}
+ */
+function splitFlowSeq(inner) {
+  const out = [];
+  let cur = "";
+  let quote = "";
+  for (const ch of inner) {
+    if (quote) {
+      if (ch === quote) quote = "";
+      else cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; continue; }
+    if (ch === ",") { out.push(cur.trim()); cur = ""; continue; }
+    cur += ch;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out.filter(Boolean);
+}
+
+/** Strip a trailing ` # comment` from an UNQUOTED scalar. */
+function stripComment(s) {
+  const t = String(s);
+  if (t.startsWith('"') || t.startsWith("'")) return t; // quoted: `#` is content
+  const idx = t.indexOf(" #");
+  return (idx === -1 ? t : t.slice(0, idx)).trim();
+}
+
+/** Strip a single layer of matching quotes. */
+function unquote(s) {
+  const t = String(s).trim();
+  if (t.length >= 2 && ((t[0] === '"' && t.endsWith('"')) || (t[0] === "'" && t.endsWith("'")))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+/**
+ * Emit a frontmatter object back to text using the SAME shapes the shipped files
+ * use (scalars bare, sequences as JSON-ish flow arrays with double quotes), in a
+ * canonical key order: authored keys first, then provenance, then anything else.
+ *
+ * Canonical ordering matters: it is what makes `hashFile` stable across a
+ * re-materialisation, which is what makes local-edit detection trustworthy.
+ *
+ * @param {object} fm
+ * @returns {string} the text BETWEEN the fences (trailing newline included)
+ */
+export function stringifyFrontmatter(fm) {
+  const obj = fm && typeof fm === "object" ? fm : {};
+  const seen = new Set();
+  const order = [...AUTHORED_KEYS, ...PROVENANCE_KEYS];
+  const keys = [];
+  for (const k of order) if (Object.prototype.hasOwnProperty.call(obj, k)) { keys.push(k); seen.add(k); }
+  for (const k of Object.keys(obj)) if (!seen.has(k)) keys.push(k);
+
+  const lines = [];
+  for (const k of keys) {
+    const v = obj[k];
+    if (v === undefined || v === null) continue;
+    if (Array.isArray(v)) {
+      lines.push(`${k}: [${v.map((x) => JSON.stringify(String(x))).join(", ")}]`);
+      continue;
+    }
+    lines.push(`${k}: ${String(v)}`);
+  }
+  return lines.length ? `${lines.join("\n")}\n` : "";
+}
+
+/** Re-assemble a full agent.md from a frontmatter object + body. */
+export function stringifyAgentMd(fm, body) {
+  const b = typeof body === "string" ? body : "";
+  return `---\n${stringifyFrontmatter(fm)}---\n${b.startsWith("\n") ? b.slice(1) : b}`;
+}
+
+/**
+ * Parse a whole agent.md. Never throws.
+ * @param {string} text
+ * @returns {{ok:boolean, frontmatter:object, body:string, errors:string[]}}
+ */
+export function parseAgentMd(text) {
+  const split = splitFrontmatter(text);
+  if (!split.ok) return { ok: false, frontmatter: {}, body: split.body, errors: [split.error] };
+  const fm = parseFrontmatter(split.frontmatterText);
+  return { ok: fm.ok, frontmatter: fm.value, body: split.body, errors: fm.errors };
+}
+
+/**
+ * Normalise a model value to its full id. Returns "" for an empty/absent value
+ * and `null` for a value that is neither an alias nor a known full id — the
+ * caller turns that into a validation error rather than guessing.
+ * @param {*} m
+ * @returns {string|null}
+ */
+export function normaliseModel(m) {
+  const s = m == null ? "" : String(m).trim();
+  if (!s) return "";
+  const hit = MODEL_ALIASES[s.toLowerCase()];
+  return hit === undefined ? null : hit;
+}
+
+/**
+ * The `{{agent.*}}`-style token paths a BODY actually uses (deduped, sorted).
+ * Reuses lib/render.mjs's collector so the registry and the renderer can never
+ * disagree about what a token even is.
+ * @param {string} body
+ * @returns {string[]}
+ */
+export function bodyTokens(body) {
+  return [...new Set(collectTokens(typeof body === "string" ? body : ""))].sort();
+}
+
+/**
+ * Token paths in `tokens[]` that this agent's LOCAL renderer cannot resolve.
+ *
+ * This is the materialisation gate: hq deliberately does NOT vendor KNOWN_TOKENS
+ * (it stores and returns whatever the author declared), so the FETCHING agent is
+ * the one that refuses a body it could not render. Refusing here is what makes
+ * `scripts/ci/check-unresolved-tokens.mjs` structurally unable to fail after a
+ * fetch — an unrenderable body never reaches disk.
+ *
+ * @param {string[]} tokens
+ * @param {Set<string>} [known] injectable for tests
+ * @returns {string[]}
+ */
+export function unsupportedTokens(tokens, known = KNOWN_TOKENS) {
+  return (Array.isArray(tokens) ? tokens : []).filter((t) => !known.has(String(t)));
+}
+
+/**
+ * Validate a parsed agent.md against the registry rules (§1.3 / §2.1).
+ *
+ * Rules, all of them errors:
+ *   - `name` present and EQUAL to the slug (identity is the directory name;
+ *     §3 makes this the whole identity story, so a mismatch is unresolvable)
+ *   - `description` non-empty
+ *   - `model` normalises to a known id
+ *   - `tools` a non-empty array of non-empty strings
+ *   - every token used in the body is declared in `tokens[]` (when `tokens` is
+ *     declared at all — an absent `tokens` is DERIVED from the body, not an
+ *     error, so existing shipped files validate unchanged)
+ *   - body non-empty
+ *
+ * @param {{frontmatter:object, body:string, slug:string, known?:Set<string>}} o
+ * @returns {{ok:boolean, errors:string[], warnings:string[], normalised:{frontmatter:object, body:string}}}
+ */
+export function validateAgentMd(o = {}) {
+  const fm = o.frontmatter && typeof o.frontmatter === "object" ? { ...o.frontmatter } : {};
+  const body = typeof o.body === "string" ? o.body : "";
+  const slug = String(o.slug || "").trim();
+  const errors = [];
+  const warnings = [];
+
+  const name = String(fm.name || "").trim();
+  if (!name) errors.push("frontmatter.name is required");
+  else if (slug && name !== slug) errors.push(`frontmatter.name "${name}" must equal the directory name "${slug}"`);
+
+  const description = String(fm.description || "").trim();
+  if (!description) errors.push("frontmatter.description is required and must be non-empty");
+
+  const model = normaliseModel(fm.model);
+  if (model === null) errors.push(`frontmatter.model "${fm.model}" is not a known model or alias (${Object.keys(MODEL_ALIASES).join(", ")})`);
+  else if (!model) errors.push("frontmatter.model is required");
+
+  const tools = Array.isArray(fm.tools) ? fm.tools.map((t) => String(t).trim()).filter(Boolean) : null;
+  if (!tools) errors.push("frontmatter.tools is required and must be an array");
+  else if (!tools.length) errors.push("frontmatter.tools must be non-empty");
+
+  const used = bodyTokens(body);
+  let tokens;
+  if (fm.tokens === undefined) {
+    // Derived, not demanded: every file that shipped before the registry existed
+    // has no `tokens:` key, and forcing one would fail-closed the entire fleet on
+    // the first `doctor` run after upgrade.
+    tokens = used;
+  } else {
+    tokens = Array.isArray(fm.tokens) ? fm.tokens.map((t) => String(t).trim()).filter(Boolean) : [];
+    if (!Array.isArray(fm.tokens)) errors.push("frontmatter.tokens must be an array when present");
+    const undeclared = used.filter((t) => !tokens.includes(t));
+    if (undeclared.length) errors.push(`body uses undeclared token(s): ${undeclared.join(", ")}`);
+    const unused = tokens.filter((t) => !used.includes(t));
+    if (unused.length) warnings.push(`tokens declared but unused in body: ${unused.join(", ")}`);
+  }
+
+  const unknown = unsupportedTokens(tokens, o.known);
+  if (unknown.length) warnings.push(`token(s) unknown to this agent's renderer: ${unknown.join(", ")}`);
+
+  if (!body.trim()) errors.push("body is empty");
+
+  const normalised = {
+    frontmatter: {
+      ...fm,
+      name: name || slug,
+      description,
+      model: model || fm.model,
+      tools: tools || [],
+      tokens,
+    },
+    body,
+  };
+  return { ok: errors.length === 0, errors, warnings, normalised };
+}
+
+/**
+ * Convenience: parse + validate a raw agent.md in one call.
+ * @param {string} text @param {string} slug @param {Set<string>} [known]
+ */
+export function checkAgentFile(text, slug, known) {
+  const parsed = parseAgentMd(text);
+  if (!parsed.ok) return { ok: false, errors: parsed.errors, warnings: [], frontmatter: parsed.frontmatter, body: parsed.body };
+  const v = validateAgentMd({ frontmatter: parsed.frontmatter, body: parsed.body, slug, known });
+  return { ...v, frontmatter: parsed.frontmatter, body: parsed.body };
+}
+
+/**
+ * Strip the registry-owned provenance keys from a frontmatter object.
+ * Called before PUBLISHING a local file back to hq: provenance describes where a
+ * copy came from, so shipping it upstream would make the next fetch claim to have
+ * come from itself.
+ * @param {object} fm
+ * @returns {object}
+ */
+export function stripProvenance(fm) {
+  const out = { ...(fm && typeof fm === "object" ? fm : {}) };
+  for (const k of PROVENANCE_KEYS) delete out[k];
+  return out;
+}
+
+/**
+ * Stamp provenance onto a body + frontmatter and emit the full agent.md text.
+ *
+ * Tokens are NEVER rendered here (§3): `{{agent.*}}` survives to disk and is
+ * rendered at LOAD time by lib/render.mjs. Rendering at materialisation would
+ * bake one agent's identity into a file the registry then treats as the shared
+ * definition — the exact identity-leak class lib/render.mjs exists to close.
+ *
+ * @param {{frontmatter:object, body:string, layer:string, source?:string, version?:number|string, contentHash?:string}} o
+ * @returns {string} the full agent.md text ready to write
+ */
+export function stampProvenance(o = {}) {
+  const fm = stripProvenance(o.frontmatter);
+  fm.layer = String(o.layer || "sdk");
+  if (o.source) fm.source = String(o.source);
+  if (o.version !== undefined && o.version !== null && o.version !== "") fm.version = String(o.version);
+  const hash = o.contentHash || hashBody(o.body);
+  if (hash) fm.contentHash = String(hash);
+  return stringifyAgentMd(fm, o.body);
+}
+
+export { KNOWN_TOKENS };