faberun 0.3.0

package/src/harnesses/replay/bin.mjs

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+
+const ENVELOPE_STATUSES = new Set(["done", "no-op", "blocked", "failed", "exhausted", "stalled", "canceled"]);
+const LINE_KEYS = new Set(["envelope", "files", "delayMs", "exitCode", "stdoutRaw"]);
+// exhaustedUntil, like error.resetAt below, is optional on a real provider
+// envelope — most statuses never carry either — so it sits outside the
+// required set even though it is a recognized field.
+const ENVELOPE_REQUIRED_KEYS = new Set(["status", "result", "continuationId", "usage", "costUsd", "error"]);
+const ENVELOPE_OPTIONAL_KEYS = new Set(["exhaustedUntil"]);
+const ENVELOPE_KEYS = new Set([...ENVELOPE_REQUIRED_KEYS, ...ENVELOPE_OPTIONAL_KEYS]);
+const USAGE_KEYS = new Set(["inputTokens", "outputTokens", "cacheReadInputTokens"]);
+const FILE_KEYS = new Set(["path", "content"]);
+const ERROR_KEYS = new Set(["code", "message", "resetAt"]);
+const METADATA_ROOTS = new Set([".git", ".runs", "node_modules", ".claude", ".codex"]);
+const PREFLIGHT_TOKEN = "FABERUN_PREFLIGHT_OK";
+
+const PREFLIGHT_ENVELOPE = Object.freeze({
+  status: "done",
+  result: PREFLIGHT_TOKEN,
+  continuationId: null,
+  usage: { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 },
+  costUsd: null,
+  error: null,
+});
+
+/** @param {string[]} args @param {string} name @returns {string|null} */
+function argValue(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 && index + 1 < args.length ? args[index + 1] : null;
+}
+
+/** @param {string} message @returns {never} */
+function fail(message) {
+  process.stderr.write(`replay: ${message}\n`);
+  process.exit(2);
+}
+
+/** @param {number} lineIndex @param {string} message @returns {never} */
+function failSchema(lineIndex, message) {
+  fail(`recording line ${lineIndex + 1} violates schema: ${message}`);
+}
+
+/**
+ * @param {string} code
+ * @param {string} message
+ * @returns {{status: "failed", result: null, continuationId: null, usage: {inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0}, costUsd: null, error: {code: string, message: string}}}
+ */
+function failedEnvelope(code, message) {
+  return {
+    status: "failed",
+    result: null,
+    continuationId: null,
+    usage: { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 },
+    costUsd: null,
+    error: { code, message },
+  };
+}
+
+/** @returns {Promise<string>} */
+function readStdin() {
+  return new Promise((settle) => {
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { input += chunk; });
+    process.stdin.on("end", () => settle(input));
+    process.stdin.on("error", () => settle(input));
+  });
+}
+
+/** @param {string} recording @returns {string[]} */
+function readRecordingLines(recording) {
+  if (!existsSync(recording)) return [];
+  let text;
+  try {
+    text = readFileSync(recording, "utf8");
+  } catch (error) {
+    fail(`cannot read recording ${recording}: ${String(error)}`);
+  }
+  return text.split(/\r?\n/u).filter((line) => line.trim().length > 0);
+}
+
+/** @param {string} cursorPath @returns {number} */
+function readCursor(cursorPath) {
+  if (!existsSync(cursorPath)) return 0;
+  const raw = readFileSync(cursorPath, "utf8").trim();
+  if (!/^(?:0|[1-9]\d*)$/u.test(raw)) {
+    fail(`cursor file ${cursorPath} must contain a non-negative integer`);
+  }
+  return Number(raw);
+}
+
+/** @param {string} cursorPath @param {number} value @returns {void} */
+function writeCursor(cursorPath, value) {
+  const temporary = `${cursorPath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporary, `${value}\n`);
+  renameSync(temporary, cursorPath);
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} lineIndex
+ * @returns {{envelope: Record<string, unknown>, files: {path: string, content: string}[], delayMs: number|undefined, exitCode: number|undefined, stdoutRaw: string|undefined}}
+ */
+function parseRecord(value, lineIndex) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) failSchema(lineIndex, "must be an object");
+  const record = /** @type {Record<string, unknown>} */ (value);
+  for (const key of Object.keys(record)) {
+    if (!LINE_KEYS.has(key)) failSchema(lineIndex, `has unknown field ${key}`);
+  }
+  if (!Object.hasOwn(record, "envelope")) failSchema(lineIndex, "is missing envelope");
+  const envelope = parseEnvelope(record.envelope, lineIndex);
+  /** @type {{path: string, content: string}[]} */
+  const files = [];
+  if (record.files !== undefined) {
+    if (!Array.isArray(record.files)) failSchema(lineIndex, "files must be an array");
+    files.push(...record.files.map((file, fileIndex) => parseFile(file, lineIndex, fileIndex)));
+  }
+  let delayMs;
+  if (record.delayMs !== undefined) {
+    if (typeof record.delayMs !== "number" || !Number.isFinite(record.delayMs) || record.delayMs < 0) {
+      failSchema(lineIndex, "delayMs must be a non-negative number");
+    }
+    delayMs = record.delayMs;
+  }
+  let exitCode;
+  if (record.exitCode !== undefined) {
+    if (typeof record.exitCode !== "number" || !Number.isInteger(record.exitCode) || record.exitCode < 0 || record.exitCode > 255) {
+      failSchema(lineIndex, "exitCode must be an integer between 0 and 255");
+    }
+    exitCode = record.exitCode;
+  }
+  let stdoutRaw;
+  if (record.stdoutRaw !== undefined) {
+    if (typeof record.stdoutRaw !== "string") failSchema(lineIndex, "stdoutRaw must be a string");
+    stdoutRaw = record.stdoutRaw;
+  }
+  return { envelope, files, delayMs, exitCode, stdoutRaw };
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} lineIndex
+ * @returns {Record<string, unknown>}
+ */
+function parseEnvelope(value, lineIndex) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) failSchema(lineIndex, "envelope must be an object");
+  const envelope = /** @type {Record<string, unknown>} */ (value);
+  for (const key of Object.keys(envelope)) {
+    if (!ENVELOPE_KEYS.has(key)) failSchema(lineIndex, `envelope has unknown field ${key}`);
+  }
+  for (const key of ENVELOPE_REQUIRED_KEYS) {
+    if (!Object.hasOwn(envelope, key)) failSchema(lineIndex, `envelope is missing ${key}`);
+  }
+  if (Object.hasOwn(envelope, "exhaustedUntil")) {
+    const exhaustedUntil = envelope.exhaustedUntil;
+    if (exhaustedUntil !== null && typeof exhaustedUntil !== "string") {
+      failSchema(lineIndex, "envelope.exhaustedUntil must be a string or null");
+    }
+  }
+  const status = envelope.status;
+  if (typeof status !== "string" || !ENVELOPE_STATUSES.has(status)) {
+    failSchema(lineIndex, `envelope.status must be one of ${[...ENVELOPE_STATUSES].join(", ")}`);
+  }
+  const result = envelope.result;
+  if (result !== null && typeof result !== "string") failSchema(lineIndex, "envelope.result must be a string or null");
+  const continuationId = envelope.continuationId;
+  if (continuationId !== null && typeof continuationId !== "string") {
+    failSchema(lineIndex, "envelope.continuationId must be a string or null");
+  }
+  const usage = envelope.usage;
+  if (!usage || typeof usage !== "object" || Array.isArray(usage)) failSchema(lineIndex, "envelope.usage must be an object");
+  for (const key of Object.keys(usage)) {
+    if (!USAGE_KEYS.has(key)) failSchema(lineIndex, `envelope.usage has unknown field ${key}`);
+  }
+  for (const key of USAGE_KEYS) {
+    if (!Object.hasOwn(usage, key)) failSchema(lineIndex, `envelope.usage is missing ${key}`);
+    const raw = /** @type {Record<string, unknown>} */ (usage)[key];
+    if (raw !== null && (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0)) {
+      failSchema(lineIndex, `envelope.usage.${key} must be a non-negative integer or null`);
+    }
+  }
+  const costUsd = envelope.costUsd;
+  if (costUsd !== null && (typeof costUsd !== "number" || !Number.isFinite(costUsd) || costUsd < 0)) {
+    failSchema(lineIndex, "envelope.costUsd must be a non-negative number or null");
+  }
+  parseError(envelope.error, lineIndex);
+  return envelope;
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} lineIndex
+ * @param {number} fileIndex
+ * @returns {{path: string, content: string}}
+ */
+function parseFile(value, lineIndex, fileIndex) {
+  const label = `files[${fileIndex}]`;
+  if (!value || typeof value !== "object" || Array.isArray(value)) failSchema(lineIndex, `${label} must be an object`);
+  const file = /** @type {Record<string, unknown>} */ (value);
+  for (const key of Object.keys(file)) {
+    if (!FILE_KEYS.has(key)) failSchema(lineIndex, `${label} has unknown field ${key}`);
+  }
+  const path = file.path;
+  if (typeof path !== "string" || path.length === 0) failSchema(lineIndex, `${label}.path must be a non-empty string`);
+  const content = file.content;
+  if (typeof content !== "string") failSchema(lineIndex, `${label}.content must be a string`);
+  return { path, content };
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} lineIndex
+ * @returns {void}
+ */
+function parseError(value, lineIndex) {
+  if (value === null) return;
+  if (!value || typeof value !== "object" || Array.isArray(value)) failSchema(lineIndex, "envelope.error must be an object or null");
+  const error = /** @type {Record<string, unknown>} */ (value);
+  for (const key of Object.keys(error)) {
+    if (!ERROR_KEYS.has(key)) failSchema(lineIndex, `envelope.error has unknown field ${key}`);
+  }
+  if (typeof error.code !== "string" || error.code.length === 0 || typeof error.message !== "string") {
+    failSchema(lineIndex, "envelope.error must carry a non-empty code and a string message");
+  }
+  if (Object.hasOwn(error, "resetAt")) {
+    const resetAt = error.resetAt;
+    if (resetAt !== null && typeof resetAt !== "string") {
+      failSchema(lineIndex, "envelope.error.resetAt must be a string or null");
+    }
+  }
+}
+
+/**
+ * Fail closed when a recorded file target could escape the real workspace:
+ * relative paths only, no `..` segments, no metadata roots, and no symlinked
+ * ancestor whose realpath leaves the workspace.
+ *
+ * @param {string} path
+ * @param {string} workspace
+ * @returns {string|null}
+ */
+function containmentProblem(path, workspace) {
+  if (isAbsolute(path)) return `replay file path must be relative: ${path}`;
+  const segments = path.split(/[\\/]+/u).filter((segment) => segment.length > 0 && segment !== ".");
+  if (segments.some((segment) => segment === "..")) {
+    return `replay file path must not traverse outside the workspace: ${path}`;
+  }
+  if (segments.length === 0 || METADATA_ROOTS.has(segments[0])) {
+    return `replay file path must not target a metadata root: ${path}`;
+  }
+  const target = join(process.cwd(), path);
+  let ancestor = target;
+  while (!existsSync(ancestor)) {
+    const parent = dirname(ancestor);
+    if (parent === ancestor) break;
+    ancestor = parent;
+  }
+  let ancestorReal = null;
+  try {
+    ancestorReal = realpathSync(ancestor);
+  } catch {
+    ancestorReal = null;
+  }
+  if (ancestorReal === null || !(ancestorReal === workspace || ancestorReal.startsWith(`${workspace}${sep}`))) {
+    return `replay file path escapes the workspace through a symlink: ${path}`;
+  }
+  return null;
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--version")) {
+  const probeArg = argValue(args, "--replay-probe");
+  if (probeArg !== null) {
+    /** @type {unknown} */
+    let probe;
+    try {
+      probe = JSON.parse(probeArg);
+    } catch {
+      fail("--replay-probe must be valid JSON");
+    }
+    if (!probe || typeof probe !== "object" || Array.isArray(probe)) {
+      fail("--replay-probe must be a JSON object");
+    }
+    const record = /** @type {Record<string, unknown>} */ (probe);
+    if (typeof record.stderr === "string" && record.stderr) process.stderr.write(`${record.stderr}\n`);
+    const exitCode = typeof record.exitCode === "number" && Number.isInteger(record.exitCode) && record.exitCode >= 0 && record.exitCode <= 255
+      ? record.exitCode
+      : 1;
+    process.exit(exitCode);
+  }
+  process.stdout.write("replay 1.0.0\n");
+  process.exit(0);
+}
+
+const recordingArg = argValue(args, "--recording");
+if (recordingArg === null) {
+  fail("--recording <recording.jsonl> is required");
+}
+const recording = resolve(recordingArg);
+const prompt = await readStdin();
+
+if (prompt.includes(PREFLIGHT_TOKEN)) {
+  process.stdout.write(`${JSON.stringify(PREFLIGHT_ENVELOPE)}\n`);
+  process.exit(0);
+}
+
+const lines = readRecordingLines(recording);
+const cursorPath = `${recording}.cursor`;
+const cursor = readCursor(cursorPath);
+if (cursor >= lines.length) {
+  const suffix = lines.length === 1 ? "" : "s";
+  process.stdout.write(`${JSON.stringify(failedEnvelope("replay_exhausted", `replay recording exhausted at cursor ${cursor} (${lines.length} line${suffix})`))}\n`);
+  process.exit(1);
+}
+
+const rawLine = lines[cursor];
+/** @type {unknown} */
+let parsed;
+try {
+  parsed = JSON.parse(rawLine);
+} catch (error) {
+  fail(`recording line ${cursor + 1} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+}
+const record = parseRecord(parsed, cursor);
+const workspace = realpathSync(process.cwd());
+
+for (const file of record.files) {
+  const problem = containmentProblem(file.path, workspace);
+  if (problem !== null) {
+    process.stdout.write(`${JSON.stringify(failedEnvelope("replay_path_escape", problem))}\n`);
+    process.exit(2);
+  }
+}
+for (const file of record.files) {
+  const target = join(process.cwd(), file.path);
+  try {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.content);
+  } catch (error) {
+    fail(`cannot write ${file.path}: ${String(error)}`);
+  }
+}
+
+writeCursor(cursorPath, cursor + 1);
+appendFileSync(
+  `${recording}.invocations.jsonl`,
+  `${JSON.stringify({ at: new Date().toISOString(), index: cursor, promptBytes: Buffer.byteLength(prompt, "utf8"), args })}\n`,
+);
+
+/**
+ * Resolve an `error.resetAt` written as `+<ms>` into an absolute instant, at
+ * the moment the envelope is emitted rather than when the recording was
+ * written.
+ *
+ * A recording that hardcodes `Date.now() + 3000` is racing the spawn: the
+ * controller only reads `resetAt` when this envelope comes back, and under a
+ * loaded suite the spawn can outlast the window, which flips
+ * `classifyTransition` from the reset branch to failover. That is how
+ * "a quota exhaustion carrying a scheduled reset..." passed alone and failed
+ * in the full run. Emitting the instant here makes the window start where the
+ * test means it to.
+ *
+ * @param {Record<string, unknown>} envelope
+ * @returns {Record<string, unknown>}
+ */
+function resolveRelativeReset(envelope) {
+  const error = envelope.error;
+  if (!error || typeof error !== "object") return envelope;
+  const record = /** @type {Record<string, unknown>} */ (error);
+  const resetAt = record.resetAt;
+  if (typeof resetAt !== "string" || !/^\+\d+$/u.test(resetAt)) return envelope;
+  const at = new Date(Date.now() + Number(resetAt.slice(1))).toISOString();
+  return { ...envelope, error: { ...record, resetAt: at } };
+}
+
+if (record.delayMs !== undefined && record.delayMs > 0) {
+  await new Promise((settle) => setTimeout(settle, record.delayMs));
+}
+if (record.stdoutRaw !== undefined) {
+  process.stdout.write(record.stdoutRaw);
+} else {
+  process.stdout.write(`${JSON.stringify(resolveRelativeReset(record.envelope))}\n`);
+}
+process.exitCode = record.exitCode ?? 0;

