okengine 0.22.0 → 0.23.1

package/src/cli/doctor-diff.ts

@@ -55,6 +55,41 @@ export interface DoctorDiffResult {
   readonly allChanges: readonly ManifestChange[];
 }
 
+const COMMENT_CATEGORIES = ["contract-breaking", "permission-widening", "effect-widening"] as const;
+
+const CATEGORY_LABEL: Record<(typeof COMMENT_CATEGORIES)[number], string> = {
+  "contract-breaking": "Contract breaks",
+  "permission-widening": "Permission widening",
+  "effect-widening": "Effect widening",
+};
+
+/**
+ * Plain-language pull-request comment for the three behavioural categories.
+ * Widening is informational. Contract breaks are the lines that fail CI
+ * when they are undeclared.
+ *
+ * @param changes - {@link diffManifest} changes
+ */
+export function formatManifestDiffComment(changes: readonly ManifestChange[]): string {
+  const lines = ["## Manifest diff", ""];
+  for (const category of COMMENT_CATEGORIES) {
+    const rows = changes.filter((change) => change.category === category);
+    lines.push(`### ${CATEGORY_LABEL[category]}`);
+    if (rows.length === 0) {
+      lines.push("None.");
+    } else {
+      for (const row of rows) {
+        lines.push(`- \`${row.path}\` — ${row.summary}`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push(
+    "Undeclared contract breaks fail the check. Permission and effect widening are comments only. Acknowledge an intentional break with `breaking: true` on the HTTP, call, MCP, or resource contract.",
+  );
+  return lines.join("\n");
+}
+
 /**
  * Diff two manifests and fail on undeclared contract breaks.
  *

package/src/cli/eval.ts

@@ -4,6 +4,7 @@
 
 import { resolve } from "node:path";
 import { parseEvalJsonl, runPromptEvals, type EvalCase } from "../elements/ai/eval.ts";
+import type { DecisionResponse } from "../elements/ai/decisions/provider.ts";
 import type { Manifest } from "../manifest/types.ts";
 
 /** Options for {@link runOkeEval}. */
@@ -96,17 +97,157 @@ export async function runOkeEval(options: OkeEvalOptions = {}): Promise<number>
  */
 export async function evalCli(args: string[]): Promise<number> {
   let manifestPath: string | undefined;
+  let certify = false;
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--manifest" || a === "-m") {
       manifestPath = args[++i];
+    } else if (a === "--certify") {
+      certify = true;
     } else if (a === "--help" || a === "-h") {
-      console.log(`oke eval [--manifest oke.manifest.json]
+      console.log(`oke eval [--manifest oke.manifest.json] [--certify]
 
 Run prompt eval sets declared in the Manifest. Fails CI on regression.
+--certify builds a decision certificate from each decision seed file.
 `);
       return 0;
     }
   }
+  if (certify) return runOkeCertify({ manifestPath });
   return runOkeEval({ manifestPath });
 }
+
+/**
+ * Build certificates from decision seed files. Prompt evals are not run.
+ *
+ * @param options - Manifest path
+ */
+export async function runOkeCertify(
+  options: {
+    readonly manifestPath?: string;
+    readonly manifest?: Manifest;
+    readonly root?: string;
+    readonly evaluate?: (input: unknown) => Promise<DecisionResponse>;
+  } = {},
+): Promise<number> {
+  const { certifySeed } = await import("../elements/ai/decisions/certify.ts");
+  const { aiDecisionRegistry } = await import("../kernel/element-registries.ts");
+  const { DECISION_LOCK_FILENAME, parseDecisionLockfile } =
+    await import("../elements/ai/decisions/certificate.ts");
+  const { resolveStartEntry } = await import("./start.ts");
+  const root = resolve(options.root ?? process.env["OKE_ROOT_DIR"] ?? ".");
+  process.env["OKE_ROOT_DIR"] ??= root;
+  let manifest = options.manifest;
+  if (!manifest) {
+    try {
+      const entry = await resolveStartEntry(root);
+      await import(entry);
+    } catch (err) {
+      console.error(
+        `oke eval: failed to load the app: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return 1;
+    }
+    const path = resolve(root, options.manifestPath ?? "oke.manifest.json");
+    const file = Bun.file(path);
+    if (!(await file.exists())) {
+      console.error(`oke eval: manifest not found: ${path}`);
+      return 1;
+    }
+    manifest = (await file.json()) as Manifest;
+  }
+  const decisions = manifest.ai?.decisions ?? {};
+  const names = Object.keys(decisions);
+  if (names.length === 0) {
+    process.stdout.write("oke eval: no decisions declared\n");
+    return 0;
+  }
+  const injected = options.evaluate;
+  const lockPath = resolve(root, DECISION_LOCK_FILENAME);
+  const existingFile = Bun.file(lockPath);
+  const current = (await existingFile.exists())
+    ? parseDecisionLockfile(await existingFile.json())
+    : undefined;
+  const next = { decisions: { ...(current?.decisions ?? {}) } };
+  for (const name of names) {
+    const decision = decisions[name];
+    if (!decision?.evals) {
+      process.stdout.write(`oke eval: skip ${name} (no evals)\n`);
+      continue;
+    }
+    const decl = aiDecisionRegistry.find((item) => item.name === name);
+    if (!decl) {
+      console.error(`oke eval: decision "${name}" is not loaded`);
+      return 1;
+    }
+    const text = await Bun.file(resolve(root, decision.evals)).text();
+    const evaluate = injected ?? (await providerForDecision(decl));
+    next.decisions[name] = await certifySeed({
+      model: decl.model ?? decision.model ?? "",
+      maxError: decision.autonomy?.maxError ?? 0.05,
+      delta: decision.autonomy?.risk ?? decl.autonomy?.risk ?? 0.1,
+      jsonl: text,
+      ask: decl.ask,
+      evaluate,
+    });
+  }
+  await Bun.write(lockPath, `${JSON.stringify(next, null, 2)}\n`);
+  const { setDecisionDrift } = await import("../elements/ai/decisions/certificate.ts");
+  const { persistDecisionDrift } = await import("../elements/ai/decisions/labels.ts");
+  for (const name of names) {
+    setDecisionDrift(name, false);
+    persistDecisionDrift(name, false);
+  }
+  return 0;
+}
+
+async function providerForDecision(
+  decl: import("../elements/ai/declare.ts").AiDecisionDecl,
+): Promise<(input: unknown) => Promise<DecisionResponse>> {
+  const typesafe = decl.driverId === "typesafe";
+  const keyName = typesafe ? "TYPESAFE_API_KEY" : "OPENROUTER_API_KEY";
+  const apiKey = process.env[keyName];
+  if (!apiKey) throw new Error(`oke eval: secret "${keyName}" is not configured`);
+  const { createTypesafeDecisionProvider, TYPESAFE_JEV_MODEL } =
+    await import("../elements/ai/decisions/typesafe.ts");
+  const { createOpenRouterDecisionProvider, OPENROUTER_JEV_MODEL } =
+    await import("../elements/ai/decisions/openrouter.ts");
+  const provider = typesafe
+    ? createTypesafeDecisionProvider(apiKey)
+    : createOpenRouterDecisionProvider(apiKey);
+  const model = decl.model ?? (typesafe ? TYPESAFE_JEV_MODEL : OPENROUTER_JEV_MODEL);
+  return (input) =>
+    provider.evaluate({
+      model,
+      state: input,
+      questions: wireFromDecl(decl),
+    });
+}
+
+function wireFromDecl(
+  decl: import("../elements/ai/declare.ts").AiDecisionDecl,
+): import("../elements/ai/decisions/provider.ts").DecisionRequest["questions"] {
+  const questions: Record<string, import("../elements/ai/decisions/provider.ts").WireQuestion> = {};
+  for (const [id, question] of Object.entries(decl.ask)) {
+    if (question.kind === "choice") {
+      questions[id] = {
+        type: "choice",
+        instructions: question.instructions,
+        criteria: { ...question.options, none_of_these: null },
+      };
+    } else if (question.kind === "score") {
+      questions[id] = {
+        type: "score",
+        instructions: question.instructions,
+        criteria: question.levels,
+      };
+    } else {
+      questions[id] = {
+        type: "noul",
+        instructions: question.instructions,
+        ...(question.criteria !== undefined ? { criteria: question.criteria } : {}),
+      };
+    }
+  }
+  return questions;
+}

package/src/cli/index.ts

@@ -16,6 +16,7 @@ import { dbCli } from "./db.ts";
 import { devCli } from "./dev.ts";
 import { doctorCli } from "./doctor.ts";
 import { dockerCli } from "./docker.ts";
+import { decideCli } from "./decide.ts";
 import { evalCli } from "./eval.ts";
 import { EXIT_CODE_HELP, EXIT_OK, EXIT_USAGE } from "./exit.ts";
 import { gatesListCli } from "./gates-list.ts";
@@ -117,6 +118,10 @@ if (cmd === "eval") {
   process.exit(await evalCli(sub ? [sub, ...rest] : rest));
 }
 
+if (cmd === "decide") {
+  process.exit(await decideCli(sub ? [sub, ...rest] : rest));
+}
+
 if (cmd === "ai") {
   process.exit(await aiCli(sub ? [sub, ...rest] : rest));
 }

package/src/cli/load-config.images.test.ts

@@ -54,7 +54,7 @@ describe("defaultImagesFromConfig", () => {
     expect(images).toEqual({
       "store.sql": "postgres:18-alpine",
       pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.59",
-      "store.kv": "redis:8-alpine",
+      "store.kv": "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0",
     });
   });
 
@@ -129,7 +129,7 @@ describe("resolveImages", () => {
       },
     });
     expect(images["store.sql"]).toBe("postgres:18-alpine");
-    expect(images["store.kv"]).toBe("redis:8-alpine");
+    expect(images["store.kv"]).toBe("docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0");
     expect(images["store.kv.durable"]).toBeUndefined();
   });
 });

