@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/subagents/schema.test.mjs

@@ -1,328 +0,0 @@
-/**
- * schema.test.mjs — the frontmatter parser/validator (Sub-Agent Registry §2.1).
- * Run: node --test lib/subagents/schema.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import {
-  AUTHORED_KEYS,
-  MODEL_ALIASES,
-  PROVENANCE_KEYS,
-  bodyTokens,
-  checkAgentFile,
-  hashBody,
-  hashFile,
-  normaliseModel,
-  parseAgentMd,
-  parseFrontmatter,
-  splitFrontmatter,
-  stampProvenance,
-  stringifyAgentMd,
-  stringifyFrontmatter,
-  stripProvenance,
-  unsupportedTokens,
-  validateAgentMd,
-} from "./schema.mjs";
-import { listAgentDirs } from "./manifest.mjs";
-
-const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
-
-const GOOD = [
-  "---",
-  "name: alpha",
-  "description: Handles alpha work.",
-  "model: claude-sonnet-4-6",
-  'tools: ["Read", "Write"]',
-  "---",
-  "# alpha",
-  "",
-  "Serve {{agent.firstName}}.",
-  "",
-].join("\n");
-
-// ---------------------------------------------------------------------------
-// splitFrontmatter
-// ---------------------------------------------------------------------------
-
-test("splitFrontmatter: splits fences and keeps the body verbatim", () => {
-  const s = splitFrontmatter(GOOD);
-  assert.equal(s.ok, true);
-  assert.match(s.frontmatterText, /^name: alpha\n/);
-  assert.match(s.body, /^# alpha\n/);
-});
-
-test("splitFrontmatter: a prose-only file is an ERROR, not empty frontmatter", () => {
-  // The bug this closes: an agents/<slug>/ with no real frontmatter used to pass
-  // doctor because doctor only checked that the directory existed.
-  const s = splitFrontmatter("# alpha\n\njust prose\n");
-  assert.equal(s.ok, false);
-  assert.match(s.error, /missing opening/);
-});
-
-test("splitFrontmatter: unterminated frontmatter is an error", () => {
-  const s = splitFrontmatter("---\nname: alpha\n# no closing fence\n");
-  assert.equal(s.ok, false);
-  assert.match(s.error, /unterminated/);
-});
-
-test("splitFrontmatter: tolerates a BOM and CRLF line endings", () => {
-  const crlf = "" + GOOD.replace(/\n/g, "\r\n");
-  const s = splitFrontmatter(crlf);
-  assert.equal(s.ok, true);
-  assert.equal(s.body.includes("\r"), false);
-});
-
-test("splitFrontmatter: empty frontmatter block parses to an empty map", () => {
-  const s = splitFrontmatter("---\n---\nbody\n");
-  assert.equal(s.ok, true);
-  assert.equal(s.frontmatterText, "");
-  assert.equal(s.body, "body\n");
-});
-
-// ---------------------------------------------------------------------------
-// parseFrontmatter
-// ---------------------------------------------------------------------------
-
-test("parseFrontmatter: scalars, flow sequences and block sequences", () => {
-  const r = parseFrontmatter([
-    "name: alpha",
-    'description: "Handles: alpha work"',
-    "model: sonnet   # trailing comment",
-    'tools: [Read, "Write", \'Edit\']',
-    "tokens:",
-    "  - agent.firstName",
-    "  - agent.company",
-  ].join("\n"));
-  assert.equal(r.ok, true, r.errors.join("; "));
-  assert.equal(r.value.name, "alpha");
-  assert.equal(r.value.description, "Handles: alpha work");
-  assert.equal(r.value.model, "sonnet");
-  assert.deepEqual(r.value.tools, ["Read", "Write", "Edit"]);
-  assert.deepEqual(r.value.tokens, ["agent.firstName", "agent.company"]);
-});
-
-test("parseFrontmatter: a `#` inside a quoted scalar is content, not a comment", () => {
-  const r = parseFrontmatter('description: "ships #1 priority"');
-  assert.equal(r.value.description, "ships #1 priority");
-});
-
-test("parseFrontmatter: a comma inside a quoted flow item is not a separator", () => {
-  // The registry round-trips these bytes into a database — "unlikely" is not a
-  // licence to corrupt.
-  const r = parseFrontmatter('tools: ["Read, maybe", Write]');
-  assert.deepEqual(r.value.tools, ["Read, maybe", "Write"]);
-});
-
-test("parseFrontmatter: anything outside the closed grammar is an ERROR, never a silent mis-parse", () => {
-  const r = parseFrontmatter("name: alpha\nnested:\n  key: value\n");
-  assert.equal(r.ok, false);
-  assert.match(r.errors.join(" "), /nested maps are outside the frontmatter grammar/);
-});
-
-test("parseFrontmatter: an orphan list item is an error", () => {
-  const r = parseFrontmatter("name: alpha\n  - stray\n");
-  assert.equal(r.ok, false);
-  assert.match(r.errors.join(" "), /no owning key/);
-});
-
-test("parseFrontmatter: an unterminated flow sequence is an error", () => {
-  const r = parseFrontmatter("tools: [Read, Write\n");
-  assert.equal(r.ok, false);
-  assert.match(r.errors.join(" "), /unterminated flow sequence/);
-});
-
-// ---------------------------------------------------------------------------
-// model normalisation — where the shipped-vs-generated drift dies
-// ---------------------------------------------------------------------------
-
-test("normaliseModel: aliases and full ids both normalise, idempotently", () => {
-  assert.equal(normaliseModel("sonnet"), "claude-sonnet-4-6");
-  assert.equal(normaliseModel("claude-sonnet-4-6"), "claude-sonnet-4-6");
-  assert.equal(normaliseModel(normaliseModel("opus")), "claude-opus-4-8");
-  assert.equal(normaliseModel("HAIKU"), "claude-haiku-4-5");
-  assert.equal(normaliseModel("inherit"), "inherit");
-});
-
-test("normaliseModel: unknown → null (an error for the caller), absent → \"\"", () => {
-  assert.equal(normaliseModel("gpt-4o"), null);
-  assert.equal(normaliseModel(""), "");
-  assert.equal(normaliseModel(undefined), "");
-});
-
-test("MODEL_ALIASES: every alias target is itself a key (normalisation is a fixpoint)", () => {
-  for (const target of Object.values(MODEL_ALIASES)) {
-    assert.equal(MODEL_ALIASES[target], target, `${target} must map to itself`);
-  }
-});
-
-// ---------------------------------------------------------------------------
-// validate
-// ---------------------------------------------------------------------------
-
-function fm(over = {}) {
-  return { name: "alpha", description: "d", model: "sonnet", tools: ["Read"], ...over };
-}
-
-test("validateAgentMd: the happy path normalises the model and derives tokens", () => {
-  const v = validateAgentMd({ frontmatter: fm(), body: "x {{agent.firstName}}", slug: "alpha" });
-  assert.equal(v.ok, true, v.errors.join("; "));
-  assert.equal(v.normalised.frontmatter.model, "claude-sonnet-4-6");
-  assert.deepEqual(v.normalised.frontmatter.tokens, ["agent.firstName"]);
-});
-
-test("validateAgentMd: name must equal the directory name (identity IS the dirname)", () => {
-  const v = validateAgentMd({ frontmatter: fm({ name: "beta" }), body: "x", slug: "alpha" });
-  assert.equal(v.ok, false);
-  assert.match(v.errors.join(" "), /must equal the directory name/);
-});
-
-test("validateAgentMd: description, model, tools and body are all required", () => {
-  const cases = [
-    [fm({ description: "" }), "x", /description is required/],
-    [fm({ model: "gpt-4o" }), "x", /not a known model/],
-    [fm({ model: "" }), "x", /model is required/],
-    [fm({ tools: undefined }), "x", /tools is required/],
-    [fm({ tools: [] }), "x", /tools must be non-empty/],
-    [fm(), "   ", /body is empty/],
-  ];
-  for (const [f, body, re] of cases) {
-    const v = validateAgentMd({ frontmatter: f, body, slug: "alpha" });
-    assert.equal(v.ok, false, `expected failure for ${re}`);
-    assert.match(v.errors.join(" "), re);
-  }
-});
-
-test("validateAgentMd: an ABSENT tokens key is derived, not an error", () => {
-  // Every file that shipped before the registry existed has no `tokens:` key.
-  // Demanding one would fail-closed the whole fleet on the first doctor run.
-  const v = validateAgentMd({ frontmatter: fm(), body: "{{agent.company}}", slug: "alpha" });
-  assert.equal(v.ok, true);
-  assert.deepEqual(v.normalised.frontmatter.tokens, ["agent.company"]);
-});
-
-test("validateAgentMd: a DECLARED tokens list must cover every token the body uses", () => {
-  const v = validateAgentMd({ frontmatter: fm({ tokens: [] }), body: "{{agent.company}}", slug: "alpha" });
-  assert.equal(v.ok, false);
-  assert.match(v.errors.join(" "), /undeclared token/);
-});
-
-test("validateAgentMd: declared-but-unused and renderer-unknown tokens WARN, never fail", () => {
-  const v = validateAgentMd({
-    frontmatter: fm({ tokens: ["agent.firstName", "agent.nope"] }),
-    body: "{{agent.firstName}}",
-    slug: "alpha",
-  });
-  assert.equal(v.ok, true, v.errors.join("; "));
-  assert.match(v.warnings.join(" "), /declared but unused/);
-  assert.match(v.warnings.join(" "), /unknown to this agent's renderer/);
-});
-
-test("unsupportedTokens: honours an injected KNOWN_TOKENS set", () => {
-  assert.deepEqual(unsupportedTokens(["a", "b"], new Set(["a"])), ["b"]);
-  assert.deepEqual(unsupportedTokens(null, new Set()), []);
-});
-
-test("bodyTokens: deduped and sorted", () => {
-  assert.deepEqual(bodyTokens("{{agent.z}} {{agent.a}} {{agent.z}}"), ["agent.a", "agent.z"]);
-});
-
-// ---------------------------------------------------------------------------
-// emit / round-trip — what makes local-edit detection trustworthy
-// ---------------------------------------------------------------------------
-
-test("stringifyFrontmatter: canonical key order (authored, then provenance, then rest)", () => {
-  const text = stringifyFrontmatter({ contentHash: "h", extra: 1, tools: ["Read"], name: "alpha" });
-  assert.deepEqual(text.trim().split("\n"), ['name: alpha', 'tools: ["Read"]', "contentHash: h", "extra: 1"]);
-});
-
-test("round trip: parse(stringify(x)) === x, and a second pass is byte-identical", () => {
-  const f = { name: "alpha", description: "d", model: "claude-sonnet-4-6", tools: ["Read", "Write"], tokens: [] };
-  const once = stringifyAgentMd(f, "# alpha\n\nbody\n");
-  const parsed = parseAgentMd(once);
-  assert.equal(parsed.ok, true, parsed.errors.join("; "));
-  assert.deepEqual(parsed.frontmatter, f);
-  assert.equal(stringifyAgentMd(parsed.frontmatter, parsed.body), once);
-});
-
-test("round trip: a file in the SHIPPED shape (blank line after the fence) survives byte-exact", () => {
-  // Regression. The round-trip test above starts its body at "# alpha", which is
-  // the one shape splitFrontmatter never returns — it slices from just after the
-  // closing fence's newline, so a real file's body ALWAYS starts with "\n".
-  // stringifyAgentMd used to strip exactly that newline, so every shipped
-  // agent.md lost its blank line on re-emit. stampProvenance takes this path on
-  // every materialisation and hashFile compares whole-file bytes, so the drift
-  // showed up as "locally edited" on files nobody had touched.
-  const src = [
-    "---", "name: alpha", "description: d", "model: claude-sonnet-4-6",
-    'tools: ["Read"]', "---", "", "You are the alpha sub-agent.", "",
-  ].join("\n");
-  const parsed = parseAgentMd(src);
-  assert.equal(parsed.ok, true, parsed.errors.join("; "));
-  assert.equal(parsed.body.startsWith("\n"), true, "body keeps its leading \\n");
-  assert.equal(stringifyAgentMd(parsed.frontmatter, parsed.body), src);
-  assert.equal(
-    hashFile(stringifyAgentMd(parsed.frontmatter, parsed.body)), hashFile(src),
-    "re-emit must not move the file hash",
-  );
-});
-
-test("stampProvenance: is IDEMPOTENT — re-stamping produces identical bytes", () => {
-  // Non-idempotent stamping would change the file hash on every materialisation
-  // and make local-edit detection permanently wrong.
-  const one = stampProvenance({
-    frontmatter: fm(), body: "b\n", layer: "workspace", source: "cohort://o/alpha", version: 7,
-  });
-  const re = parseAgentMd(one);
-  const two = stampProvenance({
-    frontmatter: re.frontmatter, body: re.body, layer: "workspace", source: "cohort://o/alpha", version: 7,
-  });
-  assert.equal(two, one);
-  assert.equal(hashFile(two), hashFile(one));
-});
-
-test("stampProvenance: never renders tokens — {{agent.*}} survives to disk", () => {
-  const text = stampProvenance({ frontmatter: fm(), body: "hi {{agent.firstName}}\n", layer: "sdk" });
-  assert.match(text, /\{\{agent\.firstName\}\}/);
-});
-
-test("stripProvenance: removes exactly the registry-owned keys", () => {
-  const out = stripProvenance({ name: "alpha", layer: "sdk", source: "s", version: "1", contentHash: "h" });
-  assert.deepEqual(Object.keys(out), ["name"]);
-  for (const k of PROVENANCE_KEYS) assert.equal(k in out, false);
-  assert.ok(AUTHORED_KEYS.includes("name"));
-});
-
-test("hashBody and hashFile have different preimages (body vs whole file)", () => {
-  const parsed = parseAgentMd(GOOD);
-  assert.notEqual(hashBody(parsed.body), hashFile(GOOD));
-  assert.equal(hashBody(parsed.body), hashBody(parsed.body));
-  assert.equal(hashBody(null), hashBody(""));
-});
-
-// ---------------------------------------------------------------------------
-// the real corpus — the validator must not reject what already shipped
-// ---------------------------------------------------------------------------
-
-test("every shipped agents/*/agent.md validates (the fleet must not fail-closed)", () => {
-  const { slugs } = listAgentDirs(MAESTRO_ROOT);
-  assert.ok(slugs.length >= 1, "expected the SDK to ship at least one agent");
-  const bad = [];
-  for (const slug of slugs) {
-    const text = readFileSync(join(MAESTRO_ROOT, "agents", slug, "agent.md"), "utf8");
-    const c = checkAgentFile(text, slug);
-    if (!c.ok) bad.push(`${slug}: ${c.errors.join(", ")}`);
-  }
-  assert.deepEqual(bad, []);
-});
-
-test("checkAgentFile: reports the parse error rather than throwing", () => {
-  const c = checkAgentFile("no frontmatter here", "alpha");
-  assert.equal(c.ok, false);
-  assert.match(c.errors.join(" "), /missing opening/);
-});

