@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/wire/stall.mjs

@@ -0,0 +1,349 @@
+/**
+ * lib/engine/wire/stall.mjs — inter-event idle timeout and stall diagnostics
+ * for a gateway stream (CF-156, client half).
+ *
+ * WHY THIS EXISTS. The W13 live measurement (docs/engine/eval.md §3) found
+ * `cohort-reason` stalling twice in 25 requests: one engine call hung past a
+ * 120 s client timeout (`req_fd528e0c1ab3f8947a77bb66`) and one raw Anthropic
+ * call took 45.5 s (`req_449cafa064e187c22993991e`), against ~1.5 s normally.
+ * Root cause was NOT diagnosed, and a stall left almost nothing behind to
+ * diagnose it with. Two occurrences in 25 requests is not a reproduction
+ * budget, so this module's job is to make the THIRD occurrence self-evident,
+ * and to end it inside the task budget it runs under instead of eating all of
+ * it. (Which budget, and why 180 s is not the dispatcher's, is set out on
+ * DEFAULT_STREAM_IDLE_TIMEOUT_MS below.)
+ *
+ * Two pieces, both usable without a socket:
+ *
+ *   · `withIdleTimeout` — wraps an async iterable of SSE frames and ends it
+ *     when no frame arrives for `idleMs`. The clock is INTER-EVENT, not
+ *     total: a long completion that keeps streaming is never cut off, and a
+ *     stream that goes quiet is. It closes the underlying iterator on the way
+ *     out, so the fetch body is released rather than left reading.
+ *
+ *   · `createStallWatch` — counts what a diagnosis needs (time to first byte,
+ *     time to first event, time since the last event, the last event type,
+ *     whether the terminal `cohort` frame had arrived) and builds a record
+ *     ONLY when asked. Per frame it touches three numbers and a string; the
+ *     record is built on trouble, never on the happy path.
+ *
+ * On keep-alive pings. The gateway sends `:` comment lines every 15 s and
+ * `readSse` drops them, by design — they are the SSE grammar's liveness
+ * filler, not events. So this timer measures silence in EVENTS, which is the
+ * thing that actually stalled: a gateway that keeps pinging while no content
+ * ever arrives is precisely the failure W13 could not tell apart from a slow
+ * model. The cost of that choice is that a tier which legitimately thinks for
+ * longer than `idleMs` without emitting anything would be cut off, which is
+ * why the default sits far above every latency yet measured and why it is
+ * named configuration rather than a constant.
+ *
+ * @module lib/engine/wire/stall
+ */
+
+/**
+ * Longest silence before a stream is called stalled — and, spent across a whole
+ * call rather than re-armed per attempt, the client's bound on a gateway that
+ * never speaks.
+ *
+ * 60 s, derived rather than chosen — and derived from a number this repo owns,
+ * which the first cut of this module did not:
+ *
+ *   · WHAT ACTUALLY BOUNDS A TURN. Earlier drafts of this module, and
+ *     docs/engine/eval.md §3, called 180 s "the dispatcher's task timeout". It
+ *     is not. The live dispatcher times a task out at 10 min to 12 h depending
+ *     on model and source (`scripts/daemon/dispatcher.mjs`,
+ *     `SONNET_INBOX_TIMEOUT` … `OPUS_BACKLOG_TIMEOUT`). The real 180 s in this
+ *     repo is `DEFAULT_TASK_TIMEOUT_MS` (`scripts/eval/replay/lib/config.mjs`),
+ *     the per-task budget of the design §8.4.2 replay eval — and the TIGHTEST
+ *     budget the engine runs a task under here. Deriving against the tightest
+ *     is the conservative choice, and unlike "the dispatcher's 180 s" it is a
+ *     constant this repo owns, so the test pins it by import instead of
+ *     restating a literal.
+ *   · THE BOUND THIS BUYS. A stalled call ends within 2 × this value, never
+ *     more: either the silence budget is spent before acceptance and the call
+ *     returns without resending, or the gateway accepts inside it and then one
+ *     silent inter-event gap ends the stream. 120 s at the default — inside the
+ *     180 s replay budget, and far inside the dispatcher's 10-minute floor.
+ *   · ABOVE EVERY REAL LATENCY. The worst legitimate latency ever recorded
+ *     against this gateway is W13's 45.5 s WHOLE call, and this budget is per
+ *     inter-event gap, which is strictly smaller. It is also well under the
+ *     120 s client timeout that a real stall already ran past.
+ *
+ * It is NOT a bound on a healthy call's total duration, by design: a stream
+ * that keeps emitting events is never cut off, however long it runs.
+ */
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 60_000;
+
+/**
+ * The band a configured budget is held to.
+ *
+ * Below the floor the guard would cut off healthy streams; above the ceiling it
+ * would exceed the very task budget the default is derived from, while still
+ * looking armed. Both are silent failures, so a value outside the band is
+ * clamped and `idleTimeoutNote` says so out loud. `0` (explicitly off) is not
+ * clamped — disabling the guard is a deliberate, documented escape hatch.
+ */
+export const MIN_STREAM_IDLE_TIMEOUT_MS = 5_000;
+/** @see MIN_STREAM_IDLE_TIMEOUT_MS */
+export const MAX_STREAM_IDLE_TIMEOUT_MS = 120_000;
+
+/**
+ * A stream that finished but took longer than this is recorded as `slow`.
+ *
+ * 20 s: above the ~1.5 s typical turn and above the 7.9 s raw
+ * `cohort-reason`/OpenAI call W13 saw, but below the 45.5 s outlier — so the
+ * outlier would have left a record, and ordinary traffic leaves none.
+ */
+export const DEFAULT_SLOW_STREAM_MS = 20_000;
+
+/**
+ * Thrown by `withIdleTimeout` when the silence budget is spent. A marker type
+ * so the HTTP edge can tell a stall from a socket fault without matching on a
+ * message.
+ */
+export class StreamIdleTimeoutSignal extends Error {
+  /** @param {number} idleMs */
+  constructor(idleMs) {
+    super(`no SSE event for ${idleMs}ms`);
+    this.name = "StreamIdleTimeoutSignal";
+    /** @type {number} */
+    this.idleMs = idleMs;
+  }
+}
+
+/**
+ * Parse a configured idle timeout. Accepts milliseconds; `0`, `off`, `false`
+ * and `none` disable the timer (0). Anything unparseable keeps the default, so
+ * a typo in the environment loosens nothing silently — it just does not apply.
+ * A finite value outside {@link MIN_STREAM_IDLE_TIMEOUT_MS} …
+ * {@link MAX_STREAM_IDLE_TIMEOUT_MS} is CLAMPED into the band: a 1 ms budget
+ * that cuts off every healthy stream and a 10-minute one that outlives the task
+ * it is protecting both look armed and are both useless. Pair with
+ * {@link idleTimeoutNote} so the adjustment is visible rather than silent.
+ *
+ * @param {unknown} value
+ * @param {number} [fallback]
+ * @returns {number} milliseconds, or 0 for "no timeout"
+ */
+export function parseIdleTimeoutMs(value, fallback = DEFAULT_STREAM_IDLE_TIMEOUT_MS) {
+  const raw = String(value ?? "").trim().toLowerCase();
+  if (raw === "") return fallback;
+  if (["0", "off", "false", "no", "none"].includes(raw)) return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return Math.min(MAX_STREAM_IDLE_TIMEOUT_MS, Math.max(MIN_STREAM_IDLE_TIMEOUT_MS, Math.round(n)));
+}
+
+/**
+ * The one line to print when a configured budget was not taken at face value —
+ * either it did not parse, or it was clamped into the band. `null` when the
+ * value was empty, an explicit "off", or applied exactly as written.
+ *
+ * Separate from {@link parseIdleTimeoutMs} so that function stays pure and
+ * total: the parse has no seam to warn through, and the CLI does.
+ *
+ * @param {unknown} value the raw configured value
+ * @param {number} [applied] what {@link parseIdleTimeoutMs} returned for it
+ * @returns {string|null}
+ */
+export function idleTimeoutNote(value, applied = parseIdleTimeoutMs(value)) {
+  const raw = String(value ?? "").trim();
+  if (raw === "") return null;
+  const lower = raw.toLowerCase();
+  if (["0", "off", "false", "no", "none"].includes(lower)) return null;
+  const n = Number(lower);
+  if (!Number.isFinite(n) || n <= 0) {
+    return `COHORT_LLM_STREAM_IDLE_TIMEOUT_MS=${raw} is not a number of milliseconds; using ${applied}ms`;
+  }
+  if (Math.round(n) === applied) return null;
+  return (
+    `COHORT_LLM_STREAM_IDLE_TIMEOUT_MS=${raw} is outside the ` +
+    `${MIN_STREAM_IDLE_TIMEOUT_MS}–${MAX_STREAM_IDLE_TIMEOUT_MS}ms band; using ${applied}ms`
+  );
+}
+
+/**
+ * Yield an async iterable's values, failing with {@link StreamIdleTimeoutSignal}
+ * when more than `idleMs` passes between them.
+ *
+ * The underlying iterator is closed in a `finally`, so a stalled fetch body is
+ * cancelled rather than left pending. A non-positive or non-finite `idleMs`
+ * passes straight through with no timer at all.
+ *
+ * @template T
+ * @param {AsyncIterable<T>} source
+ * @param {number} idleMs
+ * @param {{ setTimer?: typeof setTimeout, clearTimer?: typeof clearTimeout }} [deps]
+ * @returns {AsyncGenerator<T>}
+ */
+export async function* withIdleTimeout(source, idleMs, deps = {}) {
+  if (!Number.isFinite(idleMs) || idleMs <= 0) {
+    yield* source;
+    return;
+  }
+  const setTimer = deps.setTimer ?? setTimeout;
+  const clearTimer = deps.clearTimer ?? clearTimeout;
+  const it = source[Symbol.asyncIterator]();
+  try {
+    for (;;) {
+      const next = it.next();
+      // The loser of the race is orphaned: keep it from becoming an unhandled
+      // rejection when the timer wins and the socket errors afterwards.
+      next.catch(() => {});
+      /** @type {any} */
+      let timer;
+      const idle = new Promise((_resolve, reject) => {
+        timer = setTimer(() => reject(new StreamIdleTimeoutSignal(idleMs)), idleMs);
+      });
+      idle.catch(() => {});
+      let step;
+      try {
+        step = await Promise.race([next, idle]);
+      } finally {
+        clearTimer(timer);
+      }
+      if (step.done) return;
+      yield step.value;
+    }
+  } finally {
+    // NEVER await this. An async generator suspended at an un-resolving
+    // `await` — which is exactly what a stalled fetch body is — only processes
+    // `return()` when it next resumes, so awaiting here would hang on the very
+    // stall just detected. Ask it to close and move on; releasing the socket
+    // is the caller's job (wire/http.mjs cancels the response body).
+    try {
+      void Promise.resolve(it.return?.()).catch(() => {});
+    } catch {
+      /* a source with no return() needs no closing */
+    }
+  }
+}
+
+/**
+ * @typedef {Object} StreamDiagnostic
+ * @property {'stalled'|'failed'|'slow'} outcome
+ * @property {string|null} requestId      x-cohort-request-id (or the cohort frame's)
+ * @property {string|null} wire           'openai' | 'anthropic'
+ * @property {string|null} tier           the model tier asked for
+ * @property {boolean} accepted           the gateway had returned 2xx
+ * @property {number|null} ttfbMs         request start → response headers
+ * @property {number|null} firstEventMs   response headers → first SSE event
+ * @property {number|null} sinceLastEventMs  last SSE event → now (the silence)
+ * @property {number} events              SSE events seen (the cohort frame included)
+ * @property {string|null} lastEventType  the last event name seen
+ * @property {boolean} cohortFrameSeen    the terminal `event: cohort` frame had arrived
+ * @property {number} totalMs             THIS ATTEMPT's start → now
+ * @property {number} callMs              the whole call's start → now (every attempt and backoff sleep included)
+ * @property {number} attempts            attempts made on this call (1 unless the gateway was retried)
+ * @property {string|null} code           the wire error's code, when it failed
+ * @property {string|null} message        the wire error's message, when it failed.
+ *   MAY CONTAIN CONTENT: a protocol error quotes the offending stream chunk
+ *   (see `openai-chat.mjs` / `anthropic-messages.mjs`), which is up to 120
+ *   characters of a tenant's completion. `formatStreamDiagnostic` omits it; any
+ *   other observer that forwards a record off this machine must redact it.
+ */
+
+/**
+ * Count what diagnosing a stall needs. Cheap per frame; the record is built
+ * only when `report` is called, which the HTTP edge does on a stall, on a
+ * mid-stream fault, and on a stream slower than its `slow` threshold.
+ *
+ * `startedAt` is THIS ATTEMPT's start, so every timing in the record describes
+ * the attempt that actually ran; `callStartedAt` (defaulting to it) is the
+ * whole call's, so a record can never be read as describing more than it does.
+ * The two differ only after a retry, and `attempts` says when that happened —
+ * a record labelled `slow` that describes a 3 ms stream was exactly the
+ * confusion this separation removes.
+ *
+ * @param {{ now: () => number, startedAt: number, callStartedAt?: number, attempts?: number, wire?: string|null, tier?: string|null }} p
+ */
+export function createStallWatch({ now, startedAt, callStartedAt = startedAt, attempts: attemptCount = 1, wire = null, tier = null }) {
+  let acceptedAt = /** @type {number|null} */ (null);
+  let firstEventAt = /** @type {number|null} */ (null);
+  let lastEventAt = /** @type {number|null} */ (null);
+  let lastEventType = /** @type {string|null} */ (null);
+  let events = 0;
+  let cohortFrameSeen = false;
+
+  return {
+    /** The gateway answered 2xx: headers are in, the body is open. */
+    accepted() {
+      acceptedAt = now();
+    },
+    /** One SSE frame arrived. @param {{event?:string}} frame */
+    event(frame) {
+      events++;
+      lastEventAt = now();
+      if (firstEventAt === null) firstEventAt = lastEventAt;
+      lastEventType = frame?.event || "message";
+    },
+    /** The terminal `event: cohort` frame arrived. */
+    cohortFrame() {
+      cohortFrameSeen = true;
+    },
+    get cohortFrameSeen() {
+      return cohortFrameSeen;
+    },
+    /**
+     * @param {{ outcome:'stalled'|'failed'|'slow', requestId?:string|null, accepted?:boolean, attempts?:number, error?:{code?:string, message?:string}|null }} p
+     * @returns {StreamDiagnostic}
+     */
+    report({ outcome, requestId = null, accepted = acceptedAt !== null, attempts = attemptCount, error = null }) {
+      const at = now();
+      return {
+        outcome,
+        requestId,
+        wire,
+        tier,
+        accepted,
+        ttfbMs: acceptedAt === null ? null : acceptedAt - startedAt,
+        firstEventMs: firstEventAt === null || acceptedAt === null ? null : firstEventAt - acceptedAt,
+        sinceLastEventMs: lastEventAt === null ? (acceptedAt === null ? null : at - acceptedAt) : at - lastEventAt,
+        events,
+        lastEventType,
+        cohortFrameSeen,
+        totalMs: at - startedAt,
+        callMs: at - callStartedAt,
+        attempts,
+        code: error?.code ?? null,
+        message: error?.message ?? null,
+      };
+    },
+  };
+}
+
+/**
+ * One stderr line for a diagnostic.
+ *
+ * THIS LINE carries only ids, timings and event names — never a token, a prompt
+ * or a completion — because it goes to a seat's log. That promise is this
+ * function's, not the record's: `StreamDiagnostic.message` can quote a stream
+ * chunk, so `message` is deliberately omitted here and any other observer must
+ * redact it itself.
+ *
+ * `total` is this attempt; `call` and `attempts` appear only when the gateway
+ * was retried, so a record can never be read as describing more than it does.
+ *
+ * @param {StreamDiagnostic} d
+ * @returns {string}
+ */
+export function formatStreamDiagnostic(d) {
+  const retried = (d.attempts ?? 1) > 1;
+  const parts = [
+    `stream ${d.outcome}`,
+    d.wire ? `wire=${d.wire}` : null,
+    d.tier ? `tier=${d.tier}` : null,
+    `request=${d.requestId ?? "unknown"}`,
+    d.ttfbMs == null ? null : `ttfb=${d.ttfbMs}ms`,
+    d.firstEventMs == null ? null : `first-event=${d.firstEventMs}ms`,
+    d.sinceLastEventMs == null ? null : `silent=${d.sinceLastEventMs}ms`,
+    `events=${d.events}`,
+    `last-event=${d.lastEventType ?? "none"}`,
+    `cohort-frame=${d.cohortFrameSeen ? "yes" : "no"}`,
+    `total=${d.totalMs}ms`,
+    retried ? `call=${d.callMs}ms` : null,
+    retried ? `attempts=${d.attempts}` : null,
+    d.code ? `code=${d.code}` : null,
+  ].filter(Boolean);
+  return parts.join(" ");
+}