package/src/harnesses/replay/index.mjs

@@ -0,0 +1,238 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseVersion } from "../protocol.mjs";
+
+/** Envelope statuses a recording may carry. */
+const REPLAY_STATUSES = Object.freeze(new Set([
+  "done",
+  "no-op",
+  "blocked",
+  "failed",
+  "exhausted",
+  "stalled",
+  "canceled",
+]));
+
+/**
+ * Deterministic provider stand-in. The recording holds already-normalized
+ * envelopes consumed strictly in order through a `<recording>.cursor` sidecar,
+ * so the controller exercises everything after provider normalization with
+ * zero model invocations.
+ *
+ * @type {import("../index.mjs").HarnessAdapter}
+ */
+export const replayHarness = {
+  capabilities: {
+    structuredOutput: true,
+    promptTransport: "stdin",
+    sandbox: false,
+    permissions: false,
+    continuation: true,
+    tokenBudget: true,
+    costBudget: true,
+    usage: true,
+    cost: true,
+    // A recording cannot prove mechanical tool-policy enforcement.
+    toolPolicy: false,
+    // replay/bin.mjs writes its one envelope line after the recorded delay,
+    // never incrementally.
+    streamsOutput: false,
+  },
+
+  // A recording exposes no permission mode.
+  permissionExecution: null,
+
+  /** @param {import("../index.mjs").HarnessRuntime} runtime @returns {string} */
+  executable(runtime) {
+    return process.env.FABERUN_REPLAY_BIN
+      ?? runtime.executable
+      ?? fileURLToPath(new URL("./bin.mjs", import.meta.url));
+  },
+
+  /**
+   * A recording only stands in for a prompt invocation; the live version
+   * probe (`probeRuntime`) never touches it, so a deterministic case that
+   * needs to prove a probe's own balance/quota/missing-CLI classification
+   * declares `config["replay.probe"]` instead — carried to replay/bin.mjs as
+   * a `--replay-probe` argument, the same way a recorded envelope carries
+   * `error.resetAt` to prove a reset instant.
+   *
+   * @param {import("../index.mjs").HarnessRuntime} runtime @returns {string[]}
+   */
+  versionArgs(runtime) {
+    const probe = runtime.config?.["replay.probe"];
+    if (probe === undefined) return runtime.versionArgs ?? ["--version"];
+    if (!probe || typeof probe !== "object" || Array.isArray(probe)) {
+      throw new TypeError('replay runtime config["replay.probe"] must be an object');
+    }
+    return ["--version", "--replay-probe", JSON.stringify(probe)];
+  },
+
+  parseVersion,
+
+  /** @param {import("../index.mjs").HarnessRuntime} runtime @param {string} prompt @param {import("../index.mjs").CommandOptions} options @returns {import("../index.mjs").HarnessCommand} */
+  command(runtime, prompt, options) {
+    const recording = runtime.config?.["replay.recording"];
+    if (typeof recording !== "string" || recording.length === 0) {
+      throw new TypeError('replay runtime requires config["replay.recording"]');
+    }
+    const args = ["--recording", resolve(recording)];
+    if (options.continuationId) args.push("--continuation", options.continuationId);
+    if (options.schema || options.schemaPath) args.push("--schema");
+    return {
+      executable: this.executable(runtime),
+      args,
+      promptTransport: "stdin",
+      input: prompt,
+    };
+  },
+
+  normalize: normalizeReplayResult,
+};
+
+export const harness = replayHarness;
+export default replayHarness;
+
+/**
+ * Parse the last non-empty stdout line as an already-normalized provider
+ * envelope. Canonical fields are kept — including the optional
+ * `error.resetAt` and `exhaustedUntil`, in exactly the shape
+ * `ProviderEnvelope` declares for a real harness — and unknown fields are
+ * dropped; anything else (prose, an empty stream, a non-zero exit with no
+ * envelope) normalizes to a `failed` envelope with error code
+ * `invalid_output`. Never throws.
+ *
+ * @param {string} stdout
+ * @param {number|null} exitCode
+ * @param {string|null} signal
+ * @returns {import("../index.mjs").ProviderEnvelope}
+ */
+function normalizeReplayResult(stdout, exitCode, signal) {
+  const envelope = parseLastEnvelope(stdout);
+  if (envelope) return envelope;
+  const reason = signal
+    ? `provider ended after ${signal}`
+    : exitCode
+      ? `replay exited with code ${exitCode}`
+      : lastNonEmpty(stdout) === null
+        ? "replay emitted no stdout"
+        : "replay stdout is not a valid envelope";
+  return {
+    status: "failed",
+    result: null,
+    continuationId: null,
+    usage: { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 },
+    costUsd: null,
+    error: { code: "invalid_output", message: boundedText(reason, 512) },
+  };
+}
+
+/**
+ * @param {string} stdout
+ * @returns {import("../index.mjs").ProviderEnvelope|null}
+ */
+function parseLastEnvelope(stdout) {
+  const line = lastNonEmpty(stdout);
+  if (line === null) return null;
+  /** @type {unknown} */
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  return canonicalEnvelope(parsed);
+}
+
+/**
+ * @param {string} stdout
+ * @returns {string|null}
+ */
+function lastNonEmpty(stdout) {
+  return String(stdout ?? "")
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .at(-1) ?? null;
+}
+
+/**
+ * Validate one parsed stdout value as a canonical envelope and return it with
+ * exactly the canonical fields. Returns null (never throws) when the value is
+ * not a well-formed envelope.
+ *
+ * @param {unknown} value
+ * @returns {import("../index.mjs").ProviderEnvelope|null}
+ */
+function canonicalEnvelope(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const envelope = /** @type {Record<string, unknown>} */ (value);
+  const status = envelope.status;
+  if (typeof status !== "string" || !REPLAY_STATUSES.has(status)) return null;
+  const result = envelope.result;
+  if (result !== null && typeof result !== "string") return null;
+  const continuationId = envelope.continuationId;
+  if (continuationId !== null && typeof continuationId !== "string") return null;
+  const usage = canonicalUsage(envelope.usage);
+  if (!usage) return null;
+  const costUsd = envelope.costUsd;
+  if (costUsd !== null && (typeof costUsd !== "number" || !Number.isFinite(costUsd) || costUsd < 0)) return null;
+  const error = canonicalError(envelope.error);
+  if (error === undefined) return null;
+  const exhaustedUntil = envelope.exhaustedUntil;
+  if (exhaustedUntil !== undefined && exhaustedUntil !== null && typeof exhaustedUntil !== "string") return null;
+  return {
+    status: /** @type {"done"|"no-op"|"blocked"|"failed"|"exhausted"|"stalled"|"canceled"} */ (status),
+    result,
+    continuationId,
+    usage,
+    costUsd,
+    error,
+    ...(exhaustedUntil !== undefined ? { exhaustedUntil } : {}),
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {{inputTokens: number|null, outputTokens: number|null, cacheReadInputTokens: number|null}|null}
+ */
+function canonicalUsage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const usage = /** @type {Record<string, unknown>} */ (value);
+  /** @type {{inputTokens: number|null, outputTokens: number|null, cacheReadInputTokens: number|null}} */
+  const record = { inputTokens: null, outputTokens: null, cacheReadInputTokens: null };
+  for (const key of /** @type {("inputTokens"|"outputTokens"|"cacheReadInputTokens")[]} */ (Object.keys(record))) {
+    const raw = usage[key];
+    if (raw === undefined) continue;
+    if (raw !== null && (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0)) return null;
+    record[key] = raw;
+  }
+  return record;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {{code: string, message: string, resetAt?: string|null}|null|undefined}
+ */
+function canonicalError(value) {
+  if (value === null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const error = /** @type {Record<string, unknown>} */ (value);
+  if (typeof error.code !== "string" || error.code.length === 0 || typeof error.message !== "string") return undefined;
+  const resetAt = error.resetAt;
+  if (resetAt !== undefined && resetAt !== null && typeof resetAt !== "string") return undefined;
+  return { code: error.code, message: error.message, ...(resetAt !== undefined ? { resetAt } : {}) };
+}
+
+/**
+ * @param {string} value
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+function boundedText(value, maxBytes) {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.length <= maxBytes) return bytes.toString("utf8");
+  let end = maxBytes;
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+  return `${bytes.subarray(0, end).toString("utf8")}…`;
+}