@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/hooks/bus.test.mjs

@@ -1,387 +0,0 @@
-/**
- * Tests for lib/hooks/bus.mjs — the typed lifecycle hook bus.
- *
- * Covers the contract the audit (gaps-product-quality P1-8) specifies:
- *   - ordered priority dispatch (higher priority first, FIFO within a band)
- *   - a beforeSend subscriber can cancel the chain with a reason
- *   - a throwing subscriber is isolated (others still run; chain completes)
- *   - async subscribers are awaited in order
- *   - an unknown event type is rejected at subscribe AND emit
- */
-
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  HookBus,
-  createHookBus,
-  getHookBus,
-  resetHookBus,
-  HOOK_EVENT_NAMES,
-  HOOK_EVENTS,
-  isHookEvent,
-  isCancellableEvent,
-} from "./bus.mjs";
-
-/** A bus with an in-memory logger so error reporting is observable + silent. */
-function busWithLog() {
-  const logged = [];
-  const bus = createHookBus({ logger: (e) => logged.push(e) });
-  return { bus, logged };
-}
-
-describe("HookBus — closed event set", () => {
-  it("exposes exactly the eight specified lifecycle events", () => {
-    assert.deepEqual(
-      [...HOOK_EVENT_NAMES].sort(),
-      [
-        "afterSend",
-        "beforeSend",
-        "onClassify",
-        "onDispatch",
-        "onError",
-        "onGuardFail",
-        "onSessionClose",
-        "onSkillAuthored",
-      ]
-    );
-  });
-
-  it("marks only beforeSend as cancellable", () => {
-    assert.equal(isCancellableEvent("beforeSend"), true);
-    for (const e of HOOK_EVENT_NAMES) {
-      if (e === "beforeSend") continue;
-      assert.equal(isCancellableEvent(e), false, `${e} must not be cancellable`);
-    }
-  });
-
-  it("isHookEvent recognises known names and rejects others", () => {
-    assert.equal(isHookEvent("beforeSend"), true);
-    assert.equal(isHookEvent("nope"), false);
-  });
-});
-
-describe("HookBus — ordered priority dispatch", () => {
-  it("runs subscribers in descending priority order", async () => {
-    const { bus } = busWithLog();
-    const order = [];
-    bus.subscribe("onClassify", () => order.push("low"), { priority: 1 });
-    bus.subscribe("onClassify", () => order.push("high"), { priority: 10 });
-    bus.subscribe("onClassify", () => order.push("mid"), { priority: 5 });
-    await bus.emit("onClassify", {});
-    assert.deepEqual(order, ["high", "mid", "low"]);
-  });
-
-  it("breaks priority ties by registration order (FIFO)", async () => {
-    const { bus } = busWithLog();
-    const order = [];
-    bus.subscribe("onDispatch", () => order.push("a"), { priority: 5 });
-    bus.subscribe("onDispatch", () => order.push("b"), { priority: 5 });
-    bus.subscribe("onDispatch", () => order.push("c"), { priority: 5 });
-    await bus.emit("onDispatch", {});
-    assert.deepEqual(order, ["a", "b", "c"]);
-  });
-
-  it("passes the same ctx object to every subscriber", async () => {
-    const { bus } = busWithLog();
-    const ctx = { tool: "slack_send", text: "hi" };
-    const seen = [];
-    bus.subscribe("afterSend", (c) => seen.push(c));
-    bus.subscribe("afterSend", (c) => seen.push(c));
-    await bus.emit("afterSend", ctx);
-    assert.equal(seen.length, 2);
-    assert.equal(seen[0], ctx);
-    assert.equal(seen[1], ctx);
-  });
-
-  it("returns a not-cancelled decision for observe-only events", async () => {
-    const { bus } = busWithLog();
-    bus.subscribe("onGuardFail", () => ({ cancel: true, reason: "ignored" }));
-    const res = await bus.emit("onGuardFail", {});
-    // cancel returns are ignored for non-cancellable events.
-    assert.deepEqual(res, { cancelled: false, reason: null, by: null, errors: 0 });
-  });
-});
-
-describe("HookBus — cancellable beforeSend chain", () => {
-  it("a subscriber cancels the chain with a reason and short-circuits", async () => {
-    const { bus } = busWithLog();
-    const ran = [];
-    bus.subscribe("beforeSend", () => { ran.push("gate-a"); }, { priority: 10 });
-    bus.subscribe("beforeSend", () => {
-      ran.push("send-gate");
-      return { cancel: true, reason: "banned-phrase" };
-    }, { priority: 5 });
-    bus.subscribe("beforeSend", () => { ran.push("should-not-run"); }, { priority: 1 });
-
-    const res = await bus.emit("beforeSend", { text: "Absolutely!" });
-    assert.equal(res.cancelled, true);
-    assert.equal(res.reason, "banned-phrase");
-    assert.equal(res.by, 1); // index of the canceller in priority order
-    assert.deepEqual(ran, ["gate-a", "send-gate"]); // third never ran
-  });
-
-  it("an async subscriber can cancel the chain", async () => {
-    const { bus } = busWithLog();
-    const res = await (async () => {
-      bus.subscribe("beforeSend", async () => {
-        await Promise.resolve();
-        return { cancel: true, reason: "ownership-backstop" };
-      });
-      return bus.emit("beforeSend", {});
-    })();
-    assert.equal(res.cancelled, true);
-    assert.equal(res.reason, "ownership-backstop");
-  });
-
-  it("defaults the reason when a canceller omits one", async () => {
-    const { bus } = busWithLog();
-    bus.subscribe("beforeSend", () => ({ cancel: true }));
-    const res = await bus.emit("beforeSend", {});
-    assert.equal(res.cancelled, true);
-    assert.equal(res.reason, "cancelled");
-  });
-
-  it("does NOT cancel when no subscriber vetoes", async () => {
-    const { bus } = busWithLog();
-    bus.subscribe("beforeSend", () => undefined);
-    bus.subscribe("beforeSend", () => ({ cancel: false }));
-    bus.subscribe("beforeSend", () => "non-object-return");
-    const res = await bus.emit("beforeSend", {});
-    assert.equal(res.cancelled, false);
-    assert.equal(res.reason, null);
-  });
-});
-
-describe("HookBus — error isolation (fail-open)", () => {
-  it("isolates a throwing subscriber; later subscribers still run", async () => {
-    const { bus, logged } = busWithLog();
-    const ran = [];
-    bus.subscribe("onClassify", () => ran.push("first"), { priority: 10 });
-    bus.subscribe("onClassify", () => { throw new Error("boom"); }, { priority: 5 });
-    bus.subscribe("onClassify", () => ran.push("third"), { priority: 1 });
-
-    const res = await bus.emit("onClassify", {});
-    assert.deepEqual(ran, ["first", "third"]);
-    assert.equal(res.errors, 1);
-    assert.equal(res.cancelled, false);
-    // the error was reported to the logger
-    const errRows = logged.filter((e) => e.stage === "hook_subscriber_error");
-    assert.equal(errRows.length, 1);
-    assert.equal(errRows[0].event, "onClassify");
-    assert.match(errRows[0].error, /boom/);
-  });
-
-  it("isolates a rejecting async subscriber", async () => {
-    const { bus, logged } = busWithLog();
-    const ran = [];
-    bus.subscribe("onDispatch", async () => { throw new Error("async-boom"); });
-    bus.subscribe("onDispatch", () => ran.push("after"));
-    const res = await bus.emit("onDispatch", {});
-    assert.deepEqual(ran, ["after"]);
-    assert.equal(res.errors, 1);
-    assert.equal(logged.filter((e) => e.stage === "hook_subscriber_error").length, 1);
-  });
-
-  it("a throwing subscriber in a cancellable chain does NOT cancel the send", async () => {
-    const { bus } = busWithLog();
-    const ran = [];
-    bus.subscribe("beforeSend", () => { throw new Error("gate crashed"); }, { priority: 10 });
-    bus.subscribe("beforeSend", () => ran.push("downstream"), { priority: 1 });
-    const res = await bus.emit("beforeSend", {});
-    // fail-open: a buggy gate must not silently drop traffic
-    assert.equal(res.cancelled, false);
-    assert.equal(res.errors, 1);
-    assert.deepEqual(ran, ["downstream"]);
-  });
-
-  it("a throwing subscriber re-emits onError without recursing forever", async () => {
-    const { bus, logged } = busWithLog();
-    const onErrorSeen = [];
-    bus.subscribe("onError", (ctx) => { onErrorSeen.push(ctx); });
-    bus.subscribe("onSessionClose", () => { throw new Error("close-boom"); });
-    await bus.emit("onSessionClose", {});
-    // let the fire-and-forget onError re-emit settle
-    await new Promise((r) => setTimeout(r, 0));
-    assert.equal(onErrorSeen.length, 1);
-    assert.equal(onErrorSeen[0].sourceEvent, "onSessionClose");
-    assert.match(onErrorSeen[0].error, /close-boom/);
-    // exactly one subscriber-error row (the original) — onError did not recurse
-    assert.equal(logged.filter((e) => e.stage === "hook_subscriber_error").length, 1);
-  });
-
-  it("a throwing onError subscriber is logged but does not loop", async () => {
-    const { bus, logged } = busWithLog();
-    bus.subscribe("onError", () => { throw new Error("handler-boom"); });
-    bus.subscribe("onClassify", () => { throw new Error("orig"); });
-    await bus.emit("onClassify", {});
-    await new Promise((r) => setTimeout(r, 0));
-    // original error + the onError handler's own throw == 2 rows, then it stops.
-    const rows = logged.filter((e) => e.stage === "hook_subscriber_error");
-    assert.equal(rows.length, 2);
-    assert.deepEqual(rows.map((r) => r.event).sort(), ["onClassify", "onError"]);
-  });
-
-  it("a broken logger never breaks the bus", async () => {
-    const bus = createHookBus({ logger: () => { throw new Error("logger down"); } });
-    const ran = [];
-    bus.subscribe("onClassify", () => { throw new Error("x"); });
-    bus.subscribe("onClassify", () => ran.push("survived"));
-    const res = await bus.emit("onClassify", {});
-    assert.deepEqual(ran, ["survived"]);
-    assert.equal(res.errors, 1);
-  });
-});
-
-describe("HookBus — async ordering", () => {
-  it("awaits async subscribers in priority order before the next runs", async () => {
-    const { bus } = busWithLog();
-    const order = [];
-    const delay = (ms) => new Promise((r) => setTimeout(r, ms));
-    // higher priority deliberately SLOWER — must still complete before the
-    // lower-priority one starts, proving emit awaits in order.
-    bus.subscribe("onDispatch", async () => {
-      order.push("high-start");
-      await delay(20);
-      order.push("high-end");
-    }, { priority: 10 });
-    bus.subscribe("onDispatch", async () => {
-      order.push("low-start");
-      await delay(1);
-      order.push("low-end");
-    }, { priority: 1 });
-    await bus.emit("onDispatch", {});
-    assert.deepEqual(order, ["high-start", "high-end", "low-start", "low-end"]);
-  });
-
-  it("mixes sync and async subscribers, preserving order", async () => {
-    const { bus } = busWithLog();
-    const order = [];
-    bus.subscribe("afterSend", () => order.push("sync-1"), { priority: 3 });
-    bus.subscribe("afterSend", async () => {
-      await Promise.resolve();
-      order.push("async-2");
-    }, { priority: 2 });
-    bus.subscribe("afterSend", () => order.push("sync-3"), { priority: 1 });
-    await bus.emit("afterSend", {});
-    assert.deepEqual(order, ["sync-1", "async-2", "sync-3"]);
-  });
-
-  it("a cancel in an async chain short-circuits subsequent subscribers", async () => {
-    const { bus } = busWithLog();
-    const ran = [];
-    bus.subscribe("beforeSend", async () => {
-      await Promise.resolve();
-      ran.push("first");
-      return { cancel: true, reason: "stop" };
-    }, { priority: 10 });
-    bus.subscribe("beforeSend", () => ran.push("second"), { priority: 1 });
-    const res = await bus.emit("beforeSend", {});
-    assert.equal(res.cancelled, true);
-    assert.deepEqual(ran, ["first"]);
-  });
-});
-
-describe("HookBus — unknown event rejection", () => {
-  it("rejects subscribe to an unknown event", () => {
-    const { bus } = busWithLog();
-    assert.throws(() => bus.subscribe("notAnEvent", () => {}), /unknown event "notAnEvent"/);
-  });
-
-  it("rejects emit of an unknown event", async () => {
-    const { bus } = busWithLog();
-    await assert.rejects(() => bus.emit("notAnEvent", {}), /unknown event "notAnEvent"/);
-  });
-
-  it("rejects unsubscribe/count/clear of an unknown event", () => {
-    const { bus } = busWithLog();
-    assert.throws(() => bus.unsubscribe("nope", () => {}), /unknown event/);
-    assert.throws(() => bus.count("nope"), /unknown event/);
-    assert.throws(() => bus.clear("nope"), /unknown event/);
-  });
-
-  it("rejects a non-function handler", () => {
-    const { bus } = busWithLog();
-    assert.throws(() => bus.subscribe("beforeSend", 42), /must be a function/);
-  });
-});
-
-describe("HookBus — unsubscribe", () => {
-  it("the handle returned by subscribe removes the subscriber", async () => {
-    const { bus } = busWithLog();
-    const ran = [];
-    const off = bus.subscribe("onClassify", () => ran.push("x"));
-    assert.equal(bus.count("onClassify"), 1);
-    off();
-    assert.equal(bus.count("onClassify"), 0);
-    await bus.emit("onClassify", {});
-    assert.deepEqual(ran, []);
-  });
-
-  it("the unsubscribe handle is idempotent", () => {
-    const { bus } = busWithLog();
-    const fn = () => {};
-    const off = bus.subscribe("onClassify", fn);
-    // re-register the same fn so we can prove the handle removes only its own.
-    bus.subscribe("onClassify", fn);
-    off();
-    off(); // second call is a no-op
-    assert.equal(bus.count("onClassify"), 1);
-  });
-
-  it("unsubscribe(event, fn) removes the first matching registration", () => {
-    const { bus } = busWithLog();
-    const fn = () => {};
-    bus.subscribe("onClassify", fn);
-    assert.equal(bus.unsubscribe("onClassify", fn), true);
-    assert.equal(bus.unsubscribe("onClassify", fn), false);
-  });
-
-  it("unsubscribing during emit does not perturb the in-flight chain", async () => {
-    const { bus } = busWithLog();
-    const ran = [];
-    let off3;
-    bus.subscribe("onClassify", () => { ran.push("1"); off3(); }, { priority: 3 });
-    bus.subscribe("onClassify", () => ran.push("2"), { priority: 2 });
-    off3 = bus.subscribe("onClassify", () => ran.push("3"), { priority: 1 });
-    await bus.emit("onClassify", {});
-    // 3 was removed mid-emit but the snapshot still ran it this round.
-    assert.deepEqual(ran, ["1", "2", "3"]);
-    // next emit reflects the removal.
-    ran.length = 0;
-    await bus.emit("onClassify", {});
-    assert.deepEqual(ran, ["1", "2"]);
-  });
-});
-
-describe("HookBus — factory + singleton", () => {
-  it("createHookBus returns isolated instances", async () => {
-    const a = createHookBus({ logger: () => {} });
-    const b = createHookBus({ logger: () => {} });
-    assert.notEqual(a, b);
-    const ranA = [];
-    a.subscribe("onClassify", () => ranA.push("a"));
-    await b.emit("onClassify", {});
-    assert.deepEqual(ranA, []); // b's emit never touched a's subscribers
-  });
-
-  it("getHookBus returns the same instance across calls", () => {
-    resetHookBus();
-    const first = getHookBus({ logger: () => {} });
-    const second = getHookBus();
-    assert.equal(first, second);
-    resetHookBus();
-    const third = getHookBus({ logger: () => {} });
-    assert.notEqual(first, third);
-    resetHookBus();
-  });
-
-  it("is an instance of HookBus", () => {
-    assert.ok(createHookBus() instanceof HookBus);
-  });
-
-  it("HOOK_EVENTS is frozen (closed set is immutable)", () => {
-    assert.ok(Object.isFrozen(HOOK_EVENTS));
-    assert.ok(Object.isFrozen(HOOK_EVENT_NAMES));
-  });
-});

