@agentswf/engine 0.0.0-stage → 0.1.0-beta.1

package/src/decisions/directory.ts

@@ -0,0 +1,432 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { DecisionArtifact, Money, SettledDecision } from "@agentswf/contract/records";
+import {
+  type AbsoluteDeadline,
+  type Answers,
+  DeadlineExceededError,
+  DecisionError,
+  type DecisionRecord,
+  type DecisionSpec,
+  type JsonObject,
+  type JsonValue,
+  type Question,
+} from "@agentswf/contract/workflow";
+import { canonical } from "../canonical-json";
+import {
+  abortableSleep,
+  assertDeadline,
+  assertDeadlineValue,
+  earlierDeadline,
+  scheduleAt,
+} from "../deadlines";
+import { messageOf } from "../errors";
+import type { RunEventBody } from "../run-event-log";
+import {
+  type DecisionInstallation,
+  type DecisionProvider,
+  DecisionProviderError,
+  type ProviderAnswer,
+  type ProviderResponse,
+} from "./seam";
+
+const MAX_ATTEMPTS = 3;
+const FIRST_BACKOFF_MILLISECONDS = 500;
+
+/** Where a call runs: its scope's deadline, and the scope's way of cancelling what it owns. */
+export type DecisionScope = {
+  deadline: AbsoluteDeadline;
+  /** Returns the removal. */
+  add?(cancel: (reason: string) => Promise<unknown>): () => void;
+  /** The workflow stage it is asked in. */
+  stage?: string;
+};
+
+type PreparedCall = {
+  spec: DecisionSpec;
+  ids: string[];
+  resolved: { provider: string; model: string };
+  provider: DecisionProvider;
+  deadline: AbsoluteDeadline;
+  slot: number;
+};
+
+type Ending =
+  | { outcome: "timed-out"; deadline: AbsoluteDeadline }
+  | { outcome: "cancelled"; reason: string };
+
+/**
+ * Every decision one run asks: it resolves aliases, bounds each call by its deadline, retries what
+ * the provider says is retryable, and keeps a record and an artifact of each, answered or not.
+ */
+export class RunDecisions {
+  readonly #slots: (SettledDecision | undefined)[] = [];
+  readonly #cancellers = new Set<(reason: string) => void>();
+  readonly #inFlight = new Set<Promise<unknown>>();
+  #closed = false;
+
+  constructor(
+    private readonly options: {
+      installation?: DecisionInstallation;
+      runDir: string;
+      sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+      /** Writes the run's event log. */
+      event?(body: RunEventBody): void;
+    },
+  ) {}
+
+  decide<Q extends Record<string, Question>>(
+    spec: DecisionSpec<Q>,
+    scope: DecisionScope,
+  ): Promise<{ answers: Answers<Q>; record: DecisionRecord }> {
+    try {
+      if (this.#closed) throw new Error("workflow context is closed");
+      const call = this.#prepare(spec, scope);
+      const running = this.#run(call, scope);
+      this.#inFlight.add(running);
+      running.finally(() => this.#inFlight.delete(running)).catch(() => undefined);
+      return running as Promise<{ answers: Answers<Q>; record: DecisionRecord }>;
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+
+  /** Every call that has settled, in the order they were asked. */
+  records(): SettledDecision[] {
+    return this.#slots.filter((record): record is SettledDecision => record !== undefined);
+  }
+
+  /** Cancels every call still in flight, and waits for each to be recorded. */
+  async close(): Promise<void> {
+    this.#closed = true;
+    for (const cancel of this.#cancellers) cancel("workflow closed");
+    await Promise.allSettled([...this.#inFlight]);
+  }
+
+  #prepare(spec: DecisionSpec, scope: DecisionScope): PreparedCall {
+    if (typeof spec.key !== "string" || spec.key === "") {
+      throw new Error("a decision needs a key");
+    }
+    const ids = Object.keys(spec.questions ?? {});
+    if (ids.length === 0) throw new Error(`decision ${spec.key} asks no questions`);
+    for (const id of ids) assertQuestion(spec.key, id, spec.questions[id]!);
+    if (typeof spec.state !== "string" && (typeof spec.state !== "object" || spec.state === null)) {
+      throw new Error(`decision ${spec.key}: a state is text, an object or an array`);
+    }
+    const installed = this.options.installation;
+    const resolved =
+      installed && Object.hasOwn(installed.aliases, spec.model)
+        ? installed.aliases[spec.model]
+        : undefined;
+    const unavailable = installed?.unavailable;
+    if (!resolved && unavailable && Object.hasOwn(unavailable, spec.model)) {
+      throw new Error(`decision model "${spec.model}" is unavailable: ${unavailable[spec.model]}`);
+    }
+    if (!installed || !resolved) {
+      const known = Object.keys(installed?.aliases ?? {});
+      throw new Error(
+        `no decision model alias "${spec.model}"; ${known.length === 0 ? "none is installed" : `installed: ${known.join(", ")}`}`,
+      );
+    }
+    const provider = Object.hasOwn(installed.providers, resolved.provider)
+      ? installed.providers[resolved.provider]
+      : undefined;
+    if (!provider) throw new Error(`decision provider "${resolved.provider}" is not installed`);
+    if (spec.deadline) assertDeadlineValue(spec.deadline);
+    const deadline = spec.deadline
+      ? earlierDeadline(spec.deadline, scope.deadline)
+      : scope.deadline;
+    assertDeadline(deadline);
+    const slot = this.#slots.length;
+    this.#slots.push(undefined);
+    this.options.event?.({
+      kind: "decision-asked",
+      decision: slot + 1,
+      ...(scope.stage === undefined ? {} : { stage: scope.stage }),
+      key: spec.key,
+      alias: spec.model,
+      provider: resolved.provider,
+      model: resolved.model,
+    });
+    return { spec, ids, resolved, provider, deadline, slot };
+  }
+
+  async #run(
+    call: PreparedCall,
+    scope: DecisionScope,
+  ): Promise<{ answers: Record<string, unknown>; record: DecisionRecord }> {
+    const { spec, ids, resolved, provider, deadline, slot } = call;
+    const startedAt = new Date().toISOString();
+    const controller = new AbortController();
+    let ending: Ending | undefined;
+    const end = (next: Ending) => {
+      ending ??= next;
+      controller.abort(next.outcome);
+    };
+    const cancel = (reason: string) => end({ outcome: "cancelled", reason });
+    const cancelTimer = scheduleAt(deadline, () => end({ outcome: "timed-out", deadline }));
+    this.#cancellers.add(cancel);
+    const removeFromScope = scope.add?.(async (reason) => cancel(reason));
+
+    let attempts = 0;
+    let tokens: { input: number; output: number } | undefined;
+    let charged: Money[] = [];
+    let requestId: string | undefined;
+    let response: ProviderResponse | undefined;
+    let answers: Record<string, unknown> | undefined;
+    let error: string | undefined;
+    const count = (spent: {
+      tokens?: ProviderResponse["tokens"];
+      charged?: Money;
+      requestId?: string;
+    }) => {
+      if (spent.tokens) {
+        tokens = {
+          input: (tokens?.input ?? 0) + spent.tokens.input,
+          output: (tokens?.output ?? 0) + spent.tokens.output,
+        };
+      }
+      if (spent.charged) charged = [...charged, spent.charged];
+      if (spent.requestId) requestId = spent.requestId;
+    };
+    const request = {
+      key: spec.key,
+      model: resolved.model,
+      state: spec.state,
+      questions: spec.questions,
+    };
+    try {
+      while (true) {
+        attempts += 1;
+        try {
+          // A provider that ignores the signal still cannot hold the call past its end.
+          response = await untilAborted(
+            provider.decide(structuredClone(request), controller.signal),
+            controller.signal,
+          );
+          count(response);
+          answers = answersOf(spec.questions, response.answers);
+          break;
+        } catch (thrown) {
+          if (thrown instanceof DecisionProviderError) count(thrown);
+          if (ending) break;
+          error = messageOf(thrown);
+          const backoff = FIRST_BACKOFF_MILLISECONDS * 2 ** (attempts - 1);
+          const retry =
+            thrown instanceof DecisionProviderError &&
+            thrown.retryable &&
+            attempts < MAX_ATTEMPTS &&
+            Date.now() + backoff < deadline.unixMilliseconds;
+          if (!retry) break;
+          await (this.options.sleep ?? abortableSleep)(backoff, controller.signal);
+          if (ending) break;
+          error = undefined;
+        }
+      }
+    } finally {
+      cancelTimer();
+      removeFromScope?.();
+      this.#cancellers.delete(cancel);
+    }
+
+    const artifact = join("decisions", `${slot + 1}.json`);
+    const outcome: DecisionRecord["outcome"] = ending
+      ? ending.outcome
+      : answers
+        ? "answered"
+        : "failed";
+    const failure =
+      ending?.outcome === "timed-out"
+        ? `deadline exceeded after ${attempts} attempt${attempts === 1 ? "" : "s"}`
+        : ending?.outcome === "cancelled"
+          ? `cancelled: ${ending.reason}`
+          : error;
+    const record: DecisionRecord = {
+      callPath: [],
+      key: spec.key,
+      ...(scope.stage === undefined ? {} : { stage: scope.stage }),
+      alias: spec.model,
+      provider: resolved.provider,
+      model: resolved.model,
+      ...(response ? { snapshot: response.snapshot } : {}),
+      startedAt,
+      settledAt: new Date().toISOString(),
+      questions: ids.map((id) => ({ id, type: spec.questions[id]!.type })),
+      questionsDigest: digestOf(spec.questions),
+      outcome,
+      ...(outcome === "answered" || failure === undefined ? {} : { error: failure }),
+      attempts,
+      ...(tokens ? { tokens } : {}),
+      ...(requestId ? { requestId } : {}),
+      artifact,
+    };
+    const total = sumMoney(charged);
+    let settled: SettledDecision = { ...record, ...(total ? { charged: total } : {}) };
+    const written: DecisionArtifact = {
+      record: settled,
+      request: { state: spec.state, questions: spec.questions },
+      ...(answers ? { answers: answers as JsonObject } : {}),
+    };
+    try {
+      await mkdir(join(this.options.runDir, "decisions"), { recursive: true });
+      await writeFile(join(this.options.runDir, artifact), `${JSON.stringify(written, null, 2)}\n`);
+    } catch (thrown) {
+      const lost = `artifact not written: ${messageOf(thrown)}`;
+      // Without its artifact an answer cannot be fitted again, so it does not count as one; any
+      // other outcome stands.
+      settled =
+        settled.outcome === "answered"
+          ? { ...settled, outcome: "failed", error: lost }
+          : { ...settled, error: `${settled.error ?? settled.outcome}; ${lost}` };
+    }
+    this.#slots[slot] = settled;
+    this.options.event?.({
+      kind: "decision-ended",
+      decision: slot + 1,
+      ...(settled.stage === undefined ? {} : { stage: settled.stage }),
+      outcome: settled.outcome,
+      ...(settled.error === undefined ? {} : { error: settled.error }),
+    });
+    const { charged: _charged, ...returned } = settled;
+
+    if (returned.outcome === "answered") return { answers: answers!, record: returned };
+    if (returned.outcome === "timed-out") throw new DeadlineExceededError(deadline);
+    throw new DecisionError(`decision ${spec.key}: ${returned.error}`, returned);
+  }
+}
+
+function assertQuestion(key: string, id: string, question: Question): void {
+  const where = `decision ${key}, question ${id}`;
+  if (!question || typeof question !== "object") throw new Error(`${where} is not a question`);
+  switch (question.type) {
+    case "choice":
+      if (Object.keys(question.options ?? {}).length === 0)
+        throw new Error(`${where} has no options`);
+      return;
+    case "score":
+      if (!Array.isArray(question.levels) || question.levels.length === 0) {
+        throw new Error(`${where} has no levels`);
+      }
+      return;
+    case "yes-no":
+      return;
+    default:
+      throw new Error(
+        `${where} has unknown type ${JSON.stringify((question as { type?: unknown }).type)}`,
+      );
+  }
+}
+
+/**
+ * Every question answered with its own type and a whole distribution, or the call failed: a
+ * partial answer is never passed on.
+ */
+export function answersOf(
+  questions: Record<string, Question>,
+  provided: Record<string, ProviderAnswer>,
+): Record<string, unknown> {
+  const answers: Record<string, unknown> = {};
+  for (const [id, question] of Object.entries(questions)) {
+    const answer = Object.hasOwn(provided, id) ? provided[id] : undefined;
+    const invalid = (detail: string) => new Error(`question ${id}: ${detail}`);
+    if (!answer) throw invalid("not answered");
+    if (answer.type !== question.type) throw invalid(`answered as ${answer.type}`);
+    if (question.type === "choice" && answer.type === "choice") {
+      const names = Object.keys(question.options);
+      const given = answer.probabilities ?? {};
+      const extra = Object.keys(given).filter((name) => !names.includes(name));
+      if (extra.length > 0) throw invalid(`unknown option ${extra.join(", ")}`);
+      const probabilities = names.map((name) =>
+        Object.hasOwn(given, name) ? given[name] : undefined,
+      );
+      const missing = names.find((_, index) => !isProbability(probabilities[index]));
+      if (missing !== undefined) throw invalid(`no probability for option ${missing}`);
+      const index = assertDistribution(probabilities as number[], invalid);
+      answers[id] = {
+        type: "choice",
+        choice: names[index]!,
+        // Built from entries, so an option named like a prototype key is still an own key.
+        probabilities: Object.fromEntries(names.map((name, at) => [name, probabilities[at]!])),
+      };
+    } else if (question.type === "score" && answer.type === "score") {
+      const probabilities = answer.probabilities ?? [];
+      if (probabilities.length !== question.levels.length || !probabilities.every(isProbability)) {
+        throw invalid(`expected a probability for each of ${question.levels.length} levels`);
+      }
+      const level = assertDistribution(probabilities, invalid);
+      const total = probabilities.reduce((sum, probability) => sum + probability, 0);
+      const expected =
+        probabilities.reduce((sum, probability, at) => sum + probability * at, 0) / total;
+      answers[id] = { type: "score", level, expected, probabilities: [...probabilities] };
+    } else if (answer.type === "yes-no") {
+      if (!isProbability(answer.yes)) throw invalid("no probability of yes");
+      answers[id] = { type: "yes-no", yes: answer.yes };
+    }
+  }
+  return answers;
+}
+
+/**
+ * A distribution sums to 1, give or take each probability's rounding to two decimals (Jev's sum to
+ * 0.99–1.00, S10). Returns the most likely index, the first of them on a tie.
+ */
+function assertDistribution(
+  probabilities: readonly number[],
+  invalid: (detail: string) => Error,
+): number {
+  const total = probabilities.reduce((sum, probability) => sum + probability, 0);
+  const slack = Math.max(0.02, probabilities.length * 0.005);
+  if (Math.abs(total - 1) > slack) throw invalid(`probabilities sum to ${total}, not 1`);
+  return probabilities.reduce(
+    (best, probability, at) => (probability > probabilities[best]! ? at : best),
+    0,
+  );
+}
+
+/**
+ * SHA-256 of the questions as JSON with every object's keys sorted, except a choice's options:
+ * their order breaks ties and may sway the model, so it counts.
+ */
+export function digestOf(questions: Record<string, Question>): string {
+  const ordered = Object.fromEntries(
+    Object.entries(questions).map(([id, question]) => [
+      id,
+      question.type === "choice"
+        ? { ...question, options: Object.entries(question.options) }
+        : question,
+    ]),
+  );
+  return createHash("sha256")
+    .update(JSON.stringify(canonical(ordered as unknown as JsonValue)))
+    .digest("hex");
+}
+
+function isProbability(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+/** Charges in more than one currency cannot be added without converting, so their sum is unknown. */
+function sumMoney(charges: readonly Money[]): Money | undefined {
+  const currency = charges[0]?.currency;
+  if (!currency || charges.some((charge) => charge.currency !== currency)) return undefined;
+  return { amount: charges.reduce((sum, charge) => sum + charge.amount, 0), currency };
+}
+
+function untilAborted<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", abort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", abort);
+        reject(error);
+      },
+    );
+  });
+}

