@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/goals/collaborate.test.mjs

@@ -0,0 +1,324 @@
+/**
+ * lib/goals/collaborate.test.mjs — the four dispositions route through the
+ * collaboration primitives that ALREADY EXIST.
+ *
+ * The design claim being tested is a negative one: no new coordination
+ * mechanism. COLLABORATE takes a `work-claim` lease, HANDOFF sends a handoff
+ * envelope, NEEDS_REVIEW goes through `approval.request` when the action class
+ * is gated, and "ask, don't pile on" uses `escalation.*`. If any of these grew
+ * a parallel mechanism, these tests are where it shows up.
+ *
+ * Every test drives the failure side too: an unreachable org must produce
+ * `{ok:false, reason}` plus a log line, never a silent success and never a
+ * throw into the loop.
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  createWorkItem, routeWorkItem, routeSelf, routeCollaborate, routeHandoff,
+  routeNeedsReview, raiseEscalation, workResourceId, WORK_LEASE_SCOPE,
+} from "./collaborate.mjs";
+import { classifyWorkItem } from "./classify.mjs";
+
+const SELF = "mem_self";
+const PEER = "mem_peer";
+
+const ITEM = {
+  id: "goal-pipeline-1",
+  title: "Book 6 discovery calls",
+  objectiveKey: "pipeline",
+  obligationKey: "outcome.pipeline",
+  priority: "high",
+  expectedDelta: 0.5,
+  successCriteria: ["6 calls booked"],
+  why: { reason: "kpi-gap", objectiveKey: "pipeline", clause: "cs_12" },
+};
+
+function spy(over = {}) {
+  const calls = { board: [], handoff: [], approval: [], lease: [], rpc: [], logs: [] };
+  const deps = {
+    memberId: SELF,
+    log: (lvl, msg) => calls.logs.push(`${lvl}:${msg}`),
+    createItem: async (p) => { calls.board.push(p); return { ok: true, result: { id: "bi_1" } }; },
+    sendHandoff: async (o) => { calls.handoff.push(o); return { sent: true, runId: "run_1", transport: { reason: "offered" } }; },
+    requestApproval: async (o) => { calls.approval.push(o); return { requested: true, id: "appr_1" }; },
+    claimLease: async (scope, resourceId) => { calls.lease.push({ scope, resourceId }); return { held: true, leaseToken: "lt_1" }; },
+    callImpl: async (method, params) => { calls.rpc.push({ method, params }); return { ok: true, result: { id: "r_1" } }; },
+    ...over,
+  };
+  return { calls, deps };
+}
+
+/** Build the classification the loop would have produced. */
+function classify(candidate, ctx = {}) {
+  return classifyWorkItem(candidate, { memberId: SELF, ...ctx });
+}
+
+// ---------------------------------------------------------------------------
+// The board item — the one thing every disposition creates
+// ---------------------------------------------------------------------------
+
+test("workResourceId is stable and objective-scoped", () => {
+  const a = workResourceId("pipeline", "Book 6 discovery calls");
+  assert.equal(a, workResourceId("pipeline", "Book 6 discovery calls"));
+  assert.notEqual(a, workResourceId("pipeline", "A different task"));
+  assert.notEqual(a, workResourceId("retention", "Book 6 discovery calls"));
+  assert.match(a, /^objective:pipeline:[0-9a-f]{10}$/);
+});
+
+test("every work item carries the full provenance chain onto the board", async () => {
+  const { calls, deps } = spy();
+  const r = await createWorkItem(ITEM, deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.itemId, "bi_1");
+  const payload = calls.board[0];
+  assert.equal(payload.objectiveKey, "pipeline");
+  assert.equal(payload.obligationKey, "outcome.pipeline");
+  assert.equal(payload.why.clause, "cs_12");
+  assert.equal(payload.assignee, SELF);
+});
+
+test("SERVER UNREACHABLE: a thrown board.create is reported, logged, and never throws out", async () => {
+  const { calls, deps } = spy({ createItem: async () => { throw new Error("ECONNREFUSED"); } });
+  const r = await createWorkItem(ITEM, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.itemId, null);
+  assert.equal(r.reason, "board-create-threw");
+  assert.ok(calls.logs.some((l) => l.startsWith("warn:")), "the failure must be logged");
+});
+
+test("SERVER UNREACHABLE: an error FRAME is distinguished from a throw", async () => {
+  const { calls, deps } = spy({ createItem: async () => ({ ok: false, error: { code: "RATE_LIMITED" } }) });
+  const r = await createWorkItem(ITEM, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, "RATE_LIMITED");
+  assert.ok(calls.logs.some((l) => /the local backlog item still stands/.test(l)));
+});
+
+// ---------------------------------------------------------------------------
+// SELF
+// ---------------------------------------------------------------------------
+
+test("SELF creates the board item and nothing else", async () => {
+  const { calls, deps } = spy();
+  const c = classify({ title: ITEM.title, advances: ["pipeline"] });
+  assert.equal(c.disposition, "SELF");
+  const r = await routeSelf(ITEM, c, deps);
+  assert.equal(r.primitive, "board.create");
+  assert.equal(r.ok, true);
+  assert.equal(calls.handoff.length, 0);
+  assert.equal(calls.approval.length, 0);
+  assert.equal(calls.lease.length, 0);
+});
+
+test("SELF carries a capability gap forward rather than losing it", async () => {
+  const { deps } = spy();
+  const c = classify(
+    { title: "Do the thing", advances: ["pipeline"], requiredCapabilities: ["stripe_refund"] },
+    { reachable: new Set([]), peers: [] }
+  );
+  assert.equal(c.disposition, "SELF");
+  const r = await routeSelf(ITEM, c, deps);
+  assert.ok(r.capabilityGap, "an unreachable capability must travel with the route result");
+  assert.ok(r.capabilityGap.uncovered.includes("stripe_refund"));
+});
+
+// ---------------------------------------------------------------------------
+// COLLABORATE — the existing lease, not a new mechanism
+// ---------------------------------------------------------------------------
+
+test("COLLABORATE claims the work-claim lease BEFORE creating the item", async () => {
+  const order = [];
+  const { calls, deps } = spy();
+  const baseLease = deps.claimLease;
+  const baseBoard = deps.createItem;
+  deps.claimLease = async (s, r, o) => { order.push("lease"); return baseLease(s, r, o); };
+  deps.createItem = async (p) => { order.push("board"); return baseBoard(p); };
+  const c = classify({ title: ITEM.title, advances: ["pipeline"], collaborators: [{ memberId: PEER, role: "CONTRIBUTOR" }] });
+  assert.equal(c.disposition, "COLLABORATE");
+  const r = await routeCollaborate(ITEM, c, deps);
+  assert.deepEqual(order, ["lease", "board"], "claiming after creating would race two agents onto one item");
+  assert.equal(calls.lease[0].scope, WORK_LEASE_SCOPE);
+  assert.equal(r.ok, true);
+  // The contributor is told, over the existing board comment method.
+  const comment = calls.rpc.find((x) => x.method === "board.comment");
+  assert.ok(comment);
+  assert.deepEqual(comment.params.mentionedMemberIds, [PEER]);
+});
+
+test("COLLABORATE: losing the lease stands down — no board item at all", async () => {
+  const { calls, deps } = spy({ claimLease: async () => ({ held: false, reason: "held-by-peer" }) });
+  const c = classify({ title: ITEM.title, advances: ["pipeline"], collaborators: [{ memberId: PEER, role: "CONTRIBUTOR" }] });
+  const r = await routeCollaborate(ITEM, c, deps);
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /^lease-lost:/);
+  assert.equal(calls.board.length, 0, "a peer owns it — creating a second item is the duplicate-work bug");
+  assert.ok(calls.logs.some((l) => /standing down/.test(l)));
+});
+
+test("COLLABORATE: a lease service that THROWS fails open — loudly, and duplicate work is flagged", async () => {
+  const { calls, deps } = spy({ claimLease: async () => { throw new Error("lease service down"); } });
+  const c = classify({ title: ITEM.title, advances: ["pipeline"], collaborators: [{ memberId: PEER, role: "CONTRIBUTOR" }] });
+  const r = await routeCollaborate(ITEM, c, deps);
+  // Fail-open: the work proceeds…
+  assert.equal(r.ok, true);
+  assert.equal(r.failedOpen, true);
+  // …but never silently.
+  assert.ok(calls.logs.some((l) => /FAILED OPEN/.test(l) && /duplicate work is possible/.test(l)));
+});
+
+// ---------------------------------------------------------------------------
+// HANDOFF — the existing envelope
+// ---------------------------------------------------------------------------
+
+test("HANDOFF assigns the item to the target and sends the envelope with full context", async () => {
+  const { calls, deps } = spy();
+  const c = classify({ title: ITEM.title, advances: ["pipeline"], collaborators: [{ memberId: PEER, role: "DOER" }] });
+  assert.equal(c.disposition, "HANDOFF");
+  const r = await routeHandoff(ITEM, c, deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.primitive, "handoff.offer");
+  assert.equal(calls.board[0].assignee, PEER, "the board item must be assigned to whoever is doing it");
+  const env = calls.handoff[0];
+  assert.equal(env.to, PEER);
+  assert.equal(env.from, SELF);
+  assert.equal(env.itemId, "bi_1");
+  assert.equal(env.payload.objectiveKey, "pipeline");
+  assert.equal(env.payload.obligationKey, "outcome.pipeline");
+  assert.deepEqual(env.payload.successCriteria, ["6 calls booked"]);
+});
+
+test("HANDOFF that is not sent leaves the item effectively unassigned — and says so", async () => {
+  const { calls, deps } = spy({ sendHandoff: async () => ({ sent: false, transport: { reason: "no-channel" } }) });
+  const c = classify({ title: ITEM.title, advances: ["pipeline"], collaborators: [{ memberId: PEER, role: "DOER" }] });
+  const r = await routeHandoff(ITEM, c, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, "no-channel");
+  assert.ok(calls.logs.some((l) => /was NOT sent/.test(l)));
+});
+
+test("HANDOFF that throws still leaves the work item behind", async () => {
+  const { calls, deps } = spy({ sendHandoff: async () => { throw new Error("boom"); } });
+  const c = classify({ title: ITEM.title, advances: ["pipeline"], collaborators: [{ memberId: PEER, role: "DOER" }] });
+  const r = await routeHandoff(ITEM, c, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, "handoff-threw");
+  assert.equal(r.itemId, "bi_1", "the work must not evaporate because the envelope failed");
+  assert.equal(calls.board.length, 1);
+});
+
+// ---------------------------------------------------------------------------
+// NEEDS_REVIEW — approvals are the gate, and the gate holds
+// ---------------------------------------------------------------------------
+
+test("a gated action class goes through approval.request, carrying the classification", async () => {
+  const { calls, deps } = spy();
+  const c = classify({ title: "Wire the money", advances: ["pipeline"], actionClasses: ["financial"] });
+  assert.equal(c.disposition, "NEEDS_REVIEW");
+  const r = await routeNeedsReview({ ...ITEM, title: "Wire the money" }, c, deps);
+  assert.equal(r.primitive, "approval.request");
+  assert.equal(r.ok, true);
+  assert.deepEqual(calls.approval[0].classification, ["financial"]);
+  assert.equal(calls.approval[0].requester, SELF);
+  assert.equal(calls.approval[0].itemId, "bi_1");
+  assert.equal(calls.approval[0].payload.why.clause, "cs_12");
+});
+
+test("APPROVAL GATE HOLDS: an approval that cannot be requested BLOCKS the work", async () => {
+  const { calls, deps } = spy({ requestApproval: async () => ({ requested: false, id: null }) });
+  const c = classify({ title: "Send the external note", advances: ["pipeline"], actionClasses: ["external"] });
+  const r = await routeNeedsReview(ITEM, c, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.blocked, true, "a gated action with no approval must NOT execute");
+  assert.ok(calls.logs.some((l) => /stays BLOCKED, not executed/.test(l)));
+});
+
+test("APPROVAL GATE HOLDS: a throwing approval service also blocks", async () => {
+  const { deps } = spy({ requestApproval: async () => { throw new Error("503"); } });
+  const c = classify({ title: "Delete the bucket", advances: ["pipeline"], actionClasses: ["irreversible"] });
+  const r = await routeNeedsReview(ITEM, c, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, "approval-threw");
+});
+
+test("a plain named reviewer does NOT consume an approval — it degrades to a review envelope, logged", async () => {
+  const { calls, deps } = spy();
+  const c = classify({ title: ITEM.title, advances: ["pipeline"], collaborators: [{ memberId: PEER, role: "REVIEWER" }] });
+  assert.equal(c.disposition, "NEEDS_REVIEW");
+  assert.deepEqual(c.gatedClasses, []);
+  const r = await routeNeedsReview(ITEM, c, deps);
+  assert.equal(calls.approval.length, 0, "a review is not an approval — do not burn the approval path on it");
+  // Either the first-class method (once hq ships it) or the logged fallback.
+  assert.ok(["board.requestReview", "handoff.offer(review)"].includes(r.primitive));
+  if (r.primitive === "handoff.offer(review)") {
+    assert.equal(r.degraded, true);
+    assert.ok(calls.logs.some((l) => /falling back to a REVIEW handoff/.test(l)),
+      "a degradation must be announced, not silent");
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Escalation — "ask, don't pile on"
+// ---------------------------------------------------------------------------
+
+test("an escalation carries concrete OPTIONS, not prose", async () => {
+  const { calls, deps } = spy();
+  const r = await raiseEscalation({
+    objectiveKey: "pipeline",
+    question: "Coverage is flat at 1.5 against a target of 3. What should change?",
+    options: [{ label: "Re-target" }, { label: "Add resourcing" }, "Accept the miss"],
+    gap: { gap: 1.5, target: 3, trend: "flat" },
+  }, deps);
+  assert.equal(r.ok, true);
+  const call = calls.rpc[0];
+  assert.match(call.method, /^escalation\./);
+  assert.equal(call.params.options.length, 3);
+  // A bare string option is normalised to {label} so the consumer has one shape.
+  assert.deepEqual(call.params.options[2], { label: "Accept the miss" });
+  assert.equal(call.params.objectiveKey, "pipeline");
+});
+
+test("SERVER UNREACHABLE: a failed escalation is reported, and the question survives in the ledger", async () => {
+  const { calls, deps } = spy({ callImpl: async () => { throw new Error("ECONNREFUSED"); } });
+  const r = await raiseEscalation({ objectiveKey: "pipeline", question: "?", options: [] }, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, "escalation-threw");
+  assert.ok(calls.logs.some((l) => l.startsWith("warn:")));
+});
+
+test("an escalation error FRAME still records the question", async () => {
+  const { calls, deps } = spy({ callImpl: async () => ({ ok: false, error: { code: "FORBIDDEN" } }) });
+  const r = await raiseEscalation({ objectiveKey: "pipeline", question: "?", options: [] }, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, "FORBIDDEN");
+  assert.ok(calls.logs.some((l) => /still recorded in the audit ledger/.test(l)));
+});
+
+// ---------------------------------------------------------------------------
+// The dispatcher
+// ---------------------------------------------------------------------------
+
+test("routeWorkItem dispatches each disposition to its own primitive", async () => {
+  for (const [collaborators, actionClasses, expected] of [
+    [[], [], "board.create"],
+    [[{ memberId: PEER, role: "DOER" }], [], "handoff.offer"],
+    [[{ memberId: PEER, role: "CONTRIBUTOR" }], [], "lease+board"],
+    [[], ["financial"], "approval.request"],
+  ]) {
+    const { deps } = spy();
+    const c = classify({ title: ITEM.title, advances: ["pipeline"], collaborators, actionClasses });
+    const r = await routeWorkItem(ITEM, c, deps);
+    assert.equal(r.primitive, expected, `${c.disposition} must route to ${expected}`);
+  }
+});
+
+test("an unknown disposition falls back to SELF rather than dropping the work", async () => {
+  const { calls, deps } = spy();
+  const r = await routeWorkItem(ITEM, { disposition: "NONSENSE", contributors: [], gatedClasses: [] }, deps);
+  assert.equal(r.routed, "SELF");
+  assert.equal(calls.board.length, 1);
+});

package/lib/goals/gaps.mjs

@@ -0,0 +1,111 @@
+/**
+ * lib/goals/gaps.mjs — the read-only bridge between the goal loop's measured
+ * KPI series and the daemon's backlog sweep.
+ *
+ * The goal-steward (`lib/goals/loop.mjs`) MEASURES and writes
+ * `state/kpi/measurements.jsonl`. The daemon's `sweepBacklog()` DISPATCHES.
+ * Between them sits exactly one question: "how badly is each objective missed
+ * right now?" — so that `lib/backlog.rankBacklog` can float work that advances
+ * a lagging objective above work that advances nothing.
+ *
+ * This module answers that question from local state ONLY: the cached mandate
+ * plus the local measurement series. No network, no LLM, no sub-session. The
+ * daemon's hot path must never block on hq, and a partitioned agent must still
+ * rank its backlog sensibly.
+ *
+ * Fail-open, never silent: a missing/corrupt cache returns `{}` **and logs**.
+ * An empty map means the ranking degrades to exactly today's flat priority
+ * ordering, which is the correct fallback.
+ *
+ * @module lib/goals/gaps
+ */
+
+"use strict";
+
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { readCache, stalenessTier } from "../mandate/cache.mjs";
+import { adoptedObjectives, memberIdOf, validateMandateBody } from "../mandate/model.mjs";
+import { readSeries, gapFor } from "../kpi.mjs";
+
+function logOf(deps) {
+  return deps && typeof deps.log === "function" ? deps.log : () => {};
+}
+
+/**
+ * Latest gap per adopted objective, keyed by objective key.
+ *
+ * Only ADOPTED objectives are included — a proposed objective drives no work,
+ * so it must not influence dispatch order either. Self-adopted objectives are
+ * excluded by `adoptedObjectives` (the anti-Goodhart law): a seat cannot float
+ * its own backlog by grading itself.
+ *
+ * @param {string} [agentRoot]
+ * @param {object} [deps] - { cacheRecord?, readSeries?, now?, log?, memberId? }
+ * @returns {Object<string, object>} objectiveKey → lib/kpi.gapFor() output
+ */
+export function readLatestGaps(agentRoot, deps = {}) {
+  const log = logOf(deps);
+  let root;
+  try {
+    root = resolveAgentRoot(agentRoot);
+  } catch (err) {
+    log("warn", `[goals] cannot resolve the agent root for gap ranking: ${err && err.message ? err.message : err}`);
+    return {};
+  }
+
+  let record;
+  try {
+    record = deps.cacheRecord !== undefined ? deps.cacheRecord : readCache(root);
+  } catch (err) {
+    log("warn", `[goals] mandate cache unreadable — backlog falls back to flat priority order: ${err && err.message ? err.message : err}`);
+    return {};
+  }
+  if (!record) {
+    // Not an error: an agent with no adopted mandate is the normal pre-adoption
+    // state. Logged at info so it is visible, not silent.
+    log("info", "[goals] no mandate cache — backlog ranks on flat priority order");
+    return {};
+  }
+  if (record.corrupt) {
+    log("warn", `[goals] mandate cache is corrupt (${record.reason}) — backlog falls back to flat priority order`);
+    return {};
+  }
+
+  // A mandate nobody has refreshed in over a week must not keep steering
+  // dispatch: the staleness ladder suspends OUTCOME work at >72h, and ranking
+  // on a week-old target is worse than not ranking at all.
+  const tier = stalenessTier(record, deps.now ? deps.now() : Date.now());
+  if (tier === "expired") {
+    log("warn", "[goals] mandate cache is expired (>7d) — backlog falls back to flat priority order");
+    return {};
+  }
+
+  const memberId = deps.memberId || memberIdOf(record) || null;
+  let objectives;
+  try {
+    const validation = validateMandateBody(record, { ownerMemberId: memberId });
+    objectives = adoptedObjectives(record, { ownerMemberId: memberId, badKeys: validation.badKeys });
+  } catch (err) {
+    log("warn", `[goals] mandate did not validate for gap ranking: ${err && err.message ? err.message : err}`);
+    return {};
+  }
+
+  const read = typeof deps.readSeries === "function" ? deps.readSeries : (r, k) => readSeries(r, k);
+  const out = {};
+  for (const objective of objectives) {
+    if (!objective || !objective.key) continue;
+    try {
+      const series = read(root, objective.key) || [];
+      const gap = gapFor(objective, series, deps);
+      // An unmeasured or stale objective contributes no urgency. Recording it
+      // with a zeroed gap keeps the map complete for callers that want to
+      // report coverage without letting it distort the ranking.
+      out[objective.key] = gap.stale ? { ...gap, normalizedGap: 0 } : gap;
+    } catch (err) {
+      log("warn", `[goals] could not compute the gap for "${objective.key}": ${err && err.message ? err.message : err}`);
+    }
+  }
+  return out;
+}
+
+export default { readLatestGaps };