@visual-z/xeno 0.1.0

package/src/runtime/recall-trial.ts

@@ -0,0 +1,226 @@
+/**
+ * F2 delayed recall across three harnesses behind one metered gateway.
+ *
+ * Each page is deleted when its stage ends, so a later question can only be
+ * answered from what the harness itself retained. The arms differ in exactly
+ * that: xeno keeps a lossless log with a `history` reader; the ablation keeps
+ * the same windowed projection without the reader; Pi keeps its own compaction
+ * summary. See docs/tasks/bench-recall-runner.md.
+ */
+import { appendFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { recallCodes, recallPrompt, verifyRecallAnswer, type RecallFixture, type RecallKind, type RecallVerdict } from "../core/recall-trial.ts";
+import type { BenchmarkPrice, BenchmarkUsage } from "../core/benchmark.ts";
+import { Session } from "./loop.ts";
+import { OpenAICompletionsProvider } from "./openai.ts";
+import type { ProviderConfig, ToolSchema } from "./provider.ts";
+import { COMPARISON_SYSTEM, COMPARISON_TOOLS, comparisonGateway, runPiPrompt, type ComparisonBackend, type ComparisonLedger, type GatewayRecord, type PiIdentity } from "./harness-comparison.ts";
+import { DEFAULT_TOOL_CONTEXT, TOOL_SCHEMAS, runTool } from "./tools.ts";
+
+export const RECALL_ARMS = ["xeno", "xeno-nohistory", "pi"] as const;
+export type RecallArm = typeof RECALL_ARMS[number];
+
+/** Native memory tools are the independent variable; everything else is shared. */
+export function recallToolNames(arm: RecallArm): readonly string[] {
+  return arm === "xeno" ? [...COMPARISON_TOOLS, "history", "note"] : COMPARISON_TOOLS;
+}
+export const recallTools = (arm: RecallArm): ToolSchema[] =>
+  recallToolNames(arm).map((name) => TOOL_SCHEMAS.find((tool) => tool.name === name)!);
+
+export interface RecallStageResult {
+  stage: number; kind: RecallKind; source: number; distance: number;
+  /** A context boundary (xeno cut / Pi compaction) separated the source page from the answer. */
+  crossed: boolean;
+  /**
+   * The expected code was in the first request of this stage. A crossed
+   * boundary does not imply loss (xeno retains recent exchanges, a Pi summary
+   * may copy a code); this measures loss on the wire, identically per arm.
+   */
+  visibleAtAsk: boolean | null;
+  /** Visible in every task request of the stage; a mid-stage boundary can evict it after the ask. Null for recent. */
+  visibleThroughout: boolean | null;
+  status: "answered" | "stopped" | "error"; reason: string; verdict: RecallVerdict;
+  requests: number; pageReads: number; historyCalls: number; boundariesAfter: number;
+}
+export interface RecallTrialResult {
+  arm: RecallArm; planned: number; unrun: number; stages: RecallStageResult[];
+  toolNames: string[]; boundaries: number; requests: number;
+  knownCost: number; reservedUnknown: number; usage: BenchmarkUsage; peakPrompt: number;
+  /** Files other than answers the model created: its own notes, reported separately. */
+  modelFiles: string[];
+  /** Workspace copies of deleted pages; must be empty for the stage to count as observed-once. */
+  leakedPages: string[];
+  stopped: "budget" | "balance" | "error" | "limit" | null; wallMs: number;
+}
+
+const sha = (body: string) => createHash("sha256").update(body).digest("hex");
+
+async function listFiles(root: string): Promise<string[]> {
+  const out: string[] = [];
+  for (const entry of await readdir(root, { withFileTypes: true, recursive: true })) {
+    if (entry.isFile()) out.push(relative(root, join(entry.parentPath, entry.name)));
+  }
+  return out.sort();
+}
+
+export async function runRecallTrial(options: {
+  directory: string; fixture: RecallFixture; arm: RecallArm;
+  config: ProviderConfig; price: BenchmarkPrice; ledger: ComparisonLedger; backend: ComparisonBackend;
+  maxTurnsPerStage: number; stageTimeoutMs: number;
+  pi: PiIdentity | null; extension: string;
+  /** Synthetic pressure only; live trials keep Pi's default compaction. */
+  piCompaction?: { reserveTokens: number; keepRecentTokens: number };
+  onProgress?: (event: Record<string, unknown>) => Promise<void>;
+}): Promise<RecallTrialResult> {
+  const { fixture, arm } = options, started = performance.now();
+  const workspace = join(options.directory, "workspace"), outputStore = join(options.directory, "observations");
+  await mkdir(workspace, { recursive: true }); await mkdir(outputStore, { recursive: true });
+  const tools = recallTools(arm), allow = recallToolNames(arm);
+  const result: RecallTrialResult = { arm, planned: fixture.pages.length, unrun: fixture.pages.length, stages: [],
+    toolNames: [...allow], boundaries: 0, requests: 0, knownCost: 0, reservedUnknown: 0,
+    usage: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 }, peakPrompt: 0,
+    modelFiles: [], leakedPages: [], stopped: null, wallMs: 0 };
+  let stage = 0, pageReads = 0, historyCalls = 0, stageTaskRequests = 0;
+  let seen: boolean[] = [];
+  const page = () => fixture.pages[stage]!;
+  const countCall = (name: string, input: unknown) => {
+    if (name === "history") historyCalls++;
+    if (name === "read" && input !== null && typeof input === "object" && (input as Record<string, unknown>)["path"] === page().path) pageReads++;
+  };
+  const toolContext = { ...DEFAULT_TOOL_CONTEXT, root: workspace, allow, outputStore };
+  const gateway = comparisonGateway({ config: options.config, price: options.price, ledger: options.ledger, tools,
+    // Pi's summary calls share this ceiling; the slack keeps them from starving task turns.
+    maxRequests: (options.maxTurnsPerStage + 2) * fixture.pages.length,
+    // The same per-stage cap for every arm: Session enforces maxTurns itself,
+    // Pi has no such flag, so the gateway refuses its excess task requests.
+    admit: (hasTools) => !hasTools || stageTaskRequests++ < options.maxTurnsPerStage,
+    backend: (payload, signal) => {
+      // Summary calls carry no tools; only a task turn shows what the model sees.
+      if (Array.isArray(payload["tools"])) seen.push(JSON.stringify(payload["messages"]).replaceAll("\\", "").includes(page().question.expected));
+      return options.backend(payload, signal);
+    },
+    executeTool: (name, input) => { countCall(name, input); return runTool(toolContext, name, input); },
+    record: async (record: GatewayRecord) => {
+      await appendFile(join(options.directory, "requests.jsonl"), JSON.stringify({ stage, ...record }) + "\n");
+      if (record.kind === "settled") {
+        result.requests++;
+        if (record.measured === null) result.reservedUnknown += record.charge; else result.knownCost += record.measured;
+        if (record.usage) {
+          for (const key of Object.keys(result.usage) as (keyof BenchmarkUsage)[]) result.usage[key] += record.usage[key];
+          result.peakPrompt = Math.max(result.peakPrompt, record.usage.input_tokens + record.usage.cache_read_input_tokens);
+        }
+      }
+      await options.onProgress?.({ phase: record.kind, arm, stage, request: record.request, measured: record.measured, failure: record.failure });
+    } });
+  const config = { ...options.config, spec: { ...options.config.spec, baseUrl: gateway.url } };
+  const codes = recallCodes(fixture), boundaryAfter: number[] = [];
+  let session: Session | null = null;
+  try {
+    if (arm !== "pi") {
+      await mkdir(join(options.directory, "log"));
+      const provider = new OpenAICompletionsProvider(config, gateway.token, { retry: { maxRetries: 0, maxRetryDelayMs: 0 } });
+      session = new Session({ logDir: join(options.directory, "log"), frozen: { system: COMPARISON_SYSTEM, tools },
+        tools: toolContext, contextPolicy: "windowed", maxTurns: options.maxTurnsPerStage, harnessReviews: false }, provider);
+      await session.start();
+    } else if (!options.pi) throw new Error("Pi identity required");
+    for (const current of fixture.pages) {
+      if (options.ledger.halted || gateway.stopped) break;
+      stage = current.stage; pageReads = 0; historyCalls = 0; seen = []; stageTaskRequests = 0;
+      const file = join(workspace, current.path);
+      await mkdir(dirname(file), { recursive: true }); await mkdir(join(workspace, "answers"), { recursive: true });
+      await writeFile(file, current.body, { flag: "wx" });
+      const requestsBefore = result.requests, signal = AbortSignal.timeout(options.stageTimeoutMs);
+      let status: RecallStageResult["status"] = "stopped", reason = "no completion";
+      try {
+        if (session) {
+          for await (const event of session.send(recallPrompt(fixture, stage), signal)) {
+            if (event.kind === "cut") result.boundaries++;
+            if (event.kind === "tool_call" && event.tool) countCall(event.tool.name, event.tool.input);
+            if (event.kind === "done") reason = event.reason ?? "unknown completion";
+          }
+          if (["stop", "end_turn"].includes(reason)) status = "answered";
+        } else {
+          const run = await runPiPrompt({ directory: options.directory, workspace, prompt: recallPrompt(fixture, stage), config,
+            gateway, price: options.price, pi: options.pi!, extension: options.extension, signal, resume: stage > 0, tools,
+            ...(options.piCompaction ? { piCompaction: options.piCompaction } : {}) });
+          result.boundaries += run.cuts; reason = run.reason; status = run.answered ? "answered" : "error";
+        }
+      } catch {
+        status = "error"; reason = signal.aborted ? "stage deadline" : gateway.stopped ? `model gateway: ${gateway.stopped}` : "stage failed";
+      }
+      boundaryAfter[stage] = result.boundaries;
+      const answer = await readFile(join(workspace, current.answerPath), "utf8").catch(() => null);
+      const verdict = verifyRecallAnswer(answer, current.question, codes);
+      await rm(file);
+      const { question } = current;
+      const row: RecallStageResult = { stage, kind: question.kind, source: question.source, distance: stage - question.source,
+        crossed: question.source < stage && result.boundaries > boundaryAfter[question.source]!,
+        visibleAtAsk: question.source === stage || seen.length === 0 ? null : seen[0]!,
+        visibleThroughout: question.source === stage || seen.length === 0 ? null : seen.every(Boolean),
+        status, reason, verdict, requests: result.requests - requestsBefore, pageReads, historyCalls, boundariesAfter: result.boundaries };
+      result.stages.push(row); result.unrun = result.planned - result.stages.length;
+      await writeFile(join(options.directory, `stage-${String(stage).padStart(3, "0")}.json`),
+        JSON.stringify({ ...row, answer }, null, 2) + "\n", { flag: "wx" });
+      await options.onProgress?.({ phase: "stage", arm, stage, verdict: verdict.reason, crossed: row.crossed, boundaries: result.boundaries });
+    }
+  } finally { await gateway.close(); }
+  const files = await listFiles(workspace), bodies = new Set(fixture.pages.map((p) => sha(p.body)));
+  result.modelFiles = files.filter((path) => !path.startsWith("answers/") && !path.startsWith("incoming/"));
+  for (const path of files) if (bodies.has(sha(await readFile(join(workspace, path), "utf8")))) result.leakedPages.push(path);
+  result.stopped = gateway.stopped; result.wallMs = performance.now() - started;
+  await writeFile(join(options.directory, "result.json"), JSON.stringify(result, null, 2) + "\n", { flag: "wx" });
+  return result;
+}
+
+/**
+ * Mechanical backend: answers only from what the request actually shows.
+ *
+ * It cannot remember across requests, so a code it finds proves the
+ * information was in that projection (or recovered by history). Its summary
+ * text for Pi is invented here, which is why nothing it produces is a score.
+ */
+export function recallMechanicalBackend(): ComparisonBackend {
+  let id = 0;
+  return async (payload) => {
+    const messages = payload["messages"] as Record<string, unknown>[], tools = payload["tools"] as { function: { name: string } }[] | undefined;
+    const reply = (content: string | null, call?: { name: string; input: unknown }) => ({
+      id: `recall-mock-${++id}`, object: "chat.completion", created: 1, model: "recall-mechanical",
+      choices: [{ index: 0, finish_reason: call ? "tool_calls" : "stop", message: { role: "assistant", content,
+        ...(call ? { tool_calls: [{ id: `call-${id}`, type: "function", function: { name: call.name, arguments: JSON.stringify(call.input) } }] } : {}) } }],
+      usage: { prompt_tokens: Math.ceil(JSON.stringify([tools ?? [], messages]).length / 3.6), completion_tokens: 64, prompt_cache_hit_tokens: 0 },
+    });
+    if (!tools) return reply("Checkpoint: staged pages processed and answers written.");
+    const text = (m: Record<string, unknown>) => typeof m["content"] === "string" ? m["content"] : JSON.stringify(m["content"] ?? "");
+    const at = messages.findLastIndex((m) => m["role"] === "user" && /Stage \d+: read /.test(text(m)));
+    // After a cut the current request can sit inside a handoff that also quotes
+    // earlier stages; the latest quoted stage is the active one.
+    const asks = [...text(messages[at]!).matchAll(/read (\S+) in full\. Question: what is the current code of ticket (T-\d{5})\? Write only the code to (\S+),/g)];
+    const [, path, ticket, answerPath] = asks.at(-1)!;
+    const calls = messages.slice(at + 1).flatMap((m) => (m["tool_calls"] as { function: { name: string; arguments: string } }[] | undefined) ?? [])
+      .map((c) => ({ name: c.function.name, input: JSON.parse(c.function.arguments) as Record<string, unknown> }));
+    if (calls.some((c) => c.name === "write")) return reply("Stage done.");
+    if (!calls.some((c) => c.name === "read" && c.input["path"] === path)) return reply(null, { name: "read", input: { path } });
+    // Backslashes vanish so nested JSON (history results) matches the same way.
+    const visible = JSON.stringify(messages).replaceAll("\\", "");
+    const pattern = new RegExp(`"ticket":"${ticket}","code":"(K-[0-9a-f]{12})"`, "g");
+    // Search results are newest first, so the first hit there is the latest code;
+    // in the conversation itself the last occurrence is the latest.
+    const search = messages.slice(at + 1).findLast((m) => m["role"] === "tool" && text(m).includes('"matches"'));
+    const found = (search ? [...text(search).replaceAll("\\", "").matchAll(pattern)][0]?.[1] : undefined)
+      ?? [...visible.matchAll(pattern)].at(-1)?.[1];
+    if (found) return reply(null, { name: "write", input: { path: answerPath, content: found } });
+    const names = new Set(tools.map((t) => t.function.name));
+    const history = calls.filter((c) => c.name === "history");
+    if (names.has("history") && history.length === 0) return reply(null, { name: "history", input: { query: ticket } });
+    if (names.has("history") && history.length === 1) {
+      // Pick an observation that read a page; the question prompt also matches the ticket.
+      const result = messages.slice(at + 1).findLast((m) => m["role"] === "tool" && text(m).includes('"matches"'));
+      let items: { event: string; tool?: string }[] = [];
+      try { items = (JSON.parse(text(result ?? {})) as { items: typeof items }).items; } catch { /* not a search page */ }
+      const event = items.find((item) => item.tool === "read")?.event;
+      if (event) return reply(null, { name: "history", input: { event } });
+    }
+    return reply(null, { name: "write", input: { path: answerPath, content: "UNKNOWN" } });
+  };
+}

