@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/subagents/resolve.test.mjs

@@ -1,422 +0,0 @@
-/**
- * resolve.test.mjs — three-layer, total, per-slug resolution (§3):
- * LOCAL > WORKSPACE > SDK, layers never merge, and a local edit is never
- * clobbered without --force.
- * Run: node --test lib/subagents/resolve.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  LAYERS,
-  agentFilePath,
-  buildWorkspaceLayer,
-  classifyLocal,
-  materialise,
-  materialiseAll,
-  readLocalAgents,
-  resolveSubagents,
-} from "./resolve.mjs";
-import { buildManifest, writeManifest } from "./manifest.mjs";
-import { mergeLock, readLock, writeCache } from "./lock.mjs";
-import { hashBody, hashFile, parseAgentMd, stringifyAgentMd } from "./schema.mjs";
-
-function md(slug, body = "# body\n\nprose\n", over = {}) {
-  return stringifyAgentMd({ name: slug, description: `${slug} does things`, model: "sonnet", tools: ["Read"], ...over }, body);
-}
-function put(root, slug, text) {
-  mkdirSync(join(root, "agents", slug), { recursive: true });
-  writeFileSync(join(root, "agents", slug, "agent.md"), text);
-  return text;
-}
-
-/** An SDK checkout shipping `slugs`, with its manifest generated. */
-function sdkWith(slugs, bodies = {}) {
-  const root = mkdtempSync(join(tmpdir(), "subagent-sdk-"));
-  for (const s of slugs) put(root, s, md(s, bodies[s] || `# ${s}\n\nsdk body\n`));
-  writeManifest(root, buildManifest({ maestroRoot: root, sdkVersion: "9.9.9" }).manifest);
-  return root;
-}
-const agentRepo = () => mkdtempSync(join(tmpdir(), "subagent-agent-"));
-
-// ---------------------------------------------------------------------------
-// classification — the rule everything else rests on
-// ---------------------------------------------------------------------------
-
-test("LAYERS is the precedence order", () => {
-  assert.deepEqual(LAYERS, ["local", "workspace", "sdk"]);
-});
-
-test("classifyLocal: the four cases of §3 rule 1", () => {
-  const shas = new Set(["sdk-sha"]);
-  assert.deepEqual(classifyLocal({ fileHash: "h", lockEntry: { fileHash: "h" }, shas }).localEdits, false);
-  assert.deepEqual(classifyLocal({ fileHash: "changed", lockEntry: { fileHash: "h" }, shas }).localEdits, true);
-  assert.deepEqual(classifyLocal({ fileHash: "sdk-sha", lockEntry: null, shas }).localEdits, false);
-  assert.deepEqual(classifyLocal({ fileHash: "mystery", lockEntry: null, shas }).localEdits, true);
-});
-
-test("classifyLocal: no lock and no manifest ⇒ local edit ⇒ nothing is overwritten", () => {
-  // The safe default in every degraded case.
-  const c = classifyLocal({ fileHash: "x", lockEntry: null, shas: new Set() });
-  assert.equal(c.localEdits, true);
-  assert.match(c.reason, /no lock entry and no SDK sha match/);
-});
-
-test("readLocalAgents: reads every on-disk agent.md with its file hash", () => {
-  const root = agentRepo();
-  const text = put(root, "alpha", md("alpha"));
-  mkdirSync(join(root, "agents", "hollow"), { recursive: true });
-  const { files, empty } = readLocalAgents(root);
-  assert.equal(files.get("alpha").fileHash, hashFile(text));
-  assert.deepEqual(empty, ["hollow"]);
-});
-
-// ---------------------------------------------------------------------------
-// precedence
-// ---------------------------------------------------------------------------
-
-test("SDK wins when nothing else offers the slug", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  const r = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  assert.deepEqual(r.entries.map((e) => [e.slug, e.layer]), [["alpha", "sdk"]]);
-  assert.equal(r.entries[0].source, "sdk://9.9.9/alpha");
-  assert.equal(r.entries[0].onDisk, false);
-});
-
-test("WORKSPACE beats SDK for the same slug (total precedence, no merging)", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  const r = resolveSubagents({
-    agentRoot: agent, maestroRoot: sdk, orgSlug: "acme",
-    pins: [{ slug: "alpha", definitionId: "def_1", version: 7, body: "# alpha\n\nworkspace body\n", frontmatter: { name: "alpha" } }],
-  });
-  const e = r.bySlug.get("alpha");
-  assert.equal(e.layer, "workspace");
-  assert.equal(e.version, 7);
-  assert.equal(e.definitionId, "def_1");
-  assert.equal(e.source, "cohort://acme/alpha");
-  assert.match(e.body, /workspace body/);
-});
-
-test("LOCAL beats everything and is reported as a local edit", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  put(agent, "alpha", md("alpha", "# alpha\n\nHAND EDITED\n"));
-  const r = resolveSubagents({
-    agentRoot: agent, maestroRoot: sdk,
-    pins: [{ slug: "alpha", version: 7, body: "# alpha\n\nworkspace body\n" }],
-  });
-  const e = r.bySlug.get("alpha");
-  assert.equal(e.layer, "local");
-  assert.equal(e.localEdits, true);
-  assert.match(e.body, /HAND EDITED/);
-  assert.deepEqual(r.localEdits, ["alpha"]);
-});
-
-test("a file matching the SDK manifest sha is MANAGED — the higher layer still wins", () => {
-  // This is the graft that lets `create`'s copy list and UPGRADE_PATHS stay as
-  // they are: a pristine copy is updatable, a human's edit is sacred.
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  put(agent, "alpha", readFileSync(join(sdk, "agents", "alpha", "agent.md"), "utf8"));
-  const r = resolveSubagents({
-    agentRoot: agent, maestroRoot: sdk,
-    pins: [{ slug: "alpha", version: 3, body: "# alpha\n\nworkspace body\n" }],
-  });
-  assert.equal(r.bySlug.get("alpha").layer, "workspace");
-  assert.deepEqual(r.localEdits, []);
-});
-
-test("the slug set is (SDK manifest) ∪ (pins) ∪ (on-disk), sorted", () => {
-  const sdk = sdkWith(["from-sdk"]);
-  const agent = agentRepo();
-  put(agent, "on-disk", md("on-disk"));
-  const r = resolveSubagents({
-    agentRoot: agent, maestroRoot: sdk,
-    pins: [{ slug: "pinned", version: 1, body: "b\n" }],
-  });
-  assert.deepEqual(r.entries.map((e) => e.slug), ["from-sdk", "on-disk", "pinned"]);
-});
-
-test("an orphaned managed file still resolves, flagged rather than mislabelled as SDK", () => {
-  const sdk = sdkWith([]);
-  const agent = agentRepo();
-  const text = put(agent, "gone", md("gone"));
-  mergeLock(agent, { agents: { gone: { layer: "workspace", fileHash: hashFile(text), version: 4, definitionId: "def_9" } } });
-  const r = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  const e = r.bySlug.get("gone");
-  assert.equal(e.layer, "local");
-  assert.equal(e.orphaned, true);
-  assert.equal(e.localEdits, false);
-  assert.equal(e.version, 4);
-});
-
-// ---------------------------------------------------------------------------
-// the workspace layer, offline
-// ---------------------------------------------------------------------------
-
-test("buildWorkspaceLayer: a body-less pin is filled from the offline cache", () => {
-  const agent = agentRepo();
-  writeCache(agent, "alpha", 4, stringifyAgentMd({ name: "alpha", description: "d", model: "sonnet", tools: ["Read"] }, "cached body\n"));
-  const m = buildWorkspaceLayer({ agentRoot: agent, pins: [{ slug: "alpha", version: 4, contentHash: "" }] });
-  assert.equal(m.get("alpha").fromCache, true);
-  assert.equal(m.get("alpha").body, "cached body\n");
-  assert.equal(m.get("alpha").contentHash, hashBody("cached body\n"));
-});
-
-test("buildWorkspaceLayer: a pin with no body and no cache has NO workspace layer", () => {
-  // Degraded-but-correct: resolution falls through to SDK rather than
-  // materialising an empty body.
-  const m = buildWorkspaceLayer({ agentRoot: agentRepo(), pins: [{ slug: "alpha", version: 1 }] });
-  assert.equal(m.size, 0);
-});
-
-test("resolveSubagents: a cache-sourced workspace layer sets degraded", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  writeCache(agent, "alpha", 2, stringifyAgentMd({ name: "alpha", description: "d", model: "sonnet", tools: ["Read"] }, "cached\n"));
-  const r = resolveSubagents({ agentRoot: agent, maestroRoot: sdk, pins: [{ slug: "alpha", version: 2 }] });
-  assert.equal(r.bySlug.get("alpha").layer, "workspace");
-  assert.deepEqual(r.degraded, ["workspace-from-cache"]);
-});
-
-test("resolveSubagents: cold cache + no pins + no manifest resolves nothing and throws nothing", () => {
-  const r = resolveSubagents({ agentRoot: agentRepo(), maestroRoot: mkdtempSync(join(tmpdir(), "empty-sdk-")) });
-  assert.deepEqual(r.entries, []);
-  assert.deepEqual(r.localEdits, []);
-});
-
-// ---------------------------------------------------------------------------
-// materialise
-// ---------------------------------------------------------------------------
-
-test("materialise: writes the winner with provenance stamped in the frontmatter", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  const r = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  const out = materialise({ agentRoot: agent, entry: r.bySlug.get("alpha") });
-  assert.equal(out.written, true);
-  const text = readFileSync(agentFilePath(agent, "alpha"), "utf8");
-  const fm = parseAgentMd(text).frontmatter;
-  assert.equal(fm.layer, "sdk");
-  assert.equal(fm.source, "sdk://9.9.9/alpha");
-  assert.equal(fm.contentHash, hashBody(r.bySlug.get("alpha").body));
-  assert.equal(fm.model, "claude-sonnet-4-6", "the model alias is normalised on the way to disk");
-  assert.equal(out.fileHash, hashFile(text));
-});
-
-test("materialise: is idempotent — a second pass writes nothing", () => {
-  // Not just an optimisation: a no-op write would churn mtime on every doctor
-  // run and make "when did this last change" useless.
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  const entry = resolveSubagents({ agentRoot: agent, maestroRoot: sdk }).bySlug.get("alpha");
-  assert.equal(materialise({ agentRoot: agent, entry }).written, true);
-  const second = materialise({ agentRoot: agent, entry });
-  assert.equal(second.written, false);
-  assert.equal(second.reason, "already up to date");
-});
-
-test("materialise: REFUSES to overwrite a local edit without --force", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  const mine = put(agent, "alpha", md("alpha", "# alpha\n\nMINE\n"));
-  const r = resolveSubagents({ agentRoot: agent, maestroRoot: sdk, pins: [{ slug: "alpha", version: 2, body: "theirs\n" }] });
-  const refused = materialise({ agentRoot: agent, entry: r.bySlug.get("alpha") });
-  assert.equal(refused.written, false);
-  assert.match(refused.reason, /--force/);
-  assert.equal(readFileSync(agentFilePath(agent, "alpha"), "utf8"), mine);
-});
-
-test("--force demotes the local layer so the upstream body actually wins", () => {
-  // Both halves are required: resolution must stop letting the file absorb the
-  // slug, AND materialise must permit the write. Either alone is a no-op — with
-  // force only on the write, --force would rewrite the file from itself.
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  put(agent, "alpha", md("alpha", "# alpha\n\nMINE\n"));
-
-  const unforced = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  assert.equal(unforced.bySlug.get("alpha").layer, "local");
-
-  const forced = resolveSubagents({ agentRoot: agent, maestroRoot: sdk, force: true });
-  assert.equal(forced.bySlug.get("alpha").layer, "sdk", "the local layer is demoted");
-  assert.deepEqual(forced.localEdits, ["alpha"], "…but the edit is still REPORTED");
-
-  assert.equal(materialise({ agentRoot: agent, entry: forced.bySlug.get("alpha"), force: true }).written, true);
-  assert.match(readFileSync(agentFilePath(agent, "alpha"), "utf8"), /sdk body/);
-});
-
-test("--force with NO upstream layer keeps the file and still flags the edit", () => {
-  // There is nothing to override it WITH; blanking it would be data loss.
-  const agent = agentRepo();
-  put(agent, "solo", md("solo", "# solo\n\nMINE\n"));
-  const r = resolveSubagents({ agentRoot: agent, maestroRoot: sdkWith([]), force: true });
-  const e = r.bySlug.get("solo");
-  assert.equal(e.layer, "local");
-  assert.equal(e.localEdits, true);
-  assert.equal(e.orphaned, false, "an edited file is not an orphan");
-  assert.match(e.body, /MINE/);
-});
-
-test("materialise: refuses a body declaring tokens THIS agent cannot render", () => {
-  // hq deliberately does not vendor KNOWN_TOKENS, so the fetching agent is the
-  // only place this can be caught — refusing here makes the unresolved-token CI
-  // guard structurally unable to fail after a fetch.
-  const agent = agentRepo();
-  const out = materialise({
-    agentRoot: agent,
-    entry: {
-      slug: "alpha", layer: "workspace", source: "cohort://o/alpha", version: 1,
-      frontmatter: { name: "alpha", description: "d", model: "sonnet", tools: ["Read"], tokens: ["agent.firstName", "agent.invented"] },
-      body: "hi {{agent.firstName}} {{agent.invented}}\n",
-      contentHash: "h",
-    },
-  });
-  assert.equal(out.written, false);
-  assert.match(out.reason, /cannot render: agent\.invented/);
-  assert.equal(existsSync(agentFilePath(agent, "alpha")), false);
-});
-
-test("materialise: refuses a body that fails the schema", () => {
-  const agent = agentRepo();
-  const out = materialise({
-    agentRoot: agent,
-    entry: { slug: "alpha", layer: "sdk", frontmatter: { name: "WRONG", description: "d", model: "sonnet", tools: ["Read"] }, body: "b\n" },
-  });
-  assert.equal(out.written, false);
-  assert.equal(out.reason, "failed schema validation");
-  assert.match(out.errors.join(" "), /must equal the directory name/);
-});
-
-test("materialiseAll: writes every winner and returns the lock patch", () => {
-  const sdk = sdkWith(["alpha", "beta"]);
-  const agent = agentRepo();
-  const resolved = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  const out = materialiseAll({ agentRoot: agent, resolved });
-  assert.equal(out.written, 2);
-  assert.deepEqual(Object.keys(out.lockAgents).sort(), ["alpha", "beta"]);
-  assert.equal(out.lockAgents.alpha.layer, "sdk");
-  assert.equal(out.lockAgents.alpha.fileHash, hashFile(readFileSync(agentFilePath(agent, "alpha"), "utf8")));
-  assert.ok(out.lockAgents.alpha.materialisedAt);
-});
-
-test("materialiseAll: `only` restricts the write set", () => {
-  const sdk = sdkWith(["alpha", "beta"]);
-  const agent = agentRepo();
-  const resolved = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  const out = materialiseAll({ agentRoot: agent, resolved, only: ["alpha"] });
-  assert.equal(out.written, 1);
-  assert.equal(existsSync(agentFilePath(agent, "beta")), false);
-});
-
-test("materialiseAll: a refusal is reported and still recorded in the lock patch", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  put(agent, "alpha", md("alpha", "# alpha\n\nMINE\n"));
-  const resolved = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  const out = materialiseAll({ agentRoot: agent, resolved });
-  assert.equal(out.written, 0);
-  assert.equal(out.lockAgents.alpha.localEdits, true, "so the next run does not re-offer the same overwrite");
-  assert.equal(out.lockAgents.alpha.materialisedAt, "", "we never claim to have written what we did not");
-  assert.equal(
-    out.lockAgents.alpha.fileHash,
-    "",
-    "and we never record an unmanaged file's bytes as ours — that is a licence to overwrite",
-  );
-});
-
-test("a refused local edit SURVIVES repeated runs (no --force) — data-loss regression", () => {
-  // The refusal used to protect the file for exactly ONE run: it recorded the
-  // human's own hash as `fileHash`, i.e. as bytes we had materialised, so the
-  // next resolve classified the file as managed and overwrote it silently.
-  // Reproduced end to end before the fix: run 1 refused, run 2 destroyed the
-  // edit with no --force and no warning.
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  const MINE = md("alpha", "# alpha\n\nMY PRECIOUS LOCAL EDIT\n");
-  put(agent, "alpha", MINE);
-
-  let lock;
-  for (let run = 1; run <= 3; run++) {
-    const resolved = resolveSubagents({ agentRoot: agent, maestroRoot: sdk, lock });
-    const out = materialiseAll({ agentRoot: agent, resolved });
-    lock = { agents: out.lockAgents };
-    assert.equal(out.written, 0, `run ${run} must not write over a local edit`);
-    assert.equal(out.lockAgents.alpha.localEdits, true, `run ${run} must keep the edit flagged`);
-    assert.equal(
-      readFileSync(agentFilePath(agent, "alpha"), "utf8"),
-      MINE,
-      `run ${run} must leave the human's bytes untouched`,
-    );
-  }
-});
-
-test("--force resolves the edit, and the file is managed from then on", () => {
-  // The other half: once we DO overwrite, the flag must clear, or the file
-  // would be treated as dirty forever and never updated again.
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  put(agent, "alpha", md("alpha", "# alpha\n\nMINE\n"));
-
-  const first = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  const forced = materialiseAll({ agentRoot: agent, resolved: first, force: true });
-  assert.equal(forced.written, 1);
-  assert.equal(forced.lockAgents.alpha.localEdits, false, "the edit is resolved");
-  assert.ok(forced.lockAgents.alpha.fileHash, "and now we DID write these bytes");
-
-  const second = resolveSubagents({
-    agentRoot: agent,
-    maestroRoot: sdk,
-    lock: { agents: forced.lockAgents },
-  });
-  const entry = second.entries.find((e) => e.slug === "alpha");
-  assert.equal(entry.localEdits, false, "a managed file stays managed");
-});
-
-// ---------------------------------------------------------------------------
-// the full loop — this is what `pull` does
-// ---------------------------------------------------------------------------
-
-test("resolve → materialise → lock → resolve is STABLE (no phantom local edits)", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-
-  const first = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  const out = materialiseAll({ agentRoot: agent, resolved: first });
-  mergeLock(agent, { agents: out.lockAgents });
-
-  const second = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  assert.equal(second.bySlug.get("alpha").layer, "sdk", "the file we just wrote must not read as a local edit");
-  assert.deepEqual(second.localEdits, []);
-  assert.equal(materialiseAll({ agentRoot: agent, resolved: second }).written, 0);
-
-  // …and a human edit after that IS detected.
-  writeFileSync(agentFilePath(agent, "alpha"), readFileSync(agentFilePath(agent, "alpha"), "utf8") + "\nhand written\n");
-  const third = resolveSubagents({ agentRoot: agent, maestroRoot: sdk, lock: readLock(agent) });
-  assert.equal(third.bySlug.get("alpha").layer, "local");
-  assert.deepEqual(third.localEdits, ["alpha"]);
-});
-
-test("an SDK upgrade re-materialises a MANAGED file but not an edited one", () => {
-  const sdk = sdkWith(["alpha"]);
-  const agent = agentRepo();
-  const first = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  mergeLock(agent, { agents: materialiseAll({ agentRoot: agent, resolved: first }).lockAgents });
-
-  // Ship a new SDK body + regenerate the manifest (history carries the old sha).
-  const prev = buildManifest({ maestroRoot: sdk }).manifest;
-  put(sdk, "alpha", md("alpha", "# alpha\n\nSDK v2 body\n"));
-  writeManifest(sdk, buildManifest({ maestroRoot: sdk, sdkVersion: "9.9.10", previous: prev }).manifest);
-
-  const upgraded = resolveSubagents({ agentRoot: agent, maestroRoot: sdk });
-  assert.equal(upgraded.bySlug.get("alpha").layer, "sdk");
-  assert.equal(materialiseAll({ agentRoot: agent, resolved: upgraded }).written, 1);
-  assert.match(readFileSync(agentFilePath(agent, "alpha"), "utf8"), /SDK v2 body/);
-});