@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/execution/pipeline.mjs

@@ -0,0 +1,341 @@
+/**
+ * lib/execution/pipeline.mjs — the ONE call the inbox pipeline makes.
+ *
+ * `index.handleInboundEvent` decides and acts on one event, but it demands a
+ * `{candidate, verdict}` pair and an already-matched obligation. Nothing that
+ * actually holds inbound events has either: the daemon has flattened inbox items
+ * on disk, the channel adapters have their own item shape, the diagnostics
+ * modules have alert records, and the compiled plan sits unread in
+ * `config/plan.yaml`. This module closes that distance so a caller can hand over
+ * whatever it happens to have:
+ *
+ *   import { processInbound } from "../../lib/execution/pipeline.mjs";
+ *
+ *   const { results, stats } = await processInbound({
+ *     items,                      // inbox items | MessageEvents | raw rows | alerts
+ *     me: cfg.org.cohort.memberId,
+ *     agentRoot,
+ *     runtime,                    // emergencyStop / directive / staleness / budget
+ *     effects: defaultEffects({ agentRoot, react, me }),
+ *     log,
+ *   });
+ *
+ * What it adds over calling `handleInboundEvent` in a loop, all of which is
+ * wrong if a caller re-implements it:
+ *
+ *   **One history load per batch.** `loadHistory` scans the journal tail; doing
+ *   it per item turns a 200-event sweep into 200 file reads.
+ *
+ *   **In-batch dedupe, ping-pong and flood accounting.** The on-disk history is
+ *   a SNAPSHOT taken before the batch. Without an overlay, an event delivered
+ *   twice inside one sweep (the SSE push and the poll backstop converge — that
+ *   convergence is the design, per §6.1) passes the dedupe guard twice, and a
+ *   burst from one actor never trips the flood limit. The overlay makes the
+ *   guards behave as if each event had been processed alone, in order.
+ *
+ *   **Obligation binding.** The plan is read ONCE and every event is matched
+ *   against its REACT obligations, so `decide` gets the argument that lifts it
+ *   off the rung-1 cap — and an uncovered event produces the proposed obligation
+ *   §6.1 asks for, not just a complaint.
+ *
+ *   **Per-item isolation.** One malformed row cannot take a sweep down. It is
+ *   caught, logged as an error (never swallowed), counted, and the batch
+ *   continues.
+ *
+ * @module lib/execution/pipeline
+ */
+
+"use strict";
+
+import { handleInboundEvent } from "./index.mjs";
+import { intake } from "./intake.mjs";
+import { loadHistory, threadKey, dedupeKey } from "./journal.mjs";
+import { matchObligation, proposeReact, loadReactObligations } from "./match.mjs";
+import { tierOf, willAct } from "./disposition.mjs";
+
+/** Blank-safe string. */
+function s(v) {
+  return v == null ? "" : String(v);
+}
+
+/**
+ * Wrap a history snapshot so decisions taken EARLIER IN THIS BATCH count.
+ *
+ * The journal is appended by `drive` as it goes, but `loadHistory` already read
+ * its tail; re-reading per item would be correct and slow. This overlay is the
+ * cheap half: it tracks the same three facts the guards ask for and answers from
+ * the union of "on disk before the batch" and "decided during it".
+ *
+ * @param {object} base a `loadHistory` view
+ * @returns {object} the same interface, plus `note(decision, spoke)`
+ */
+export function batchHistory(base) {
+  const seen = new Set();
+  const chains = new Map();
+  const actors = new Map();
+  // Threads a human spoke in DURING this batch. The on-disk chain count for them
+  // is stale by definition, so it is masked rather than added to — otherwise a
+  // human re-entering a conversation mid-sweep would not unblock the agent until
+  // the next sweep, which is the exact bug the human-turn reset exists to stop.
+  const reset = new Set();
+
+  return {
+    seen: (key) => seen.has(s(key)) || (base ? base.seen(key) : false),
+    chainDepth: (tk) =>
+      (chains.get(s(tk)) || 0) + (reset.has(s(tk)) || !base ? 0 : base.chainDepth(tk)),
+    actorActivity: (a) => (actors.get(s(a)) || 0) + (base ? base.actorActivity(a) : 0),
+    failures: (k) => (base ? base.failures(k) : 0),
+    rows: base ? base.rows : [],
+    degraded: base ? !!base.degraded : true,
+    degradedReason: base ? base.degradedReason : "no history supplied",
+
+    /**
+     * A human spoke in this thread. Called BEFORE the decision that follows it,
+     * mirroring `handleInboundEvent`'s ordering.
+     */
+    humanTurn(tk) {
+      const k = s(tk);
+      if (!k) return;
+      reset.add(k);
+      chains.set(k, 0);
+    },
+
+    /** Fold one processed event back into the overlay. */
+    note(decision, spoke) {
+      if (!decision) return;
+      if (decision.key) seen.add(s(decision.key));
+      if (decision.actor) actors.set(s(decision.actor), (actors.get(s(decision.actor)) || 0) + 1);
+      // Only a turn where the agent actually SPOKE deepens a conversation —
+      // identical to the rule `loadHistory` applies to journal rows, and for the
+      // same reason: three ignores in a row must not gag the fourth message.
+      if (spoke === true && decision.thread) {
+        chains.set(s(decision.thread), (chains.get(s(decision.thread)) || 0) + 1);
+      }
+    },
+  };
+}
+
+/**
+ * Decide and act on ONE inbound artefact of any shape.
+ *
+ * @param {object} o
+ * @param {object} o.item                inbox item | MessageEvent | raw row | alert | {candidate,verdict}
+ * @param {string} [o.me]
+ * @param {string} [o.agentRoot]
+ * @param {object} [o.runtime]
+ * @param {object} [o.effects]
+ * @param {object} [o.history]           a `batchHistory` view (made here if absent)
+ * @param {object[]} [o.obligations]     REACT obligations from the compiled plan
+ * @param {Array} [o.manifest]           capability manifest
+ * @param {object} [o.facts]             delegation/authority facts for this item
+ * @param {boolean} [o.humanTurn]
+ * @param {number} [o.nowMs]
+ * @param {Function} [o.log]
+ * @param {string} [o.traceId]
+ * @returns {Promise<object>} { ok, origin, decision, effect, ref, spoke, degraded, error, obligationKey, proposed }
+ */
+export async function processOne(o = {}) {
+  const log = typeof o.log === "function" ? o.log : () => {};
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const nowIso = new Date(nowMs).toISOString();
+
+  const norm = intake(o.item, { me: o.me, now: nowIso, facts: o.facts, opts: o.intakeOpts });
+  for (const d of norm.degraded) log("warn", `[execution] intake degraded (${norm.origin}): ${d}`);
+
+  const tier = norm.verdict && norm.verdict.directed ? tierOf(norm.verdict.reason) : null;
+
+  // Bind the event to the plan. An unbindable event is not an error — it is the
+  // signal that the plan has a hole, and it is reported as one below.
+  const match = matchObligation({
+    candidate: norm.candidate,
+    verdict: norm.verdict,
+    plan: { obligations: Array.isArray(o.obligations) ? o.obligations : [] },
+    tier,
+  });
+  for (const line of match.why) log("debug", `[execution] match: ${line}`);
+
+  const history = o.history || batchHistory(loadHistory({ agentRoot: o.agentRoot, nowMs }));
+  if (o.humanTurn === true && norm.candidate && typeof history.humanTurn === "function") {
+    history.humanTurn(threadKey(norm.candidate));
+  }
+
+  const res = await handleInboundEvent({
+    candidate: norm.candidate,
+    verdict: norm.verdict,
+    me: o.me,
+    history,
+    runtime: o.runtime,
+    obligation: match.obligation,
+    need: o.need,
+    manifest: o.manifest,
+    facts: o.facts,
+    actorFloodLimit: o.actorFloodLimit,
+    effects: o.effects,
+    agentRoot: o.agentRoot,
+    nowMs,
+    traceId: o.traceId,
+    log,
+    humanTurn: o.humanTurn === true,
+  });
+
+  // Fold the intake's own degradations onto the decision so the journal row and
+  // the caller see one list rather than two.
+  if (res.decision && Array.isArray(res.decision.degraded) && norm.degraded.length) {
+    res.decision.degraded = res.decision.degraded.concat(norm.degraded.map((d) => `intake:${d}`));
+  }
+  history.note(res.decision, res.spoke);
+
+  // §6.1's other half: an event that was unmistakably mine and matched nothing
+  // proposes the obligation that WOULD have covered it.
+  let proposed = null;
+  if (!match.obligation && willAct(res.decision) && !match.suspended.length) {
+    const p = proposeReact({ candidate: norm.candidate, verdict: norm.verdict, tier });
+    if (p.obligation) {
+      proposed = p.obligation.key;
+      const fn = o.effects && typeof o.effects.proposeObligation === "function" ? o.effects.proposeObligation : null;
+      if (fn) {
+        try {
+          await fn({ obligation: p.obligation, decision: res.decision, candidate: norm.candidate });
+          log("info", `[execution] ${p.why}`);
+        } catch (err) {
+          log("error", `[execution] could not record the proposed obligation ${p.obligation.key}: ${err && err.message ? err.message : String(err)}`);
+        }
+      } else {
+        log("warn", `[execution] no proposeObligation effect wired — ${p.obligation.key} was derived but not recorded`);
+      }
+    } else {
+      log("warn", `[execution] uncovered event produced no proposable obligation: ${p.why}`);
+    }
+  }
+
+  return {
+    ...res,
+    origin: norm.origin,
+    intakeWhy: norm.why,
+    tier,
+    obligationKey: match.obligation ? match.obligation.key || null : null,
+    suspendedObligations: match.suspended.map((x) => x.key),
+    proposed,
+  };
+}
+
+/**
+ * Decide and act on a BATCH — the shape a sweep, an SSE drain or a cadence tick
+ * actually has.
+ *
+ * Items are processed IN ORDER. Order matters: the in-batch overlay means an
+ * earlier event's decision constrains a later one (dedupe, ping-pong, flood), so
+ * shuffling the batch would change the outcome. Callers should preserve ledger
+ * order, which every producer in the tree already does.
+ *
+ * @param {object} o  as {@link processOne}, with `items` instead of `item`, plus:
+ * @param {object[]} o.items
+ * @param {object[]} [o.obligations]  pre-loaded; read from config/plan.yaml when absent
+ * @param {boolean}  [o.loadPlan]     set false to skip the plan read entirely
+ * @param {Function} [o.factsFor]     (norm, item) => facts, per item
+ * @param {Function} [o.isHumanTurn]  (item) => boolean
+ * @returns {Promise<{results:object[], stats:object}>}
+ */
+export async function processInbound(o = {}) {
+  const log = typeof o.log === "function" ? o.log : () => {};
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const items = Array.isArray(o.items) ? o.items : [];
+
+  const stats = {
+    total: items.length,
+    processed: 0,
+    acted: 0,
+    ignored: 0,
+    failed: 0,
+    byDisposition: {},
+    bySurface: {},
+    byReason: {},
+    uncovered: 0,
+    proposed: [],
+    degraded: [],
+  };
+  if (items.length === 0) return { results: [], stats };
+
+  // ── the plan, read once ──────────────────────────────────────────────────
+  let obligations = Array.isArray(o.obligations) ? o.obligations : null;
+  if (!obligations && o.loadPlan !== false) {
+    const loaded = await loadReactObligations(o.agentRoot);
+    obligations = loaded.obligations;
+    if (loaded.degraded) {
+      // NEVER SILENT: with no plan every event reads as uncovered and the whole
+      // reactive lane is pinned at rung ≤1. That is a legitimate state for an
+      // un-adopted agent, but the operator has to be able to see it.
+      stats.degraded.push(`plan_unavailable:${loaded.reason}`);
+      log("warn", `[execution] no compiled REACT obligations (${loaded.reason}) — every event will route at rung ≤1`);
+    } else if (obligations.length === 0) {
+      stats.degraded.push("plan_has_no_react_obligations");
+      log("warn", "[execution] config/plan.yaml has no REACT obligations — the reactive lane is uncovered by construction");
+    }
+  }
+  if (!obligations) obligations = [];
+
+  // ── the journal tail, read once, then kept live for the batch ────────────
+  const base = o.history || loadHistory({ agentRoot: o.agentRoot, nowMs });
+  if (base && base.degraded) {
+    stats.degraded.push(`history_degraded:${base.degradedReason || "unknown"}`);
+    log("warn", `[execution] journal history degraded (${base.degradedReason || "unknown"}) — dedupe/ping-pong guards are weakened`);
+  }
+  const history = batchHistory(base);
+
+  const results = [];
+  for (const item of items) {
+    let res;
+    try {
+      const facts = typeof o.factsFor === "function" ? o.factsFor(item) : o.facts;
+      res = await processOne({
+        ...o,
+        item,
+        facts,
+        history,
+        obligations,
+        nowMs,
+        humanTurn: typeof o.isHumanTurn === "function" ? o.isHumanTurn(item) === true : o.humanTurn === true,
+      });
+      stats.processed += 1;
+    } catch (err) {
+      // A per-item throw is a bug somewhere below; it must not cost the caller
+      // the other 199 events. Loud, counted, and the batch continues.
+      const msg = err && err.message ? err.message : String(err);
+      stats.failed += 1;
+      log("error", `[execution] item threw and was skipped: ${msg}`);
+      results.push({ ok: false, error: msg, decision: null, origin: null });
+      continue;
+    }
+
+    results.push(res);
+    const d = res.decision || {};
+    const disp = s(d.disposition) || "unknown";
+    stats.byDisposition[disp] = (stats.byDisposition[disp] || 0) + 1;
+    const surf = s(d.surface) || "unknown";
+    stats.bySurface[surf] = (stats.bySurface[surf] || 0) + 1;
+    const reason = s(d.reason) || "unknown";
+    stats.byReason[reason] = (stats.byReason[reason] || 0) + 1;
+    if (willAct(d)) stats.acted += 1;
+    else stats.ignored += 1;
+    if (res.ok === false) stats.failed += 1;
+    if (!res.obligationKey && willAct(d)) stats.uncovered += 1;
+    if (res.proposed) stats.proposed.push(res.proposed);
+  }
+
+  const summary = Object.entries(stats.byDisposition)
+    .map(([k, v]) => `${k}×${v}`)
+    .sort()
+    .join(", ");
+  log(
+    "info",
+    `[execution] ${stats.processed}/${stats.total} event(s): ${summary || "none"}` +
+      (stats.uncovered ? ` · ${stats.uncovered} uncovered by the plan` : "") +
+      (stats.failed ? ` · ${stats.failed} failed` : ""),
+  );
+
+  return { results, stats };
+}
+
+export { dedupeKey, threadKey };
+
+export default { processInbound, processOne, batchHistory };