package/src/runtime/resume.ts

@@ -0,0 +1,66 @@
+/**
+ * Picking a session back up where it stopped.
+ *
+ * Pure: it decides, given a recorded cursor and the model about to run, what
+ * should happen. Doing the reading and the refusing in separate places keeps
+ * the one interesting rule -- when a resume is unsafe -- testable without a
+ * filesystem.
+ */
+
+import type { Cursor } from "../store/log.ts";
+
+export type ResumePlan =
+  | { kind: "fresh" }
+  | { kind: "resume"; cursor: Cursor }
+  | { kind: "refuse"; reason: string };
+
+/**
+ * A session's thinking blocks belong to the model that produced them.
+ *
+ * Every provider this harness talks to requires them replayed unchanged, and
+ * the two do not use the same representation at all: DeepSeek carries
+ * `reasoning_content`, Anthropic carries a signed block. Handing one to the
+ * other is a bad request, and it would surface on the first turn of the
+ * resumed session rather than here.
+ *
+ * Refusing rather than converting is the point. pi converts, wrapping a
+ * foreign thinking trace in `<thinking>` tags inside assistant content -- a
+ * lossy, opinionated rewrite of what the model is told happened. This
+ * project's position is that the context is a recomputable projection of the
+ * log, so a resume that silently rewrites history breaks the one property
+ * everything else rests on. The log is intact; switching back to the model
+ * that wrote it picks up exactly where it left off.
+ */
+export function planResume(
+  cursor: Cursor | null,
+  model: string,
+  hasNodes: boolean,
+): ResumePlan {
+  if (cursor === null) {
+    // No cursor and no nodes is simply a new session. No cursor but nodes on
+    // disk is a log this build cannot place itself in -- written before the
+    // cursor existed, or with a manifest that was lost. Refused rather than
+    // guessed: the whole reason the cursor is recorded is that the tree shape
+    // cannot be read backwards to find it, and inventing an answer here would
+    // reintroduce exactly the ambiguity it exists to remove.
+    return hasNodes
+      ? {
+          kind: "refuse",
+          reason:
+            "this log has nodes but no recorded cursor, so there is no way to " +
+            "know which one the session was in. It is intact and nothing will " +
+            "be touched -- start a separate session with --fresh",
+        }
+      : { kind: "fresh" };
+  }
+  if (cursor.model !== model) {
+    return {
+      kind: "refuse",
+      reason:
+        `this session ran under ${cursor.model}, and ${model} cannot replay its ` +
+        `thinking blocks. Resume it with --model ${cursor.model}, or start a ` +
+        `separate session with --fresh`,
+    };
+  }
+  return { kind: "resume", cursor };
+}

