@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/execution/effects.mjs

@@ -0,0 +1,340 @@
+/**
+ * lib/execution/effects.mjs — the real machinery behind each disposition.
+ *
+ * `drive.mjs` sequences; this module supplies. It is the only file in
+ * `lib/execution/` that touches the network or the filesystem, which is what
+ * keeps the decision ladder and the driver testable with plain fakes.
+ *
+ * Every effect here is a THIN adapter onto machinery that already exists. This
+ * repo has repeatedly grown a second mechanism next to a working one, so the
+ * rule for this file is: if there is an existing module that does the thing,
+ * call it, and if there isn't, write to the on-disk format an existing consumer
+ * already reads.
+ *
+ *   react           → handed to the caller's responder/session spawner. NOT
+ *                     reimplemented here: the dispatcher owns session spawning
+ *                     and prompt construction, and a second spawner would be
+ *                     exactly the duplication this codebase keeps suffering.
+ *   schedule        → appends a queue item to `state/queues/inbound.yaml` in the
+ *                     format `lib/backlog.mjs parseQueueItems` already parses and
+ *                     the daemon's 2-minute backlog sweep already dispatches. No
+ *                     dispatcher edit, no new transport.
+ *   delegate        → `lib/org/handoff.mjs sendHandoff` (the A2A envelope path).
+ *   escalate        → `escalation.create` via `lib/org/client.mjs call`, which is
+ *                     the first real writer for the escalation lane.
+ *   requestApproval → `lib/org/approvals.mjs requestApproval` + `awaitDecision`,
+ *                     including the `payloadHash` single-use binding.
+ *   arbitrate       → `lib/org/leases.mjs preSendArbitration` (3s fail-open).
+ *   reportDrift     → append to `state/plan/drift.jsonl`, mirrored best-effort.
+ *   propose         → append to `state/plan/proposed.jsonl` (the observe-only sink).
+ *
+ * Every function returns `{ok, ref, error}` rather than throwing, matching the
+ * shape `drive.runEffect` normalises to.
+ *
+ * @module lib/execution/effects
+ */
+
+"use strict";
+
+import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { appendJsonl } from "../fs-atomic.mjs";
+import { yamlScalar } from "../channels/inbox-item.mjs";
+
+/** Where scheduled work lands — a queue file the daemon's sweep already reads. */
+export const INBOUND_QUEUE_REL = "state/queues/inbound.yaml";
+/** Where drift records land, mirrored by the reconciler. */
+export const DRIFT_REL = "state/plan/drift.jsonl";
+/** Where observe-only proposals land instead of becoming work (§5.10). */
+export const PROPOSED_REL = "state/plan/proposed.jsonl";
+
+/** Map a directedness tier + surface latency onto the queue's priority vocabulary. */
+function priorityFor(decision) {
+  if (decision.reason === "budget_exhausted" || decision.reason === "actor_flood") return "normal";
+  if (decision.tier === "T0") return "high";
+  return "normal";
+}
+
+/**
+ * A stable, human-legible queue item id. Derived from the dedupe key so a
+ * redelivery that somehow slips past the journal guard collides on the id rather
+ * than creating a second item.
+ */
+function queueItemId(decision) {
+  const raw = String(decision.key || `${decision.family}.${decision.kind}`);
+  return `inb-${raw.replace(/[^A-Za-z0-9._#:@-]/g, "-").slice(0, 80)}`;
+}
+
+/**
+ * Append one item to `state/queues/inbound.yaml`, creating the file with its
+ * header when absent. Idempotent on the item id: an id already present in the
+ * file is a no-op, so a retry of the same decision cannot double-queue.
+ *
+ * @param {object} decision
+ * @param {object} [o] { agentRoot, nowMs }
+ * @returns {{ok:boolean, ref:object|null, error:string|null}}
+ */
+export function scheduleToQueue(decision, o = {}) {
+  const root = resolveAgentRoot(o.agentRoot);
+  const path = join(root, INBOUND_QUEUE_REL);
+  const id = queueItemId(decision);
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    if (!existsSync(path)) {
+      writeFileSync(
+        path,
+        [
+          "queue: inbound",
+          "description: >-",
+          "  Directed inbound events the execution ladder queued rather than answered",
+          "  immediately. Written by lib/execution/effects.mjs; consumed by the daemon's",
+          "  backlog sweep. Each item carries the decision that produced it.",
+          "items:",
+          "",
+        ].join("\n"),
+      );
+    } else {
+      const body = readFileSync(path, "utf-8");
+      // Anchor on a whole `id:` key at line start so a `correlation_id:` can
+      // never be mistaken for a match — the same trap lib/backlog.mjs documents.
+      const re = new RegExp(`^\\s*-?\\s*"?id"?:\\s*["']?${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']?\\s*$`, "m");
+      if (re.test(body)) {
+        return { ok: true, ref: { id, path, deduped: true }, error: null };
+      }
+    }
+
+    const title = `${decision.surface || "inbound"}: ${decision.reason || "queued"}`;
+    const nextAction =
+      decision.disposition === "schedule" && decision.surface
+        ? `Handle the ${decision.surface} event ${decision.key} at rung ${decision.rung ?? "?"}`
+        : `Handle ${decision.key}`;
+
+    const lines = [
+      `  - id: ${yamlScalar(id)}`,
+      `    title: ${yamlScalar(title)}`,
+      "    status: open",
+      `    priority: ${priorityFor(decision)}`,
+      `    next_action: ${yamlScalar(nextAction)}`,
+      `    created: ${yamlScalar(new Date(nowMs).toISOString())}`,
+      `    surface: ${yamlScalar(decision.surface || "")}`,
+      `    event_key: ${yamlScalar(decision.key || "")}`,
+      `    thread: ${yamlScalar(decision.thread || "")}`,
+      `    rung: ${Number.isFinite(decision.rung) ? decision.rung : "null"}`,
+      `    obligation_key: ${yamlScalar(decision.obligationKey || "")}`,
+      // The reasoning travels WITH the work. A queue item whose provenance is a
+      // mystery is a queue item nobody trusts enough to action.
+      `    why: ${yamlScalar((decision.why || []).join(" | "))}`,
+      "",
+    ];
+    appendFileSync(path, lines.join("\n"));
+    return { ok: true, ref: { id, path, deduped: false }, error: null };
+  } catch (err) {
+    return { ok: false, ref: null, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/** Append a drift record locally. Mirroring to hq is the reconciler's job. */
+export function writeDrift(drift, o = {}) {
+  const root = resolveAgentRoot(o.agentRoot);
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const ok = appendJsonl(join(root, DRIFT_REL), {
+    at: new Date(nowMs).toISOString(),
+    kind: drift && drift.kind ? String(drift.kind) : "unknown",
+    key: (drift && drift.key) || (o.decision && o.decision.obligationKey) || null,
+    detail: (drift && drift.detail) || null,
+    source: "execution-ladder",
+  });
+  return { ok, ref: { kind: drift && drift.kind }, error: ok ? null : "drift append failed" };
+}
+
+/** Append an observe-only proposal instead of doing the work. */
+export function writeProposal(decision, o = {}) {
+  const root = resolveAgentRoot(o.agentRoot);
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const ok = appendJsonl(join(root, PROPOSED_REL), {
+    at: new Date(nowMs).toISOString(),
+    source: "execution-ladder",
+    key: decision.key || null,
+    surface: decision.surface || null,
+    disposition: decision.disposition,
+    reason: decision.reason,
+    rung: decision.rung ?? null,
+    obligationKey: decision.obligationKey || null,
+    why: decision.why || [],
+  });
+  return { ok, ref: { proposed: true }, error: ok ? null : "proposal append failed" };
+}
+
+/**
+ * Append a PROPOSED REACT obligation for an event the compiled plan did not
+ * cover (§6.1: "emit `PlanDrift{uncovered_event}` **and** a proposed REACT
+ * obligation — this is how the plan learns instead of ossifying").
+ *
+ * Lands in the same file as observe-only proposals, tagged `type:"obligation"`,
+ * so a human reviewing the window sees one list: what the agent would have done,
+ * and what the plan is missing.
+ *
+ * @param {object} obligation a schema-valid proposed obligation
+ * @param {object} [o] { agentRoot, nowMs, decision }
+ */
+export function writeObligationProposal(obligation, o = {}) {
+  const root = resolveAgentRoot(o.agentRoot);
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  if (!obligation || typeof obligation !== "object" || !obligation.key) {
+    return { ok: false, ref: null, error: "obligation proposal missing a key" };
+  }
+  const decision = o.decision || {};
+  const ok = appendJsonl(join(root, PROPOSED_REL), {
+    at: new Date(nowMs).toISOString(),
+    source: "execution-ladder",
+    type: "obligation",
+    key: obligation.key,
+    obligation,
+    from_event: {
+      key: decision.key || null,
+      surface: decision.surface || null,
+      tier: decision.tier || null,
+      reason: decision.reason || null,
+    },
+  });
+  return { ok, ref: { key: obligation.key }, error: ok ? null : "obligation proposal append failed" };
+}
+
+/**
+ * Build the default effect set.
+ *
+ * `react` is deliberately NOT defaulted to a session spawn: the dispatcher owns
+ * spawning, and this module must not grow a second spawner. The caller wires it
+ * (see the wiring notes) and gets a loud `react_effect_missing` degradation if
+ * it forgets — which is the correct failure, because a missing responder is a
+ * real outage and must not look like a successful no-op.
+ *
+ * @param {object} o {
+ *   agentRoot, nowMs, client, base, token, me, principal,
+ *   react            // (args) => Promise<{ok, ref}>  — REQUIRED for react_now
+ *   escalationTarget // member id / "principal"
+ * }
+ * @returns {object} the effects object `drive` consumes
+ */
+export function defaultEffects(o = {}) {
+  const agentRoot = resolveAgentRoot(o.agentRoot);
+  const common = { agentRoot, nowMs: o.nowMs };
+
+  return {
+    react: typeof o.react === "function" ? o.react : undefined,
+
+    schedule: async ({ decision }) => scheduleToQueue(decision, common),
+
+    delegate: async ({ decision, candidate }) => {
+      const { sendHandoff } = await import("../org/handoff.mjs");
+      const r = await sendHandoff({
+        agentRoot,
+        from: o.me || "",
+        to: decision.delegateTo,
+        intent: `${decision.surface || "inbound"} event ${decision.key}: ${decision.reason}`,
+        payload: {
+          event_key: decision.key,
+          surface: decision.surface,
+          thread: decision.thread,
+          why: decision.why,
+          entityId: candidate ? candidate.entityId : null,
+        },
+        ...(o.transport ? { transport: o.transport } : {}),
+      });
+      return { ok: r && r.ok !== false, ref: r, error: r && r.error ? String(r.error) : null };
+    },
+
+    escalate: async ({ decision }) => {
+      const { call } = await import("../org/client.mjs");
+      const r = await call(
+        "escalation.create",
+        {
+          // No message bodies, ever — ids and reasons only. `assertRedactionSafe`
+          // bans addresses and content, not member ids.
+          summary: `${decision.surface || "inbound"}: ${decision.reason}`,
+          waitingOnMemberId: decision.escalateTo || o.escalationTarget || undefined,
+          options: (decision.options || []).map((label) => ({ label: String(label) })),
+          context: {
+            event_key: decision.key,
+            surface: decision.surface,
+            thread: decision.thread,
+            obligation_key: decision.obligationKey || null,
+            why: decision.why,
+          },
+        },
+        { agentRoot, client: o.client, base: o.base, token: o.token },
+      );
+      return { ok: !!r && r.ok !== false, ref: r, error: r && r.error ? String(r.error) : null };
+    },
+
+    requestApproval: async ({ decision, classes }) => {
+      const { requestApproval, awaitDecision } = await import("../org/approvals.mjs");
+      const asked = await requestApproval({
+        agentRoot,
+        action: decision.action && decision.action.method ? decision.action.method : decision.surface,
+        classification: classes,
+        payload: {
+          event_key: decision.key,
+          surface: decision.surface,
+          thread: decision.thread,
+          rung: decision.rung,
+        },
+        summary: `${decision.surface}: ${decision.reason}`,
+        client: o.client,
+        base: o.base,
+        token: o.token,
+      });
+      if (!asked || asked.ok === false) {
+        return { ok: false, ref: asked, error: (asked && asked.error) || "approval request failed" };
+      }
+      const id = asked.id || (asked.approval && asked.approval.id);
+      if (!id) return { ok: true, ref: { granted: undefined, asked }, error: null };
+      const decided = await awaitDecision(id, o.approvalTimeoutMs, {
+        agentRoot,
+        client: o.client,
+        base: o.base,
+        token: o.token,
+      });
+      const status = String((decided && (decided.status || decided.state)) || "").toLowerCase();
+      const granted = status === "approved" ? true : status === "rejected" || status === "denied" ? false : undefined;
+      return { ok: true, ref: { granted, id, status, decided }, error: null };
+    },
+
+    arbitrate: async ({ decision, candidate, resource }) => {
+      const { preSendArbitration } = await import("../org/leases.mjs");
+      const ids = (candidate && candidate.ids) || {};
+      const r = await preSendArbitration({
+        platform: "cohort",
+        channel: ids.channelId || resource || decision.thread || "",
+        thread: ids.threadRootId || ids.messageId || "",
+        agentRoot,
+        client: o.client,
+        base: o.base,
+        token: o.token,
+      });
+      return { ok: true, ref: r, error: null };
+    },
+
+    reportDrift: async ({ drift, decision }) => writeDrift(drift, { ...common, decision }),
+
+    propose: async ({ decision }) => writeProposal(decision, common),
+
+    proposeObligation: async ({ obligation, decision }) =>
+      writeObligationProposal(obligation, { ...common, decision }),
+  };
+}
+
+export default {
+  defaultEffects,
+  scheduleToQueue,
+  writeDrift,
+  writeProposal,
+  writeObligationProposal,
+  INBOUND_QUEUE_REL,
+  DRIFT_REL,
+  PROPOSED_REL,
+};

package/lib/execution/effects.test.mjs

@@ -0,0 +1,193 @@
+/**
+ * effects.test.mjs — the on-disk side effects, and the format contract with the
+ * machinery that already consumes them.
+ * Run: node --test lib/execution/effects.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { parseQueueItems } from "../backlog.mjs";
+import {
+  scheduleToQueue,
+  writeDrift,
+  writeProposal,
+  defaultEffects,
+  INBOUND_QUEUE_REL,
+  DRIFT_REL,
+  PROPOSED_REL,
+} from "./effects.mjs";
+
+const NOW = Date.parse("2026-08-11T12:00:00Z");
+function tmp() { return mkdtempSync(join(tmpdir(), "exec-effects-")); }
+
+const DECISION = {
+  key: "board.item.assigned#42",
+  thread: "board:-:t1",
+  surface: "task_assigned",
+  disposition: "schedule",
+  reason: "not_respondable",
+  tier: "T0",
+  rung: 3,
+  obligationKey: "react.task_assigned",
+  why: ["directed: assignee on task_assigned (tier T0)", "task_assigned is not a conversational surface"],
+};
+
+test("a scheduled item is parseable by the EXISTING backlog parser", () => {
+  // The whole reuse claim rests on this: the daemon's 2-minute sweep already
+  // reads this format, so scheduling needs no dispatcher change.
+  const root = tmp();
+  try {
+    const r = scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
+    assert.equal(r.ok, true);
+    const body = readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8");
+    const items = parseQueueItems(body, "inbound.yaml");
+    assert.equal(items.length, 1);
+    assert.equal(items[0].status, "open");
+    assert.equal(items[0].priority, "high", "a T0 event is high priority");
+    assert.ok(items[0].id, "the id must survive — the claim subsystem is gated on it");
+    assert.ok(items[0].title.includes("task_assigned"));
+    assert.ok(items[0].next_action);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("the reasoning travels WITH the queued work", () => {
+  const root = tmp();
+  try {
+    scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
+    const body = readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8");
+    assert.match(body, /why:/);
+    assert.match(body, /tier T0/, "a queue item whose provenance is a mystery is one nobody actions");
+    assert.match(body, /event_key: "board.item.assigned#42"/);
+    assert.match(body, /obligation_key: "react.task_assigned"/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("scheduling the same decision twice does NOT double-queue", () => {
+  const root = tmp();
+  try {
+    const a = scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
+    const b = scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
+    assert.equal(a.ref.deduped, false);
+    assert.equal(b.ref.deduped, true);
+    const items = parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q");
+    assert.equal(items.length, 1);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("distinct events append distinct items", () => {
+  const root = tmp();
+  try {
+    scheduleToQueue(DECISION, { agentRoot: root, nowMs: NOW });
+    scheduleToQueue({ ...DECISION, key: "board.item.assigned#43" }, { agentRoot: root, nowMs: NOW });
+    const items = parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q");
+    assert.equal(items.length, 2);
+    assert.notEqual(items[0].id, items[1].id);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("the dedupe check anchors on a whole `id` key, not a substring", () => {
+  const root = tmp();
+  try {
+    // `#4` must not be seen as already present because `#42` is.
+    scheduleToQueue({ ...DECISION, key: "board.item.assigned#42" }, { agentRoot: root, nowMs: NOW });
+    const r = scheduleToQueue({ ...DECISION, key: "board.item.assigned#4" }, { agentRoot: root, nowMs: NOW });
+    assert.equal(r.ref.deduped, false, "a prefix collision must not swallow a distinct event");
+    assert.equal(parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q").length, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("a hostile surface/reason cannot inject YAML lines", () => {
+  const root = tmp();
+  try {
+    scheduleToQueue(
+      { ...DECISION, key: "k1", surface: 'x"\nstatus: blocked\npriority: "critical', why: ["a\nb"] },
+      { agentRoot: root, nowMs: NOW },
+    );
+    const items = parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q");
+    assert.equal(items.length, 1, "the injected `status: blocked` must not become a real key");
+    assert.equal(items[0].status, "open");
+    assert.equal(items[0].priority, "high");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("a lower-tier or downgraded event queues at normal priority", () => {
+  const root = tmp();
+  try {
+    scheduleToQueue({ ...DECISION, key: "k1", tier: "T1" }, { agentRoot: root, nowMs: NOW });
+    scheduleToQueue({ ...DECISION, key: "k2", reason: "actor_flood" }, { agentRoot: root, nowMs: NOW });
+    const items = parseQueueItems(readFileSync(join(root, INBOUND_QUEUE_REL), "utf-8"), "q");
+    assert.deepEqual(items.map((i) => i.priority), ["normal", "normal"]);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("an unwritable root is reported, not thrown", () => {
+  const r = scheduleToQueue(DECISION, { agentRoot: "/proc/nonexistent-cannot-create", nowMs: NOW });
+  assert.equal(r.ok, false);
+  assert.ok(r.error, "the caller must be told the work was not queued");
+});
+
+test("drift and proposals are appended as JSONL with their provenance", () => {
+  const root = tmp();
+  try {
+    writeDrift({ kind: "uncovered_event", detail: { surface: "dm" } }, { agentRoot: root, nowMs: NOW, decision: DECISION });
+    const drift = JSON.parse(readFileSync(join(root, DRIFT_REL), "utf-8").trim());
+    assert.equal(drift.kind, "uncovered_event");
+    assert.equal(drift.key, "react.task_assigned");
+    assert.equal(drift.source, "execution-ladder");
+
+    writeProposal({ ...DECISION, disposition: "react_now" }, { agentRoot: root, nowMs: NOW });
+    const prop = JSON.parse(readFileSync(join(root, PROPOSED_REL), "utf-8").trim());
+    assert.equal(prop.disposition, "react_now");
+    assert.deepEqual(prop.why, DECISION.why, "the observe-only window is only readable if the reasoning is kept");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("writeDrift tolerates a malformed drift record", () => {
+  const root = tmp();
+  try {
+    assert.equal(writeDrift(null, { agentRoot: root, nowMs: NOW }).ok, true);
+    const row = JSON.parse(readFileSync(join(root, DRIFT_REL), "utf-8").trim());
+    assert.equal(row.kind, "unknown");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("defaultEffects wires every effect EXCEPT react, which the caller must supply", () => {
+  const root = tmp();
+  try {
+    const e = defaultEffects({ agentRoot: root });
+    for (const name of ["schedule", "delegate", "escalate", "requestApproval", "arbitrate", "reportDrift", "propose"]) {
+      assert.equal(typeof e[name], "function", `${name} should be wired`);
+    }
+    // `react` is deliberately absent: the dispatcher owns session spawning and
+    // this module must not grow a second spawner. A caller that forgets gets a
+    // loud `react_effect_missing`, which is the correct failure.
+    assert.equal(e.react, undefined);
+    assert.equal(typeof defaultEffects({ agentRoot: root, react: async () => ({ ok: true }) }).react, "function");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("the default schedule effect writes through to the queue", async () => {
+  const root = tmp();
+  try {
+    const e = defaultEffects({ agentRoot: root, nowMs: NOW });
+    const r = await e.schedule({ decision: DECISION });
+    assert.equal(r.ok, true);
+    assert.ok(existsSync(join(root, INBOUND_QUEUE_REL)));
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("the default propose + reportDrift effects write through", async () => {
+  const root = tmp();
+  try {
+    const e = defaultEffects({ agentRoot: root, nowMs: NOW });
+    assert.equal((await e.propose({ decision: DECISION })).ok, true);
+    assert.equal((await e.reportDrift({ drift: { kind: "budget_breach" }, decision: DECISION })).ok, true);
+    assert.ok(existsSync(join(root, PROPOSED_REL)));
+    assert.ok(existsSync(join(root, DRIFT_REL)));
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});

package/lib/execution/index.mjs

@@ -0,0 +1,152 @@
+/**
+ * lib/execution/index.mjs — the one function the inbound pipeline calls.
+ *
+ * The inbound layer (`lib/org/inbound/`) produces "here is an event, and here is
+ * whether it is yours". Everything after that — should we answer, queue, hand
+ * off, ask, or drop; how much machinery it deserves; what gates it must clear;
+ * and writing down why — is this package, behind one call:
+ *
+ *   import { handleInboundEvent } from "../execution/index.mjs";
+ *
+ *   const result = await handleInboundEvent({
+ *     candidate,          // directedness.classifyEvent(ev)
+ *     verdict,            // directedness.resolveDirected(candidate, me, facts)
+ *     me,                 // my member id
+ *     runtime,            // emergencyStop / directive / staleness / budget
+ *     effects,            // defaultEffects({ agentRoot, react, ... })
+ *     agentRoot,
+ *   });
+ *
+ * `result.decision.why` is the ordered, plain-English reasoning; `result.effect`
+ * is what actually happened. Both are already on disk in
+ * `state/execution/journal.jsonl` by the time this returns.
+ *
+ * The history view is loaded HERE rather than in `decide` so that the decision
+ * function stays pure and the (bounded, tail-only) journal read happens once per
+ * event. A caller batching a burst of events can load the history itself and
+ * pass it in, which is what the sweep does.
+ *
+ * @module lib/execution
+ */
+
+"use strict";
+
+import { decide, willAct } from "./disposition.mjs";
+import { drive } from "./drive.mjs";
+import { loadHistory, recordHumanTurn, threadKey } from "./journal.mjs";
+
+export { decide, willAct } from "./disposition.mjs";
+export { drive, EFFECT_FOR } from "./drive.mjs";
+export { routeRung, baseRung, RUNGS } from "./route.mjs";
+export {
+  policyFor,
+  SURFACE_POLICY,
+  ORG_SURFACE_POLICY,
+  EXTENDED_SURFACE_POLICY,
+  EXTENDED_SURFACE_NAMES,
+  DISPOSITIONS,
+  uncoveredSurfaces,
+  orphanPolicies,
+  adoptedExtendedSurfaces,
+} from "./surface-policy.mjs";
+export {
+  intake,
+  fromPair,
+  fromMessageEvent,
+  fromInboxItem,
+  fromChannelEvent,
+  fromAlert,
+  fromRawEvent,
+  parseRawRef,
+} from "./intake.mjs";
+export {
+  matchObligation,
+  proposeReact,
+  reactObligations,
+  loadReactObligations,
+} from "./match.mjs";
+export { processInbound, processOne, batchHistory } from "./pipeline.mjs";
+export {
+  loadHistory,
+  recordDecision,
+  recordOutcome,
+  recordHumanTurn,
+  dedupeKey,
+  threadKey,
+  journalPath,
+} from "./journal.mjs";
+export { defaultEffects, scheduleToQueue, writeDrift, writeProposal } from "./effects.mjs";
+
+/**
+ * Decide and act on one inbound event.
+ *
+ * @param {object} o
+ * @param {object} o.candidate
+ * @param {object} o.verdict
+ * @param {string} [o.me]
+ * @param {object} [o.history]  pre-loaded (a batch caller); loaded here if absent
+ * @param {object} [o.runtime]
+ * @param {object|null} [o.obligation]
+ * @param {object} [o.need]
+ * @param {Array}  [o.manifest]
+ * @param {object} [o.facts]
+ * @param {object} [o.effects]
+ * @param {string} [o.agentRoot]
+ * @param {number} [o.nowMs]
+ * @param {string} [o.traceId]
+ * @param {Function} [o.log]
+ * @param {boolean} [o.humanTurn] the actor is a human — resets the ping-pong
+ *        counter for this thread BEFORE the decision is taken, so a human
+ *        re-entering a conversation immediately unblocks the agent.
+ * @returns {Promise<{decision:object, ok:boolean, effect:string|null, ref:any, spoke:boolean, degraded:string[], error:string|null}>}
+ */
+export async function handleInboundEvent(o = {}) {
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+
+  // A human turn resets the chain counter first. Doing this before the history
+  // load (rather than after the decision) is what makes "human replies, agent
+  // may speak again" work on the very next event instead of the one after.
+  if (o.humanTurn === true && o.candidate) {
+    recordHumanTurn(
+      {
+        thread: threadKey(o.candidate),
+        actor: String(o.candidate.actor || ""),
+        surface: o.verdict ? o.verdict.surface : null,
+      },
+      { agentRoot: o.agentRoot, nowMs, traceId: o.traceId },
+    );
+  }
+
+  const history =
+    o.history || loadHistory({ agentRoot: o.agentRoot, nowMs, path: o.journalPath, rows: o.rows });
+
+  const decision = decide({
+    candidate: o.candidate,
+    verdict: o.verdict,
+    me: o.me,
+    history,
+    runtime: o.runtime,
+    obligation: o.obligation,
+    need: o.need,
+    manifest: o.manifest,
+    facts: o.facts,
+    policy: o.policy,
+    actorFloodLimit: o.actorFloodLimit,
+    nowMs,
+  });
+
+  const res = await drive(decision, {
+    candidate: o.candidate,
+    effects: o.effects,
+    agentRoot: o.agentRoot,
+    nowMs,
+    traceId: o.traceId,
+    log: o.log,
+    append: o.append,
+    journalPath: o.journalPath,
+  });
+
+  return { ...res, decision };
+}
+
+export default { handleInboundEvent, decide, drive, willAct };