package/src/decisions/fake.ts

@@ -0,0 +1,60 @@
+import type { Question } from "@agentswf/contract/workflow";
+import type { DecisionProvider, ProviderAnswer, ProviderRequest, ProviderResponse } from "./seam";
+
+/** One scripted reply: a response, an error to throw, or a function of the request. */
+export type FakeReply =
+  | ProviderResponse
+  | Error
+  | ((request: ProviderRequest, signal: AbortSignal) => Promise<ProviderResponse>);
+
+/**
+ * A provider that answers from a script, one reply per request, and then with `fallback`. For the
+ * engine's own tests; the default answers every question with its first option or level at 0.9.
+ */
+export function createFakeDecisionProvider(
+  script: FakeReply[] = [],
+  fallback: FakeReply = (request) => Promise.resolve(confidentResponse(request)),
+): DecisionProvider & { requests: ProviderRequest[] } {
+  const requests: ProviderRequest[] = [];
+  return {
+    requests,
+    async decide(request, signal) {
+      requests.push(request);
+      const reply = script.shift() ?? fallback;
+      if (reply instanceof Error) throw reply;
+      if (typeof reply === "function") return reply(request, signal);
+      return reply;
+    },
+  };
+}
+
+/** The first option or level at 0.9, the rest sharing 0.1; yes at 0.9. */
+export function confidentResponse(request: ProviderRequest): ProviderResponse {
+  const answers: Record<string, ProviderAnswer> = {};
+  for (const [id, question] of Object.entries(request.questions)) answers[id] = confident(question);
+  return {
+    snapshot: `${request.model}-20260926`,
+    answers,
+    tokens: { input: 1_000, output: 10 },
+    charged: { amount: 0.000042, currency: "USD" },
+    requestId: `request-${Object.keys(request.questions).join("-")}`,
+  };
+}
+
+function confident(question: Question): ProviderAnswer {
+  if (question.type === "yes-no") return { type: "yes-no", yes: 0.9 };
+  const names =
+    question.type === "choice" ? Object.keys(question.options) : question.levels.map(String);
+  const rest = names.length > 1 ? 0.1 / (names.length - 1) : 0;
+  const probabilities = names.map((_, index) =>
+    names.length === 1 ? 1 : index === 0 ? 0.9 : rest,
+  );
+  return question.type === "choice"
+    ? {
+        type: "choice",
+        probabilities: Object.fromEntries(
+          names.map((name, index) => [name, probabilities[index]!]),
+        ),
+      }
+    : { type: "score", probabilities };
+}