package/src/runtime/retry.ts

@@ -0,0 +1,297 @@
+/**
+ * When a failed request is worth making again.
+ *
+ * Split into a pure decision and a thin loop, because the decision is where
+ * all the rules are and none of them need a clock. What to retry, how long to
+ * wait, when to stop -- all of it is testable in microseconds, which is the
+ * difference between pinning the policy and hoping it works.
+ *
+ * The rules mirror the OpenAI and Anthropic SDKs' own, by way of pi, which
+ * notes the same lineage. That is deliberate: the failure modes were found by
+ * people running far more traffic than this, and inventing a different policy
+ * would mean rediscovering them.
+ *
+ * Retry lives at the request, inside the adapter, and not in the loop. A retry
+ * in the loop would straddle a log append -- the failed attempt would either
+ * be recorded, polluting an append-only history with something that did not
+ * happen, or dropped, leaving usage that does not add up. The loop should see
+ * a result that has already been retried, or a definite failure.
+ */
+
+import { isContextOverflow } from "../core/overflow.ts";
+
+/**
+ * Words providers and relays use for "try again": timeouts, unavailable or
+ * overloaded upstreams, rate limits, dropped connections, 5xx codes. A
+ * pattern, not a list of known providers, because relays forward their
+ * upstream's wording.
+ */
+const TRANSIENT_STREAM = /time[d ]?out|timed out|unavailable|overload|rate.?limit|too many requests|connection (?:reset|closed|refused)|ECONNRESET|temporar|\b5\d\d\b|internal.?server|bad gateway|service.?unavailable/i;
+
+/** Structural, so retry.ts need not import an adapter to recognise its error. */
+function isStreamFailure(error: unknown): error is Error & { code?: string } {
+  return error instanceof Error && error.name === "StreamError";
+}
+
+export interface RetryPolicy {
+  /**
+   * Attempts after the first. Four means a request can take about 15s of
+   * backoff before failing, which covers a rate-limit window without making a
+   * broken request take a minute to report itself.
+   */
+  maxRetries: number;
+  /**
+   * Longest server-requested delay worth honouring. Beyond this, fail. An
+   * agent that silently sleeps for twenty minutes cannot be told apart from
+   * one that has died, and is harder to diagnose than an error.
+   */
+  maxRetryDelayMs: number;
+}
+
+export const DEFAULT_RETRY: RetryPolicy = { maxRetries: 4, maxRetryDelayMs: 60_000 };
+
+export type RetryDecision =
+  | { retry: true; delayMs: number }
+  | { retry: false; reason: string };
+
+/** What this module needs from an error: a status and headers, if it has them. */
+interface HasResponse {
+  status?: unknown;
+  headers?: unknown;
+}
+
+export function statusOf(error: unknown): number | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const status = (error as HasResponse).status;
+  return typeof status === "number" ? status : undefined;
+}
+
+function headersOf(error: unknown): Headers | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const headers = (error as HasResponse).headers;
+  return headers instanceof Headers ? headers : undefined;
+}
+
+/**
+ * Whether this status is about timing rather than about the request.
+ *
+ * 400 and 401 are the two worth naming: a malformed request and a bad key are
+ * deterministic, so retrying converts one clear failure into several slow ones
+ * and delays the only message that would have helped.
+ */
+function statusIsTransient(status: number): boolean {
+  return status === 408 || status === 409 || status === 429 || status >= 500;
+}
+
+function serverDelayMs(headers: Headers | undefined): number | undefined {
+  if (headers === undefined) return undefined;
+
+  // Milliseconds first: it is the more precise of the two, and a provider
+  // that sends both means the finer one.
+  const ms = headers.get("retry-after-ms");
+  if (ms !== null) {
+    const value = Number.parseFloat(ms);
+    if (!Number.isNaN(value)) return value;
+  }
+
+  const after = headers.get("retry-after");
+  if (after !== null) {
+    const seconds = Number.parseFloat(after);
+    if (!Number.isNaN(seconds)) return seconds * 1000;
+    // The header is also allowed to be an HTTP date.
+    const at = Date.parse(after);
+    if (!Number.isNaN(at)) return Math.max(0, at - Date.now());
+  }
+
+  return undefined;
+}
+
+/**
+ * Whether to try again, and how long to wait first.
+ *
+ * `jitter` is a value in [0, 1) supplied by the caller rather than drawn here,
+ * so the backoff arithmetic is deterministic under test. It only ever
+ * shortens the wait: lengthening it could push past the window the server
+ * implied, while shortening is what breaks up the thundering herd of clients
+ * that were all rate-limited at the same instant and would otherwise wake
+ * together.
+ */
+export function retryDecision(
+  error: unknown,
+  attempt: number,
+  policy: RetryPolicy,
+  jitter: number,
+): RetryDecision {
+  if (attempt >= policy.maxRetries) {
+    return { retry: false, reason: `giving up after ${policy.maxRetries} retries` };
+  }
+
+  const headers = headersOf(error);
+  const status = statusOf(error);
+
+  // The same prompt overflows the same way however often it is sent, even
+  // when a relay dresses the rejection up as a 5xx. The loop owns the remedy.
+  if (error instanceof Error && isContextOverflow(error.message, status)) {
+    return { retry: false, reason: "the prompt exceeds the model's context window" };
+  }
+
+  // A provider that knows whether its own error is worth retrying gets the
+  // last word, in both directions.
+  // A failure reported inside a 200 stream carries no status. Relays and
+  // Anthropic's own `overloaded_error` use it for exactly the conditions a
+  // 5xx would signal; anything else in a stream is a real rejection.
+  if (status === undefined && isStreamFailure(error)) {
+    if (!TRANSIENT_STREAM.test(`${error.code ?? ""} ${error.message}`)) {
+      return { retry: false, reason: "the stream reported a non-transient error" };
+    }
+    const base = Math.min(0.5 * 2 ** attempt, 8) * 1000;
+    return { retry: true, delayMs: base * (1 - jitter * 0.25) };
+  }
+
+  const advice = headers?.get("x-should-retry");
+  let worthRetrying: boolean;
+  if (advice === "true") worthRetrying = true;
+  else if (advice === "false") worthRetrying = false;
+  else if (status !== undefined) worthRetrying = statusIsTransient(status);
+  else {
+    // No status at all. fetch reports a refused, reset or dropped connection
+    // as a TypeError, which is exactly the transient case. Anything else --
+    // a TypeError from our own code, a RangeError -- is a bug, and retrying a
+    // bug just runs it again.
+    worthRetrying = error instanceof TypeError;
+  }
+
+  if (!worthRetrying) {
+    return {
+      retry: false,
+      reason: status === undefined ? "not a retryable failure" : `HTTP ${status} is not retryable`,
+    };
+  }
+
+  const requested = serverDelayMs(headers);
+  if (requested !== undefined) {
+    if (requested > policy.maxRetryDelayMs) {
+      return {
+        retry: false,
+        reason:
+          `server asked to wait ${Math.ceil(requested / 1000)}s, ` +
+          `longer than the ${Math.ceil(policy.maxRetryDelayMs / 1000)}s cap`,
+      };
+    }
+    return { retry: true, delayMs: requested };
+  }
+
+  // 0.5s doubling to a ceiling of 8s, then flat.
+  const base = Math.min(0.5 * 2 ** attempt, 8) * 1000;
+  return { retry: true, delayMs: base * (1 - jitter * 0.25) };
+}
+
+export interface RetryEffects {
+  sleep(ms: number, signal?: AbortSignal): Promise<void>;
+  jitter(): number;
+}
+
+function abortReason(signal: AbortSignal): Error {
+  if (signal.reason instanceof Error) return signal.reason;
+  return new DOMException("The operation was aborted.", "AbortError");
+}
+
+/**
+ * A wait the caller can cancel.
+ *
+ * The SDK's own retry timers ignore AbortSignal, which is why the adapters
+ * retry with `maxRetries: 0` and sleep here. A sleep that runs to the end
+ * after Escape is the hang the user pressed it to get out of.
+ */
+function interruptibleSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal === undefined) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export const DEFAULT_RETRY_EFFECTS: RetryEffects = {
+  sleep: interruptibleSleep,
+  jitter: () => Math.random(),
+};
+
+/**
+ * Resolves when `waiting` does, or rejects as soon as the signal fires.
+ *
+ * Injected sleeps are allowed to ignore the signal -- tests do, to prove
+ * this wrapper is what stops the wait. Swallowing the abandoned sleep
+ * avoids an unhandled rejection when it later settles.
+ */
+function waitOrAbort(waiting: Promise<void>, signal?: AbortSignal): Promise<void> {
+  if (signal === undefined) return waiting;
+  if (signal.aborted) {
+    void waiting.catch(() => {});
+    return Promise.reject(abortReason(signal));
+  }
+  return new Promise<void>((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      void waiting.catch(() => {});
+      reject(abortReason(signal));
+    };
+    const onSettled = (error?: unknown) => {
+      cleanup();
+      if (error === undefined) resolve();
+      else reject(error);
+    };
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    signal.addEventListener("abort", onAbort, { once: true });
+    waiting.then(() => onSettled(), (error: unknown) => onSettled(error));
+  });
+}
+
+/**
+ * Runs a request, retrying per the policy.
+ *
+ * `onRetry` exists so the caller can say something. A retry that produces no
+ * output is indistinguishable from a hang, which is the problem this was
+ * supposed to solve rather than one to introduce.
+ *
+ * `signal` is per-request, not per-policy: aborting one send must not
+ * poison the adapter. An already-aborted signal does not start an attempt,
+ * and an abort during backoff does not wait out the delay -- both would
+ * turn Escape into "wait, then maybe stop".
+ */
+export async function withRetry<T>(
+  request: () => Promise<T>,
+  policy: RetryPolicy = DEFAULT_RETRY,
+  fx: RetryEffects = DEFAULT_RETRY_EFFECTS,
+  onRetry?: (attempt: number, delayMs: number, error: unknown) => void,
+  signal?: AbortSignal,
+): Promise<T> {
+  const effects = fx ?? DEFAULT_RETRY_EFFECTS;
+  for (let attempt = 0; ; attempt++) {
+    if (signal?.aborted) throw abortReason(signal);
+    try {
+      return await request();
+    } catch (error) {
+      // Checked here rather than inside retryDecision: abort is a user
+      // decision, not a status code, and a fetch abort that surfaces as
+      // TypeError must not start another wait.
+      if (signal?.aborted) throw abortReason(signal);
+      const decision = retryDecision(error, attempt, policy, effects.jitter());
+      if (!decision.retry) throw error;
+      onRetry?.(attempt + 1, decision.delayMs, error);
+      await waitOrAbort(effects.sleep(decision.delayMs, signal), signal);
+    }
+  }
+}