package/lib/telemetry/alerts.test.mjs

@@ -1,109 +0,0 @@
-/**
- * alerts.test.mjs — deriveAlerts over the SHARED STATUS SNAPSHOT.
- *
- * Asserts: relogin → critical; temp/mem/disk fire at warn/crit; sub-agents over
- * cap → info; threshold overrides merge; deterministic order; never throws.
- *
- * Run: node --test lib/telemetry/alerts.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { deriveAlerts, hasCritical, mergeThresholds, DEFAULT_THRESHOLDS } from "./alerts.mjs";
-
-function baseStatus(over = {}) {
-  return {
-    state: "idle",
-    activity: "idle",
-    subAgentsRunning: 0,
-    session: null,
-    machine: { loadavg: [0, 0, 0], memUsedPct: 10, ...(over.machine || {}) },
-    claudeAuth: "ok",
-    alerts: [],
-    ts: "2026-06-12T12:00:00Z",
-    ...over,
-    machine: { loadavg: [0, 0, 0], memUsedPct: 10, ...(over.machine || {}) },
-  };
-}
-
-test("relogin_required → one critical auth alert", () => {
-  const alerts = deriveAlerts(baseStatus({ claudeAuth: "relogin_required" }));
-  assert.equal(alerts.length, 1);
-  assert.equal(alerts[0].id, "claude_relogin_required");
-  assert.equal(alerts[0].severity, "critical");
-  assert.equal(alerts[0].kind, "auth");
-  assert.ok(hasCritical(alerts));
-});
-
-test("tempC fires warning then critical at the thresholds", () => {
-  assert.equal(deriveAlerts(baseStatus({ machine: { memUsedPct: 10, tempC: 80 } })).length, 0, "below warn → nothing");
-  const warn = deriveAlerts(baseStatus({ machine: { memUsedPct: 10, tempC: 88 } }));
-  assert.equal(warn[0].id, "machine_temp_high");
-  assert.equal(warn[0].severity, "warning");
-  const crit = deriveAlerts(baseStatus({ machine: { memUsedPct: 10, tempC: 99 } }));
-  assert.equal(crit[0].severity, "critical");
-});
-
-test("memUsedPct fires at warn/crit", () => {
-  assert.equal(deriveAlerts(baseStatus({ machine: { memUsedPct: 50 } })).length, 0);
-  assert.equal(deriveAlerts(baseStatus({ machine: { memUsedPct: 90 } }))[0].id, "machine_mem_high");
-  assert.equal(deriveAlerts(baseStatus({ machine: { memUsedPct: 96 } }))[0].severity, "critical");
-});
-
-test("diskUsedPct fires at warn/crit", () => {
-  assert.equal(deriveAlerts(baseStatus({ machine: { memUsedPct: 10, diskUsedPct: 50 } })).length, 0);
-  const w = deriveAlerts(baseStatus({ machine: { memUsedPct: 10, diskUsedPct: 90 } }));
-  assert.equal(w[0].id, "machine_disk_high");
-  assert.equal(w[0].severity, "warning");
-});
-
-test("subAgentsRunning over the info cap → info alert", () => {
-  assert.equal(deriveAlerts(baseStatus({ subAgentsRunning: 5 })).length, 0);
-  const a = deriveAlerts(baseStatus({ subAgentsRunning: 15 }));
-  assert.equal(a[0].id, "sub_agents_over_cap");
-  assert.equal(a[0].severity, "info");
-});
-
-test("multiple alerts sort critical → warning → info, then by id", () => {
-  const alerts = deriveAlerts(baseStatus({
-    claudeAuth: "relogin_required",
-    subAgentsRunning: 99,
-    machine: { memUsedPct: 90, diskUsedPct: 96 },
-  }));
-  const ids = alerts.map((a) => a.id);
-  // critical: claude_relogin_required, machine_disk_high (96>=95);
-  // warning: machine_mem_high; info: sub_agents_over_cap
-  assert.equal(alerts[0].severity, "critical");
-  assert.equal(alerts[alerts.length - 1].severity, "info");
-  assert.ok(ids.includes("claude_relogin_required"));
-  assert.ok(ids.includes("machine_disk_high"));
-  assert.ok(ids.includes("machine_mem_high"));
-  assert.ok(ids.includes("sub_agents_over_cap"));
-  // critical block is alphabetised by id
-  const critIds = alerts.filter((a) => a.severity === "critical").map((a) => a.id);
-  assert.deepEqual(critIds, [...critIds].sort());
-});
-
-test("threshold overrides merge over the defaults", () => {
-  const alerts = deriveAlerts(baseStatus({ machine: { memUsedPct: 70 } }), { mem: { warnPct: 65 } });
-  assert.equal(alerts[0].id, "machine_mem_high");
-  assert.equal(alerts[0].severity, "warning");
-  // defaults are not mutated
-  assert.equal(DEFAULT_THRESHOLDS.mem.warnPct, 85);
-});
-
-test("deriveAlerts never throws on garbage", () => {
-  assert.deepEqual(deriveAlerts(null), []);
-  assert.deepEqual(deriveAlerts(undefined), []);
-  assert.deepEqual(deriveAlerts(42), []);
-  assert.deepEqual(deriveAlerts({ machine: "not-an-object" }), []);
-});
-
-test("mergeThresholds deep-merges and clones", () => {
-  const m = mergeThresholds(DEFAULT_THRESHOLDS, { temp: { warnC: 70 } });
-  assert.equal(m.temp.warnC, 70);
-  assert.equal(m.temp.critC, DEFAULT_THRESHOLDS.temp.critC); // untouched sibling preserved
-  assert.equal(DEFAULT_THRESHOLDS.temp.warnC, 85);
-});