@open-everywhere/core 0.1.0

package/dist/agent/model/turn-state.js

@@ -0,0 +1,423 @@
+// turn-state — THE DURABLE HALF OF THE PER-TURN GUARDS (OPE-1522).
+//
+// ── THE FAILURE THIS EXISTS FOR ──────────────────────────────────────────────────────────────────
+// `model/step-boundary.ts` counted a turn's model round-trips in a module-level `Map`, and
+// `model/turn-closeout.ts` latched a turn's post-closeout refusal in a second one. On Vercel a turn
+// does not belong to one process: eve replays a turn's COMPLETED steps and re-runs the interrupted
+// one, so a turn interrupted by a timeout or a redeploy resumes on a FRESH INSTANCE — where both
+// maps are empty. A replayed step makes no model call, so the resolver is never asked about it and
+// the count is never rebuilt: the new instance starts the turn at zero.
+//
+// Measured on prod 2026-09-07 (seat session `wrun_41M1XN60YB0GQDPMXNZJ1588BA`): turn_3 ended at step
+// 121 — the soft boundary firing exactly where it should — and turn_4 ran to 198 round-trips ($2.93)
+// before the same boundary fired. 198 is not a value `classifyStepCount` can produce against a
+// budget of 120 in one process; it is two counts, 120 + 78, on two instances.
+//
+// The closeout latch has the same shape and a sharper cost: it is armed by ONE refusal
+// (`CLOSEOUT_REFUSAL_LIMIT`), so an instance change between the arming refusal and the next model
+// round-trip loses the arming outright and the turn spins to the step budget again.
+//
+// ── WHAT THIS MODULE IS ──────────────────────────────────────────────────────────────────────────
+// One durable row per (eve session id, eve turn id) holding both guards' state. The two in-memory
+// maps stay, as CACHES: a warm instance reads its own map and pays the store one small read and one
+// small write per model round-trip; a cold instance reads the row and CONTINUES the count instead of
+// restarting it. The count is therefore `max(cache, row) + 1`, never `row + 1`, so a row that
+// answers STALE costs at most a step on a warm instance.
+//
+// 🔴 A READ THAT FAILED IS NOT A ROW THAT IS ABSENT, and the write must be able to tell them apart.
+// The write is a whole-row overwrite (`putTaskResult`), so a failed read followed by a healthy write
+// would persist the count the caller computed from nothing — erasing a real 118-step row and its
+// armed latch, on exactly the cold instance this module exists for, where the cache offers no floor.
+// {@link readTurnState} therefore answers `undefined` for "could not read" and {@link
+// EMPTY_TURN_STATE} only for a row that genuinely is not there, and BOTH writers skip the write on
+// `undefined`. A turn whose row is unreadable falls back to its in-memory caches — the pre-OPE-1522
+// behaviour — instead of losing the record it could not see.
+//
+// 🔴 ONE ROW, NOT TWO. Both guards key on the same (session, turn) pair and both are read on the
+// SAME model round-trip, so a row apiece would double the store traffic on the hottest path OE has.
+// The two guards still own their own semantics — this module owns only the row.
+//
+// ── WHERE THE ROW LIVES ──────────────────────────────────────────────────────────────────────────
+// The operational store's opaque key-value scratch table (`task_result`, see its schema comment),
+// under this module's own `oe-turn-state:` prefix, exactly as the subagent taint markers, the
+// question bridge and the task-wake join use it. That table is TTL-pruned per write, org-partitioned
+// and already the store's home for short-lived per-run rows, so this needs no migration.
+//
+// THE COST, STATED: one small keyed read and one small keyed write per MODEL ROUND-TRIP, and
+// `putTaskResult` prunes that org's expired rows on each write. A model round-trip is seconds and
+// cents; these are milliseconds against a primary key on a table that holds a handful of short-lived
+// rows. The alternative — a row per guard — doubles it for nothing, which is why both guards share
+// one row.
+//
+// The org is {@link deploymentOrg}, never `resolvePartition(ctx).org`. The two are the same value
+// today (`bindFrom` stamps `org: deploymentOrg()`), but `resolvePartition` THROWS on an unbindable
+// context — which is exactly the state the dynamic-model resolver seam can be in, and where
+// `reportStepBoundary` already gives up. A partition key the writer and the reader can disagree
+// about is worse than no durability at all, so this reads the deployment constant that cannot fail.
+//
+// ── A SESSIONLESS TURN HAS NO DURABLE HALF (OPE-1551) ────────────────────────────────────────────
+// {@link turnPairKey} falls back to the bare `turn_N` when no session is bindable (evals,
+// sessionless schedules), and eve mints that id identically for every session's Nth turn. As a CACHE
+// key that collision is bounded to one process's map. As a ROW key it is not: the row is a six-hour
+// entry in one ORG-WIDE partition, so two sessionless turns would share a step count AND a closeout
+// latch — a latch armed by run A would end run B's first model round-trip with the `closed` stub.
+//
+// So the durable half is SESSION-SCOPED ONLY. {@link durableTurnKey} answers `undefined` for a
+// sessionless turn, and both call sites then skip the read and the write and run on their caches —
+// the pre-OPE-1522 behaviour, which is correct for that population rather than merely tolerable.
+// The CACHE key is unchanged: an in-process collision between two sessionless turns is the older
+// OPE-423 hazard, and narrowing the row does not widen it.
+//
+// ── FAIL-SOFT, IN ONE DIRECTION ──────────────────────────────────────────────────────────────────
+// Every entry point swallows its own failures. An unreachable store or an unparsable row degrades
+// that turn to "no durable half", which is the in-memory behaviour this module was added to
+// improve — never a turn ended on a guess. Because the writers skip a read they could not complete,
+// that degradation costs the CURRENT round-trip and leaves the stored record for the next one.
+//
+// 🔴 A `try/catch` CATCHES A REJECTION, NOT A HANG (OPE-1555). Every model round-trip awaits a read
+// and a write here, and neither store adapter sets a statement or connect timeout, so a
+// pool-exhausted or blackholed store would stall each round-trip to the 800-second function cap —
+// the swallowed-failure contract above says nothing about a call that never settles. So each store
+// call is raced against {@link TURN_STATE_STORE_DEADLINE_MS} and the expiry takes the SAME path a
+// failure takes: the read answers `undefined` (cache-only, and no write over a row it did not see)
+// and the write is abandoned. What this module guarantees is therefore bounded, not absolute: a
+// broken store costs a round-trip its durable half, never the turn.
+//
+// 🔴 THE BOUND IS PER CALL, NOT PER ROUND-TRIP, AND THE TWO DIFFER BY 5x. Count the worst case
+// honestly: `noteTurnStep` pays a read and a write; a `reply` into a stood-down conversation pays
+// `stoppedAckSpent`'s read, then `noteStoppedAck`'s read and write. That is FIVE deadline-bounded
+// calls, so about 2.5 s of added wall clock on such a round-trip against a store sitting just past
+// the deadline — not 500 ms. It is still a bound, and it is still far from the 800 s function cap,
+// which is what this deadline exists to keep the turn away from.
+//
+// AND IT COVERS THIS MODULE'S CALLS ONLY. `channels/engagement.ts`'s `isThreadStopped`, on the same
+// reply path, has no deadline at all. That is another module's to bound, and claiming otherwise here
+// would be exactly the kind of overclaim this section replaced.
+//
+// 🔴 THE RESIDUAL, STATED: this is read-modify-write with NO compare-and-set, because the shared
+// scratch table offers none. A write can therefore land on top of a row it never saw — ACROSS
+// PROCESSES: the resolver on instance A reads the row, a tool on instance B arms the latch and
+// writes, and A then writes a row built before B's arming.
+//
+// WITHIN ONE PROCESS the row is safe. eve serialises resolver → model → tool, so two writers cannot
+// interleave in program order, and since OPE-1564 {@link chainRowCall} keeps an ABANDONED write
+// from overtaking its successor as well (see the section below).
+//
+// WHAT THE CROSS-PROCESS RESIDUAL LOSES, AND THE FAIL DIRECTION OF EACH FIELD:
+//   • `steps` rewinds, so the turn counts on from a lower floor — the pre-OPE-1522 behaviour, and the
+//     step budget is still behind it;
+//   • `closeout` loses an arming, so the turn falls back to the step budget rather than ending here —
+//     the pre-OPE-1520 behaviour, and never a turn ended wrongly;
+//   • `stoppedAck` reads UNSPENT, so a resumed turn gets ONE more post into a conversation the person
+//     asked the seat to leave. That is the sharpest of the three, and it is the same one-duplicate
+//     cost the whole stand-down path already fails open with (`tools/reply.ts`), never a lost answer.
+//
+// 🔴 THE IN-PROCESS SAFETY OF `stoppedAck` COMES FROM THE FRESH READ, NOT FROM A CACHE. The latch
+// has an in-memory cache the resolver's snapshot reads; this field has none. What keeps it correct is
+// that every writer spreads the row it just read, so no writer names a subset of the fields and drops
+// the rest. A future writer that names fields instead of spreading breaks this silently.
+//
+// ── THE IN-FLIGHT HALF IS CLOSED (OPE-1564) ──────────────────────────────────────────────────────
+// {@link chainRowCall} orders every store call this module makes to ONE pair's row — the READS as
+// well as the writes and the delete. A call is ISSUED only after its predecessor has SETTLED, so the
+// store sees this process's calls in program order and last-write-wins gives the LATER write. An
+// abandoned write can no longer overtake its successor, which is what un-spent `stoppedAck` and
+// rewound `steps` on a slow store.
+//
+// 🔴 THE READ HAD TO JOIN THE CHAIN, OR THE LOSS ONLY MOVES. Every writer here is read-modify-write
+// over a whole-row overwrite. Order the writes alone and a FAST read can still see the row as it
+// stood before a SLOW predecessor lands; its writer then spreads those stale bytes into a new row,
+// and the chain lands that row last — deterministically dropping the field the reader never saw.
+// `stoppedAck` is the field that costs, because it is the one with no in-memory cache to repair it.
+// {@link chainRowCall} spells the interleaving out.
+//
+// The CALLER still pays only the deadline: the deadline races the queued call, so a caller whose
+// predecessor is hung waits {@link TURN_STATE_STORE_DEADLINE_MS} and no longer. What it gives up is
+// stated plainly — while a predecessor hangs, its successors stay QUEUED and never reach the store,
+// so a broken store now costs the pair its later calls as well as its abandoned one. That is the
+// same fail-soft direction the rest of this module takes: a read that did not complete answers
+// `undefined`, both writers then skip, and the turn falls back to its in-memory caches.
+//
+// THE CROSS-PROCESS HALF IS UNCHANGED and still open: the resolver on instance A reads the row,
+// instance B arms the latch and writes, and A then writes a row built before B's arming. Closing that
+// needs a CAS primitive the shared scratch table does not offer.
+import { deploymentOrg } from "../identity/deployment-identity.js";
+import { getOperationalStore } from "../operational/provider.js";
+/** Key prefix for this module's rows in the shared scratch table — namespaced so a turn-state row
+ *  can never collide with the taint markers, the question bridge or the task-wake join that share
+ *  it. */
+const TURN_STATE_PREFIX = "oe-turn-state:";
+/**
+ * How long a turn's row outlives its last write. Generous on purpose: it bounds a TURN, and a turn
+ * may legitimately run for hours (auto-compaction at ~50% of a 1M window is what makes long turns a
+ * feature rather than a fault — see `model/step-boundary.ts`'s header). Each write refreshes the
+ * row's `created_at`, so the TTL is measured from a turn's LAST round-trip, not its first. The same
+ * six hours `access/subagent-taint.ts` bounds its markers with.
+ */
+export const TURN_STATE_TTL_MS = 6 * 60 * 60 * 1000;
+/**
+ * How long ONE store call on the per-round-trip path may take before this module gives up on it and
+ * runs cache-only (OPE-1555). Hundreds of milliseconds: the read is a primary-key lookup and the
+ * write a single upsert on a table holding a handful of short-lived rows, so a healthy store answers
+ * in single-digit milliseconds and this budget is two orders of magnitude of headroom. It is not a
+ * latency dial — it is the bound that keeps an UNHEALTHY store off the model's critical path, and
+ * every expiry degrades exactly as a failure does.
+ */
+export const TURN_STATE_STORE_DEADLINE_MS = 500;
+/**
+ * Race one store call against {@link TURN_STATE_STORE_DEADLINE_MS} and answer `fallback` when the
+ * deadline wins. The abandoned call keeps running — nothing here can cancel a driver's in-flight
+ * query — so its eventual rejection is swallowed rather than left to surface as an unhandled
+ * rejection on a process that has already moved on.
+ */
+/** The answer a store call gives when the deadline beat it. Its own value, distinct from every
+ *  answer the store itself can give — `null` is a row that is genuinely absent, and conflating the
+ *  two is the read/write hazard this module's header opens with. */
+const TIMED_OUT = Symbol("turn-state-store-deadline");
+async function withStoreDeadline(work, fallback) {
+    work.catch(() => undefined); // the loser of the race must not crash the process later
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            // 🔴 NOT `unref`ed. The deadline is the ONLY thing that can settle this race when the store
+            // call never does, so an unref'd timer lets the event loop drain and leaves the caller's await
+            // pending forever — the exact stall this deadline exists to end. `clearTimeout` in the
+            // `finally` is what keeps a healthy call from holding the loop open, and it runs on every path.
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(fallback), TURN_STATE_STORE_DEADLINE_MS);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * ONE PENDING CALL CHAIN PER PAIR — the tail of every store call this process has issued for that
+ * row, or nothing when the row has none outstanding.
+ *
+ * 🔴 KEYED BY PAIR, NEVER GLOBAL. A single chain would make every turn on the instance wait behind
+ * one hung store call, and turns of different pairs cannot overwrite each other's rows at all.
+ */
+const rowCalls = new Map();
+/** The empty tail every pair's first call chains onto. */
+const NO_PENDING_CALL = Promise.resolve();
+/** The answer a chained call gives when it rejected. Its own value, distinct from every answer the
+ *  store itself can give, for the same reason {@link TIMED_OUT} is. */
+const CHAIN_FAILED = Symbol("turn-state-chain-failed");
+/**
+ * Issue one store call on `pair`'s row AFTER every call this process already issued for it has
+ * SETTLED (OPE-1564), and answer a promise that never rejects.
+ *
+ * 🔴 THE ORDER IS WHAT THIS BUYS. `putTaskResult` is an unconditional last-write-wins upsert
+ * (`agent/operational/postgres.ts`), so two calls in flight at once let the SLOWER one win — and the
+ * slow one is exactly the write {@link withStoreDeadline} already gave up on. Chaining on SETTLEMENT
+ * rather than on issue is the load-bearing half: two calls issued back to back still race inside the
+ * driver's pool, so "issued first" does not mean "landed first".
+ *
+ * 🔴 THE READ IS ON THIS CHAIN TOO, AND THAT IS NOT TIDINESS. Ordering the WRITES alone moves the
+ * loss instead of closing it. Every writer here is read-modify-write over a whole-row overwrite, so a
+ * read that beat a slow predecessor would hand its writer a row built from PRE-predecessor bytes —
+ * and the chain would then land that stale-built row LAST, deterministically. Worked through:
+ * `noteStoppedAck` writes `{steps:5, stoppedAck:true}` and is abandoned at the deadline; the next
+ * round-trip reads fast, sees `{steps:5}`, and `noteTurnStep` spreads what it read into
+ * `{steps:6}` — no `stoppedAck` (`model/step-boundary.ts`). `steps` and `closeout` survive that on a
+ * warm instance because `bump` floors the count from its cache; `stoppedAck` has no cache, so the
+ * valve would read UNSPENT. Chaining the read means a reader either sees the predecessor's bytes or
+ * loses its own deadline race and answers `undefined`, and both writers skip a write over a row they
+ * did not see.
+ *
+ * The caller does NOT wait for the chain: every entry point races this promise against the deadline
+ * exactly as it raced the bare store call. A queued call whose predecessor hangs is therefore never
+ * issued, which is the fail-soft direction — no write over a newer row, and no row read as absent.
+ *
+ * The map entry is dropped once this link is the tail AND has settled, so an instance serving many
+ * turns holds one promise per LIVE pair rather than one per turn it ever saw. A pair whose store call
+ * never settles keeps its entry, which is the same broken-store cost the rest of this module pays.
+ */
+function chainRowCall(pair, issue) {
+    const pending = rowCalls.get(pair) ?? NO_PENDING_CALL;
+    // Never rejects: a link that failed must not stop its successor from being issued, and must not
+    // surface as an unhandled rejection either.
+    const call = pending.then(issue).then((value) => value, () => CHAIN_FAILED);
+    const tail = call.then(() => undefined);
+    rowCalls.set(pair, tail);
+    void tail.then(() => {
+        if (rowCalls.get(pair) === tail)
+            rowCalls.delete(pair);
+    });
+    return call;
+}
+/** The verdict for a turn whose row is genuinely NOT THERE — the first round-trip of every turn.
+ *  Distinct from `undefined`, which means the row could not be read and must not be written over. */
+export const EMPTY_TURN_STATE = { steps: 0 };
+/**
+ * The (eve session id, eve turn id) pair both guards key on — THE one spelling, so the counter's
+ * map, the latch's map and the durable row can never address a turn three different ways.
+ *
+ * SESSION-scoped, not turn-id-scoped alone (OPE-423): eve mints `turn.id` as `` `turn_${sequence}` ``
+ * (harness/emission.js), which is IDENTICAL across every session's Nth turn, so two sessions warm on
+ * one instance would otherwise share one counter. Falls back to the bare `turnId` when no session is
+ * bindable (evals, sessionless schedules) — the population `currentSessionId` already answers
+ * `undefined` for.
+ */
+export function turnPairKey(sessionId, turnId) {
+    return sessionId !== undefined ? `${sessionId}:${turnId}` : turnId;
+}
+/**
+ * The pair a DURABLE ROW may be stored under, or `undefined` when this turn has no durable half at
+ * all (OPE-1551). The one difference from {@link turnPairKey} is the sessionless case, and it is the
+ * whole point: the bare `turn_N` fallback is safe in a per-process map and unsafe as a key in an
+ * org-wide table, where every session's Nth turn spells it the same way. See the header's section.
+ *
+ * 🔴 CALL THIS FOR THE STORE AND {@link turnPairKey} FOR THE CACHE — they are not interchangeable.
+ * A caller that keys its cache on this would stop bounding sessionless turns at all.
+ */
+export function durableTurnKey(sessionId, turnId) {
+    return sessionId === undefined || sessionId.length === 0 ? undefined : turnPairKey(sessionId, turnId);
+}
+/** The scratch-table key one turn's row is stored under. Exported so a test asserts the exact row
+ *  rather than re-deriving the prefix. */
+export function turnStateRowKey(pair) {
+    return `${TURN_STATE_PREFIX}${pair}`;
+}
+/** Read one field off an unknown parsed row, or `undefined` when it is not the expected type. */
+function numberField(row, name) {
+    const value = row[name];
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : undefined;
+}
+/**
+ * Parse a stored row back into a {@link TurnState}. `null` — no row — answers {@link
+ * EMPTY_TURN_STATE}. Anything PRESENT but unrecognised answers `undefined`, which is the caller's
+ * signal to leave the row alone: bytes this build cannot read may be a richer row a newer build
+ * wrote during a rolling deploy, and overwriting them would throw away a live turn's real count.
+ */
+export function parseTurnState(raw) {
+    if (raw === null)
+        return EMPTY_TURN_STATE;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const row = parsed;
+    // `steps` is written on EVERY row this module stores, so its absence means these are not this
+    // module's bytes — treat them as unreadable rather than as a turn that has taken no steps.
+    const steps = numberField(row, "steps");
+    if (steps === undefined)
+        return undefined;
+    // Only ever written as `true`, so anything else — absent, `false`, a string — reads as "not spent".
+    const stoppedAck = row.stoppedAck === true ? { stoppedAck: true } : undefined;
+    const closeoutRaw = row.closeout;
+    if (typeof closeoutRaw !== "object" || closeoutRaw === null)
+        return { steps, ...stoppedAck };
+    const closeout = closeoutRaw;
+    const count = numberField(closeout, "count");
+    const reason = closeout.reason;
+    if (count === undefined || count === 0 || typeof reason !== "string" || reason.length === 0)
+        return { steps, ...stoppedAck };
+    return { steps, ...stoppedAck, closeout: { count, reason, reported: closeout.reported === true } };
+}
+/**
+ * This turn's durable state: {@link EMPTY_TURN_STATE} when the row is genuinely absent, and
+ * `undefined` when it COULD NOT BE READ — an unreachable store, a rejected query, bytes this build
+ * does not recognise. Never throws.
+ *
+ * 🔴 THE TWO ANSWERS ARE NOT INTERCHANGEABLE. A caller that treats `undefined` as "empty" computes a
+ * count from nothing and then overwrites a real row with it; see the header. Read the count from
+ * `?? EMPTY_TURN_STATE` if you like, but gate the WRITE on the raw `undefined`.
+ */
+export async function readTurnState(pair) {
+    try {
+        const raw = await withStoreDeadline(
+        // ON THE PAIR'S CALL CHAIN (OPE-1564), so this cannot read bytes an abandoned predecessor is
+        // about to replace — see {@link chainRowCall} for the row that interleaving would otherwise
+        // build and land last.
+        chainRowCall(pair, () => getOperationalStore().getTaskResult(deploymentOrg(), turnStateRowKey(pair))), TIMED_OUT);
+        // A read that ran out of time, or that the chain could not issue, is a read that did not
+        // complete, so it takes the `undefined` path and nothing is written over the row it never saw
+        // (OPE-1555).
+        return raw === TIMED_OUT || raw === CHAIN_FAILED ? undefined : parseTurnState(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persist this turn's state, so the NEXT instance to serve a round-trip of this turn continues the
+ * count and sees the latch. It REPLACES the row, so call it only with a record built from a read
+ * that succeeded (see {@link readTurnState}).
+ *
+ * Best-effort and never throws — a failed write degrades this turn to the pre-OPE-1522 in-memory
+ * behaviour rather than breaking a model call. That is also why every property this row carries is
+ * best-effort rather than guaranteed: one dropped write and the next instance re-reads an older
+ * count, or re-reports a crossing the previous one already recorded.
+ */
+export async function writeTurnState(pair, state) {
+    try {
+        // Stamped when the CALLER asked, not when the chain issues the call: this is the row's
+        // `created_at` and therefore its TTL anchor, and a queued write must not read as fresher than the
+        // state it holds. Inside the `try` with everything else — this function never throws.
+        const at = new Date().toISOString();
+        const body = JSON.stringify(state);
+        // Deadline-bounded like the read (OPE-1555): a write nobody is waiting on must not be the thing
+        // that holds a model round-trip open. An abandoned write is still IN FLIGHT — nothing here can
+        // cancel a driver's query — so {@link chainRowCall} keeps the NEXT write behind it rather
+        // than letting the two race (OPE-1564). The deadline still bounds what this caller awaits.
+        await withStoreDeadline(chainRowCall(pair, () => getOperationalStore().putTaskResult(deploymentOrg(), turnStateRowKey(pair), body, at, TURN_STATE_TTL_MS)), undefined);
+    }
+    catch {
+        /* the in-memory caches still bound this turn on THIS instance — see the header */
+    }
+}
+/**
+ * Record that this turn has spent its ONE post into a stood-down conversation, durably (OPE-1551).
+ *
+ * The valve itself lives in an eve `defineState` slot (`channels/reply-signal.ts` §STOPPED), and
+ * that slot is serialized into the TURN STEP's own input and output — so a mid-turn write survives
+ * only if the turn step completes. eve runs a whole turn as ONE durable step and re-runs the
+ * interrupted one, so a turn resumed after an instance change reads the context as it stood at the
+ * turn's START and the valve reads UNSPENT. The post it already made is in the room regardless: a
+ * platform post is not rolled back. This row is the half that survives, exactly as the closeout
+ * latch's is.
+ *
+ * READ-MODIFY-WRITE over the shared row, so `steps` and `closeout` are carried through untouched;
+ * skipped entirely when the read did not complete, for the reason the header states. Never throws —
+ * a valve that cannot be recorded costs one duplicate post, which is the fail-open direction the
+ * reply path already takes.
+ */
+export async function noteStoppedAck(pair) {
+    const state = await readTurnState(pair);
+    if (state === undefined)
+        return;
+    await writeTurnState(pair, { ...state, stoppedAck: true });
+}
+/**
+ * Has this turn already spent its one post into a stood-down conversation, on ANY instance? `false`
+ * whenever the row is absent or could not be read — the same fail-open direction
+ * `wasStoppedAckSpentThisTurn` takes, and for the same reason: silencing the acknowledgement a human
+ * asked for is worse than one duplicate. Never throws.
+ */
+export async function stoppedAckSpent(pair) {
+    return (await readTurnState(pair))?.stoppedAck === true;
+}
+/** Forget one turn's durable state — the other half of `clearTurnStepCount`, and how a test stages a
+ *  turn that has never run at all. Never throws, for the same reason the writer does not.
+ *
+ *  ON THE SAME CHAIN as {@link writeTurnState} (OPE-1564), because it mutates the same row: a delete
+ *  that raced an abandoned write would leave the row RESURRECTED with the bytes the write carried. */
+export async function deleteTurnState(pair) {
+    try {
+        await withStoreDeadline(chainRowCall(pair, () => getOperationalStore().deleteTaskResult(deploymentOrg(), turnStateRowKey(pair))), undefined);
+    }
+    catch {
+        /* a clear that cannot reach the store must not break the caller that asked for it */
+    }
+}
+//# sourceMappingURL=turn-state.js.map

package/dist/agent/model/turn-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-state.js","sourceRoot":"","sources":["../../../agent/model/turn-state.ts"],"names":[],"mappings":"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"}

package/dist/agent/model/vision.d.ts

@@ -0,0 +1,75 @@
+/** One image to describe — raw bytes + their media type, plus an optional focus hint. */
+export interface ImageDescribeRequest {
+    /** The image bytes (already fetched host-side by the tool — never a URL the describer fetches). */
+    readonly bytes: Uint8Array;
+    /** IANA media type, e.g. "image/png" — steers the provider's decode. */
+    readonly mimeType: string;
+    /** Optional caller hint (e.g. the filename or "what does this dashboard show?"). */
+    readonly hint?: string;
+}
+/**
+ * WHAT ONE VISION CALL COST, as the transport observed it (OPE-403) — the reason the vision plane
+ * is not a hole in the spend plane.
+ *
+ * 🔴 WHY THE TRANSPORT REPORTS THIS RATHER THAN STAMPING IT. Every OTHER model call OE makes is
+ * costed from eve's `step.completed` event, whose model id comes from the per-session stamp
+ * (model/model-stamp.ts) that model/routing.ts leaves immediately before the call. A vision call
+ * cannot use that channel twice over: it emits no step event (it is a plain `generateText` inside
+ * a tool's `execute`), and stamping it would CORRUPT the next real step's attribution, because the
+ * vision call runs BETWEEN two steps of the same session and the stamp slot holds only the last
+ * write. So the transport hands its own accounting back with the result, and the tool — which
+ * holds the calling turn's context, and therefore the org/surface/principal/routine/lineage —
+ * writes the attributed rows through hooks/spend.ts's `recordModelCall`.
+ *
+ * OPTIONAL, on purpose: a transport that cannot observe its usage (a local model, a stub) still
+ * satisfies the seam. describe_image warns rather than failing, because a describable image is
+ * worth more than a bookkeeping row — but the warning is what stops the hole being silent again.
+ */
+export interface ImageDescribeUsage {
+    /** The model id that actually ran, as the transport asked for it — the row's `model` column. */
+    readonly model: string;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    /** REASONING tokens this call spent (OPE-1611), when the provider reported them under
+     *  `usage.outputTokenDetails.reasoningTokens`. Absent = unreported, never a zero it did not
+     *  claim. Attribution only — no rate prices it. */
+    readonly reasoningTokens?: number;
+    /** The gateway's own measured cost for this call, USD (`providerMetadata.gateway.cost`). */
+    readonly costUsd?: number;
+    /** The gateway's per-call trace id (`providerMetadata.gateway.generationId`) — the join key
+     *  between this row and the gateway's billing record. */
+    readonly generationId?: string;
+}
+/** The reduction result: a prose description, plus any transcribed on-image text (OCR). */
+export interface ImageDescribeResult {
+    /** A plain-text description of what the image shows (capped by the caller). */
+    readonly description: string;
+    /** Verbatim on-image text, when the image is text-dense (a screenshot/dashboard). Omitted
+     *  when there's no meaningful text. UNTRUSTED like the description — the tool wraps both. */
+    readonly ocrText?: string;
+    /** What the call cost (OPE-403) — see {@link ImageDescribeUsage} for why it rides the RESULT
+     *  rather than the model stamp. Absent ⇒ describe_image warns that this vision spend is
+     *  unattributed, which is the condition OPE-403 existed to end. */
+    readonly usage?: ImageDescribeUsage;
+}
+/**
+ * The image describer the `describe_image` tool calls. A single method; a throw means "could
+ * not describe" (fetch/decode/vision-call errors, and a gateway that will not route the model
+ * under a ZDR-only policy, all propagate as a throw — the tool's fail-closed contract). Mirrors
+ * DreamJudge's transport-behind-a-registry shape.
+ */
+export interface ImageDescriber {
+    describe(req: ImageDescribeRequest): Promise<ImageDescribeResult>;
+}
+/** Register the deploy's vision transport (agent.ts, at boot). A later call replaces it.
+ *  Without this the `describe_image` tool has no backend and fails closed on every call —
+ *  registration IS the "the agent can see images" opt-in, same discipline as the dream judge. */
+export declare function registerImageDescriber(describer: ImageDescriber): void;
+/** The registered describer, or null when none is wired (→ the tool reports it can't see the
+ *  image, never guesses). */
+export declare function getImageDescriber(): ImageDescriber | null;
+/** Test seam: clear the registered describer so a test starts from the unregistered state. */
+export declare function _resetImageDescriberForTest(): void;
+//# sourceMappingURL=vision.d.ts.map

package/dist/agent/model/vision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../../agent/model/vision.ts"],"names":[],"mappings":"AAsBA,yFAAyF;AACzF,MAAM,WAAW,oBAAoB;IACnC,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAkB;IACjC,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;uDAEmD;IACnD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;6DACyD;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;iGAC6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;uEAEmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACnE;AAMD;;iGAEiG;AACjG,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAEtE;AAED;6BAC6B;AAC7B,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,IAAI,CAEzD;AAED,8FAA8F;AAC9F,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/agent/model/vision.js

@@ -0,0 +1,39 @@
+// The image-describer seam (multimodal reduction-to-text). GLM-5.2 — OE's primary — is
+// text-only, and more fundamentally, model context is text: anything non-text is reduced to
+// text (or disk) BEFORE it enters context (memory mcp-context-and-code-mode.md). A vision call
+// is exactly that reduction stage — image bytes → a text description + any OCR — so it rides a
+// registered seam, EXACTLY like the dream cycle's judge (memory/dream/judge.ts): core owns the
+// interface + registry; the vendor transport (image bytes → a multimodal `generateText` call on
+// a gateway model) lives behind this seam in @open-everywhere/adapters
+// (agent/model/gateway-vision.ts). Core never imports a vendor SDK; a self-host swaps the one
+// adapter file to point at a local vLLM Qwen3-VL and nothing else changes.
+//
+// FAIL-CLOSED CONSUMER: tools/describe_image.ts calls getImageDescriber() and, on ANY
+// error OR a missing describer, reports "image could not be described" rather than guessing —
+// a hallucinated screenshot is worse than an admitted blind spot (docs Part B.4). That
+// fail-closed contract is what carries the ZERO-DATA-RETENTION posture, and it is deliberately
+// stated as a property of THIS seam rather than of any one transport's call options: whatever
+// makes a non-ZDR route unavailable — the gateway refusing to route it under a "ZDR models
+// only" org policy (the reference deployment's posture since OPE-323), or a transport that
+// chooses to pin ZDR per call — arrives here as a thrown describe(), and the tool turns it into
+// the same fail-closed message. Tommy's D6 call: for image bytes, failing the description is
+// safer than leaking them. Core states the requirement; where it is enforced is the
+// deployment's choice, not this file's.
+// --- registry (app wires a transport at boot; absent → the tool reports "can't see images") --
+let registered = null;
+/** Register the deploy's vision transport (agent.ts, at boot). A later call replaces it.
+ *  Without this the `describe_image` tool has no backend and fails closed on every call —
+ *  registration IS the "the agent can see images" opt-in, same discipline as the dream judge. */
+export function registerImageDescriber(describer) {
+    registered = describer;
+}
+/** The registered describer, or null when none is wired (→ the tool reports it can't see the
+ *  image, never guesses). */
+export function getImageDescriber() {
+    return registered;
+}
+/** Test seam: clear the registered describer so a test starts from the unregistered state. */
+export function _resetImageDescriberForTest() {
+    registered = null;
+}
+//# sourceMappingURL=vision.js.map

package/dist/agent/model/vision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.js","sourceRoot":"","sources":["../../../agent/model/vision.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,4FAA4F;AAC5F,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAC/F,gGAAgG;AAChG,uEAAuE;AACvE,8FAA8F;AAC9F,2EAA2E;AAC3E,EAAE;AACF,sFAAsF;AACtF,8FAA8F;AAC9F,uFAAuF;AACvF,+FAA+F;AAC/F,8FAA8F;AAC9F,2FAA2F;AAC3F,2FAA2F;AAC3F,gGAAgG;AAChG,6FAA6F;AAC7F,oFAAoF;AACpF,wCAAwC;AAuExC,gGAAgG;AAEhG,IAAI,UAAU,GAA0B,IAAI,CAAC;AAE7C;;iGAEiG;AACjG,MAAM,UAAU,sBAAsB,CAAC,SAAyB;IAC9D,UAAU,GAAG,SAAS,CAAC;AACzB,CAAC;AAED;6BAC6B;AAC7B,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,2BAA2B;IACzC,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC"}