@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/plan/explain.test.mjs

@@ -1,188 +0,0 @@
-/**
- * explain.test.mjs — the OFFLINE provenance walk (SPEC §8).
- * Run: node --test lib/plan/explain.test.mjs
- *
- * The claim this module has to defend: every scheduled job an agent runs can be
- * traced back to an outcome a human adopted, WITHOUT calling hq. These tests
- * inject the whole world (plan, mandate cache, agent.json) so the walk is proven
- * to touch no network and to REPORT an incomplete chain rather than fake one.
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { explain, findObligation, findObjective, findCharterSection, renderExplanation } from "./explain.mjs";
-
-const OBLIGATION = {
-  key: "schedule.measure.pipeline-coverage",
-  kind: "SCHEDULE",
-  cadence_id: "measure-pipeline-coverage",
-  status: "active",
-  source: { origin: "mandate", ref: "obj_7Kx", charter_section: "cs_12" },
-  objective_id: "obj_7Kx",
-  schedule: { calendar: { weekday: 2, hour: 14, minute: 30 } },
-  uses: ["crm_list_deals"],
-  allowed_tools: ["Glob", "Grep", "LS", "Read", "crm_list_deals"],
-  budget_cents_per_period: 500,
-};
-
-const STANDARD_OBLIGATION = {
-  key: "schedule.inbox-processor",
-  kind: "SCHEDULE",
-  cadence_id: "inbox-processor",
-  status: "active",
-  source: { origin: "standard", ref: "inbox-processor" },
-  schedule: { interval: 300 },
-  uses: ["email_inbox"],
-  allowed_tools: ["Read", "email_inbox"],
-};
-
-const PLAN = { schemaVersion: 1, obligations: [OBLIGATION, STANDARD_OBLIGATION] };
-
-function mandate(over = {}) {
-  return {
-    version: 3,
-    body: {
-      memberId: "mem_SELF",
-      objectives: [{
-        id: "obj_7Kx",
-        key: "pipeline-coverage",
-        text: "Keep qualified pipeline at 3x the quarterly target",
-        metric: "pipeline_coverage_x",
-        target: 3,
-        direction: "up",
-        cadence: "weekly",
-        state: "active",
-        memberId: "mem_SELF",
-        adoptedById: "mem_HUMAN",
-        adoptedAt: "2026-08-01T10:00:00.000Z",
-        charterSectionId: "cs_12",
-        sensor: { capability: "crm_list_deals", source: "method" },
-        ...over,
-      }],
-    },
-  };
-}
-
-const AGENT_CFG = {
-  charter: {
-    sections: [{ id: "cs_12", kind: "PILLAR", title: "Revenue durability", body: "Sustain a predictable commercial engine." }],
-  },
-};
-
-test("explain walks obligation → objective → adoption → charter clause", () => {
-  const res = explain({ agentRoot: "/agent", key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
-
-  assert.equal(res.found, true);
-  assert.equal(res.gap, null);
-  const steps = res.provenance.map((p) => p.step);
-  assert.deepEqual(steps, ["obligation", "objective", "adoption", "charter"]);
-
-  const [ob, obj, adopt, charter] = res.provenance;
-  assert.equal(ob.kind, "SCHEDULE");
-  assert.deepEqual(ob.allowedTools, ["Glob", "Grep", "LS", "Read", "crm_list_deals"]);
-  assert.equal(obj.metric, "pipeline_coverage_x");
-  assert.equal(obj.target, 3);
-  assert.equal(adopt.adoptedById, "mem_HUMAN");
-  assert.equal(adopt.selfAdopted, false);
-  assert.equal(charter.resolved, true);
-  assert.equal(charter.title, "Revenue durability");
-  assert.match(res.summary, /Keep qualified pipeline/);
-});
-
-test("explain resolves a launchd CADENCE ID, not just the obligation key", () => {
-  // A launchd job only knows `measure-pipeline-coverage`.
-  const res = explain({ key: "measure-pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
-  assert.equal(res.found, true);
-  assert.equal(res.key, "schedule.measure.pipeline-coverage");
-});
-
-test("a standard cadence is honestly reported as the floor, not as a gap", () => {
-  const res = explain({ key: "inbox-processor", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
-  assert.equal(res.found, true);
-  assert.equal(res.gap, null, "the baseline set is not drift");
-  assert.match(res.summary, /baseline every agent runs/);
-  assert.equal(res.provenance.length, 1);
-});
-
-test("a mandate-origin obligation with no objective_id is flagged as unjustified", () => {
-  const orphan = { ...OBLIGATION, key: "schedule.orphan", cadence_id: "orphan", objective_id: undefined, source: { origin: "mandate" } };
-  const res = explain({ key: "schedule.orphan", plan: { obligations: [orphan] }, mandate: mandate(), agentCfg: AGENT_CFG });
-  assert.equal(res.gap, "no-objective");
-  assert.match(res.summary, /unjustified/);
-});
-
-test("SELF-ADOPTION is surfaced as a governance violation (the anti-Goodhart law)", () => {
-  // adoptedById === the objective's own owner: a seat defining, measuring and
-  // being graded on the same number.
-  const res = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate({ adoptedById: "mem_SELF" }), agentCfg: AGENT_CFG });
-  assert.equal(res.gap, "self-adopted");
-  assert.match(res.summary, /GOVERNANCE VIOLATION/);
-  assert.equal(res.provenance.find((p) => p.step === "adoption").selfAdopted, true);
-});
-
-test("a proposed (un-adopted) objective reports the not-adopted gap", () => {
-  const res = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate({ state: "proposed", adoptedById: null, adoptedAt: null }), agentCfg: AGENT_CFG });
-  assert.equal(res.gap, "not-adopted");
-  assert.match(res.summary, /not yet adopted/);
-});
-
-test("an incomplete chain is REPORTED, never faked", () => {
-  // No mandate cache at all (an offline agent that never synced).
-  const noCache = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: null, agentCfg: AGENT_CFG });
-  assert.equal(noCache.found, true);
-  assert.equal(noCache.gap, "no-mandate-cache");
-  assert.equal(noCache.provenance.length, 1, "the walk stops where the evidence stops");
-
-  // No plan at all.
-  const noPlan = explain({ key: "whatever", plan: null });
-  assert.equal(noPlan.found, false);
-  assert.equal(noPlan.gap, "no-plan");
-
-  // Plan present, key unknown.
-  const noOb = explain({ key: "schedule.nonexistent", plan: PLAN, mandate: mandate() });
-  assert.equal(noOb.found, false);
-  assert.equal(noOb.gap, "no-obligation");
-});
-
-test("an unresolvable charter clause is marked unresolved rather than dropped", () => {
-  const res = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: { charter: { sections: [] } } });
-  const charter = res.provenance.find((p) => p.step === "charter");
-  assert.ok(charter, "the charter step is still emitted");
-  assert.equal(charter.resolved, false);
-  assert.equal(charter.sectionId, "cs_12");
-});
-
-test("lookup helpers match on either id or key", () => {
-  assert.equal(findObligation(PLAN, "measure-pipeline-coverage").key, "schedule.measure.pipeline-coverage");
-  assert.equal(findObligation(PLAN, "nope"), null);
-  const body = mandate().body;
-  assert.equal(findObjective(body, "obj_7Kx").key, "pipeline-coverage");
-  assert.equal(findObjective(body, "pipeline-coverage").id, "obj_7Kx");
-  assert.equal(findObjective(body, "nope"), null);
-  assert.equal(findCharterSection(AGENT_CFG, "cs_12").kind, "PILLAR");
-  assert.equal(findCharterSection(AGENT_CFG, "cs_99"), null);
-});
-
-test("renderExplanation prints every step it walked", () => {
-  const res = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
-  const text = renderExplanation(res);
-  assert.match(text, /obligation {2}schedule\.measure\.pipeline-coverage/);
-  assert.match(text, /objective {3}pipeline-coverage/);
-  assert.match(text, /adoption {4}by mem_HUMAN/);
-  assert.match(text, /charter {5}cs_12 — Revenue durability/);
-});
-
-test("explain touches no network and no clock (pure over injected inputs)", () => {
-  // Same inputs, twice, with fetch sabotaged: identical output.
-  const realFetch = globalThis.fetch;
-  globalThis.fetch = () => { throw new Error("explain must not call the network"); };
-  try {
-    const a = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
-    const b = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
-    assert.deepEqual(a, b);
-  } finally {
-    globalThis.fetch = realFetch;
-  }
-});

package/lib/prompts/parallelism.test.mjs

@@ -1,177 +0,0 @@
-/**
- * parallelism.test.mjs — the fleet-wide parallelism directive (WP-M7 mechanic 5).
- *
- * Three things are pinned here, and each has a distinct failure it prevents:
- *
- *   1. THE BYTES. The directive is quoted verbatim in the design spec and is the
- *      one place a fleet-wide behaviour change is auditable. A silent reword —
- *      dropping the file-scope sentence, say — would turn "maximum safe
- *      parallelism" into two agents editing one file. So the expected text is
- *      written out longhand below, NOT derived from the constant.
- *   2. IDEMPOTENCE. Two seams apply it (`session spawn` and the daemon's
- *      prompt-builder) and they compose. A doubled directive reads as emphasis
- *      to a model, which is exactly how the safety sentence loses to the
- *      permission sentence.
- *   3. BOTH WIRINGS. A constant nothing calls is worth nothing; the two seams
- *      are driven for real here.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { PARALLELISM_DIRECTIVE, withParallelism, countParallelism } from "./parallelism.mjs";
-
-/**
- * The directive, longhand. Deliberately NOT built from the import: a test that
- * compares a constant to itself proves nothing about the wording.
- */
-const EXPECTED = [
-  "You are allowed to run multiple sub-agents concurrently.",
-  "",
-  "When the plan contains independent tasks, dispatch them together in a single parallel batch rather than waiting for each task to finish before starting the next.",
-  "",
-  "Only run tasks sequentially when one task genuinely depends on the output of another.",
-  "",
-  "Before dispatching any batch, check the planned file scope for each task and ensure that no two agents are assigned to edit the same file. If tasks would overlap on a file, sequence those tasks or redefine their scope to eliminate the conflict.",
-  "",
-  "Default to maximum safe parallelism.",
-].join("\n");
-
-test("PARALLELISM_DIRECTIVE is the spec's text, byte for byte", () => {
-  assert.equal(PARALLELISM_DIRECTIVE, EXPECTED);
-  // The two sentences that carry the whole point, named individually so a
-  // partial reword fails with a readable diff rather than one giant blob.
-  assert.match(PARALLELISM_DIRECTIVE, /single parallel batch/);
-  assert.match(PARALLELISM_DIRECTIVE, /no two agents are assigned to edit the same file/);
-  assert.ok(!PARALLELISM_DIRECTIVE.endsWith("\n"), "no trailing newline — the joiner adds the separator");
-});
-
-test("withParallelism prepends once and is idempotent", () => {
-  const prompt = "Reply to the message below.";
-  const once = withParallelism(prompt);
-  assert.ok(once.startsWith(PARALLELISM_DIRECTIVE), "the directive leads");
-  assert.ok(once.endsWith(prompt), "the caller's prompt survives intact");
-  assert.equal(countParallelism(once), 1);
-
-  const twice = withParallelism(once);
-  assert.equal(twice, once, "a second application changes nothing");
-  assert.equal(countParallelism(twice), 1);
-
-  const thrice = withParallelism(withParallelism(withParallelism(prompt)));
-  assert.equal(countParallelism(thrice), 1);
-});
-
-test("withParallelism tolerates an empty or non-string prompt", () => {
-  assert.equal(withParallelism(""), PARALLELISM_DIRECTIVE);
-  assert.equal(withParallelism("   \n "), PARALLELISM_DIRECTIVE);
-  assert.equal(withParallelism(undefined), PARALLELISM_DIRECTIVE);
-  assert.equal(withParallelism(null), PARALLELISM_DIRECTIVE);
-  assert.equal(withParallelism(42), PARALLELISM_DIRECTIVE);
-});
-
-test("a prompt that already carries the directive mid-body is not re-led", () => {
-  const embedded = `Context first.\n\n${PARALLELISM_DIRECTIVE}\n\nThen the task.`;
-  assert.equal(withParallelism(embedded), embedded);
-  assert.equal(countParallelism(withParallelism(embedded)), 1);
-});
-
-test("countParallelism counts non-overlapping occurrences", () => {
-  assert.equal(countParallelism(""), 0);
-  assert.equal(countParallelism(null), 0);
-  assert.equal(countParallelism("nothing here"), 0);
-  assert.equal(countParallelism(`${PARALLELISM_DIRECTIVE}\n\n${PARALLELISM_DIRECTIVE}`), 2);
-});
-
-// ── the two wired seams ─────────────────────────────────────────────────────
-
-test("maestro session spawn leads every peer prompt with the directive, exactly once", async () => {
-  const { buildSpawnArgs } = await import("../cli/session.mjs");
-  const prompt = "Sweep the backlog and file what you find.";
-  const args = buildSpawnArgs({ first: "nova", slug: "sweep", prompt, env: {}, allowedTools: [] });
-
-  assert.equal(args[0], "--name");
-  assert.equal(args[1], "nova-sweep");
-  const sent = args[args.length - 1];
-  assert.ok(sent.startsWith(PARALLELISM_DIRECTIVE), "the peer's prompt is led by the directive");
-  assert.ok(sent.endsWith(prompt));
-  assert.equal(countParallelism(sent), 1);
-
-  // The composing case: a prompt that already carries it is not doubled.
-  const pre = withParallelism(prompt);
-  const again = buildSpawnArgs({ first: "nova", slug: "sweep", prompt: pre, env: {}, allowedTools: [] });
-  assert.equal(countParallelism(again[again.length - 1]), 1);
-  assert.equal(again[again.length - 1], pre);
-});
-
-test("the daemon's prompt-builder leads every sub-session prompt with the directive, exactly once", async (t) => {
-  const { mkdtempSync, mkdirSync, writeFileSync } = await import("node:fs");
-  const { join } = await import("node:path");
-  const { tmpdir } = await import("node:os");
-
-  const root = mkdtempSync(join(tmpdir(), "maestro-parallelism-prompt-"));
-  mkdirSync(join(root, "config"), { recursive: true });
-  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Nova" }));
-  const prevAgentDir = process.env.AGENT_DIR;
-  process.env.AGENT_DIR = root;
-  t.after(() => {
-    if (prevAgentDir === undefined) delete process.env.AGENT_DIR;
-    else process.env.AGENT_DIR = prevAgentDir;
-  });
-
-  const url = new URL("../../scripts/daemon/prompt-builder.mjs", import.meta.url);
-  const pb = await import(`${url.href}?parallelism=${Math.random()}`);
-  const prompt = await pb.buildPrompt(
-    { sender: "Ana", content: "Three unrelated things need doing.", channel: "slack" },
-    { action: "respond", priority: "normal", summary: "three things" },
-    { type: "inbox" },
-  );
-
-  assert.ok(prompt.startsWith(PARALLELISM_DIRECTIVE), "the directive leads the built prompt");
-  assert.equal(countParallelism(prompt), 1);
-  assert.match(prompt, /Three unrelated things need doing\./, "the item's own content is still there");
-});
-
-test("the persona's precedence sentence names itself, so leading the prompt with the directive cannot mis-scope it", async (t) => {
-  // The sentence used to read "The section above … anything below". That was
-  // true only while the persona was the first thing in the prompt; once the
-  // directive leads, "above" has two candidate referents and the directive
-  // itself falls outside the rule (it is above, not below). Nothing else pins
-  // this ordering, so it is pinned here, beside the change that broke it.
-  const { mkdtempSync, mkdirSync, writeFileSync } = await import("node:fs");
-  const { join } = await import("node:path");
-  const { tmpdir } = await import("node:os");
-
-  const root = mkdtempSync(join(tmpdir(), "maestro-parallelism-persona-"));
-  mkdirSync(join(root, "config"), { recursive: true });
-  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Nova", lastName: "Reyes", title: "Chief of Staff" }));
-  writeFileSync(join(root, "config", "company.json"), JSON.stringify({ name: "Northwind" }));
-  const prevAgentDir = process.env.AGENT_DIR;
-  process.env.AGENT_DIR = root;
-  t.after(() => {
-    if (prevAgentDir === undefined) delete process.env.AGENT_DIR;
-    else process.env.AGENT_DIR = prevAgentDir;
-  });
-
-  const url = new URL("../../scripts/daemon/prompt-builder.mjs", import.meta.url);
-  const pb = await import(`${url.href}?persona=${Math.random()}`);
-  const prompt = await pb.buildPrompt(
-    { sender: "Ana", content: "Three unrelated things need doing.", channel: "slack" },
-    { action: "respond", priority: "normal", summary: "three things" },
-    { type: "inbox" },
-  );
-
-  assert.ok(prompt.startsWith(PARALLELISM_DIRECTIVE), "the directive leads");
-  assert.ok(
-    !/The section above is your identity/.test(prompt),
-    "a positional referent is wrong the moment anything is prepended",
-  );
-  assert.match(
-    prompt,
-    /This section is your identity, resolved from your organisation's record of you\. Where anything else in this prompt conflicts with it, this section wins\./,
-    "the precedence rule names itself and covers the whole prompt",
-  );
-  assert.ok(
-    prompt.indexOf(PARALLELISM_DIRECTIVE) < prompt.indexOf("This section is your identity"),
-    "the directive leads and the persona follows — the ordering the sentence had to stop assuming",
-  );
-});