@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/execution/route.mjs

@@ -0,0 +1,332 @@
+/**
+ * lib/execution/route.mjs — the execution RUNG decision rule (SPEC §7).
+ *
+ * Once `disposition.mjs` has decided the agent should act, this module decides
+ * *how much machinery* the action deserves. The doctrine, stated once:
+ *
+ *   Pick the LOWEST rung whose predicate holds.
+ *   Escalate exactly ONE rung on the second failure of the same obligation.
+ *   Never skip a rung.
+ *   Never escalate past rung 3 without an adopted objective behind the work.
+ *
+ * The reason this is a module rather than a comment in the dispatcher is that
+ * today the choice is implicit: every inbound item that survives the gate gets a
+ * full Claude Code session (rung 3), whether it needed one protocol call or a
+ * week of research. That is both the dominant cost line and the dominant latency
+ * line, and it is why "answer a DM" and "rebuild the pipeline model" currently
+ * cost the same.
+ *
+ * Two gates cut ACROSS every rung and are applied after the rung is chosen:
+ *   - blast radius: an `external | irreversible | financial` action class forces
+ *     an approval BEFORE any rung executes, rung 0 included;
+ *   - budget: an estimate over the remaining envelope forces an enqueue, never a
+ *     silent downgrade to a cheaper rung (a cheaper rung would do the work
+ *     WORSE, not cheaper — downgrading on cost is how agents produce garbage).
+ *
+ * PURE. Every input arrives on the argument; nothing is read from disk or the
+ * network. That is what lets `explain.mjs`-style tooling replay a routing
+ * decision offline from the journal alone.
+ *
+ * @module lib/execution/route
+ */
+
+"use strict";
+
+import { GATED_CLASSES } from "../org/approvals.mjs";
+
+/**
+ * The six rungs. `id` is the numeric rung, `mechanism` names the machinery that
+ * actually runs it, `offline` says whether the rung survives with no network to
+ * hq (rungs that spawn sessions do; rungs that call protocol methods do not).
+ */
+export const RUNGS = Object.freeze([
+  Object.freeze({
+    id: 0,
+    key: "function_call",
+    mechanism: "tool-surface",
+    label: "single protocol method",
+    offline: false,
+  }),
+  Object.freeze({
+    id: 1,
+    key: "skill",
+    mechanism: "claude-skill",
+    label: "bounded skill session",
+    offline: true,
+  }),
+  Object.freeze({
+    id: 2,
+    key: "plugin",
+    mechanism: "integration",
+    label: "external SaaS via integration plugin",
+    offline: false,
+  }),
+  Object.freeze({
+    id: 3,
+    key: "session",
+    mechanism: "dispatcher-spawn",
+    label: "Claude Code session",
+    offline: true,
+  }),
+  Object.freeze({
+    id: 4,
+    key: "workflow",
+    mechanism: "workflow-runner",
+    label: "multi-stage durable workflow",
+    offline: true,
+  }),
+  Object.freeze({
+    id: 5,
+    key: "team",
+    mechanism: "subagent-fanout",
+    label: "sub-agent team",
+    offline: true,
+  }),
+]);
+
+/** Rung lookup by numeric id. */
+export function rungById(id) {
+  return RUNGS.find((r) => r.id === id) || null;
+}
+
+/**
+ * `MAX_STEPS` in hq's `agent-runner.ts` — the natural in-chat ceiling, and the
+ * reason 6 rather than some rounder number is the rung-3 step threshold. Kept as
+ * a named constant so the coupling is visible instead of being a magic 6.
+ */
+export const IN_CHAT_STEP_CEILING = 6;
+
+/** The number of failures of the SAME obligation that buys exactly one rung. */
+export const FAILURES_PER_RUNG = 2;
+
+/**
+ * @typedef {Object} Need
+ * @property {string[]} [methods]      protocol methods the action would call
+ * @property {boolean} [paramsKnown]   are all params already resolved (no lookup)?
+ * @property {number}  [steps]         estimated tool calls
+ * @property {boolean} [filesystem]    does it touch a repo / the filesystem?
+ * @property {boolean} [openEnded]     is it research with no known stopping point?
+ * @property {boolean} [externalSaas]  does it need a capability outside the protocol?
+ * @property {string}  [skillId]       a skill that covers this procedure
+ * @property {number}  [stages]        distinct stages with gates between them
+ * @property {boolean} [gated]         are there approval gates BETWEEN the stages?
+ * @property {boolean} [durable]       must the run survive a restart?
+ * @property {number}  [subProblems]   independent sub-problems
+ * @property {boolean} [sharedState]   do the sub-problems share mutable state?
+ * @property {string[]} [actionClasses] blast-radius classes of the action
+ * @property {string}  [obligationKey]
+ * @property {string}  [objectiveId]
+ */
+
+/**
+ * @typedef {Object} RouteContext
+ * @property {Array<{id:string, reachable:boolean}>} [manifest] capability manifest
+ * @property {number} [failures]        prior failures of THIS obligation
+ * @property {number} [estCents]        estimated cost of the action
+ * @property {number} [remainingCents]  remaining obligation/seat envelope
+ * @property {boolean} [hasAdoptedObjective] is an adopted objective behind this?
+ * @property {number} [maxRung]         hard ceiling (e.g. staleness ladder)
+ */
+
+/** Is `id` present in the manifest AND reachable? Absent manifest ⇒ unknown, not false. */
+function reachable(manifest, id) {
+  if (!Array.isArray(manifest) || !id) return null;
+  const hit = manifest.find((c) => c && String(c.id) === String(id));
+  if (!hit) return false;
+  return hit.reachable !== false;
+}
+
+/**
+ * The blast-radius classes of an action, normalised against the ONE gated-class
+ * vocabulary (`lib/org/approvals.mjs GATED_CLASSES`) so this module cannot drift
+ * into a second, parallel list of what "risky" means.
+ *
+ * @param {string[]|undefined} classes
+ * @returns {string[]} the gated subset, sorted
+ */
+export function gatedClassesOf(classes) {
+  const out = new Set();
+  for (const c of [].concat(classes || [])) {
+    const k = String(c || "").toLowerCase();
+    if (GATED_CLASSES.includes(k)) out.add(k);
+  }
+  return [...out].sort();
+}
+
+/**
+ * Choose the lowest rung whose predicate holds, before any cross-cutting gate.
+ * Split out from {@link routeRung} so a test can assert the ladder itself
+ * without the gates muddying it.
+ *
+ * @param {Need} need
+ * @param {RouteContext} ctx
+ * @returns {{rung:number, reason:string, why:string[]}}
+ */
+export function baseRung(need = {}, ctx = {}) {
+  const why = [];
+  // A default parameter only fires on `undefined`; an explicit `null` from a
+  // caller that had nothing to say must not throw here — this is the routing
+  // path for live inbound events.
+  if (!need || typeof need !== "object") need = {};
+  if (!ctx || typeof ctx !== "object") ctx = {};
+  const methods = [].concat(need.methods || []);
+  const steps = Number.isFinite(need.steps) ? need.steps : methods.length || 1;
+
+  // Rung 5 and 4 are structural: they describe the SHAPE of the work, and no
+  // amount of "it's only a small task" makes a 3-stage gated process fit in a
+  // single session. Tested first so a genuinely large job is not walked up from
+  // rung 0 one failure at a time.
+  const subProblems = Number.isFinite(need.subProblems) ? need.subProblems : 0;
+  if (subProblems >= 3 && need.sharedState !== true) {
+    why.push(`subProblems=${subProblems} independent → team`);
+    return { rung: 5, reason: "independent_sub_problems", why };
+  }
+  const stages = Number.isFinite(need.stages) ? need.stages : 0;
+  if (stages >= 3 && (need.durable === true || need.gated === true)) {
+    why.push(`stages=${stages} with gates and durability → workflow`);
+    return { rung: 4, reason: "multi_stage_durable", why };
+  }
+
+  // Rung 0 — one method, params already in hand, trivially short, no filesystem.
+  if (
+    methods.length === 1 &&
+    need.paramsKnown === true &&
+    steps <= 3 &&
+    need.filesystem !== true &&
+    need.openEnded !== true &&
+    need.externalSaas !== true
+  ) {
+    why.push(`single method ${methods[0]}, params known, ${steps} step(s) → function call`);
+    return { rung: 0, reason: "single_method", why };
+  }
+  why.push(
+    `rung 0 declined (methods=${methods.length}, paramsKnown=${need.paramsKnown === true}, steps=${steps}, filesystem=${need.filesystem === true})`,
+  );
+
+  // Rung 1 — a repeatable procedure with a REACHABLE skill behind it. The
+  // reachability check is what stops rung 1 being a lie: citing a skill file
+  // that the marketplace never registered means the session starts with no skill
+  // loaded and silently behaves like a bare rung-3 session.
+  if (
+    need.skillId &&
+    steps >= 2 &&
+    steps <= 10 &&
+    need.filesystem !== true &&
+    need.openEnded !== true &&
+    need.externalSaas !== true
+  ) {
+    const ok = reachable(ctx.manifest, need.skillId);
+    if (ok === false) {
+      why.push(`rung 1 declined: skill ${need.skillId} is not reachable in the manifest`);
+    } else {
+      why.push(`skill ${need.skillId} covers ${steps} step(s)${ok === null ? " (manifest absent — assumed reachable)" : ""}`);
+      return { rung: 1, reason: "skill_covers", why };
+    }
+  }
+
+  // Rung 2 — the capability lives outside the protocol entirely.
+  if (need.externalSaas === true && need.filesystem !== true) {
+    why.push("capability is external SaaS outside the protocol → integration plugin");
+    return { rung: 2, reason: "external_capability", why };
+  }
+
+  // Rung 3 — filesystem, or too long for chat, or open-ended.
+  if (need.filesystem === true) {
+    why.push("touches the filesystem → session");
+    return { rung: 3, reason: "filesystem", why };
+  }
+  if (steps > IN_CHAT_STEP_CEILING) {
+    why.push(`steps=${steps} > in-chat ceiling ${IN_CHAT_STEP_CEILING} → session`);
+    return { rung: 3, reason: "too_many_steps", why };
+  }
+  if (need.openEnded === true) {
+    why.push("open-ended research → session");
+    return { rung: 3, reason: "open_ended", why };
+  }
+
+  // Nothing matched cleanly: a handful of protocol calls with judgment in
+  // between. Rung 1 without a skill is not available, so the honest floor is a
+  // bounded session.
+  why.push("no lower predicate held → bounded session");
+  return { rung: 3, reason: "default_session", why };
+}
+
+/**
+ * Route a need to a rung, applying the failure walk-up and both cross-cutting
+ * gates. Never throws.
+ *
+ * @param {Need} need
+ * @param {RouteContext} ctx
+ * @returns {{
+ *   rung:number, mechanism:string, key:string, reason:string, why:string[],
+ *   blocked:boolean, gate:null|{kind:string, detail:object},
+ *   approval:null|{required:true, classes:string[]},
+ *   escalatedFrom:number|null
+ * }}
+ */
+export function routeRung(need = {}, ctx = {}) {
+  if (!need || typeof need !== "object") need = {};
+  if (!ctx || typeof ctx !== "object") ctx = {};
+  const base = baseRung(need, ctx);
+  const why = base.why.slice();
+  let rung = base.rung;
+  let escalatedFrom = null;
+
+  // ── the failure walk-up: exactly one rung per FAILURES_PER_RUNG failures,
+  //    and never a skip. Two failures at rung 0 buys rung 1, not rung 3.
+  const failures = Number.isFinite(ctx.failures) ? Math.max(0, ctx.failures) : 0;
+  if (failures >= FAILURES_PER_RUNG) {
+    const steps = Math.floor(failures / FAILURES_PER_RUNG);
+    const target = Math.min(rung + steps, 5);
+    if (target !== rung) {
+      why.push(`${failures} prior failure(s) of this obligation → walk up ${rung}→${target}`);
+      escalatedFrom = rung;
+      rung = target;
+    }
+  }
+
+  // ── "never escalate past rung 3 without an adopted objective behind the work"
+  if (rung > 3 && ctx.hasAdoptedObjective !== true) {
+    why.push(`rung ${rung} needs an adopted objective behind it; none → capped at 3`);
+    rung = 3;
+  }
+
+  // ── an externally imposed ceiling (the staleness ladder, a beat directive)
+  if (Number.isFinite(ctx.maxRung) && rung > ctx.maxRung) {
+    why.push(`ceiling maxRung=${ctx.maxRung} → capped from ${rung}`);
+    rung = Math.max(0, ctx.maxRung);
+  }
+
+  const def = rungById(rung) || RUNGS[3];
+
+  // ── gate 1: blast radius. Applied AFTER the rung is known so the approval
+  //    card can name the mechanism, but BEFORE anything executes.
+  const classes = gatedClassesOf(need.actionClasses);
+  const approval = classes.length ? { required: true, classes } : null;
+  if (approval) why.push(`blast radius ${classes.join("+")} → approval required before rung ${rung} runs`);
+
+  // ── gate 2: budget. An over-envelope estimate ENQUEUES; it never quietly
+  //    picks a cheaper rung, because a cheaper rung is a worse answer, not a
+  //    cheaper one.
+  let gate = null;
+  const est = Number.isFinite(ctx.estCents) ? ctx.estCents : null;
+  const remaining = Number.isFinite(ctx.remainingCents) ? ctx.remainingCents : null;
+  if (est !== null && remaining !== null && est > remaining) {
+    gate = { kind: "budget", detail: { estCents: est, remainingCents: remaining } };
+    why.push(`estimate ${est}c exceeds remaining envelope ${remaining}c → enqueue, not downgrade`);
+  }
+
+  return {
+    rung,
+    mechanism: def.mechanism,
+    key: def.key,
+    reason: base.reason,
+    why,
+    blocked: gate !== null,
+    gate,
+    approval,
+    escalatedFrom,
+  };
+}
+
+export default { RUNGS, rungById, baseRung, routeRung, gatedClassesOf, IN_CHAT_STEP_CEILING, FAILURES_PER_RUNG };

