@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/session/ask-ledger.mjs

@@ -0,0 +1,271 @@
+/**
+ * lib/session/ask-ledger.mjs — the ask ledger, owned by the lane that ACCEPTS
+ * the ask rather than by the lane that dispatches it.
+ *
+ * ── THE THIRTEEN-DAY BLACKOUT THIS EXISTS FOR ────────────────────────────────
+ *
+ * Every automatic board row for an inbound ask was written from ONE place:
+ * `scripts/daemon/agent-daemon.mjs#answerItem`, which calls `trackWorkStep` at
+ * accepted / working / done / failed. `answerItem` is reachable only from
+ * `pollService`, and on 2026-09-08 `de35690` put a gate in front of
+ * `pollService`:
+ *
+ *     const fd = _frontDoorGate.check(svc.name);
+ *     if (!fd.dispatch) return 0;            // ← the live session owns intake
+ *
+ * That gate is correct — two lanes answering the same room in the seat's voice
+ * is the failure it was written for. But the ledger rode along inside the lane
+ * it switched off. From the moment a seat's front-door session came up, the
+ * daemon stopped dispatching, `answerItem` stopped running, and with it every
+ * `accepted`, every `working`, every `done` and every channel tag. The last
+ * automatic row in the org's ledger is 2026-09-10; the last `item.tagged` event
+ * is the same day. Boards kept moving the whole time (295 `item.moved`, 8457
+ * `item.commented`) because the SESSION works boards through its tools — so
+ * nothing looked broken. The ask path was simply gone.
+ *
+ * The session lane had the capability all along: `maestro board track <id>
+ * --stage accepted` exists, and `plugins/maestro-skills/skills/inbound-triage.md`
+ * tells the session to run it. Thirteen days and several thousand tool calls
+ * produced zero rows. That is the whole lesson, and hq's own
+ * `llm-responder/responder.ts` had already written it down:
+ *
+ *     "the failure it exists for is an agent that goes quiet, and an agent that
+ *      has gone quiet is exactly the one that will not remember to file a task
+ *      about it."
+ *
+ * ── THE RULE THIS MODULE ENFORCES ────────────────────────────────────────────
+ *
+ * A lane that ACCEPTS an ask owns its ledger, and the acceptance is what writes
+ * it — not a later dispatch step that some future gate can stand down. The two
+ * lanes now write from their two acceptance points:
+ *
+ *   daemon lane   `answerItem`           (unchanged — it IS its own acceptance)
+ *   session lane  `maestro inbox claim`  (this module, via lib/cli/inbox.mjs)
+ *                 `… reply | done | defer`
+ *
+ * Both reach the SAME `lib/org/work-ledger.mjs#recordWorkStep`, which reaches
+ * the same `board.track` wire method and the same `hq/src/server/work/
+ * threshold.ts` gate. There is still exactly one implementation of "does this
+ * ask deserve a row"; this adds a second CALLER, not a second answer. A future
+ * step-back in either lane cannot silence the ledger, because it can only stand
+ * down a lane that is no longer accepting anything.
+ *
+ * ── WHY THE STAGES ARE WHAT THEY ARE ─────────────────────────────────────────
+ *
+ * `deferred` means "this could not be answered inside the turn". At claim time
+ * nobody knows that yet, and claiming is not evidence of it — the session
+ * claims a one-line question and a week of work identically. So the session
+ * lane reports `deferred:false` and lets the server's gate judge from the text,
+ * which is the same verdict the daemon's quick-reply path gets. A chatty claim
+ * is refused `answerable-in-turn` and mints nothing; a work ask is tracked
+ * `asks-for-work`. Neither lane decides; the shared gate does.
+ *
+ * `claim` chains `accepted` → `working` for the reason the daemon does: `running`
+ * is the only column hq's "On now" banner reads, and a row parked in `triage` is
+ * a row that surface will never show. A session claim IS the assertion that the
+ * seat is on it now — that is what the `.dispatched` marker and the 20-minute
+ * reopen sweep already mean.
+ *
+ * A REPLY closes the row, because in this lane the reply is the delivery. `done`
+ * after a reply would say the same thing twice, so it is skipped; `done` without
+ * one closes the row itself. `defer` parks it in `blocked` with the reason,
+ * which is the truthful reading of an item nobody is working right now.
+ *
+ * ── WHAT THIS LANE STILL DOES NOT COVER ─────────────────────────────────────
+ *
+ * Stated here rather than discovered later, and pinned by the negative cases in
+ * `lib/cli/inbox-ledger-wiring.test.mjs`:
+ *
+ * 1. A WORK-SHAPED BROADCAST OPENS NO ROW. `lib/org/work-ledger.mjs` reports
+ *    `directed` from `priority_signals.mentions_agent`, which
+ *    `lib/org/inbound/project.mjs` sets only for the reasons `mention`,
+ *    `named`, `dm` and `direct`. A post addressed to a room — "Everyone, please
+ *    review the binder by Friday" — carries none of them, and hq's gate refuses
+ *    it `not-directed` (`src/server/work/threshold.ts`). Claiming it does not
+ *    change that: the gate judges the MESSAGE's addressing, not the claim.
+ *    That is the same addressing gap that leaves a broadcast unanswered in the
+ *    first place (`lib/org/inbound/directedness.mjs` has no broadcast concept
+ *    at all), and it closes in one place — when the ingest layer learns a
+ *    `collective` verdict and `project.mjs` counts it as a genuine address.
+ *    When it does, the negative test here goes red and becomes a positive one.
+ *
+ * 2. A REPLY WITHOUT A CLAIM STILL WRITES `done`. `reply` records its step on
+ *    delivery, whether or not the item was ever claimed, so an ask answered
+ *    straight out of the inbox reaches hq with no row yet open. hq does NOT
+ *    mint a closed row for it: `ledger.ts`'s born-closed rule downgrades a
+ *    first-touch `done` to `accepted`, so the room is told the ask was picked
+ *    up, not that it was completed, and the row stays open for whatever
+ *    genuinely finishes it. Truthful, but new and channel-visible, so it is
+ *    pinned on both sides rather than left to be rediscovered.
+ *
+ * Pure core + one injected effect. {@link ledgerStepsFor} is a total function
+ * over plain data with no clock, no fs and no network; {@link runAskLedger} is
+ * the only thing here that does I/O and it cannot throw into its caller.
+ *
+ * @module lib/session/ask-ledger
+ */
+
+const NOTE_MAX = 2000;
+
+/** Actions the session lane can take on an inbox item. */
+export const LEDGER_ACTIONS = ["claim", "reply", "done", "defer"];
+
+/** Collapse whitespace and clip — a note is a board comment, not a transcript. */
+function note(text, max = NOTE_MAX) {
+  const one = String(text == null ? "" : text).replace(/\s+/g, " ").trim();
+  return one.length > max ? `${one.slice(0, max - 1)}…` : one;
+}
+
+/**
+ * The ledger steps ONE session-lane action owes, in order. Pure and total: any
+ * unknown action, or an action whose facts say the step would be a duplicate,
+ * yields `[]` rather than throwing.
+ *
+ * Chained, never parallel: `triage` is not terminal, so an `accepted` that
+ * commits after a `working` drags the row back out of `running` for good. The
+ * caller awaits each step before the next.
+ *
+ * @param {object} a
+ * @param {string} a.action one of {@link LEDGER_ACTIONS}
+ * @param {{repliedAt?:string}} [a.markers] session markers already on the item
+ * @param {string} [a.text] the reply text (`reply`)
+ * @param {string} [a.until] ISO the item is parked until (`defer`)
+ * @param {string} [a.reason] why it was parked (`defer`)
+ * @returns {Array<{stage:string, deferred:boolean, note?:string}>}
+ */
+export function ledgerStepsFor(a = {}) {
+  const action = String(a.action || "").trim();
+  const markers = a.markers && typeof a.markers === "object" ? a.markers : {};
+
+  if (action === "claim") {
+    return [
+      {
+        stage: "accepted",
+        deferred: false,
+        note: "Picked this up — working on it now.",
+      },
+      { stage: "working", deferred: false },
+    ];
+  }
+
+  if (action === "reply") {
+    const body = note(a.text);
+    return [
+      {
+        stage: "done",
+        deferred: false,
+        note: body ? `Answered in the conversation: ${body}` : "Answered in the conversation.",
+      },
+    ];
+  }
+
+  if (action === "done") {
+    // The reply already closed the row and said what was delivered. Saying it
+    // again adds a second comment that carries no new fact.
+    if (markers.repliedAt) return [];
+    return [{ stage: "done", deferred: false, note: "Marked finished from the inbox." }];
+  }
+
+  if (action === "defer") {
+    const until = String(a.until || "").trim();
+    const why = note(a.reason, 400);
+    return [
+      {
+        stage: "blocked",
+        deferred: false,
+        note:
+          `Parked${until ? ` until ${until}` : ""}.` + (why ? ` ${why}` : ""),
+      },
+    ];
+  }
+
+  return [];
+}
+
+/**
+ * Write the steps one session-lane action owes, against the org board.
+ *
+ * FAIL-OPEN, NEVER SILENT — the same contract the daemon's `trackWorkStep`
+ * carries. A ledger write must never cost the human their reply or fail the
+ * command that already had its effect, so every path returns a result and
+ * nothing throws past this boundary. But every refusal comes back with a
+ * reason, because a process going quiet is the bug this workstream exists to
+ * remove.
+ *
+ * AWAITED, not fire-and-forget. The daemon is a long-lived process and can let
+ * a promise settle after the fact; the CLI is a short one whose caller exits the
+ * moment this returns, so an un-awaited write is a write that never leaves the
+ * machine. It is awaited AFTER the action's own effect has landed, so a slow or
+ * dead server delays the JSON on stdout and changes nothing else.
+ *
+ * @param {object} a
+ * @param {object} a.item   the enriched inbox item (carries `service`)
+ * @param {string} a.action one of {@link LEDGER_ACTIONS}
+ * @param {object} [a.cfg]  agent org config; `{}` reads as org-disabled
+ * @param {object} [a.markers]
+ * @param {string} [a.text]
+ * @param {string} [a.until]
+ * @param {string} [a.reason]
+ * @param {string} [a.title] row title, sent with the OPENING step only
+ * @param {string} [a.why]   why the row was opened, sent with the OPENING step only
+ * @param {object} [a.source] free provenance stamped into the row's `why`
+ * @param {Function} [a.recordImpl] injected `recordWorkStep` (test seam)
+ * @param {Function} [a.trackImpl] injected `board.track` (test seam)
+ * @param {Function} [a.fetchImpl] injected fetch (test seam)
+ * @returns {Promise<{steps:Array<object>, results:Array<object>}>}
+ */
+export async function runAskLedger(a = {}) {
+  const steps = ledgerStepsFor(a);
+  const results = [];
+  if (steps.length === 0) return { steps, results };
+  try {
+    const record = a.recordImpl || (await import("../org/work-ledger.mjs")).recordWorkStep;
+    for (const [i, step] of steps.entries()) {
+      const res = await record({
+        item: a.item,
+        stage: step.stage,
+        deferred: step.deferred,
+        note: step.note,
+        cfg: a.cfg,
+        // ONLY THE FIRST STEP CAN OPEN THE ROW — a refused step breaks the loop
+        // below, so nothing after index 0 ever reaches hq's `if (!taskId)`
+        // branch. `title` and `why` are read there and nowhere else, so sending
+        // them on a later step would be a write that is accepted and ignored.
+        ...(i === 0 && a.title ? { title: a.title } : {}),
+        ...(i === 0 && a.why ? { why: a.why } : {}),
+        source: { lane: "session", action: a.action, ...(a.source || {}) },
+        trackImpl: a.trackImpl,
+        fetchImpl: a.fetchImpl,
+      });
+      results.push(res || { tracked: false, reason: "no-result" });
+      // A refused step refuses every step after it for the same reason (the
+      // gate is pure over the same facts), so stop rather than repeat the call.
+      if (!res || !res.tracked) break;
+    }
+  } catch (err) {
+    results.push({ tracked: false, reason: `error: ${err && err.message ? err.message : String(err)}`.slice(0, 200) });
+  }
+  return { steps, results };
+}
+
+/**
+ * One log line per action, for the session lane's own stdout. Pure.
+ * @param {string} action
+ * @param {{steps:Array<object>, results:Array<object>}} outcome
+ * @returns {string|null} null when the action owed no steps at all
+ */
+export function formatLedgerOutcome(action, outcome) {
+  const steps = (outcome && outcome.steps) || [];
+  const results = (outcome && outcome.results) || [];
+  if (steps.length === 0) return null;
+  const parts = steps.map((s, i) => {
+    const r = results[i];
+    if (!r) return `${s.stage}: not attempted`;
+    return r.tracked
+      ? `${s.stage} → task ${r.taskId || "?"}${r.col ? ` [${r.col}]` : ""}${r.tagged ? ` tagged=${r.tagged}` : ""}`
+      : `${s.stage}: ${r.reason || "unknown"}`;
+  });
+  return `[board] ${action}: ${parts.join("; ")}`;
+}
+
+export default { LEDGER_ACTIONS, ledgerStepsFor, runAskLedger, formatLedgerOutcome };