@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/lib/execution/effects.mjs

@@ -338,6 +338,93 @@ export function writeProposal(decision, o = {}) {
   return { ok, ref: { proposed: true }, error: ok ? null : "proposal append failed" };
 }
 
+/**
+ * Compact the engagement run result for the outcome journal. Ids, surface and
+ * the machine reason — never the body, never a room name.
+ */
+function engagementRef(eng) {
+  if (!eng || typeof eng !== "object") return null;
+  const d = eng.decision || {};
+  return {
+    engaged: eng.engaged === true,
+    outcome: eng.outcome || null,
+    surface: eng.surface || d.surface || "none",
+    reasonCode: d.reasonCode || null,
+    targets: Array.isArray(d.targets) ? d.targets.map((t) => t.memberId) : [],
+    rungs: Array.isArray(d.targets) ? d.targets.map((t) => t.rung) : [],
+  };
+}
+
+/**
+ * An engagement problem the operator must see. A DELIBERATE non-engagement
+ * (`self_contained`, `already_engaged`, a rate limit) is not an error — it is
+ * the judgement working — so it returns null and lives in the ledger instead.
+ */
+function engagementError(eng) {
+  if (!eng || eng.engaged) return null;
+  const hard = new Set(["send_failed", "send_blocked", "engage_threw", "unroutable"]);
+  if (!hard.has(String(eng.outcome))) return null;
+  return `engagement ${eng.outcome}${eng.error ? `: ${eng.error}` : ""}`;
+}
+
+/**
+ * Turn a ladder decision into the `work` shape `lib/org/engagement.mjs` judges.
+ *
+ * ── WHY AN ESCALATION HAS TO ENGAGE SOMEBODY ──
+ * `escalate` used to end at `escalation.ask` / `escalation.create`: a row in a
+ * table. The live journal shows nine escalations, every one `spoke:false`, and
+ * three of them raised nothing at all ("Nothing was raised."). The ladder could
+ * decide a human was needed and then not tell a human. A record of a blockage
+ * that nobody is told about is a blockage nobody clears.
+ *
+ * So the record is still written — it is the auditable artefact and the thing a
+ * human can resolve in one click — and then the same decision is put in front of
+ * a person, through the judgement in engagement.mjs rather than by broadcasting.
+ * The judgement is what stops this becoming a firehose: it picks the addressee
+ * from the directory, picks the cheapest surface that reaches them, dedupes, and
+ * rate-limits. When it decides nobody needs to be involved, that is recorded too.
+ *
+ * `selfServeExhausted: true` is asserted here and it is honest: reaching the
+ * escalate rung IS the ladder having exhausted every disposition it can execute
+ * alone. This is the one caller entitled to assert it.
+ *
+ * @param {object} decision
+ * @param {object} candidate
+ * @param {object} [o] { me, escalationTarget }
+ * @returns {object} work
+ */
+function workFromDecision(decision, candidate, o = {}) {
+  const ids = (candidate && candidate.ids) || {};
+  const options = (decision.options || []).map((l) => String(l || "").trim()).filter(Boolean);
+  return {
+    id: String(decision.key || `${decision.surface || "inbound"}:${decision.obligationKey || "uncovered"}`),
+    title: `${decision.surface || "inbound"}: ${decision.reason || "needs a decision"}`,
+    // REDACTION HOLDS. The escalation lane never carries message bodies, room
+    // names or addresses — ids, surfaces and machine reasons only. The engagement
+    // body is assembled from the decision, exactly as the escalation text is.
+    summary: `The execution ladder stopped at \`${decision.reason}\` on ${decision.surface || "an inbound event"} (rung ${decision.rung ?? "?"}).`,
+    scope: decision.surface || "",
+    state: "blocked",
+    blocker: {
+      kind: options.length >= 2 ? "decision" : "approval",
+      scope: decision.surface || "",
+      detail: (decision.why || []).join("; ") || String(decision.reason || ""),
+      ownerId: decision.escalateTo || o.escalationTarget || null,
+    },
+    // Reaching this rung IS the exhaustion of what the agent can do alone.
+    selfServeExhausted: true,
+    origin: {
+      surface: decision.surface || "",
+      channelId: ids.channelId || null,
+      threadRootId: ids.threadRootId || ids.messageId || null,
+      requesterId: ids.fromMemberId || ids.actorId || null,
+    },
+    question: options.length >= 2 ? "Which way should this go?" : "",
+    options,
+    tried: (decision.why || []).slice(0, 4),
+  };
+}
+
 /**
  * Append a PROPOSED REACT obligation for an event the compiled plan did not
  * cover (§6.1: "emit `PlanDrift{uncovered_event}` **and** a proposed REACT
@@ -403,8 +490,48 @@ export function defaultEffects(o = {}) {
     schedule: async ({ decision, candidate, item }) =>
       scheduleToQueue(decision, { ...common, candidate, item: item || o.item || null }),
 
+    /**
+     * Hand the work to someone else — and TELL them.
+     *
+     * `sendHandoff` writes an A2A envelope. That is the right machine-to-machine
+     * artefact and it is also, on its own, invisible: the journal shows the
+     * delegate lane has never once produced `spoke:true`, because an envelope is
+     * not a message. A human delegatee learns nothing from it, and an agent
+     * delegatee learns it only when it next drains its queue.
+     *
+     * So the envelope still goes, and the delegatee is also told directly. The
+     * engagement judgement is used rather than an unconditional DM, so the
+     * dedupe and the rate caps apply here exactly as they do to escalation — a
+     * retried handoff must not re-ping.
+     */
     delegate: async ({ decision, candidate }) => {
       const { sendHandoff } = await import("../org/handoff.mjs");
+      const notifyLeg = (async () => {
+        if (!decision.delegateTo) return { ok: true, engaged: false, outcome: "no_delegatee" };
+        try {
+          const eng = o.engageImpl || (await import("../org/engagement.mjs")).engage;
+          const work = workFromDecision(decision, candidate, { me: o.me, escalationTarget: o.escalationTarget });
+          return await eng(
+            {
+              ...work,
+              title: `Handed to you: ${work.title}`,
+              blocker: { ...work.blocker, kind: "decision", ownerId: String(decision.delegateTo) },
+              question: "This is now yours — shout if it should come back to me.",
+              options: [],
+            },
+            {
+              cfg: o.cfg,
+              agentRoot,
+              me: o.me || "",
+              fetchImpl: o.fetchImpl,
+              nowMs: o.nowMs,
+              ctx: o.engagementCtx,
+            },
+          );
+        } catch (err) {
+          return { ok: false, engaged: false, outcome: "engage_threw", error: (err && err.message) || String(err) };
+        }
+      })();
       const r = await sendHandoff({
         agentRoot,
         from: o.me || "",
@@ -419,7 +546,12 @@ export function defaultEffects(o = {}) {
         },
         ...(o.transport ? { transport: o.transport } : {}),
       });
-      return { ok: r && r.ok !== false, ref: r, error: r && r.error ? String(r.error) : null };
+      const eng = await notifyLeg;
+      return {
+        ok: r && r.ok !== false,
+        ref: { handoff: r, engagement: engagementRef(eng), spoke: eng.engaged === true },
+        error: r && r.error ? String(r.error) : engagementError(eng),
+      };
     },
 
     /**
@@ -461,6 +593,30 @@ export function defaultEffects(o = {}) {
         return { ok: false, ref: null, error: "org not configured (no base) — cannot escalate" };
       }
 
+      // THE PERSON LEG. Runs regardless of whether the record leg below can find
+      // a target, because "escalation.create needs a taskId or channelId and this
+      // event carries neither" must no longer mean nobody hears about it. The
+      // judgement decides who and where; it is entitled to decide nobody, and it
+      // records that decision either way.
+      const engageLeg = (async () => {
+        try {
+          const eng = o.engageImpl || (await import("../org/engagement.mjs")).engage;
+          const cfg = o.cfg || { org: { cohort: { enabled: true, base: conn.base, token: conn.token, agentId: o.me } } };
+          return await eng(workFromDecision(decision, candidate, { me: o.me, escalationTarget: o.escalationTarget }), {
+            cfg,
+            agentRoot,
+            me: o.me || "",
+            supervisorId: o.escalationTarget || undefined,
+            fetchImpl: o.fetchImpl,
+            nowMs: o.nowMs,
+            ctx: o.engagementCtx,
+          });
+        } catch (err) {
+          // FAIL-OPEN IS FINE; SILENT IS NOT.
+          return { ok: false, engaged: false, outcome: "engage_threw", error: (err && err.message) || String(err) };
+        }
+      })();
+
       const surface = decision.surface || "inbound";
       const ids = (candidate && candidate.ids) || {};
       const options = (decision.options || [])
@@ -488,10 +644,13 @@ export function defaultEffects(o = {}) {
           },
           { ...conn, agentRoot },
         );
+        const eng = await engageLeg;
         return {
-          ok: !!r && r.ok !== false,
-          ref: { method: "escalation.ask", frame: r },
-          error: r && r.error ? errText(r.error) : null,
+          ok: (!!r && r.ok !== false) || eng.engaged === true,
+          // `spoke` is read by drive.mjs. It is TRUE only when a message actually
+          // reached a person — never merely because a row was written.
+          ref: { method: "escalation.ask", frame: r, engagement: engagementRef(eng), spoke: eng.engaged === true },
+          error: r && r.error ? errText(r.error) : engagementError(eng),
         };
       }
 
@@ -501,13 +660,32 @@ export function defaultEffects(o = {}) {
       const taskId = ids.taskId || ids.itemId || null;
       const channelId = ids.channelId || null;
       if (!taskId && !channelId) {
+        // No RECORD could be raised. That used to be the end of it — an honest
+        // error string and a human who never heard. The person leg still ran, so
+        // check it before declaring failure.
+        const eng = await engageLeg;
+        const cannotRaise =
+          `escalation.create needs a taskId or channelId and ${surface} event ` +
+          `${decision.key} carries neither; escalation.ask needs ≥2 options and ` +
+          `the decision offered ${options.length}. No escalation ROW was raised`;
+        if (eng.engaged) {
+          return {
+            ok: true,
+            ref: {
+              method: "engagement-only",
+              engagement: engagementRef(eng),
+              spoke: true,
+              // Still a degradation: the audit ROW is missing even though the
+              // person was reached. Both facts travel together on the outcome.
+              degraded: [`escalation_record_unraisable:${decision.key}`],
+            },
+            error: null,
+          };
+        }
         return {
           ok: false,
-          ref: null,
-          error:
-            `escalation.create needs a taskId or channelId and ${surface} event ` +
-            `${decision.key} carries neither; escalation.ask needs ≥2 options and ` +
-            `the decision offered ${options.length}. Nothing was raised.`,
+          ref: { engagement: engagementRef(eng), spoke: false },
+          error: `${cannotRaise}, and nobody was engaged either (${eng.outcome || "no outcome"}${eng.error ? `: ${eng.error}` : ""}). Nothing reached a human.`,
         };
       }
       const r = await call(
@@ -522,10 +700,11 @@ export function defaultEffects(o = {}) {
         },
         { ...conn, agentRoot },
       );
+      const eng = await engageLeg;
       return {
-        ok: !!r && r.ok !== false,
-        ref: { method: "escalation.create", frame: r },
-        error: r && r.error ? errText(r.error) : null,
+        ok: (!!r && r.ok !== false) || eng.engaged === true,
+        ref: { method: "escalation.create", frame: r, engagement: engagementRef(eng), spoke: eng.engaged === true },
+        error: r && r.error ? errText(r.error) : engagementError(eng),
       };
     },
 

package/lib/execution/effects.test.mjs

@@ -237,12 +237,16 @@ test("escalate resolves the org binding from the agent root — `agentRoot` alon
       });
     {
         assert.equal(r.ok, true, r.error || "escalate failed");
-        assert.equal(seen.length, 1, "no request was made");
-        assert.match(seen[0].url, /escalation\.ask$/, "≥2 options must go to ask, not create");
-        assert.equal(seen[0].body.options.length, 2);
-        assert.equal(typeof seen[0].body.context, "string", "hq's `context` is a STRING");
-        assert.equal(seen[0].body.trigger, "cannot_self_decide");
-        assert.ok(seen[0].body.question, "hq requires a question");
+        // The escalation now has TWO legs — the record, and the person. The
+        // person leg reads the directory + rooms first, so the request this test
+        // is about is found by name rather than by being the only one.
+        const ask = seen.find((s) => /escalation\.ask$/.test(s.url));
+        assert.ok(ask, "no escalation.ask request was made");
+        assert.equal(ask.body.options.length, 2);
+        assert.equal(typeof ask.body.context, "string", "hq's `context` is a STRING");
+        assert.equal(ask.body.trigger, "cannot_self_decide");
+        assert.ok(ask.body.question, "hq requires a question");
+        assert.ok(r.ref.engagement, "the escalation must report what it did about telling a human");
     }
   } finally {
     globalThis.fetch = orig;
@@ -277,11 +281,11 @@ test("fewer than two options falls back to escalation.create WITH a target", asy
   }
 });
 
-test("no options AND no target REFUSES loudly rather than 400ing on the wire", async () => {
+test("no options AND no target: no escalation ROW is attempted, and the failure names the human who was not reached", async () => {
   const root = enrolledRoot();
   const orig = globalThis.fetch;
-  let called = 0;
-  globalThis.fetch = async () => { called += 1; return new Response("{}", { status: 200 }); };
+  const urls = [];
+  globalThis.fetch = async (url) => { urls.push(String(url)); return new Response("{}", { status: 200 }); };
   try {
     const eff = defaultEffects({ agentRoot: root, me: "M-1" });
     const r = await eff
@@ -289,14 +293,49 @@ test("no options AND no target REFUSES loudly rather than 400ing on the wire", a
     {
         assert.equal(r.ok, false);
         assert.match(r.error, /needs a taskId or channelId/);
-        assert.match(r.error, /Nothing was raised/);
-        assert.equal(called, 0, "a call that cannot succeed must not be made");
+        assert.match(r.error, /No escalation ROW was raised/);
+        // THE POINT OF THE CHANGE. It used to end at "Nothing was raised" — a
+        // true statement about a table that told nobody anything. The failure now
+        // has to account for the person as well, and only claims total failure
+        // when neither leg reached anyone.
+        assert.match(r.error, /nobody was engaged either/);
+        assert.match(r.error, /Nothing reached a human/);
+        assert.equal(r.ref.spoke, false);
+        assert.ok(
+          urls.every((u) => !/escalation\./.test(u)),
+          "an escalation.* call that cannot succeed must still not be made",
+        );
     }
   } finally {
     globalThis.fetch = orig;
   }
 });
 
+test("when the record cannot be raised but a PERSON is reached, the escalation succeeds — and says the row is missing", async () => {
+  const root = enrolledRoot();
+  const orig = globalThis.fetch;
+  globalThis.fetch = async () => new Response("{}", { status: 200 });
+  try {
+    const eff = defaultEffects({
+      agentRoot: root,
+      me: "M-1",
+      // The judgement is injected here; it is proved on its own terms in
+      // lib/org/engagement.test.mjs.
+      engageImpl: async () => ({ ok: true, engaged: true, outcome: "engaged", surface: "dm", decision: { targets: [{ memberId: "M-2", rung: "supervisory" }], reasonCode: "blocked:approval" } }),
+    });
+    const r = await eff.escalate({
+      decision: { key: "k", surface: "approval", reason: "r", why: [], options: [] },
+      candidate: { ids: {} },
+    });
+    assert.equal(r.ok, true, "a human heard about it — that is not a failure");
+    assert.equal(r.ref.spoke, true);
+    assert.deepEqual(r.ref.engagement.targets, ["M-2"]);
+    assert.deepEqual(r.ref.degraded, ["escalation_record_unraisable:k"]);
+  } finally {
+    globalThis.fetch = orig;
+  }
+});
+
 test("errText renders an RPC error frame as a line, never `[object Object]`", () => {
   assert.equal(errText({ code: "BAD_REQUEST", message: "title is required" }), "BAD_REQUEST: title is required");
   assert.equal(errText("plain"), "plain");

package/lib/goals/admission.mjs

@@ -33,6 +33,7 @@
 "use strict";
 
 import { WORK_CREATING_SOURCES } from "../kpi.mjs";
+import { adoptionDefect } from "../mandate/model.mjs";
 
 /** Ordered gate names — evaluated in this order, first failure wins. */
 export const GATES = Object.freeze([
@@ -122,11 +123,22 @@ export function admit(candidate = {}, ctx = {}) {
   pass("freshness", "mandate cache is fresh");
 
   // --- adoption -------------------------------------------------------------
+  // The gate's contract is "adopted by SOMEBODY WHO IS NOT ITS OWNER", but for a
+  // long time it only tested the state column — so a hand-edited cache with
+  // `state:"active"` and no `adoptedById` (or the owner's own id) admitted work.
+  // Same law as the compiler; one implementation, in lib/mandate/model.mjs.
   const obj = ctx.objective || {};
   if (obj.state !== "active") {
     return fail("adoption", `objective "${obj.key || "?"}" is ${obj.state || "unknown"}, not active — a proposed objective admits no work`);
   }
-  pass("adoption", `objective "${obj.key}" is active`);
+  const defect = adoptionDefect(obj, ctx.memberId || obj.ownerMemberId || obj.memberId || null);
+  if (defect === "self_adopted") {
+    return fail("adoption", `objective "${obj.key || "?"}" was adopted by its own owning seat — a seat cannot define, measure and be graded on the same number`);
+  }
+  if (defect === "missing_adoption_provenance") {
+    return fail("adoption", `objective "${obj.key || "?"}" is active but carries no adoptedById — nobody is on record as having handed this seat the number`);
+  }
+  pass("adoption", `objective "${obj.key}" is active and adopted by ${obj.adoptedById}`);
 
   // --- honesty --------------------------------------------------------------
   const source = ctx.latestSample && ctx.latestSample.source;

package/lib/goals/admission.test.mjs

@@ -10,7 +10,10 @@ import assert from "node:assert/strict";
 
 import { admit, decideForGap, titleSimilarity, GATES, DUPLICATE_THRESHOLD } from "./admission.mjs";
 
-const OBJ = { key: "pipeline", state: "active", metric: "pipeline_coverage_x", target: 3, cadence: "weekly" };
+// `adoptedById` is load-bearing, not decoration: an active objective with no
+// adopter on record admits no work (the gate's contract has always been "adopted
+// by SOMEBODY WHO IS NOT ITS OWNER", and it used to check only the state column).
+const OBJ = { key: "pipeline", state: "active", metric: "pipeline_coverage_x", target: 3, cadence: "weekly", memberId: "M-OWNER", adoptedById: "M-SUPERVISOR" };
 const GAP = { gap: 1, target: 3, value: 2, withinTolerance: false, trend: "flat", normalizedGap: 0.33, stale: false };
 const SAMPLE = { source: "method", value: 2, window: "2026-W33" };
 
@@ -137,3 +140,25 @@ test("every rejection carries its gate and the full check trail — nothing is d
   assert.equal(v.checks[v.checks.length - 1].ok, false);
   assert.equal(v.checks[v.checks.length - 1].gate, v.gate);
 });
+
+// ---------------------------------------------------------------------------
+// the adoption gate reads the LAW, not the state column
+// ---------------------------------------------------------------------------
+
+test("GATE adoption — an active objective with NO adoptedById admits nothing", () => {
+  // The cheap tamper. Forging a supervisor id is work; DELETING the field was one
+  // keystroke, and `isSelfAdopted` returned false for a missing field, so the row
+  // sailed through both the compiler and this gate.
+  const { adoptedById, ...noProvenance } = OBJ;
+  const v = admit(candidate(), ctx({ objective: noProvenance }));
+  assert.equal(v.admitted, false);
+  assert.equal(v.gate, "adoption");
+  assert.match(v.reason, /no adoptedById/);
+});
+
+test("GATE adoption — a SELF-adopted objective admits nothing", () => {
+  const v = admit(candidate(), ctx({ objective: { ...OBJ, adoptedById: "M-OWNER" } }));
+  assert.equal(v.admitted, false);
+  assert.equal(v.gate, "adoption");
+  assert.match(v.reason, /own owning seat/);
+});

package/lib/goals/loop.mjs

@@ -104,6 +104,19 @@ export function renderQueueItems(items) {
     L.push(`    disposition: ${it.disposition || "SELF"}`);
     L.push(`    rung: ${it.rung == null ? "null" : it.rung}`);
     L.push(`    why: "${String((it.why && it.why.reason) || "kpi-gap").replace(/"/g, "'")}"`);
+    // The provenance an operator needs to answer "why did the agent do that?"
+    // from the queue file alone, with no network and no LLM. `why` used to be
+    // flattened to the bare string "kpi-gap", which named the CLASS of reason
+    // and none of the facts: which charter clause the item advances, which
+    // obligation it discharges, how big the gap was, and — the governance one —
+    // who adopted the objective it serves. A machine-created task that cannot
+    // say who authorised the number behind it is exactly the thing the mandate
+    // split exists to prevent.
+    const w = it.why || {};
+    if (w.clause) L.push(`    charter_clause: ${w.clause}`);
+    if (w.adoptedBy) L.push(`    adopted_by: ${w.adoptedBy}`);
+    if (Number.isFinite(w.gap)) L.push(`    gap: ${w.gap}`);
+    if (w.trend) L.push(`    trend: ${w.trend}`);
     L.push(`    created: ${it.created}`);
   }
   return L.join("\n");

package/lib/kpi-sensors.test.mjs

@@ -52,6 +52,9 @@ function fakeExec(table, calls = []) {
 const OBJ = (capability, params = {}) => ({
   key: "k", kind: "GOAL", state: "active", metric: "m", direction: "up",
   target: 90, tolerance: 2, cadence: "weekly",
+  // `adoptedById` is part of the law the admission gate enforces, not decoration:
+  // an active objective with nobody on record as having adopted it admits no work.
+  memberId: "M-OWNER", adoptedById: "M-SUPERVISOR",
   sensor: { capability, params, source: "method" },
 });
 

package/lib/mandate/cache.mjs

@@ -33,6 +33,8 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 
+import { adoptedObjectives as modelAdoptedObjectives } from "./model.mjs";
+
 /** Relative path of the cache (git-ignored runtime state). */
 export const CACHE_REL = join("state", "mandate", "cache.json");
 
@@ -143,11 +145,17 @@ export function permissionsForTier(tier) {
   }
 }
 
-/** Are the adopted objectives in this cache usable to compile obligations? */
-export function adoptedObjectives(record) {
-  const body = (record && record.body) || {};
-  const list = Array.isArray(body.objectives) ? body.objectives : [];
-  return list.filter((o) => o && o.state === "active");
+/**
+ * Are the adopted objectives in this cache usable to compile obligations?
+ *
+ * DELEGATES to `lib/mandate/model.adoptedObjectives`, which carries the whole
+ * anti-Goodhart law (measurable kind, active, real adoption provenance, not
+ * self-adopted). This used to be a second, LAW-FREE implementation that filtered
+ * on `state === "active"` alone — so whichever module a caller happened to
+ * import decided whether the law applied. One law, one implementation.
+ */
+export function adoptedObjectives(record, opts = {}) {
+  return modelAdoptedObjectives(record, opts);
 }
 
 /** Every objective in the cache, adopted or not (the proposal surface). */