@cohortapp/agent-sdk 2.4.1 → 2.5.0

package/scripts/ci/check.mjs

@@ -19,6 +19,7 @@
  *   - check-no-residual-identity: de-Robin'd paths stay persona-agnostic
  *   - check-no-build-artifacts  : no tracked .pyc/symlinks reach the tarball
  *   - check-docs-accuracy       : README links resolve; counts/agent-refs WARN
+ *   - check-subagent-frontmatter: every agents/*.md passes the registry validator
  *
  * Usage: `node scripts/ci/check.mjs`
  *   exit 0 → all checks passed; exit 1 → one or more failed.
@@ -36,6 +37,7 @@ import { run as runUnresolvedTokens } from "./check-unresolved-tokens.mjs";
 import { run as runNoResidualIdentity } from "./check-no-residual-identity.mjs";
 import { run as runNoBuildArtifacts } from "./check-no-build-artifacts.mjs";
 import { run as runDocsAccuracy } from "./check-docs-accuracy.mjs";
+import { run as runSubagentFrontmatter } from "./check-subagent-frontmatter.mjs";
 
 /**
  * The ordered list of guards this aggregator runs.
@@ -51,6 +53,7 @@ export const CHECKS = [
   { name: "check-no-residual-identity", run: runNoResidualIdentity },
   { name: "check-no-build-artifacts", run: runNoBuildArtifacts },
   { name: "check-docs-accuracy", run: runDocsAccuracy },
+  { name: "check-subagent-frontmatter", run: runSubagentFrontmatter },
 ];
 
 /**

package/scripts/ci/conformance-org-api.mjs

@@ -441,6 +441,22 @@ export function buildProbes() {
       guard: "ghost",
       why: "the task target 404s before the Escalation row",
     },
+    {
+      // The OpenQuestion sibling. Two DISTINCT options are mandatory server-side
+      // (one option is a notification, none is prose), and `context` is a STRING
+      // — the exact shape the contract row asserts, so the probe tests it rather
+      // than restating it. Ghost-guarded on the task target like its sibling.
+      method: "escalation.ask",
+      params: {
+        question: "conformance probe — which option?",
+        options: ["probe-option-a", "probe-option-b"],
+        context: "raised by the org-api conformance probe",
+        taskId: ghostTask,
+      },
+      writes: false,
+      guard: "ghost",
+      why: "the task target 404s before any OpenQuestion row is created",
+    },
     {
       method: "knowledge.invalidate",
       params: { id: ghostId("epi"), reason: "conformance probe" },

package/scripts/ci/journey-approval-escalation.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * scripts/ci/journey-approval-escalation.mjs — ONE JOURNEY, END TO END, LIVE.
+ *
+ * ── WHY THIS EXISTS ──
+ * Every layer of the inbound → execution stack has unit tests and every one of
+ * them passes with fakes on both sides of the joint. That proves the layers, not
+ * the seams. This script drives ONE real journey against a REAL org and prints
+ * what happened at every hop, so "the units connect" is a thing you can read
+ * rather than a thing you assert:
+ *
+ *   hop 1  hq  approval.request                 → an Approval row
+ *   hop 2  hq  ctx.appendEvent                  → an `approval.requested` frame
+ *   hop 3  SDK pullWideInbound                  → the frame off /v1/events
+ *   hop 4  SDK directedness.resolveDirected     → "mine, because <reason>"
+ *   hop 5  SDK match.matchObligation            → the plan obligation it binds to
+ *   hop 6  SDK route.routeRung                  → rung + mechanism + gates
+ *   hop 7  SDK drive → effects.escalate         → escalation.ask (an OpenQuestion)
+ *   hop 8  SDK journal.recordOutcome            → state/execution/journal.jsonl
+ *   hop 9  SDK kpi-sensors                      → is this lane measurable at all?
+ *
+ * ── WHAT IS REAL AND WHAT IS NOT ──
+ * REAL: the org, the credentials, the `/v1/events` ledger page, the board read,
+ * the channel roster, the directedness resolver, the whole execution ladder, the
+ * journal write, and the exact JSON body the escalation write would put on the
+ * wire.
+ *
+ * NOT REAL, and deliberately so: the Approval row itself. Creating one means
+ * writing to a production org, so the row and its ledger frame are synthesised —
+ * the frame BYTE-FOR-BYTE as `hq src/server/methods/approval/request.ts`
+ * appends it, the row byte-for-byte as `hq methods/approval/_shared.ts
+ * #projectApproval` returns it. Everything downstream of the frame is the
+ * shipping code path with nothing stubbed.
+ *
+ * EVERY SIDE-EFFECTING POST IS BLOCKED. The guard consults the vendored protocol
+ * table and refuses anything `sideEffecting:true`, printing the body instead. So
+ * this script can be run against production without writing to it — which is the
+ * only way it is useful, because a journey you can only run against an empty
+ * fixture org is a journey you have not tested.
+ *
+ * ── USAGE ──
+ *   AGENT_DIR=/path/to/agent \
+ *   COHORT_BASE=… COHORT_ORG_ID=… COHORT_AGENT_ID=… COHORT_API_KEY=… \
+ *   node scripts/ci/journey-approval-escalation.mjs
+ *
+ *   --allow-writes   actually send the escalation write (NOT the default)
+ *   --json           machine-readable hop report on stdout
+ *
+ * Exit 0 when every hop moved; exit 1 naming the first hop that did not.
+ */
+
+"use strict";
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { METHODS } from "../../lib/org/protocol.mjs";
+import { loadOrgConfig } from "../../lib/org/client.mjs";
+
+const ARGV = new Set(process.argv.slice(2));
+const ALLOW_WRITES = ARGV.has("--allow-writes");
+const AS_JSON = ARGV.has("--json");
+
+const AGENT_DIR = process.env.AGENT_DIR || process.env.AGENT_ROOT || process.cwd();
+const BASE = process.env.COHORT_BASE || "";
+const KEY = process.env.COHORT_API_KEY || process.env.COHORT_API_TOKEN || "";
+const ME = process.env.COHORT_AGENT_ID || "";
+
+const hops = [];
+const writes = [];
+
+function hop(n, name, ok, detail) {
+  hops.push({ n, name, ok, detail });
+  const mark = ok ? "✓" : "✗";
+  if (!AS_JSON) console.log(`\n${mark} HOP ${n}  ${name}`);
+  if (!AS_JSON && detail) console.log(String(detail).replace(/^/gm, "     "));
+  return ok;
+}
+
+function die(n, name, why) {
+  hop(n, name, false, why);
+  report();
+  process.exit(1);
+}
+
+function report() {
+  if (AS_JSON) {
+    console.log(JSON.stringify({ hops, writes }, null, 2));
+    return;
+  }
+  console.log("\n──────────────────────────────────────────────────────────────");
+  for (const h of hops) console.log(`  ${h.ok ? "✓" : "✗"}  hop ${h.n}  ${h.name}`);
+  console.log("──────────────────────────────────────────────────────────────");
+}
+
+// ---------------------------------------------------------------------------
+// the fetch guard: live reads, blocked writes, one synthesised row
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap `globalThis.fetch` so that:
+ *   - `GET /v1/events` is served live and the synthetic frame is appended;
+ *   - `approval.get` for the synthetic id returns the synthetic row;
+ *   - any POST to a `sideEffecting` protocol method is RECORDED, not sent.
+ *
+ * @param {{seq:number, approvalId:string, frame:object, row:object}} synth
+ */
+function installGuard(synth) {
+  const real = globalThis.fetch;
+  const json = (o) => new Response(JSON.stringify(o), { status: 200, headers: { "content-type": "application/json" } });
+
+  globalThis.fetch = async (input, init = {}) => {
+    const url = String(typeof input === "string" ? input : (input && input.url) || input);
+    const method = String(init.method || "GET").toUpperCase();
+    const m = url.match(/\/api\/v1\/([^?]+)/);
+    const rpc = m ? m[1] : "";
+
+    if (rpc === "approval.get") {
+      const body = init.body ? JSON.parse(init.body) : {};
+      if (String(body.id) === synth.approvalId) return json({ ok: true, result: synth.row });
+    }
+
+    if (rpc === "events" && method === "GET") {
+      const r = await real(input, init);
+      const j = await r.json();
+      const events = Array.isArray(j.events) ? j.events : [];
+      events.push(synth.frame);
+      return json({ events });
+    }
+
+    const d = METHODS[rpc];
+    if (method === "POST" && d && d.sideEffecting && !ALLOW_WRITES) {
+      const params = init.body ? JSON.parse(init.body) : {};
+      writes.push({ method: rpc, params });
+      return json({ ok: true, result: { id: `blocked_${writes.length}`, __blocked: true } });
+    }
+
+    if (method === "POST" && d && d.sideEffecting) writes.push({ method: rpc, params: init.body ? JSON.parse(init.body) : {} });
+    return real(input, init);
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+async function main() {
+  if (!BASE || !KEY || !ME) {
+    console.error("set COHORT_BASE, COHORT_API_KEY and COHORT_AGENT_ID");
+    process.exit(2);
+  }
+
+  // agent cfg exactly as `cadence-handlers.loadAgentCfg` assembles it
+  let cfg = {};
+  try {
+    const p = join(AGENT_DIR, "config", "agent.json");
+    if (existsSync(p)) cfg = JSON.parse(readFileSync(p, "utf8"));
+  } catch { /* fail-open */ }
+  const orgCfg = loadOrgConfig(AGENT_DIR);
+  if (orgCfg && orgCfg.org) cfg.org = orgCfg.org;
+  if (!cfg.org || !cfg.org.cohort) die(0, "agent config", "no `org.cohort` in config/org.yaml — nothing to talk to");
+
+  const auth = { authorization: `Bearer ${KEY}` };
+
+  // ── the ledger head, so the synthetic frame is the ONLY new row ──────────
+  let head = 0;
+  {
+    let c = 0;
+    for (let page = 0; page < 200; page += 1) {
+      const r = await fetch(`${BASE}/api/v1/events?cursor=${c}&limit=500`, { headers: auth });
+      const j = await r.json();
+      const e = Array.isArray(j.events) ? j.events : [];
+      if (!e.length) break;
+      c = e[e.length - 1].seq;
+      if (e.length < 500) break;
+    }
+    head = c;
+  }
+
+  // ── a REAL board item this seat owns or reviews: the thing the approval blocks
+  const { collectTasks } = await import("../../lib/org/inbound/facts.mjs");
+  const board = await (await fetch(`${BASE}/api/v1/board.context`, { headers: auth })).json();
+  const tasks = collectTasks(board);
+  const mine = tasks.filter(
+    (t) => String(t.assigneeId || t.assignee || "") === ME || String(t.reviewerId || t.reviewer || "") === ME,
+  );
+  if (!mine.length) die(0, "fixture", `no live board item names ${ME} as assignee or reviewer — nothing to hang an approval on`);
+  const task = mine.find((t) => String(t.reviewerId || "") === ME) || mine[0];
+  const requester = String(task.assigneeId || task.assignee || "") || "unknown";
+
+  // ── hop 1 + 2: the hq write and its chain append, synthesised to hq's shape
+  const approvalId = `aprv_journey_${Date.now().toString(36)}`;
+  const payloadHash = "0".repeat(64);
+  const row = {
+    id: approvalId,
+    requester,
+    approver: null, // hq: NULL until resolved (G5)
+    actionClass: "exec",
+    payloadHash,
+    status: "pending",
+    itemId: task.id,
+    reason: null,
+    subject: { note: "journey harness — synthetic, never written to the org" },
+    createdAt: new Date().toISOString(),
+    expiresAt: null,
+    decidedAt: null,
+  };
+  const frame = {
+    seq: head + 1,
+    family: "approval",
+    kind: "approval.requested",
+    entity_id: approvalId,
+    actor: requester,
+    at: new Date().toISOString(),
+    payload: { requester, actionClass: "exec", payloadHash, itemId: task.id },
+    prev_hash: "",
+    row_hash: "",
+  };
+  hop(1, "hq approval.request → Approval row", true,
+    `hq src/server/methods/approval/request.ts\n` +
+    `approval ${approvalId} blocks task ${task.id} (${task.title})\nrequester ${requester}, approver NULL (G5), status pending`);
+  hop(2, "hq ctx.appendEvent → approval.requested", true,
+    `family=approval kind=approval.requested seq=${frame.seq}\n${JSON.stringify(frame.payload)}`);
+
+  installGuard({ seq: frame.seq, approvalId, frame, row });
+
+  // ── hop 3: delivery ──────────────────────────────────────────────────────
+  const { pullWideInbound } = await import("../../lib/org/inbound/index.mjs");
+  const seen = [];
+  const log = (lvl, msg) => { seen.push(`[${lvl}] ${msg}`); };
+  const pulled = await pullWideInbound({ cfg, agentId: ME, cursor: head, log });
+  const ok3 = pulled.events.length > 0;
+  hop(3, "SDK pullWideInbound → the frame off /v1/events", ok3,
+    `scanned=${pulled.stats.scanned} classified=${pulled.stats.classified} directed=${pulled.stats.directed} delivered=${pulled.stats.delivered}\n` +
+    `dropped=${JSON.stringify(pulled.stats.dropped)}\ndegraded=${JSON.stringify(pulled.stats.degraded)}\n` +
+    seen.join("\n"));
+  if (!ok3) die(3, "SDK pullWideInbound", `nothing was delivered — dropped: ${JSON.stringify(pulled.stats.dropped)}`);
+
+  let roundTrip = "not attempted";
+  const ev = pulled.events.find((e) => e.cohort && e.cohort.surface === "approval") || pulled.events[0];
+
+  // ── hop 4: directedness ─────────────────────────────────────────────────
+  hop(4, "directedness → mine, and why", !!(ev.cohort && ev.cohort.reason),
+    `surface=${ev.cohort.surface} reason=${ev.cohort.reason} family=${ev.cohort.family} kind=${ev.cohort.event_kind}\n` +
+    `subject: ${ev.subject}\ntext: ${ev.text}`);
+
+  // ── hops 5-8: the execution ladder ──────────────────────────────────────
+  process.env.MAESTRO_DAEMON_NO_AUTOSTART = "1";
+  const { eventToInboxItem } = await import("../../lib/channels/inbox-item.mjs");
+  const daemon = await import("../daemon/agent-daemon.mjs");
+
+  // THE REAL POLL LANE, not a shortcut past it. `guardMessagingInbound` writes
+  // the flattened item to `state/inbox/cohort/*.yaml` and the daemon's scan
+  // poller reads it back; anything the writer does not enumerate dies in
+  // between. Going straight from MessageEvent to the ladder would hide exactly
+  // that class of bug — which is how the chain kind, the directedness reason and
+  // the subject id all came to be dropped at this boundary.
+  const flat = eventToInboxItem(ev);
+  const { writeInboxItem } = await import("../poller/utils.mjs");
+  const { parseInboxItemYaml } = await import("../poller/inbox-scan-poller.mjs");
+  let item = flat;
+  try {
+    writeInboxItem("cohort", flat, AGENT_DIR);
+    const dir = join(AGENT_DIR, "state", "inbox", "cohort");
+    const { readdirSync } = await import("node:fs");
+    const file = readdirSync(dir).filter((f) => f.includes(String(flat.id))).pop();
+    if (file && typeof parseInboxItemYaml === "function") {
+      item = parseInboxItemYaml(readFileSync(join(dir, file), "utf8"));
+      roundTrip = `wrote + re-read ${file}`;
+    } else {
+      roundTrip = `WROTE but could not re-read (parseInboxItemYaml exported? ${typeof parseInboxItemYaml}) — using the in-memory item`;
+    }
+  } catch (err) {
+    roundTrip = `YAML round-trip skipped: ${err.message}`;
+  }
+  daemon.enrichItem(item, "cohort");
+  const gate = await daemon.runExecutionLadder(item, "cohort", item.raw_ref || item.id, "journey", {
+    answerItem: async () => ({ ok: true, path: "journey-stub" }),
+  });
+  hop(3.5, "poll-lane YAML round-trip", !/skipped|could not/.test(roundTrip), roundTrip);
+
+  const d = gate.decision;
+  if (!d) die(5, "execution ladder", "the ladder produced no decision at all");
+
+  hop(5, "obligation match", true,
+    d.obligationKey ? `bound to ${d.obligationKey}` : "UNCOVERED — no compiled REACT obligation matched (config/plan.yaml)");
+  hop(6, "rung decision", Number.isFinite(d.rung),
+    `disposition=${d.disposition} reason=${d.reason} rung=${d.rung} mechanism=${d.mechanism}\n` +
+    `gates=${JSON.stringify(d.gates)}\nwhy:\n` + (d.why || []).map((w) => `  - ${w}`).join("\n"));
+
+  const escalation = writes.find((w) => w.method === "escalation.ask" || w.method === "escalation.create");
+  hop(7, "the action taken", !!escalation,
+    escalation
+      ? `${escalation.method}\n${JSON.stringify(escalation.params, null, 2)}`
+      : `NO escalation write was attempted. writes=${JSON.stringify(writes.map((w) => w.method))}`);
+
+  // ── hop 8: the journal ──────────────────────────────────────────────────
+  const { journalPath } = await import("../../lib/execution/journal.mjs");
+  const jp = journalPath(AGENT_DIR);
+  let tail = [];
+  try {
+    tail = readFileSync(jp, "utf8").trim().split("\n").map((l) => JSON.parse(l))
+      .filter((r) => String(r.key || "").includes(String(frame.seq)));
+  } catch (err) {
+    hop(8, "outcome journalled", false, `${jp} unreadable: ${err.message}`);
+  }
+  hop(8, "outcome journalled", tail.length > 0,
+    tail.length ? `${jp}\n` + tail.map((r) => JSON.stringify(r)).join("\n")
+                : `no row in ${jp} carries this event's key`);
+
+  // ── hop 9: the KPI ──────────────────────────────────────────────────────
+  // The goal loop measures against the CAPABILITY SENSORS, so the honest check
+  // is whether the surface this journey exercised is reachable by one at all.
+  let kpiDetail = "";
+  let kpiOk = false;
+  try {
+    const { buildSensorRegistry, reachableCapabilities } = await import("../../lib/kpi-sensors.mjs");
+    const reg = buildSensorRegistry({ agentRoot: AGENT_DIR, memberId: ME });
+    const reach = reachableCapabilities(AGENT_DIR);
+    const names = Object.keys(reg || {});
+    const escalationSensors = names.filter((n) => /escal|approv|decision/i.test(n));
+    kpiOk = escalationSensors.length > 0;
+    kpiDetail =
+      `${names.length} sensor(s) registered, ${reach ? reach.size : "n/a"} reachable capabilities\n` +
+      (escalationSensors.length
+        ? `governance sensors: ${escalationSensors.join(", ")}`
+        : "NO sensor measures the escalation/approval/decision lane — this journey moves no KPI");
+  } catch (err) {
+    kpiDetail = `kpi-sensors unavailable: ${err.message}`;
+  }
+  hop(9, "KPI — is this lane measurable at all?", kpiOk, kpiDetail +
+    "\n(NOTE: this journey moved no KPI number. `escalate` is journalled, not scored — " +
+    "the goal loop measures obligations, and this event bound to none.)");
+
+  report();
+  const failed = hops.find((h) => !h.ok);
+  process.exit(failed ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error("[journey] fatal:", err && err.stack ? err.stack : err);
+  process.exit(1);
+});