package/lib/engine/wire/token-provider.mjs

@@ -0,0 +1,175 @@
+/**
+ * lib/engine/wire/token-provider.mjs — the gateway credential for a run that
+ * may outlive its seat token.
+ *
+ * A seat token (`cst_…`) is short-lived. A headless run finishes well inside
+ * its life, but a `cohort session` front door runs for days, so the engine
+ * must not read `COHORT_LLM_TOKEN` once and keep it. In order:
+ *
+ *   COHORT_LLM_TOKEN_HELPER   a shell command that prints a fresh token on its
+ *                             first stdout line (maestro sets it to
+ *                             scripts/cohort-llm/api-key-helper.mjs). Its token
+ *                             is cached for COHORT_LLM_TOKEN_TTL_MS (default 10
+ *                             minutes) and the command runs again when the
+ *                             cache has aged out or the gateway answered 401
+ *                             (`{refresh:true}` from wire/http.mjs).
+ *   COHORT_LLM_TOKEN          the token itself. With a helper it seeds the cache
+ *                             (the adapter minted it at spawn), so a short run
+ *                             never forks the helper; without one it is used as
+ *                             given, as before.
+ *
+ * The provider returns what the wire takes: a string (env only) or a token
+ * function (helper). Concurrent refreshes share one helper run. The helper's
+ * output never reaches an error message; only its exit and its stderr's first
+ * line do.
+ *
+ * Re-mints after a 401 are bounded (CF-136): a refresh naming a `rejected`
+ * token that the cache has already replaced returns the replacement with no
+ * helper run; the helper is told the rejected token's fingerprint
+ * (COHORT_LLM_TOKEN_REJECTED_FP) so the seat's manager mints only when its own
+ * token is the refused one; and at most MAX_REFRESHES_PER_WINDOW re-mints run
+ * per REFRESH_WINDOW_MS — past that the token function throws, which the wire
+ * returns as a non-retryable `token_unavailable`. Only a 401 asks for a
+ * refresh: a 429 or a 503 never reaches this provider's refresh path.
+ *
+ * @module lib/engine/wire/token-provider
+ */
+
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+
+export const DEFAULT_TOKEN_TTL_MS = 10 * 60 * 1000;
+export const TOKEN_HELPER_TIMEOUT_MS = 20_000;
+
+/** @param {Record<string,string|undefined>} env */
+export function tokenTtlMs(env) {
+  const n = Number(env.COHORT_LLM_TOKEN_TTL_MS);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_TOKEN_TTL_MS;
+}
+
+/**
+ * Run a helper command in /bin/sh and resolve its stdout.
+ * @param {string} command
+ * @param {{env:Record<string,string|undefined>, timeoutMs?:number}} o
+ * @returns {Promise<string>}
+ */
+export function runShellTokenHelper(command, { env, timeoutMs = TOKEN_HELPER_TIMEOUT_MS }) {
+  return new Promise((resolve, reject) => {
+    execFile("/bin/sh", ["-c", command], { env: /** @type any */ (env), timeout: timeoutMs, maxBuffer: 64 * 1024, encoding: "utf8" }, (err, stdout, stderr) => {
+      if (err) {
+        const why = String(stderr || "").split(/\r?\n/).find((l) => l.trim() !== "") ?? (/** @type any */ (err).killed ? "timed out" : err.message);
+        reject(new Error(`COHORT_LLM_TOKEN_HELPER failed: ${why.slice(0, 300)}`));
+        return;
+      }
+      resolve(String(stdout));
+    });
+  });
+}
+
+/**
+ * @typedef {{refresh?:boolean, rejected?:string}} TokenRequest
+ * @typedef {{ok:true, source:'env'|'helper', token:string|((o?:TokenRequest)=>Promise<string>), helperRuns:()=>number}
+ *         | {ok:false, error:{code:'missing_token', message:string}}} TokenProvider
+ */
+
+/**
+ * @param {object} p
+ * @param {Record<string,string|undefined>} p.env
+ * @param {() => number} [p.now]
+ * @param {(command:string, o:{env:Record<string,string|undefined>}) => Promise<string>} [p.runHelper]
+ * @param {{max?:number, windowMs?:number}} [p.refreshCaps]  overrides DEFAULT_REFRESH_CAPS
+ * @returns {TokenProvider}
+ */
+export function createTokenProvider({ env, now = Date.now, runHelper = runShellTokenHelper, refreshCaps = {} }) {
+  const caps = { ...DEFAULT_REFRESH_CAPS, ...refreshCaps };
+  const helper = String(env.COHORT_LLM_TOKEN_HELPER ?? "").trim();
+  const envToken = String(env.COHORT_LLM_TOKEN ?? "").trim();
+  if (!helper && !envToken) {
+    return { ok: false, error: { code: "missing_token", message: "no gateway credential: set COHORT_LLM_TOKEN (or COHORT_LLM_TOKEN_HELPER)" } };
+  }
+  if (!helper) return { ok: true, source: "env", token: envToken, helperRuns: () => 0 };
+
+  const ttl = tokenTtlMs(env);
+  /** @type {{token:string, at:number}|null} */
+  let cached = envToken ? { token: envToken, at: now() } : null;
+  /** @type {Promise<string>|null} */
+  let inflight = null;
+  let runs = 0;
+  /** @type {number[]} when each 401-driven re-mint started (the refresh window) */
+  let refreshes = [];
+
+  /** @param {string|null} rejectedToken */
+  const mint = async (rejectedToken) => {
+    runs++;
+    // The helper learns WHICH token was refused (a fingerprint, never the token),
+    // so its seat manager re-mints only when its cached token is that one.
+    const helperEnv = rejectedToken ? { ...env, [REJECTED_TOKEN_FP_ENV]: tokenFingerprint(rejectedToken) } : env;
+    const out = await runHelper(helper, { env: helperEnv });
+    const fresh = String(out).split(/\r?\n/)[0].trim();
+    if (!fresh) throw new Error("COHORT_LLM_TOKEN_HELPER printed no token");
+    cached = { token: fresh, at: now() };
+    return fresh;
+  };
+
+  return {
+    ok: true,
+    source: "helper",
+    helperRuns: () => runs,
+    /** @param {TokenRequest} [o] */
+    token: async ({ refresh = false, rejected } = {}) => {
+      if (!refresh) {
+        if (cached && now() - cached.at < ttl) return cached.token;
+        if (!inflight) inflight = mint(null).finally(() => (inflight = null));
+        return inflight;
+      }
+      // A 401. A concurrent request may already have replaced the rejected token.
+      if (rejected && cached && cached.token !== rejected && now() - cached.at < ttl) return cached.token;
+      if (inflight) return inflight;
+      const t = now();
+      const budget = refreshBudget(refreshes, t, caps);
+      refreshes = budget.recent;
+      if (!budget.allowed) {
+        throw new Error(`COHORT_LLM_TOKEN_HELPER re-mint capped: ${caps.max} refreshes after a 401 within ${Math.round(caps.windowMs / 1000)}s; the gateway keeps refusing fresh tokens`);
+      }
+      refreshes.push(t);
+      const rejectedToken = rejected || (cached ? cached.token : null);
+      cached = null; // a rejected token is never served again
+      inflight = mint(rejectedToken).finally(() => (inflight = null));
+      return inflight;
+    },
+  };
+}
+
+/** Env var naming the fingerprint of the token a 401 rejected (read by maestro's api-key-helper). */
+export const REJECTED_TOKEN_FP_ENV = "COHORT_LLM_TOKEN_REJECTED_FP";
+/** A 401-driven re-mint may run at most MAX_REFRESHES_PER_WINDOW times per REFRESH_WINDOW_MS. */
+export const REFRESH_WINDOW_MS = 60_000;
+export const MAX_REFRESHES_PER_WINDOW = 3;
+/**
+ * The engine's re-mint cap as one named config (CF-143). The values are the W7
+ * defaults, pending owner confirmation; `createTokenProvider({ refreshCaps })`
+ * overrides them. docs/engine/README.md "Retry caps" lists every cap.
+ */
+export const DEFAULT_REFRESH_CAPS = Object.freeze({ max: MAX_REFRESHES_PER_WINDOW, windowMs: REFRESH_WINDOW_MS });
+
+/**
+ * sha256 of a token, first 16 hex chars — the same shape as lib/org/llm-token.mjs
+ * `keyFingerprint`, so the helper compares like with like.
+ * @param {string} token
+ */
+export function tokenFingerprint(token) {
+  return createHash("sha256").update(String(token || "")).digest("hex").slice(0, 16);
+}
+
+/**
+ * The sliding-window re-mint budget. PURE.
+ * @param {number[]} history  start times of earlier re-mints
+ * @param {number} nowMs
+ * @param {{max?:number, windowMs?:number}} [o]
+ * @returns {{allowed:boolean, recent:number[], retryAt:number|null}}
+ */
+export function refreshBudget(history, nowMs, { max = MAX_REFRESHES_PER_WINDOW, windowMs = REFRESH_WINDOW_MS } = {}) {
+  const recent = (Array.isArray(history) ? history : []).filter((at) => Number.isFinite(at) && at > nowMs - windowMs && at <= nowMs).sort((a, b) => a - b);
+  if (recent.length < max) return { allowed: true, recent, retryAt: null };
+  return { allowed: false, recent, retryAt: recent[recent.length - max] + windowMs };
+}