package/lib/execution/route.test.mjs

@@ -0,0 +1,186 @@
+/**
+ * route.test.mjs — the execution rung ladder (SPEC §7).
+ * Run: node --test lib/execution/route.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { GATED_CLASSES } from "../org/approvals.mjs";
+import {
+  RUNGS,
+  rungById,
+  baseRung,
+  routeRung,
+  gatedClassesOf,
+  IN_CHAT_STEP_CEILING,
+  FAILURES_PER_RUNG,
+} from "./route.mjs";
+
+const ONE_CALL = { methods: ["messaging.send"], paramsKnown: true, steps: 1 };
+
+test("the ladder is six rungs, contiguous, each with a mechanism", () => {
+  assert.equal(RUNGS.length, 6);
+  RUNGS.forEach((r, i) => {
+    assert.equal(r.id, i);
+    assert.ok(r.mechanism && r.key && r.label);
+  });
+  assert.equal(rungById(3).key, "session");
+  assert.equal(rungById(99), null);
+});
+
+test("rung 0: one method, params known, short, no filesystem", () => {
+  const r = baseRung(ONE_CALL);
+  assert.equal(r.rung, 0);
+  assert.equal(r.reason, "single_method");
+});
+
+test("rung 0 is declined when any of its four predicates fails", () => {
+  assert.notEqual(baseRung({ ...ONE_CALL, paramsKnown: false }).rung, 0);
+  assert.notEqual(baseRung({ ...ONE_CALL, methods: ["a", "b"] }).rung, 0);
+  assert.notEqual(baseRung({ ...ONE_CALL, steps: 4 }).rung, 0);
+  assert.notEqual(baseRung({ ...ONE_CALL, filesystem: true }).rung, 0);
+  // and a bare need with nothing known does not sneak into rung 0
+  assert.notEqual(baseRung({}).rung, 0);
+});
+
+test("rung 1: a reachable skill covers a 2–10 step procedure", () => {
+  const need = { methods: ["a", "b", "c"], steps: 4, skillId: "triage-inbox" };
+  const ctx = { manifest: [{ id: "triage-inbox", reachable: true }] };
+  const r = baseRung(need, ctx);
+  assert.equal(r.rung, 1);
+  assert.equal(r.reason, "skill_covers");
+});
+
+test("rung 1 is DECLINED when the skill is not reachable — the marketplace lie", () => {
+  // Citing a skill the marketplace never registered means the session starts
+  // with no skill loaded. That must fall through, not pretend to be rung 1.
+  const need = { methods: ["a", "b", "c"], steps: 4, skillId: "triage-inbox" };
+  const r = baseRung(need, { manifest: [{ id: "triage-inbox", reachable: false }] });
+  assert.notEqual(r.rung, 1);
+  assert.ok(r.why.some((w) => /not reachable/.test(w)));
+});
+
+test("rung 1 with an ABSENT manifest is allowed, and says so", () => {
+  const need = { methods: ["a", "b"], steps: 3, skillId: "triage" };
+  const r = baseRung(need, {});
+  assert.equal(r.rung, 1);
+  assert.ok(r.why.some((w) => /manifest absent/.test(w)));
+});
+
+test("rung 1 declines a skill outside the 2–10 step band", () => {
+  assert.notEqual(baseRung({ steps: 1, skillId: "s", methods: ["a"], paramsKnown: true }).rung, 1);
+  assert.equal(baseRung({ steps: 40, skillId: "s" }).rung, 3);
+});
+
+test("rung 2: an external SaaS capability outside the protocol", () => {
+  const r = baseRung({ externalSaas: true, steps: 2 });
+  assert.equal(r.rung, 2);
+  assert.equal(r.reason, "external_capability");
+});
+
+test("rung 3: filesystem, too many steps, or open-ended", () => {
+  assert.equal(baseRung({ filesystem: true }).reason, "filesystem");
+  assert.equal(baseRung({ steps: IN_CHAT_STEP_CEILING + 1 }).reason, "too_many_steps");
+  assert.equal(baseRung({ openEnded: true, steps: 2 }).reason, "open_ended");
+  assert.equal(baseRung({ filesystem: true }).rung, 3);
+});
+
+test("rung 3 is the honest floor when nothing lower matches", () => {
+  const r = baseRung({ methods: ["a", "b"], steps: 3 });
+  assert.equal(r.rung, 3);
+  assert.equal(r.reason, "default_session");
+});
+
+test("rungs 4 and 5 are STRUCTURAL — tested before the cheap rungs", () => {
+  // A genuinely large job must not be walked up from rung 0 one failure at a time.
+  const workflow = baseRung({ stages: 4, gated: true, durable: true, methods: ["a"], paramsKnown: true, steps: 1 });
+  assert.equal(workflow.rung, 4);
+  const team = baseRung({ subProblems: 4, methods: ["a"], paramsKnown: true, steps: 1 });
+  assert.equal(team.rung, 5);
+});
+
+test("rung 5 declines when the sub-problems share mutable state", () => {
+  const r = baseRung({ subProblems: 5, sharedState: true, filesystem: true });
+  assert.equal(r.rung, 3);
+});
+
+test("rung 4 declines when the stages have neither gates nor durability", () => {
+  assert.notEqual(baseRung({ stages: 5, steps: 3, methods: ["a", "b"] }).rung, 4);
+});
+
+test("failure walk-up: one rung per two failures, and never a skip", () => {
+  const need = { ...ONE_CALL };
+  assert.equal(routeRung(need, { failures: 0 }).rung, 0);
+  assert.equal(routeRung(need, { failures: 1 }).rung, 0, "one failure buys nothing");
+  assert.equal(routeRung(need, { failures: 2 }).rung, 1);
+  assert.equal(routeRung(need, { failures: 3 }).rung, 1);
+  assert.equal(routeRung(need, { failures: 4 }).rung, 2);
+  assert.equal(routeRung(need, { failures: 2 }).escalatedFrom, 0);
+  assert.equal(FAILURES_PER_RUNG, 2);
+});
+
+test("the walk-up cannot pass rung 3 without an adopted objective", () => {
+  const need = { ...ONE_CALL };
+  const capped = routeRung(need, { failures: 20, hasAdoptedObjective: false });
+  assert.equal(capped.rung, 3);
+  assert.ok(capped.why.some((w) => /adopted objective/.test(w)));
+
+  const allowed = routeRung(need, { failures: 20, hasAdoptedObjective: true });
+  assert.ok(allowed.rung > 3);
+});
+
+test("an external ceiling (staleness ladder / beat directive) caps the rung", () => {
+  const r = routeRung({ filesystem: true }, { maxRung: 1 });
+  assert.equal(r.rung, 1);
+  assert.ok(r.why.some((w) => /ceiling maxRung=1/.test(w)));
+  // maxRung 0 is a real value, not a falsy no-op
+  assert.equal(routeRung({ filesystem: true }, { maxRung: 0 }).rung, 0);
+});
+
+test("blast radius forces an approval BEFORE any rung — rung 0 included", () => {
+  const r = routeRung({ ...ONE_CALL, actionClasses: ["external"] });
+  assert.equal(r.rung, 0, "the gate does not change the rung");
+  assert.deepEqual(r.approval, { required: true, classes: ["external"] });
+  assert.ok(r.why.some((w) => /approval required before rung 0/.test(w)));
+});
+
+test("no gated class ⇒ no approval gate", () => {
+  assert.equal(routeRung(ONE_CALL).approval, null);
+  assert.equal(routeRung({ ...ONE_CALL, actionClasses: [] }).approval, null);
+  assert.equal(routeRung({ ...ONE_CALL, actionClasses: ["chatty"] }).approval, null);
+});
+
+test("gatedClassesOf normalises against the ONE gated-class vocabulary", () => {
+  assert.deepEqual(gatedClassesOf(["EXTERNAL", "financial", "nonsense"]), ["external", "financial"]);
+  assert.deepEqual(gatedClassesOf(undefined), []);
+  assert.deepEqual(gatedClassesOf("irreversible"), ["irreversible"]);
+  assert.deepEqual(gatedClassesOf(["external", "external"]), ["external"], "deduped");
+  // the vocabulary is not re-declared locally
+  for (const c of GATED_CLASSES) assert.deepEqual(gatedClassesOf([c]), [c]);
+});
+
+test("over-budget BLOCKS with an enqueue signal — it never downgrades the rung", () => {
+  const r = routeRung({ filesystem: true }, { estCents: 900, remainingCents: 100 });
+  assert.equal(r.blocked, true);
+  assert.equal(r.gate.kind, "budget");
+  assert.equal(r.rung, 3, "a cheaper rung would be a worse answer, not a cheaper one");
+});
+
+test("budget gate is inert when either side of the comparison is unknown", () => {
+  assert.equal(routeRung(ONE_CALL, { estCents: 900 }).blocked, false);
+  assert.equal(routeRung(ONE_CALL, { remainingCents: 10 }).blocked, false);
+  assert.equal(routeRung(ONE_CALL, {}).blocked, false);
+  // exactly-at-budget is allowed; only strictly-over blocks
+  assert.equal(routeRung(ONE_CALL, { estCents: 100, remainingCents: 100 }).blocked, false);
+});
+
+test("routeRung never throws and always names a mechanism", () => {
+  for (const need of [undefined, null, {}, { methods: null }, { steps: NaN }, { subProblems: "x" }]) {
+    const r = routeRung(need, {});
+    assert.ok(Number.isInteger(r.rung) && r.rung >= 0 && r.rung <= 5);
+    assert.ok(r.mechanism, "every routing result names its mechanism");
+    assert.ok(Array.isArray(r.why) && r.why.length > 0, "and explains itself");
+  }
+});