@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/session/inbox-claims.mjs

@@ -0,0 +1,434 @@
+/**
+ * lib/session/inbox-claims.mjs — session claims on inbox items and the
+ * assurance reopen sweep (design §3.3).
+ *
+ * The daemon and the main session share ONE inbox state machine — the file
+ * suffixes `scripts/poller/utils.mjs` already defines:
+ *
+ *   <name>.yaml              new — anyone may take it
+ *   <name>.yaml.dispatched   in flight (durable admission, F1/H2)
+ *   <name>.yaml.deferred     parked
+ *   <name>.yaml.processed    terminal
+ *
+ * A SESSION claim is a `.dispatched` file carrying two top-level YAML lines
+ * appended below the item — `claimed_by: "session"` / `claimed_at: "<iso>"` —
+ * so the daemon can tell a session claim from its own (which carries none)
+ * and reopen it on a shorter clock: 20 minutes instead of the scanner's 2-hour
+ * crash-reclaim. A session deferral (`maestro inbox defer --until`) is a
+ * `.deferred` file carrying `deferred_until:` / `deferred_reason:`; the same
+ * sweep reopens it when its time passes (and `promoteDeferred` leaves it
+ * alone — a session deferral is not a thread-lock burst). A reply stamps
+ * `replied_at:` — a REPLIED claim is never reopened (that would answer the
+ * human twice); it is retired to `.processed` once past the retire window if
+ * the session never runs `inbox done`. Reopening strips the markers IN PLACE
+ * (same inode, so a concurrent `inbox done` rename can never be resurrected
+ * by a tmp+rename recreating the path) and renames back to `.yaml`, so the
+ * item is byte-identical to how it arrived.
+ *
+ * While the session is live the daemon's scanner is gated off, and with it
+ * the scanner's 2 h reclaim of the daemon's OWN `.dispatched` files (no
+ * marker) — items admitted just before a daemon restart would otherwise be
+ * stranded, invisible to `inbox list`. The sweep reopens those too, on the
+ * same 2 h clock, but only when told the session is live (`sessionLive`).
+ *
+ * The markers are read as COLUMN-0 keys only (the same anchoring
+ * `inbox-deferral.mjs` uses) so an indented look-alike inside a message body
+ * can never forge a claim. Clock injected; fs via node:fs on the agent root;
+ * every function returns a value and never throws past its boundary.
+ *
+ * @module lib/session/inbox-claims
+ */
+
+import { join } from "node:path";
+import { readdirSync, readFileSync, existsSync, renameSync, statSync, openSync, ftruncateSync, writeSync, closeSync } from "node:fs";
+import { writeFileAtomic } from "../fs-atomic.mjs";
+import { readFrontDoorState } from "./frontdoor.mjs";
+
+/** A session claim neither replied nor done within this window is reopened. */
+export const SESSION_CLAIM_STALE_MS = 20 * 60_000;
+/**
+ * A replied claim the session never finished with `inbox done` is retired to
+ * `.processed` this long after the reply. The human has been answered; leaving
+ * it in flight forever would let the scanner re-dispatch it once the session
+ * dies. Same window as the scanner's own reclaim.
+ */
+export const REPLIED_RETIRE_MS = 2 * 60 * 60_000;
+/**
+ * A daemon-owned `.dispatched` (no session marker) older than this is an
+ * orphan of a daemon that restarted — mirrors the scanner's DEFAULT_RECLAIM_MS
+ * (scripts/poller/inbox-scan-poller.mjs), which is gated off while the
+ * session is live.
+ */
+export const DAEMON_ORPHAN_RECLAIM_MS = 2 * 60 * 60_000;
+
+const MARKER_KEYS = ["claimed_by", "claimed_at", "deferred_until", "deferred_reason", "replied_at"];
+const MARKER_LINE = new RegExp(`^(?:${MARKER_KEYS.join("|")}):.*$`);
+
+function iso(ms) { return new Date(ms).toISOString(); }
+function nowOf(o) { return typeof o.now === "number" ? o.now : Date.now(); }
+function q(v) { return `"${String(v).replace(/[\r\n]+/g, " ").replace(/"/g, "'")}"`; }
+
+/**
+ * The marker lines to append below an item.
+ * @param {{claimedBy?:string, claimedAt?:string, now?:number, deferredUntil?:number|string, deferredReason?:string, repliedAt?:number|string}} o
+ * @returns {string} zero or more `key: "value"\n` lines
+ */
+export function sessionMarkerLines(o = {}) {
+  const lines = [];
+  if (o.claimedBy) {
+    lines.push(`claimed_by: ${q(o.claimedBy)}`);
+    lines.push(`claimed_at: ${q(o.claimedAt || iso(nowOf(o)))}`);
+  }
+  if (o.repliedAt != null) {
+    lines.push(`replied_at: ${q(typeof o.repliedAt === "number" ? iso(o.repliedAt) : String(o.repliedAt))}`);
+  }
+  if (o.deferredUntil != null) {
+    const until = typeof o.deferredUntil === "number" ? iso(o.deferredUntil) : String(o.deferredUntil);
+    lines.push(`deferred_until: ${q(until)}`);
+    if (o.deferredReason) lines.push(`deferred_reason: ${q(o.deferredReason)}`);
+  }
+  return lines.length ? lines.join("\n") + "\n" : "";
+}
+
+function scalar(body, key) {
+  const m = String(body || "").match(new RegExp(`^${key}:\\s*"?([^"\\n]*)"?\\s*$`, "m"));
+  return m && m[1] !== "" ? m[1] : null;
+}
+
+/**
+ * Read the markers off an item body. Column-0 keys only.
+ * @param {string} body
+ * @returns {{claimedBy:string|null, claimedAt:string|null, deferredUntil:string|null, deferredReason:string|null, repliedAt:string|null}}
+ */
+export function parseSessionMarkers(body) {
+  return {
+    claimedBy: scalar(body, "claimed_by"),
+    claimedAt: scalar(body, "claimed_at"),
+    deferredUntil: scalar(body, "deferred_until"),
+    deferredReason: scalar(body, "deferred_reason"),
+    repliedAt: scalar(body, "replied_at"),
+  };
+}
+
+/**
+ * The item body without any marker lines — byte-identical to how it arrived.
+ * @param {string} body
+ * @returns {string}
+ */
+export function stripSessionMarkers(body) {
+  const src = String(body || "");
+  const lines = src.split("\n");
+  if (!lines.some((l) => MARKER_LINE.test(l))) return src;
+  return lines.filter((l) => !MARKER_LINE.test(l)).join("\n");
+}
+
+const STATE_BY_SUFFIX = [
+  [".yaml.processed-bundled", "bundled"],
+  [".yaml.processed", "processed"],
+  [".yaml.dispatched", "claimed"],
+  [".yaml.deferred", "deferred"],
+  [".yaml", "new"],
+];
+
+function stateOf(name) {
+  for (const [suffix, state] of STATE_BY_SUFFIX) if (name.endsWith(suffix)) return state;
+  return null;
+}
+
+function serviceDirs(agentRoot, only) {
+  if (only) return [only];
+  try {
+    return readdirSync(join(agentRoot, "state", "inbox"), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== "attachments")
+      .map((e) => e.name)
+      .sort();
+  } catch { return []; /* no inbox at all */ }
+}
+
+// `writeInboxItem` names a file `<timestamp-with-:.→->-<id>.yaml`; this
+// recovers the `<id>` so a lookup can be EXACT rather than a substring guess.
+const FILE_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(?:-\d+)?Z?-(.+?)\.yaml(?:\.[a-z-]+)?$/;
+function idOfFile(file) {
+  const m = file.match(FILE_ID);
+  return m ? m[1] : null;
+}
+
+/**
+ * Locate an inbox item by id (or raw_ref substring) across services.
+ * Prefers the live/claimed/deferred copy over a terminal one. An EXACT id
+ * match (the id the file was written under) always wins over a substring
+ * look-alike (`cohort-m1` vs `cohort-m10`); when only substring matches exist
+ * and they name more than one distinct item, the lookup is refused (null) —
+ * a truncated id must never silently pick a neighbour.
+ *
+ * @param {string} agentRoot
+ * @param {string} id
+ * @param {{service?:string}} [o]
+ * @returns {{service:string, file:string, path:string, state:string}|null}
+ */
+export function findInboxFile(agentRoot, id, o = {}) {
+  const needle = String(id || "").trim();
+  if (!needle) return null;
+  const rank = { new: 0, claimed: 1, deferred: 2, processed: 3, bundled: 4 };
+  let exact = null;
+  let loose = null;
+  const looseIds = new Set();
+  for (const service of serviceDirs(agentRoot, o.service)) {
+    const dir = join(agentRoot, "state", "inbox", service);
+    let names;
+    try { names = readdirSync(dir); } catch { continue; }
+    for (const file of names) {
+      if (!file.includes(needle)) continue;
+      const state = stateOf(file);
+      if (!state) continue;
+      const hit = { service, file, path: join(dir, file), state };
+      if (idOfFile(file) === needle) {
+        if (!exact || rank[state] < rank[exact.state]) exact = hit;
+      } else {
+        looseIds.add(`${service}/${idOfFile(file) || file.replace(/\.yaml(\.[a-z-]+)?$/, "")}`);
+        if (!loose || rank[state] < rank[loose.state]) loose = hit;
+      }
+    }
+  }
+  if (exact) return exact;
+  return looseIds.size === 1 ? loose : null;
+}
+
+/**
+ * Claim an item for the session: `.yaml` → `.yaml.dispatched` (the shared
+ * durable-admission marker) + `claimed_by: "session"`. Only a NEW item is
+ * claimable — an in-flight or parked one returns `not-claimable`.
+ *
+ * @param {string} agentRoot
+ * @param {string} service
+ * @param {{id?:string, raw_ref?:string}} item
+ * @param {{now?:number, by?:string}} [o]
+ * @returns {{ok:true, path:string}|{ok:false, error:string}}
+ */
+export function markSessionClaim(agentRoot, service, item, o = {}) {
+  try {
+    const found = findInboxFile(agentRoot, (item && (item.id || item.raw_ref)) || "", { service });
+    if (!found || found.state !== "new") return { ok: false, error: "not-claimable" };
+    // ONE file: the located item, never every substring look-alike.
+    const dst = `${found.path}.dispatched`;
+    try { renameSync(found.path, dst); }
+    catch (err) { return err && err.code === "ENOENT" ? { ok: false, error: "not-claimable" } : { ok: false, error: err.message }; }
+    const body = stripSessionMarkers(readFileSync(dst, "utf-8"));
+    const sep = body.endsWith("\n") || body === "" ? "" : "\n";
+    writeFileAtomic(dst, body + sep + sessionMarkerLines({ claimedBy: o.by || "session", now: nowOf(o) }));
+    return { ok: true, path: dst };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Record that the session REPLIED to a claimed item (`replied_at:`), keeping
+ * the claim markers. Only an in-flight (`.dispatched`) item can be marked —
+ * a reply to a new item first needs a claim, a terminal item is finished.
+ *
+ * @param {string} agentRoot
+ * @param {string} service
+ * @param {{id?:string, raw_ref?:string}} item
+ * @param {{now?:number}} [o]
+ * @returns {{ok:true, path:string}|{ok:false, error:string}}
+ */
+export function markSessionReplied(agentRoot, service, item, o = {}) {
+  try {
+    const found = findInboxFile(agentRoot, (item && (item.id || item.raw_ref)) || "", { service });
+    if (!found || found.state !== "claimed") return { ok: false, error: "not-in-flight" };
+    const raw = readFileSync(found.path, "utf-8");
+    const m = parseSessionMarkers(raw);
+    const body = stripSessionMarkers(raw);
+    const sep = body.endsWith("\n") || body === "" ? "" : "\n";
+    const markers = sessionMarkerLines({
+      claimedBy: m.claimedBy || "session",
+      claimedAt: m.claimedAt || undefined,
+      now: nowOf(o),
+      repliedAt: nowOf(o),
+    });
+    writeInPlace(found.path, body + sep + markers);
+    return { ok: true, path: found.path };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Defer an item until a time: `.yaml` or `.yaml.dispatched` → `.yaml.deferred`
+ * with `deferred_until:` / `deferred_reason:`. The sweep reopens it when due.
+ *
+ * @param {string} agentRoot
+ * @param {string} service
+ * @param {{id?:string, raw_ref?:string}} item
+ * @param {{until:number|string, reason?:string, now?:number}} o
+ * @returns {{ok:true, path:string, until:string}|{ok:false, error:string}}
+ */
+export function markSessionDeferral(agentRoot, service, item, o = {}) {
+  try {
+    const untilMs = typeof o.until === "number" ? o.until : Date.parse(String(o.until || ""));
+    if (!Number.isFinite(untilMs)) return { ok: false, error: "invalid until" };
+    const found = findInboxFile(agentRoot, (item && (item.id || item.raw_ref)) || "", { service });
+    if (!found || (found.state !== "new" && found.state !== "claimed")) return { ok: false, error: "not-deferrable" };
+    const base = found.file.replace(/\.dispatched$/, "");
+    const dst = join(agentRoot, "state", "inbox", service, `${base}.deferred`);
+    const body = stripSessionMarkers(readFileSync(found.path, "utf-8"));
+    const sep = body.endsWith("\n") || body === "" ? "" : "\n";
+    writeFileAtomic(found.path, body + sep + sessionMarkerLines({ deferredUntil: untilMs, deferredReason: o.reason || "" }));
+    renameSync(found.path, dst);
+    return { ok: true, path: dst, until: iso(untilMs) };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Rewrite a file's contents on its EXISTING inode (open r+, truncate, write).
+ * Unlike tmp+rename this can never recreate a path that a concurrent rename
+ * (`inbox done`, `inbox reply`) has just moved away — the write either lands
+ * in the moved file (harmless: markers are stripped from a terminal copy) or
+ * fails ENOENT. The reader side is the sweep itself, so the non-atomic window
+ * has no other observer.
+ */
+function writeInPlace(path, text) {
+  const fd = openSync(path, "r+");
+  try {
+    ftruncateSync(fd, 0);
+    writeSync(fd, text, 0, "utf-8");
+  } finally { closeSync(fd); }
+}
+
+/** Reopen a parked/claimed file: strip markers in place, rename back to `.yaml`. */
+function reopen(dir, file) {
+  const src = join(dir, file);
+  const dst = join(dir, file.replace(/\.(dispatched|deferred)$/, ""));
+  writeInPlace(src, stripSessionMarkers(readFileSync(src, "utf-8")));
+  renameSync(src, dst);
+  return dst;
+}
+
+/** Retire a claimed file to `.processed` (terminal), markers stripped in place. */
+function retire(dir, file) {
+  const src = join(dir, file);
+  const dst = join(dir, file.replace(/\.(dispatched|deferred)$/, "") + ".processed");
+  try { writeInPlace(src, stripSessionMarkers(readFileSync(src, "utf-8"))); } catch { /* strip is cosmetic on a terminal file */ }
+  renameSync(src, dst);
+  return dst;
+}
+
+/**
+ * Strip the session markers off a file in place (same inode). Exported for
+ * the CLI's terminal transitions. Never throws; returns whether it wrote.
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function stripMarkersInPlace(path) {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const clean = stripSessionMarkers(raw);
+    if (clean !== raw) writeInPlace(path, clean);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * THE ASSURANCE SWEEP. Reopens (a) a session claim neither replied nor done
+ * within `staleMs` (default 20 min), (b) a session deferral whose
+ * `deferred_until` has passed, and (c) — only when `sessionLive` — a
+ * daemon-owned `.dispatched` orphan (no marker) older than
+ * `daemonReclaimMs` (default 2 h), because the scanner that would normally
+ * reclaim it is gated off while the session is live. A REPLIED claim is
+ * never reopened; one still in flight `repliedRetireMs` (default 2 h) after
+ * the reply is retired to `.processed` (reason `replied-retired`). Legacy
+ * thread-lock `.deferred` files (no marker) are never touched —
+ * `promoteDeferred` owns those. A claim with an unreadable `claimed_at` falls
+ * back to the file mtime.
+ *
+ * @param {string} agentRoot
+ * @param {{now?:number, staleMs?:number, services?:string[], sessionLive?:boolean, daemonReclaimMs?:number, repliedRetireMs?:number}} [o]
+ * @returns {{reopened:{id:string, service:string, file:string, reason:string}[], scanned:number}}
+ */
+export function sweepSessionInbox(agentRoot, o = {}) {
+  const now = nowOf(o);
+  const staleMs = Number.isFinite(o.staleMs) && o.staleMs > 0 ? o.staleMs : SESSION_CLAIM_STALE_MS;
+  const daemonReclaimMs = Number.isFinite(o.daemonReclaimMs) && o.daemonReclaimMs > 0 ? o.daemonReclaimMs : DAEMON_ORPHAN_RECLAIM_MS;
+  const repliedRetireMs = Number.isFinite(o.repliedRetireMs) && o.repliedRetireMs > 0 ? o.repliedRetireMs : REPLIED_RETIRE_MS;
+  const sessionLive = o.sessionLive === true;
+  const services = Array.isArray(o.services) && o.services.length ? o.services : serviceDirs(agentRoot);
+  const reopened = [];
+  let scanned = 0;
+  for (const service of services) {
+    const dir = join(agentRoot, "state", "inbox", service);
+    if (!existsSync(dir)) continue;
+    let names;
+    try { names = readdirSync(dir); } catch { continue; }
+    for (const file of names) {
+      const isClaim = file.endsWith(".yaml.dispatched");
+      const isDeferral = file.endsWith(".yaml.deferred");
+      if (!isClaim && !isDeferral) continue;
+      scanned += 1;
+      try {
+        const path = join(dir, file);
+        const body = readFileSync(path, "utf-8");
+        const m = parseSessionMarkers(body);
+        let reason = null;
+        let action = reopen;
+        if (isClaim && m.claimedBy && m.repliedAt) {
+          // Answered. Never reopened; retired once the session has had its window to finish.
+          let at = Date.parse(m.repliedAt);
+          if (!Number.isFinite(at)) { try { at = statSync(path).mtimeMs; } catch { at = now; } }
+          if (now - at >= repliedRetireMs) { reason = "replied-retired"; action = retire; }
+        } else if (isClaim && m.claimedBy) {
+          let at = Date.parse(m.claimedAt || "");
+          if (!Number.isFinite(at)) { try { at = statSync(path).mtimeMs; } catch { at = now; } }
+          if (now - at >= staleMs) reason = "claim-stale";
+        } else if (isClaim && sessionLive) {
+          // Daemon-owned. Its scanner is gated off while the session is live.
+          let age = 0;
+          try { age = now - statSync(path).mtimeMs; } catch { age = 0; }
+          if (age >= daemonReclaimMs) reason = "daemon-orphan";
+        } else if (isDeferral && m.deferredUntil) {
+          const until = Date.parse(m.deferredUntil);
+          if (!Number.isFinite(until) || now >= until) reason = "deferral-due";
+        }
+        if (!reason) continue;
+        action(dir, file);
+        reopened.push({ id: scalar(body, "id") || file, service, file, reason });
+      } catch { /* a racing rename or unreadable file — the next sweep retries */ }
+    }
+  }
+  return { reopened, scanned };
+}
+
+/**
+ * The daemon's call site for the sweep: reads the front-door state (so the
+ * daemon-orphan reclaim runs only while the session is live) and sweeps. A
+ * throwing reader means "not live" — the scanner keeps its own reclaim.
+ *
+ * @param {string} agentRoot
+ * @param {{now?:number, readState?:Function}} [o]
+ * @returns {{reopened:object[], scanned:number, sessionLive:boolean}}
+ */
+export function sweepSessionInboxForDaemon(agentRoot, o = {}) {
+  const now = nowOf(o);
+  const readState = typeof o.readState === "function" ? o.readState : readFrontDoorState;
+  let sessionLive = false;
+  try { sessionLive = readState(agentRoot, { now }).sessionLive === true; } catch { sessionLive = false; }
+  return { ...sweepSessionInbox(agentRoot, { now, sessionLive }), sessionLive };
+}
+
+export default {
+  SESSION_CLAIM_STALE_MS,
+  REPLIED_RETIRE_MS,
+  DAEMON_ORPHAN_RECLAIM_MS,
+  sessionMarkerLines,
+  parseSessionMarkers,
+  stripSessionMarkers,
+  stripMarkersInPlace,
+  findInboxFile,
+  markSessionClaim,
+  markSessionDeferral,
+  markSessionReplied,
+  sweepSessionInbox,
+  sweepSessionInboxForDaemon,
+};