package/lib/identity/persona.test.mjs

@@ -1,142 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { renderPersona, loadPersonaBlock, MESSAGE_CRAFT } from "./persona.mjs";
-
-const AGENT = {
-  firstName: "Jamie",
-  lastName: "Okafor",
-  fullName: "Jamie Okafor",
-  title: "SVP AI Systems & Agent Platform",
-  altitude: "svp",
-  company: "Northwind",
-  principal: { firstName: "Robin", fullName: "Robin Vance", title: "Chief Product & Technology Officer" },
-  responsibilities: ["Agent platform reliability", "Fleet enrolment integrity"],
-  operatingPrinciples: ["Evidence over opinion"],
-  communication: { defaultTone: "warm-professional", externalTone: "formal" },
-};
-
-test("renders name, title, company and the seniority standing for the altitude band", () => {
-  const out = renderPersona(AGENT);
-  assert.match(out, /You are Jamie Okafor, SVP AI Systems & Agent Platform at Northwind\./);
-  assert.match(out, /You are a senior vice president\./);
-  assert.match(out, /You report to Robin Vance, Chief Product & Technology Officer\./);
-});
-
-test("renders responsibilities, principles and register when present", () => {
-  const out = renderPersona(AGENT);
-  assert.match(out, /### What you own/);
-  assert.match(out, /- Agent platform reliability/);
-  assert.match(out, /### How you operate/);
-  assert.match(out, /- Evidence over opinion/);
-  assert.match(out, /Default tone: warm-professional/);
-  assert.match(out, /outside Northwind: formal/);
-});
-
-// The regression this module exists for: the agent signing off as an AI
-// assistant working on behalf of its principal.
-test("instructs against assistant framing and on-behalf-of signatures", () => {
-  const out = renderPersona(AGENT);
-  assert.match(out, /Do not introduce, describe or sign yourself as an assistant/);
-  assert.match(out, /working on behalf of/); // named as the thing NOT to do
-  assert.match(out, /You report to Robin the way any senior colleague reports to their manager/);
-  assert.match(out, /full member of this team, not a service attached to it/);
-});
-
-// The truthfulness invariant in policies/ai-disclosure.yaml is locked and must
-// survive the seniority rewrite — senior AND honest, neither traded for the other.
-test("preserves the answer-truthfully-if-asked invariant", () => {
-  const out = renderPersona(AGENT);
-  assert.match(out, /sincerely asks whether they are dealing with an AI, say so plainly/);
-  assert.match(out, /not a standing disclaimer/);
-});
-
-test("omits unconfigured sections rather than rendering placeholders", () => {
-  const out = renderPersona({ fullName: "Ada Lovelace", title: "Head of Analysis" });
-  assert.match(out, /You are Ada Lovelace, Head of Analysis\./);
-  assert.doesNotMatch(out, /### What you own/);
-  assert.doesNotMatch(out, /### How you operate/);
-  assert.doesNotMatch(out, /### Your register/);
-  assert.doesNotMatch(out, /You report to/);
-  assert.doesNotMatch(out, /undefined|null|unconfigured/i);
-});
-
-test("returns empty string when there is no identity at all", () => {
-  assert.equal(renderPersona({}), "");
-  assert.equal(renderPersona(null), "");
-  assert.equal(renderPersona({ company: "Northwind" }), "");
-});
-
-test("persona prose falls back across persona → background → bio", () => {
-  assert.match(renderPersona({ ...AGENT, persona: "P-text" }), /### Background\n\nP-text/);
-  assert.match(renderPersona({ ...AGENT, background: "B-text" }), /### Background\n\nB-text/);
-  assert.match(renderPersona({ ...AGENT, bio: "Bio-text" }), /### Background\n\nBio-text/);
-});
-
-test("an unknown altitude drops the standing line without breaking the block", () => {
-  const out = renderPersona({ ...AGENT, altitude: "wizard" });
-  assert.match(out, /You are Jamie Okafor/);
-  assert.doesNotMatch(out, /senior vice president/);
-});
-
-test("company falls back to config/company.json when agent.json lacks it", () => {
-  const out = renderPersona({ fullName: "Ada Lovelace", title: "Head of Analysis" }, { name: "Northwind" });
-  assert.match(out, /Head of Analysis at Northwind\./);
-});
-
-test("includeVoiceRules:false emits identity only", () => {
-  const out = renderPersona(AGENT, {}, { includeVoiceRules: false });
-  assert.match(out, /You are Jamie Okafor/);
-  assert.doesNotMatch(out, /How you write and carry yourself/);
-});
-
-test("junk values in list fields are dropped, not rendered", () => {
-  const out = renderPersona({ ...AGENT, responsibilities: ["real", "", null, {}, 42] });
-  assert.match(out, /- real/);
-  assert.match(out, /- 42/);
-  assert.doesNotMatch(out, /\[object Object\]/);
-});
-
-// The message-craft doctrine is a separately-exported constant (NOT part of the
-// persona block) precisely so the responder — which never renders the persona —
-// can inject the identical string. These pin the substance both planes rely on.
-test("MESSAGE_CRAFT carries the distil-by-default / format-when-large / attach-when-verbose doctrine", () => {
-  // Distil by default; most replies are short.
-  assert.match(MESSAGE_CRAFT, /Distil to what matters, by default/);
-  assert.match(MESSAGE_CRAFT, /Lead with the answer, the decision, or the ask/);
-  // Offer depth on request rather than front-loading.
-  assert.match(MESSAGE_CRAFT, /Offer depth, don't front-load it/);
-  // Format only when the message must be large — never a wall of text.
-  assert.match(MESSAGE_CRAFT, /when a message genuinely must be long, FORMAT it/i);
-  assert.match(MESSAGE_CRAFT, /never a wall of text/);
-  // Attach verbose content with a short summary rather than dumping it.
-  assert.match(MESSAGE_CRAFT, /do NOT dump it into the chat/);
-  assert.match(MESSAGE_CRAFT, /two-to-three-line summary/);
-});
-
-test("MESSAGE_CRAFT names the REAL attach mechanisms and forbids local paths", () => {
-  assert.match(MESSAGE_CRAFT, /scripts\/pdf-generation\/build-document\.mjs/);
-  assert.match(MESSAGE_CRAFT, /npm run pdf:memo/);
-  assert.match(MESSAGE_CRAFT, /scripts\/slack-upload-v2\.py/);
-  assert.match(MESSAGE_CRAFT, /--attachment/);
-  assert.match(MESSAGE_CRAFT, /Never reference a local file path/);
-});
-
-test("loadPersonaBlock reads an agent repo, and fails open on a broken config", () => {
-  const dir = mkdtempSync(join(tmpdir(), "persona-"));
-  try {
-    mkdirSync(join(dir, "config"));
-    writeFileSync(join(dir, "config/agent.json"), JSON.stringify(AGENT));
-    assert.match(loadPersonaBlock(dir), /You are Jamie Okafor/);
-
-    writeFileSync(join(dir, "config/agent.json"), "{ not json");
-    assert.equal(loadPersonaBlock(dir), "");
-
-    assert.equal(loadPersonaBlock(join(dir, "nope")), "");
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});