package/src/cli/load-config.ts

@@ -16,7 +16,7 @@ import type { Manifest } from "../manifest/types.ts";
 const DEFAULT_SQL_IMAGE = "postgres:18-alpine";
 const DEFAULT_PGVECTOR_IMAGE = "pgvector/pgvector:pg17";
 const DEFAULT_PGDOG_IMAGE = "ghcr.io/pgdogdev/pgdog:v0.1.59";
-const DEFAULT_KV_IMAGE = "redis:8-alpine";
+const DEFAULT_KV_IMAGE = "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0";
 
 /**
  * Prefer `dev` then `prod` for a driver map (compose infra ≈ production).

package/src/cli/manifest-pr-diff.ts

@@ -0,0 +1,16 @@
+/**
+ * Pull-request manifest diff.
+ *
+ * Writes the comment body, then exits non-zero only for undeclared
+ * contract breaks. Widening changes stay in the comment.
+ *
+ *   bun src/cli/manifest-pr-diff.ts comment.md
+ */
+
+import { writeFileSync } from "node:fs";
+import { formatManifestDiffComment, runDoctorDiff } from "./doctor-diff.ts";
+
+const out = process.argv[2] ?? "manifest-diff.md";
+const result = await runDoctorDiff({ write: () => {} });
+writeFileSync(out, formatManifestDiffComment(result.allChanges));
+process.exit(result.code);