package/src/decisions/openrouter.ts

@@ -0,0 +1,161 @@
+import { isRecord } from "@agentswf/contract";
+import type { Question } from "@agentswf/contract/workflow";
+import { messageOf } from "../errors";
+import {
+  type DecisionProvider,
+  DecisionProviderError,
+  type ProviderAnswer,
+  type ProviderRequest,
+  type ProviderResponse,
+} from "./seam";
+
+export const OPENROUTER_DECISIONS = "https://openrouter.ai/api/alpha/decisions";
+
+/**
+ * OpenRouter's Decisions API, which serves Jev (docs/research/system-one-models.md §2). It speaks
+ * Jev's words: a yes-no is a `noul`, and `criteria` carries a choice's options, a score's levels
+ * and a yes-no's criteria alike.
+ */
+export function createOpenRouterProvider(options: {
+  apiKey: string;
+  endpoint?: string;
+  fetch?: typeof globalThis.fetch;
+}): DecisionProvider {
+  const { apiKey, endpoint = OPENROUTER_DECISIONS, fetch = globalThis.fetch } = options;
+  // An error from the transport can quote the request's headers; the key never leaves in one.
+  const redacted = (error: unknown) => messageOf(error).replaceAll(apiKey, "[OPENROUTER_API_KEY]");
+  return {
+    async decide(request, signal) {
+      let text: string;
+      let status: number;
+      try {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+          body: JSON.stringify(wireRequest(request)),
+          signal,
+        });
+        status = response.status;
+        text = await response.text();
+      } catch (error) {
+        if (signal.aborted) throw error;
+        // The connection failed before or while answering; it may come back.
+        throw new DecisionProviderError(`openrouter unreachable: ${redacted(error)}`, {
+          retryable: true,
+        });
+      }
+      const body = parse(text);
+      const failure = errorOf(body);
+      if (status < 200 || status >= 300 || failure) {
+        const code = failure?.code ?? status;
+        const message = failure?.message ?? (text.slice(0, 200) || `status ${status}`);
+        throw new DecisionProviderError(`openrouter ${code}: ${message}`, {
+          retryable: code === 429 || code >= 500,
+          ...spendOf(body),
+        });
+      }
+      return fromWire(request.questions, body);
+    },
+  };
+}
+
+function wireRequest(request: ProviderRequest): Record<string, unknown> {
+  return {
+    model: request.model,
+    state: request.state,
+    questions: Object.fromEntries(
+      Object.entries(request.questions).map(([id, question]) => [id, wireQuestion(question)]),
+    ),
+  };
+}
+
+function wireQuestion(question: Question): Record<string, unknown> {
+  switch (question.type) {
+    case "choice":
+      return { type: "choice", instructions: question.instructions, criteria: question.options };
+    case "score":
+      return { type: "score", instructions: question.instructions, criteria: question.levels };
+    case "yes-no":
+      return {
+        type: "noul",
+        instructions: question.instructions,
+        ...(question.criteria
+          ? { criteria: { true: question.criteria.yes, false: question.criteria.no } }
+          : {}),
+      };
+  }
+}
+
+/**
+ * Only the distributions are kept: the pick and `score` are derived again from them, and Jev's
+ * `confidence` cannot be (findings S10). What is missing is left missing, for the directory to
+ * reject.
+ */
+function fromWire(questions: Record<string, Question>, body: unknown): ProviderResponse {
+  if (!isRecord(body) || typeof body.model !== "string" || !isRecord(body.answers)) {
+    throw new DecisionProviderError("openrouter answered without a model or answers", {
+      retryable: false,
+      ...spendOf(body),
+    });
+  }
+  const answers: Record<string, ProviderAnswer> = {};
+  for (const [id, question] of Object.entries(questions)) {
+    const answer = Object.hasOwn(body.answers, id) ? body.answers[id] : undefined;
+    if (!isRecord(answer)) continue;
+    const probabilities = isRecord(answer.probabilities) ? answer.probabilities : {};
+    if (answer.type === "noul") {
+      answers[id] = { type: "yes-no", yes: answer.noul as number };
+    } else if (answer.type === "choice") {
+      answers[id] = { type: "choice", probabilities: probabilities as Record<string, number> };
+    } else if (answer.type === "score") {
+      answers[id] = { type: "score", probabilities: levelsOf(question, probabilities) };
+    }
+  }
+  return { snapshot: body.model, answers, ...spendOf(body) };
+}
+
+/**
+ * A score's probabilities, keyed "0" to "n-1", as a list. Any other key makes the list the wrong
+ * length, for the directory to reject, as it rejects an option nobody asked about.
+ */
+function levelsOf(question: Question, probabilities: Record<string, unknown>): number[] {
+  const count = question.type === "score" ? question.levels.length : 0;
+  const listed = Array.from(
+    { length: count },
+    (_, index) => probabilities[String(index)] as number,
+  );
+  const expected = new Set(listed.map((_, index) => String(index)));
+  const extra = Object.keys(probabilities).filter((key) => !expected.has(key));
+  return extra.length === 0 ? listed : [...listed, ...extra.map(() => Number.NaN)];
+}
+
+/** What a body says was spent, as far as it says: tokens only when both counts are reported. */
+function spendOf(body: unknown): Pick<ProviderResponse, "tokens" | "charged" | "requestId"> {
+  if (!isRecord(body)) return {};
+  const usage = isRecord(body.usage) ? body.usage : {};
+  const counted = typeof usage.input_tokens === "number" && typeof usage.output_tokens === "number";
+  return {
+    ...(counted
+      ? { tokens: { input: usage.input_tokens as number, output: usage.output_tokens as number } }
+      : {}),
+    ...(typeof usage.cost === "number" ? { charged: { amount: usage.cost, currency: "USD" } } : {}),
+    ...(typeof body.id === "string" ? { requestId: body.id } : {}),
+  };
+}
+
+function errorOf(body: unknown): { code: number; message: string } | undefined {
+  if (!isRecord(body) || !isRecord(body.error)) return undefined;
+  const { code, message } = body.error;
+  return {
+    code: typeof code === "number" ? code : 500,
+    message: typeof message === "string" ? message : JSON.stringify(body.error),
+  };
+}
+
+function parse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}