package/src/cli/mcp-from-console.ts

@@ -22,6 +22,10 @@ export interface McpConsoleSurface {
   readonly cwd: string;
   /** Clock shared with Console. */
   readonly now: () => number;
+  /** Journal that holds agent events and parked approvals. */
+  readonly journalStore?: import("../kernel/journal.ts").JournalStore | null;
+  /** In-process agent ledger. The follow log is the durable source. */
+  readonly aiRuntime?: import("../elements/ai.ts").AiRuntime | null;
 }
 
 /**
@@ -33,6 +37,50 @@ export function mcpContextFromConsole(state: McpConsoleSurface): McpContext {
   return {
     getManifest: () => state.manifest,
     listRuns: () => state.listRuns(),
+    listAgentRuns: async () => {
+      const { loadConsoleAgentRuns } = await import("../console/server/ai-runs.ts");
+      return loadConsoleAgentRuns({
+        runtime: state.aiRuntime ?? null,
+        store: state.journalStore ?? null,
+        now: state.now(),
+      });
+    },
+    getAgentRun: async (runId) => {
+      const { loadConsoleAgentRun } = await import("../console/server/ai-runs.ts");
+      const run = await loadConsoleAgentRun(
+        {
+          runtime: state.aiRuntime ?? null,
+          store: state.journalStore ?? null,
+          now: state.now(),
+        },
+        runId,
+      );
+      if (!run) return undefined;
+      return { run, events: run.events };
+    },
+    listApprovals: async () => {
+      const { loadApprovalQueue } = await import("../console/server/ai-runs.ts");
+      return loadApprovalQueue(state.journalStore ?? null, state.now());
+    },
+    listDecisions: async (tenant) => {
+      const { loadDecisionQueue, projectMcpDecisions, candidateMetrics } =
+        await import("../console/server/decisions.ts");
+      const { listDecisionCandidates, loadDecisionCandidate } =
+        await import("../elements/ai/decisions/labels.ts");
+      const names = await listDecisionCandidates();
+      const fitted: Record<string, Record<string, number>> = {};
+      for (const name of names) {
+        const metrics = candidateMetrics(await loadDecisionCandidate(name));
+        if (metrics) fitted[name] = metrics;
+      }
+      const queue = await loadDecisionQueue(state.journalStore ?? null, state.now(), tenant);
+      const pending: Record<string, number> = {};
+      for (const row of queue) {
+        if (row.status !== "pending" || row.labelOnly) continue;
+        pending[row.decision] = (pending[row.decision] ?? 0) + 1;
+      }
+      return projectMcpDecisions(state.manifest, pending, fitted);
+    },
     proposeStructural: async (input) =>
       emitStructuralDiff({
         cwd: state.cwd,

package/src/cli/registry.ts

@@ -550,7 +550,41 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
     name: "eval",
     summary: "prompt eval sets (CI gate)",
     leaf: true,
-    flags: [MANIFEST, HELP],
+    flags: [
+      MANIFEST,
+      {
+        long: "--certify",
+        takesValue: false,
+        summary: "Build a decision certificate from the seed file",
+      },
+      HELP,
+    ],
+  },
+  {
+    name: "decide",
+    summary: "promote a decision certificate",
+    subcommands: [
+      {
+        name: "promote",
+        summary: "Fetch the operator candidate and write the app lockfile",
+        positionals: "<name>",
+        flags: [
+          {
+            long: "--origin",
+            takesValue: true,
+            valueName: "url",
+            summary: "App origin that serves the candidate",
+          },
+          {
+            long: "--lock",
+            takesValue: true,
+            valueName: "path",
+            summary: "Lockfile path (default oke-decisions.lock.json)",
+          },
+          HELP,
+        ],
+      },
+    ],
   },
   {
     name: "ai",

package/src/client/agent.ts

@@ -0,0 +1,307 @@
+/**
+ * Parse AG-UI agent events from JSON or SSE.
+ *
+ * Import from `okengine/client/agent`. This stays off the core `okengine/client`
+ * graph. Wire `CUSTOM` events stay `CUSTOM`. The three OKE subagent names are
+ * also returned as typed variants.
+ */
+
+import type { AgUiEvent } from "../elements/ai/events.ts";
+
+/** Typed subagent notice parsed from `CUSTOM`. */
+export type ParsedSubagentEvent =
+  | {
+      readonly type: "subagent.started";
+      readonly runId: string;
+      readonly parentToolCallId?: string;
+    }
+  | {
+      readonly type: "subagent.finished";
+      readonly runId: string;
+      readonly parentToolCallId?: string;
+    }
+  | {
+      readonly type: "subagent.error";
+      readonly runId: string;
+      readonly parentToolCallId?: string;
+      readonly message?: string;
+    };
+
+/** One event from {@link parseAgentEvent}. */
+export type ParsedAgentEvent = AgUiEvent | ParsedSubagentEvent;
+
+const SUBAGENT_NAMES = {
+  "oke.subagent.started": "subagent.started",
+  "oke.subagent.finished": "subagent.finished",
+  "oke.subagent.error": "subagent.error",
+} as const;
+
+/**
+ * Parse one JSON event. Unknown objects return undefined.
+ *
+ * @param data - Parsed JSON value
+ */
+export function parseAgentEvent(data: unknown): ParsedAgentEvent | undefined {
+  if (typeof data !== "object" || data === null || !("type" in data)) return undefined;
+  const event = data as AgUiEvent;
+  if (event.type !== "CUSTOM") return event;
+  const kind = SUBAGENT_NAMES[event.name as keyof typeof SUBAGENT_NAMES];
+  if (!kind) return event;
+  const value =
+    typeof event.value === "object" && event.value !== null
+      ? (event.value as { runId?: unknown; parentToolCallId?: unknown; message?: unknown })
+      : {};
+  const runId = typeof value.runId === "string" ? value.runId : "";
+  const parentToolCallId =
+    typeof value.parentToolCallId === "string" ? value.parentToolCallId : undefined;
+  if (kind === "subagent.error") {
+    return {
+      type: kind,
+      runId,
+      ...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
+      ...(typeof value.message === "string" ? { message: value.message } : {}),
+    };
+  }
+  return {
+    type: kind,
+    runId,
+    ...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
+  };
+}
+
+/**
+ * Read `data:` frames from an SSE response body.
+ *
+ * Pass a URL to follow a run: the generator reconnects and sends
+ * `Last-Event-ID` from the last frame it yielded.
+ *
+ * @param source - One response, or the follow URL
+ * @param init - Fetch, abort, and a starting event id
+ */
+export async function* readAgentEvents(
+  source: Response | string | URL,
+  init?: AgentFollowInit,
+): AsyncIterable<ParsedAgentEvent> {
+  if (source instanceof Response) {
+    yield* readAgentEventResponse(source, init);
+    return;
+  }
+  const fetcher = init?.fetch ?? fetch;
+  let lastEventId = init?.lastEventId;
+  let delayMs = 250;
+  for (;;) {
+    if (init?.signal?.aborted) return;
+    const headers = new Headers(init?.headers);
+    if (lastEventId) headers.set("last-event-id", lastEventId);
+    let response: Response;
+    try {
+      response = await fetcher(source, { headers, signal: init?.signal });
+    } catch (err) {
+      if (init?.signal?.aborted) return;
+      init?.trace?.(err instanceof Error ? err.message : "agent events: network error");
+      await wait(delayMs, init?.signal);
+      delayMs = Math.min(delayMs * 2, 10_000);
+      continue;
+    }
+    delayMs = 250;
+    if (!response.ok) throw new Error(`agent events: HTTP ${response.status}`);
+    let sawFrame = false;
+    try {
+      for await (const frame of readAgentEventFrames(response, init?.trace)) {
+        sawFrame = true;
+        if (frame.id) {
+          lastEventId = frame.id;
+          init?.onId?.(frame.id);
+        }
+        if (frame.event) yield frame.event;
+        if (frame.event?.type === "RUN_ERROR") return;
+        if (frame.event?.type === "RUN_FINISHED" && frame.event.outcome?.type !== "interrupt")
+          return;
+      }
+    } catch (err) {
+      if (init?.signal?.aborted) return;
+      init?.trace?.(err instanceof Error ? err.message : "agent events: network error");
+      await wait(delayMs, init?.signal);
+      delayMs = Math.min(delayMs * 2, 10_000);
+      continue;
+    }
+    if (!sawFrame || init?.signal?.aborted) return;
+  }
+}
+
+/** Options for {@link approve} and {@link deny}. */
+export interface AgentDecisionInit {
+  readonly fetch?: typeof fetch;
+  /** Cap on lease retries. Default 5. */
+  readonly attempts?: number;
+  readonly headers?: Record<string, string>;
+}
+
+/**
+ * Approve a parked tool. Retries `JournalLeaseBusy`. Throws on `Conflict`.
+ *
+ * @param url - Approve route (`/agent/approvals/approve`)
+ * @param id - Approval id
+ * @param args - Replacement tool input
+ * @param init - Fetch override
+ */
+export async function approve(
+  url: string,
+  id: string,
+  args?: unknown,
+  init?: AgentDecisionInit,
+): Promise<void> {
+  await postDecision(url, { id, ...(args !== undefined ? { args } : {}) }, init);
+}
+
+/**
+ * Deny a parked tool. Retries `JournalLeaseBusy`. Throws on `Conflict`.
+ *
+ * @param url - Deny route (`/agent/approvals/deny`)
+ * @param id - Approval id
+ * @param reason - Text the model sees
+ * @param init - Fetch override
+ */
+export async function deny(
+  url: string,
+  id: string,
+  reason?: string,
+  init?: AgentDecisionInit,
+): Promise<void> {
+  await postDecision(url, { id, ...(reason !== undefined ? { reason } : {}) }, init);
+}
+
+/** Follow options for {@link readAgentEvents}. */
+export interface AgentFollowInit {
+  readonly fetch?: typeof fetch;
+  readonly headers?: Record<string, string>;
+  readonly signal?: AbortSignal;
+  readonly lastEventId?: string;
+  /** Called with each SSE id as it is read. */
+  onId?(id: string): void;
+  /** Called when a frame cannot be parsed. The frame is skipped. */
+  trace?(message: string): void;
+}
+
+async function* readAgentEventResponse(
+  response: Response,
+  init?: AgentFollowInit,
+): AsyncIterable<ParsedAgentEvent> {
+  for await (const frame of readAgentEventFrames(response, init?.trace)) {
+    if (frame.id) init?.onId?.(frame.id);
+    if (frame.event) yield frame.event;
+  }
+}
+
+async function* readAgentEventFrames(
+  response: Response,
+  trace?: (message: string) => void,
+): AsyncIterable<{ id?: string; event?: ParsedAgentEvent }> {
+  const body = response.body;
+  if (!body) return;
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (;;) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    buffer += decoder.decode(chunk.value, { stream: true });
+    const frames = buffer.split("\n\n");
+    buffer = frames.pop() ?? "";
+    for (const frame of frames) {
+      const lines = frame.split("\n");
+      const idLine = lines.find((line) => line.startsWith("id:"));
+      const data = lines
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trim())
+        .join("\n");
+      if (!data || data === "[DONE]") continue;
+      let parsed: ParsedAgentEvent | undefined;
+      try {
+        parsed = parseAgentEvent(JSON.parse(data) as unknown);
+      } catch (err) {
+        trace?.(err instanceof Error ? err.message : "agent events: malformed frame");
+        continue;
+      }
+      yield {
+        ...(idLine ? { id: idLine.slice(3).trim() } : {}),
+        ...(parsed ? { event: parsed } : {}),
+      };
+    }
+  }
+}
+
+async function postDecision(
+  url: string,
+  body: { id: string; args?: unknown; reason?: string },
+  init?: AgentDecisionInit,
+): Promise<void> {
+  const fetcher = init?.fetch ?? fetch;
+  const attempts = init?.attempts ?? 5;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const response = await fetcher(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headersOf(init?.headers) },
+      body: JSON.stringify(body),
+    });
+    if (response.ok) return;
+    const payload = (await response.json().catch(() => ({}))) as {
+      error?: { code?: string };
+    };
+    const code = payload.error?.code;
+    if (response.status === 409 && code === "JournalLeaseBusy") {
+      const retryAfter = retryAfterMs(response.headers.get("retry-after"));
+      await new Promise((resolve) => setTimeout(resolve, retryAfter));
+      continue;
+    }
+    if (response.status === 409 && code === "Conflict") {
+      const error = new Error("That value is already in use.");
+      error.name = "Conflict";
+      throw error;
+    }
+    const error = new Error(code ?? `agent decision: HTTP ${response.status}`);
+    error.name = code ?? "Error";
+    throw error;
+  }
+  const error = new Error("This run is locked by another worker. Retry after the given delay.");
+  error.name = "JournalLeaseBusy";
+  throw error;
+}
+
+/**
+ * `Retry-After` as delta-seconds or an HTTP-date.
+ *
+ * @param header - Header value
+ */
+function retryAfterMs(header: string | null): number {
+  if (!header) return 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds) * 1000;
+  const at = Date.parse(header);
+  if (Number.isNaN(at)) return 0;
+  return Math.max(0, at - Date.now());
+}
+
+function headersOf(headers: Record<string, string> | undefined): Record<string, string> {
+  return headers ?? {};
+}
+
+/**
+ * Wait, or return early when `signal` aborts.
+ *
+ * @param ms - Delay
+ * @param signal - Abort
+ */
+function wait(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}