decision-api 1.2.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # decision-api
 
-One client for decision models: models that answer typed questions with calibrated probabilities instead of text. It speaks TypeSafe's Jev, Cloudflare's Clef and Clef-flash (Workers AI), OpenAI's gpt-6-luna and the decision models on OpenRouter (such as `microsoft/microsoft-decision-1` and `typesafe/jev-1.13`), and returns the same answer shape from all of them. It depends only on `zod`.
+One client for decision models: models that answer typed questions with calibrated probabilities instead of text. It speaks TypeSafe's Jev, Cloudflare's Clef and Clef-flash (Workers AI), OpenAI's gpt-6-luna and the decision models on OpenRouter (such as `microsoft/microsoft-decision-1` and `typesafe/jev-1.13`), and returns the same answer shape from all of them. Jev also reads images. It depends only on `zod`.
 
 ```sh
 npm install decision-api
@@ -18,7 +18,8 @@ const decide = createDecisionApi({
 	},
 	defaultModel: 'jev',
 	registerUsage: (usage, context: { customerId: string }) => {
-		// usage: model, provider, inputTokens, outputTokens, costUsd, latencyMs
+		// usage: model, resolvedModel, provider, inputTokens, outputTokens,
+		// costUsd, latencyMs, attempts
 	},
 	onError: (error, context) => console.warn(error.kind, error.message)
 })
@@ -49,13 +50,123 @@ TypeScript enforces the setup:
 - **The model is optional only with a default.** Without `defaultModel`, every call must name one.
 - **Usage context is required when typed.** The type of `registerUsage`'s second parameter is required on every call and passed back to `registerUsage` and `onError`.
 
-A call answers `null` instead of throwing, and `onError` says why: `timeout`, `aborted` (the call's own signal), `unauthorized` (401/403, a bad key), `out-of-credits` (402), `rate-limited` (429 after the retry), `request-failed` (any other status, or a transport error), `state-too-large`, `unreadable-response` or `answer-mismatch`. Every error carries its `model` and `provider`, and `status` when the provider answered; a throwing `registerUsage` reports `usage-failed` without failing the call. Retryable statuses (429 and 5xx) are retried once, after the provider's `Retry-After` when it asks for 2 s or less, and not at all when it asks for more. `fetch` replaces the transport, for example to route calls through your own rate limits, and `defaultSignal` supplies the signal for calls that pass none. A call with no questions answers `{}` without a request. The one throw is a call with no model and no `defaultModel`, which TypeScript already rejects.
+A call answers `null` instead of throwing, and `onError` says why: `timeout`, `aborted` (the call's own signal: your own doing, so a logging `onError` may skip it), `unauthorized` (401/403, a bad key), `out-of-credits` (402), `rate-limited` (429 after the retry), `request-failed` (any other status, or a transport error), `request-too-large` (see below), `images-unsupported`, `image-detached` (see [Images](#images)), `unreadable-response` or `answer-mismatch`. Every error carries its `model` and `provider`, `status` when the provider answered, `latencyMs` and `attempts`; a throwing `registerUsage` reports `usage-failed` without failing the call. `fetch` replaces the transport, for example to route calls through your own rate limits, and `defaultSignal` supplies the signal for calls that pass none. A call with no questions answers `{}` without a request. The one throw is a call with no model and no `defaultModel`, which TypeScript already rejects.
+
+**Timeouts and retries.** `timeoutMs` (default 4 s, per client or per call) bounds the whole call: every attempt, the pause between them and the body read. A status of 429, 500, 502, 503, 504 or 529 and a transport error are retried once, after the provider's `Retry-After` when it asks for 2 s or less and the deadline leaves time for it; otherwise the call fails at once. `attemptTimeoutMs` (off by default) abandons a request that has not answered by then and sends one more while time remains, so a voice turn can set `timeoutMs: 1_200, attemptTimeoutMs: 500` and still get a second try. An abandoned request may still be billed.
+
+**Size.** The state and questions together are measured before sending: past `maxRequestChars` (default `DECISION_MAX_REQUEST_CHARS`, 90k characters, under Jev's ~32.5k-token wall) the call fails with `request-too-large` and nothing is sent. So does a call over its model's `maxQuestions`, `maxChoices` (options in one choice) or `maxLevels` (levels in one score) in `DECISION_MODELS`, and a provider's own token-limit refusal maps to the same kind. Extra questions add next to nothing to latency, but every question's instructions and criteria are billed as input tokens.
+
+## Usage and errors per call
+
+`decide.result()` takes the same arguments as `decide()` and answers what happened, so a caller can store the model, tokens and latency next to its own record, or the reason there is no answer, without a side channel through the usage context:
+
+```ts
+const outcome = await decide.result({ state, questions, customerId: 'c_1' })
+if (outcome.ok) {
+	outcome.answers // as decide() answers them
+	outcome.usage // DecisionUsage; null for a call with no questions
+} else {
+	outcome.error // DecisionError: kind, status, latencyMs, attempts
+}
+```
+
+`registerUsage` and `onError` still run. `usage.resolvedModel` is the model the provider says answered, when it says: TypeSafe resolves `jev` (sent as `jev-latest`) to a release there, so a new Jev release shows up in your rows.
+
+## One question per item
+
+`perItem` asks the same question about each item of a list under keys `prefix_0`, `prefix_1`… and reads the answers back typed, with no key helpers and no `undefined` to default:
+
+```ts
+import { perItem } from 'decision-api'
+
+const perBlock = perItem(blocks, 'block', (block, index) => ({
+	type: 'noul',
+	instructions: `Does \`blocks[${index}]\` hold private material?`
+}))
+const answers = await decide({
+	state: { blocks },
+	questions: { ...perBlock.questions, rules },
+	customerId: 'c_1'
+})
+for (const { item, answer } of answers ? perBlock.read(answers) : []) {
+	if (answer.noul >= 0.35) flagged.push(item.id)
+}
+```
+
+The single answer types are exported too: `DecisionNoulAnswer`, `DecisionChoiceAnswer`, `DecisionScoreAnswer` and their union `DecisionAnswer`.
+
+## Images
+
+`jev` and `typesafe/jev-1.13` read images (`images: true` in `DECISION_MODELS`). Make one with `image()` from PNG or JPEG bytes or base64, and put it anywhere text can go: in the state, as a question's instructions or as a criterion. Inside a sentence, write it into a `withImages` template:
+
+```ts
+import { image, withImages } from 'decision-api'
+import { readFile } from 'node:fs/promises'
+
+const door = image(await readFile('door-camera.jpg'))
+const badge = image(await readFile('badge.jpg'))
+const thumbsUp = image(await readFile('thumbs-up.png'))
+
+const answers = await decide({
+	state: { door },
+	questions: {
+		same: {
+			type: 'noul',
+			instructions: withImages`Is the person in \`door\` the one on this badge: ${badge}?`
+		},
+		gesture: {
+			type: 'choice',
+			instructions: 'Which gesture does the hand in `door` make?',
+			criteria: { thumbs_up: thumbsUp, none: 'No hand, or another gesture' }
+		}
+	},
+	customerId: 'c_1'
+})
+```
+
+Each image is sent once, base64-encoded under a unique reference, however often it is used; every use still counts as input tokens. TypeSafe's image preview header is added for you. Put an image several questions use in the state, not in each question's instructions.
+
+- **TypeScript rejects an image on a model that reads none**, when the image's type is visible in the call. Questions typed as `Record<string, DecisionQuestion>` don't show it, so the call checks as well and answers `null` with `images-unsupported`.
+- **A plain template loses the image.** `` `Same as ${badge}?` `` writes only the reference; the call answers `null` with `image-detached` instead of asking about a bare string.
+- **Prepare images first.** `image()` throws for anything but PNG or JPEG. Jev rejects images, and never resizes them, outside 280 to 1568 px a side or over 16 MiB, and ignores EXIF orientation, so scale and rotate before sending ([limits](https://docs.typesafe.ai/images#limits)). TypeSafe calls images a preview: the format and accuracy may change between Jev releases.
+
+## Testing
+
+`decision-api/testing` has a fake client typed as the real one, so a test needs no cast. A number answers a noul or a score, a string a choice, or give the full answer. An answer that does not fit its question, or a missing one, throws in the test, since the real client would never return it:
+
+```ts
+import { fakeDecide } from 'decision-api/testing'
+
+const ask = fakeDecide<typeof decide>(() => ({ agreed: 0.9, team: 'billing' }))
+const down = fakeDecide<typeof decide>(() => null) // fails as request-failed
+ask.calls[0]?.questions // what the code under test sent
+```
+
+## Evaluating thresholds
+
+`decision-api/eval` runs labelled cases against a real client and reports each question at the threshold your code ships. The app brings the cases; a case is a call plus the answers a careful human would give:
+
+```ts
+import { report, runCases } from 'decision-api/eval'
+
+const logs = await runCases({
+	decide,
+	cases: [{ name: 'salary slip', state, questions, expected: { private: true } }],
+	runs: 3,
+	models: ['jev'], // the client's default when left out
+	context: { customerId: 'eval' } // when registerUsage types a context
+})
+const summary = report(logs, { thresholds: { private: 0.35 } })
+if (!summary.ok) process.exitCode = 1
+```
+
+Per model it reports failed calls, latency p50/p90, input tokens and cost, and per question its accuracy at the threshold (0.5 when unset; a noul is positive at or above it). For nouls it adds misses and false positives there and at every threshold from 0.05 to 0.95, the margin between the lowest positive and the highest negative (below zero, no threshold separates them), the Brier score and a 10-bin reliability table. `summary.ok` is false when any call failed or any answer was wrong.
 
 ## Benchmark
 
-`bun run bench` asks every model with a key the fixed questions in [`bench/cases.ts`](bench/cases.ts) and writes `.artifacts/bench/report.html`: accuracy against the expected answers, probability on the right answer, latency p50/p90 and cost per model, every answer side by side, and a closing leaderboard that scores each model out of 100 (one point per right answer, a failed call scores zero). Keys come from the environment or `.env`: copy [`.env.example`](.env.example) to `.env` and fill in the providers you have; `--runs=5` and `--models=jev,clef` narrow or widen a run.
+`bun run bench` asks every model with a key the fixed questions in [`bench/cases.ts`](bench/cases.ts) and writes `.artifacts/bench/report.html`: accuracy against the expected answers, probability on the right answer, latency p50/p90 and cost per model, every answer side by side, and a closing leaderboard; the console also prints each model's Brier score on the nouls that scores each model out of 100 (one point per right answer, a failed call scores zero). Keys come from the environment or `.env`: copy [`.env.example`](.env.example) to `.env` and fill in the providers you have; `--runs=5` and `--models=jev,clef` narrow or widen a run.
 
-Results from 2026-10-10 (12 cases, 21 questions, 3 runs per case):
+Results from 2026-10-10 (12 cases, 21 questions, 3 runs per case; `typesafe/jev-1.13` was added after this run):
 
 | # | Model | Score | Points | p(correct) | Latency p50 / p90 | Cost / 1k calls |
 | --- | --- | --- | --- | --- | --- | --- |

package/dist/create-decision-api.d.ts

@@ -1,26 +1,49 @@
-import { type DecisionModel, type DecisionProvider, type DecisionProviderKeys, type ModelsFor } from './models.ts';
+import { type DecisionImage, type DecisionImageText, type DecisionText } from './images.ts';
+import { type DecisionImageModel, type DecisionModel, type DecisionProvider, type DecisionProviderKeys, type ModelsFor } from './models.ts';
 import { type DecisionAnswers, type DecisionQuestion } from './questions.ts';
 /**
  * Jev answers `400 max_tokens_exceeded` past roughly 32.5k input tokens (96k
- * chars passed, 128k did not). A state over this is refused before it leaves
- * the process; keep well under the wall, since tokenization varies. Clef takes
- * 64k tokens but silently truncates long state, so the same guard keeps it
- * from judging half a corpus.
+ * chars of state passed, 128k did not). Every question's instructions and
+ * criteria count too, so a request whose state and questions together are over
+ * this is refused before it leaves the process; keep well under the wall,
+ * since tokenization varies. Clef takes 64k tokens but silently truncates long
+ * state, so the same guard keeps it from judging half a corpus.
  */
-export declare const DECISION_MAX_STATE_CHARS = 90000;
+export declare const DECISION_MAX_REQUEST_CHARS = 90000;
 /** What one answered call cost; `costUsd` is priced from `DECISION_MODELS`. */
 export type DecisionUsage<Model extends DecisionModel = DecisionModel> = {
     model: Model;
+    /**
+     * The model the provider says answered, when it says: an alias such as
+     * `jev` (sent as `jev-latest`) resolves to a release here.
+     */
+    resolvedModel?: string;
     provider: DecisionProvider;
     inputTokens: number;
     outputTokens: number;
     costUsd: number;
+    /** From the first request to the answer, retries included. */
     latencyMs: number;
+    /** Requests sent: 2 when the first was retried. */
+    attempts: number;
 };
-export type DecisionErrorKind = 'state-too-large'
-/** No answer within `timeoutMs`. */
+export type DecisionErrorKind = 
+/**
+ * The state and questions together are over `maxRequestChars`, the call is
+ * over the model's question, option or level limit (`DECISION_MODELS`), or
+ * the provider refused it as too many tokens.
+ */
+'request-too-large'
+/** The call holds an image and the model reads none (`images: false`). */
+ | 'images-unsupported'
+/** An image's reference is in the text without the image: build that text with `withImages`. */
+ | 'image-detached'
+/** No answer within `timeoutMs`, retries included. */
  | 'timeout'
-/** The call's own signal (or `defaultSignal`) aborted it. */
+/**
+ * The call's own signal (or `defaultSignal`) aborted it: the caller's own
+ * doing, which an `onError` that logs failures may want to skip.
+ */
  | 'aborted'
 /** 401 or 403: the provider rejected the key. Retrying will not help. */
  | 'unauthorized'
@@ -36,6 +59,10 @@ export declare class DecisionError extends Error {
     /** The HTTP status, when the provider answered. */
     readonly status?: number | undefined;
     readonly provider: DecisionProvider;
+    /** From the start of the call to this failure. Set by the client. */
+    latencyMs: number;
+    /** Requests sent before this failure: 0 when it failed before sending. */
+    attempts: number;
     constructor(kind: DecisionErrorKind, model: DecisionModel, message: string, 
     /** The HTTP status, when the provider answered. */
     status?: number | undefined);
@@ -51,12 +78,18 @@ export type DecisionFetch = (request: {
     /** The same signal `init` carries: the call's own, plus its timeout. */
     signal: AbortSignal;
 }) => Promise<Response>;
-type DecisionCall<Q extends Record<string, DecisionQuestion>> = {
-    /** A string, or named fields - name them when the state has several parts. */
-    state: unknown;
+type DecisionCall<Q extends Record<string, DecisionQuestion>, State> = {
+    /**
+     * A string, or named fields - name them when the state has several parts.
+     * Images go in as values, on models that read them.
+     */
+    state: State;
     questions: Q;
     signal?: AbortSignal;
+    /** The whole call, retries and pauses included. */
     timeoutMs?: number;
+    /** One request; see `attemptTimeoutMs` on `createDecisionApi`. */
+    attemptTimeoutMs?: number;
 };
 type DecisionApiOptions<Keys extends DecisionProviderKeys, Default, Context> = {
     keys: Keys;
@@ -72,15 +105,34 @@ type DecisionApiOptions<Keys extends DecisionProviderKeys, Default, Context> = {
     /** The signal of a call that passes none. */
     defaultSignal?: () => AbortSignal | undefined;
     fetch?: DecisionFetch;
+    /** The whole call, retries and pauses included. Defaults to 4 s. */
     timeoutMs?: number;
-    maxStateChars?: number;
+    /**
+     * Abandon a request that has not answered by then and send one more, while
+     * `timeoutMs` leaves time. Off by default; the abandoned request may still
+     * be billed.
+     */
+    attemptTimeoutMs?: number;
+    /** State plus questions, in characters. Defaults to `DECISION_MAX_REQUEST_CHARS`. */
+    maxRequestChars?: number;
+};
+/** What `decide.result()` answers: the answers and their usage, or why there are none. */
+export type DecisionResult<Q extends Record<string, DecisionQuestion>, Model extends DecisionModel = DecisionModel> = {
+    ok: true;
+    answers: DecisionAnswers<Q>;
+    /** `null` only for a call with no questions, which sends nothing. */
+    usage: DecisionUsage<Model> | null;
+} | {
+    ok: false;
+    error: DecisionError;
 };
 /**
  * Ask one or more independent judgments about the same state.
  *
  * **Send every independent question in ONE call**: questions are evaluated
- * together, so extra ones are close to free, and latency tracks the size of
- * `state`, not the number of questions.
+ * together, so extra ones add next to nothing to latency, which tracks the
+ * size of `state`. They are not free: every question's instructions and
+ * criteria are billed as input tokens.
  *
  * **Answers `null` rather than throwing** - on a timeout, an abort, a
  * transport error, a rejected request or an answer that does not match its
@@ -88,7 +140,25 @@ type DecisionApiOptions<Keys extends DecisionProviderKeys, Default, Context> = {
  * tagging job treats `null` as "no tags this time", a policy guard as "refuse".
  * It throws only when there is no model at all - a setup bug TypeScript
  * already rejects, which a silent `null` would hide.
+ *
+ * `decide.result()` takes the same arguments and answers the usage with the
+ * answers, or the error instead of `null`.
+ */
+export type DecisionApi<Model extends DecisionModel, Default, Context> = {
+    <Q extends Record<string, DecisionQuestion>, State = unknown>(input: DecisionCall<Q, State> & Context, ...model: DecisionModelArgument<Model, Default, Q, State>): Promise<DecisionAnswers<Q> | null>;
+    result<Q extends Record<string, DecisionQuestion>, State = unknown>(input: DecisionCall<Q, State> & Context, ...model: DecisionModelArgument<Model, Default, Q, State>): Promise<DecisionResult<Q, Model>>;
+};
+type DecisionModelArgument<Model extends DecisionModel, Default, Q, State> = ModelArgument<HasImage<State> extends true ? Extract<Model, DecisionImageModel> : HasImage<Q> extends true ? Extract<Model, DecisionImageModel> : Model, Default>;
+type ModelArgument<Model, Default> = [Default] extends [Model] ? [model?: Model] : [model: Model];
+/**
+ * Whether a call's state or questions hold an image, as far as their types
+ * tell: a value typed as any text (`DecisionText`, `unknown`, `any`) does not
+ * say, and the call checks it instead. Stops at a few levels deep, so a
+ * recursive JSON type cannot recurse forever.
  */
-export type DecisionApi<Model extends DecisionModel, Default, Context> = <Q extends Record<string, DecisionQuestion>>(input: DecisionCall<Q> & Context, ...model: [Default] extends [Model] ? [model?: Model] : [model: Model]) => Promise<DecisionAnswers<Q> | null>;
+type HasImage<T, Depth extends unknown[] = []> = 0 extends 1 & T ? false : [DecisionText] extends [T] ? false : Depth['length'] extends 6 ? false : true extends ImageIn<T, [...Depth, unknown]> ? true : false;
+type ImageIn<T, Depth extends unknown[]> = T extends DecisionImage | DecisionImageText ? true : T extends readonly (infer Item)[] ? HasImage<Item, Depth> : T extends object ? {
+    [K in keyof T]-?: HasImage<T[K], Depth>;
+}[keyof T] : false;
 export declare function createDecisionApi<const Keys extends DecisionProviderKeys, Default extends ModelsFor<Keys> | undefined = undefined, Context extends object = Record<never, never>>(options: DecisionApiOptions<Keys, Default, Context>): DecisionApi<ModelsFor<Keys>, Default, Context>;
 export {};

package/dist/create-decision-api.js

@@ -1,20 +1,22 @@
-import { buildDecisionRequest, DECISION_MODELS, readDecisionResponse } from "./models.js";
+import { collectImages, detachedReference } from "./images.js";
+import { buildDecisionRequest, DECISION_MODELS, overModelLimit, readDecisionResponse } from "./models.js";
 import { matchesQuestion } from "./questions.js";
 /**
  * Jev answers `400 max_tokens_exceeded` past roughly 32.5k input tokens (96k
- * chars passed, 128k did not). A state over this is refused before it leaves
- * the process; keep well under the wall, since tokenization varies. Clef takes
- * 64k tokens but silently truncates long state, so the same guard keeps it
- * from judging half a corpus.
+ * chars of state passed, 128k did not). Every question's instructions and
+ * criteria count too, so a request whose state and questions together are over
+ * this is refused before it leaves the process; keep well under the wall,
+ * since tokenization varies. Clef takes 64k tokens but silently truncates long
+ * state, so the same guard keeps it from judging half a corpus.
  */
-export const DECISION_MAX_STATE_CHARS = 90_000;
+export const DECISION_MAX_REQUEST_CHARS = 90_000;
 /**
  * A generous ceiling rather than a target (Jev's p90 is ~280 ms for ten
  * questions): past it the caller is better served by its own fallback.
  */
 const DEFAULT_TIMEOUT_MS = 4_000;
 /** Retried once: the providers' own guidance for these is to back off and retry. */
-const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 529]);
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504, 529]);
 const RETRY_DELAY_MS = 250;
 /**
  * A provider asking for a longer pause (`Retry-After`) will not be ready within
@@ -26,6 +28,10 @@ export class DecisionError extends Error {
     model;
     status;
     provider;
+    /** From the start of the call to this failure. Set by the client. */
+    latencyMs = 0;
+    /** Requests sent before this failure: 0 when it failed before sending. */
+    attempts = 0;
     constructor(kind, model, message, 
     /** The HTTP status, when the provider answered. */
     status) {
@@ -37,7 +43,6 @@ export class DecisionError extends Error {
         this.provider = DECISION_MODELS[model].provider;
     }
 }
-/** The kind a refused response maps to; anything unlisted is `request-failed`. */
 const KIND_BY_STATUS = {
     401: 'unauthorized',
     402: 'out-of-credits',
@@ -46,35 +51,51 @@ const KIND_BY_STATUS = {
 };
 export function createDecisionApi(options) {
     const send = options.fetch ?? ((request) => fetch(request.url, request.init));
-    const maxStateChars = options.maxStateChars ?? DECISION_MAX_STATE_CHARS;
-    return async (input, ...[requestedModel]) => {
-        const { state, questions, signal, timeoutMs, ...rest } = input;
+    const maxRequestChars = options.maxRequestChars ?? DECISION_MAX_REQUEST_CHARS;
+    const result = async (input, requestedModel) => {
+        const calledAt = Date.now();
+        const { state, questions, signal, timeoutMs, attemptTimeoutMs, ...rest } = input;
         const context = rest;
         const model = requestedModel ?? options.defaultModel;
         if (!model)
             throw new Error('No model given and no defaultModel set');
         const report = (error) => {
+            error.latencyMs = Date.now() - calledAt;
             options.onError?.(error, context);
-            return null;
+            return { ok: false, error };
         };
         const fail = (kind, message) => report(new DecisionError(kind, model, message));
         if (Object.keys(questions).length === 0) {
-            return {};
+            return { ok: true, answers: {}, usage: null };
         }
+        // An image counts as its reference here: its tokens are the provider's to count.
         const stateText = typeof state === 'string' ? state : JSON.stringify(state);
-        const stateChars = stateText.length;
-        if (stateChars > maxStateChars) {
-            return fail('state-too-large', `State is ${stateChars} chars, over ${maxStateChars}`);
+        const questionsText = JSON.stringify(questions);
+        const requestChars = stateText.length + questionsText.length;
+        if (requestChars > maxRequestChars) {
+            return fail('request-too-large', `State and questions are ${requestChars} chars, over ${maxRequestChars}`);
+        }
+        const overLimit = overModelLimit(model, questions);
+        if (overLimit)
+            return fail('request-too-large', overLimit);
+        const images = collectImages(questions, collectImages(state));
+        const detached = detachedReference(stateText + questionsText, images);
+        if (detached) {
+            return fail('image-detached', `${detached} is in the text without its image; write that text with withImages`);
+        }
+        if (images.size > 0 && !DECISION_MODELS[model].images) {
+            return fail('images-unsupported', `${model} does not read images`);
         }
         const startedAt = Date.now();
-        let text;
+        let sent;
         try {
-            text = await postWithRetry({
+            sent = await postWithRetry({
                 send,
                 model,
-                request: buildDecisionRequest(model, { state, questions }, options.keys),
+                request: buildDecisionRequest(model, { state, questions, images: [...images.values()] }, options.keys),
                 signal: signal ?? options.defaultSignal?.(),
-                timeoutMs: timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+                timeoutMs: timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                attemptTimeoutMs: attemptTimeoutMs ?? options.attemptTimeoutMs
             });
         }
         catch (error) {
@@ -82,39 +103,58 @@ export function createDecisionApi(options) {
                 return report(error);
             return fail('request-failed', messageOf(error));
         }
+        const failAfterSend = (kind, message) => {
+            const error = new DecisionError(kind, model, message);
+            error.attempts = sent.attempts;
+            return report(error);
+        };
         let json;
         try {
-            json = JSON.parse(text);
+            json = JSON.parse(sent.text);
         }
         catch (error) {
-            return fail('unreadable-response', messageOf(error));
+            return failAfterSend('unreadable-response', messageOf(error));
         }
         const parsed = readDecisionResponse(model, json);
         if (!parsed.success) {
-            return fail('unreadable-response', parsed.error.issues[0]?.message ?? 'unknown');
+            return failAfterSend('unreadable-response', parsed.error.issues[0]?.message ?? 'unknown');
         }
-        const { usage, answers } = parsed.data;
-        reportUsage({
+        const { usage: tokens, answers, model: resolvedModel } = parsed.data;
+        const usage = {
             model,
+            ...(resolvedModel !== undefined && { resolvedModel }),
             provider: DECISION_MODELS[model].provider,
-            inputTokens: usage.input_tokens,
-            outputTokens: usage.output_tokens,
-            costUsd: (usage.input_tokens * DECISION_MODELS[model].inputUsdPerMTok) /
+            inputTokens: tokens.input_tokens,
+            outputTokens: tokens.output_tokens,
+            costUsd: (tokens.input_tokens * DECISION_MODELS[model].inputUsdPerMTok) /
                 1_000_000,
-            latencyMs: Date.now() - startedAt
-        }, context);
+            latencyMs: Date.now() - startedAt,
+            attempts: sent.attempts
+        };
+        reportUsage(usage, context);
         for (const [key, question] of Object.entries(questions)) {
             if (!matchesQuestion(question, answers[key])) {
-                return fail('answer-mismatch', `Answer to "${key}" does not fit it`);
+                return failAfterSend('answer-mismatch', `Answer to "${key}" does not fit it`);
             }
         }
         // Every requested key, kind and option set was validated above.
-        return answers;
+        return {
+            ok: true,
+            answers: answers,
+            usage
+        };
+    };
+    const decide = async (input, model) => {
+        const outcome = await result(input, model);
+        return outcome.ok ? outcome.answers : null;
     };
+    // The call signatures above are checked per call; one implementation serves them all.
+    return Object.assign(decide, { result });
     /**
-     * Only a call that reached the provider is reported - a state over the
+     * Only a call that reached the provider is reported - a request over the
      * wall, a timeout or an unreadable body reports nothing, so a 0 ms row can
-     * never flatter a latency percentile. A failing hook never fails the call.
+     * never flatter a latency percentile (`onError` carries `latencyMs` for
+     * those). A failing hook never fails the call.
      */
     function reportUsage(usage, context) {
         const { registerUsage } = options;
@@ -131,16 +171,34 @@ export function createDecisionApi(options) {
         });
     }
 }
-/** The body of the first OK response, read under the same timeout as the request. */
+/**
+ * The body of the first OK response and how many requests it took. One
+ * deadline (`timeoutMs`) bounds every attempt, the pause between them and the
+ * body read. A retryable status, a transport error or an abandoned attempt
+ * (`attemptTimeoutMs`) is retried once, when the deadline leaves time for it.
+ */
 async function postWithRetry(input) {
     const provider = DECISION_MODELS[input.model].provider;
-    const failure = (kind, message) => new DecisionError(kind, input.model, message);
+    const endsAt = Date.now() + input.timeoutMs;
+    let attempts = 0;
+    const failure = (kind, message, status) => {
+        const error = new DecisionError(kind, input.model, message, status);
+        error.attempts = attempts;
+        return error;
+    };
+    const timedOut = () => failure('timeout', `No answer within ${input.timeoutMs} ms`);
     for (let attempt = 0;; attempt++) {
         if (input.signal?.aborted)
             throw failure('aborted', 'Aborted by the caller');
-        // A fresh timeout per attempt, so a retry gets its own budget.
-        const timeout = AbortSignal.timeout(input.timeoutMs);
+        const remainingMs = endsAt - Date.now();
+        if (remainingMs <= 0)
+            throw timedOut();
+        const canRetry = attempt === 0;
+        const attemptMs = Math.min(input.attemptTimeoutMs ?? remainingMs, remainingMs);
+        const timeout = AbortSignal.timeout(attemptMs);
         const { signal, release } = linkSignals(timeout, input.signal);
+        attempts += 1;
+        let delayMs = RETRY_DELAY_MS;
         try {
             const response = await input.send({
                 url: input.request.url,
@@ -153,17 +211,17 @@ async function postWithRetry(input) {
                 }
             }, { model: input.model, provider, attempt, signal });
             if (response.ok)
-                return await response.text();
-            const delayMs = retryDelayMs(response);
-            if (attempt > 0 ||
+                return { text: await response.text(), attempts };
+            delayMs = retryDelayMs(response);
+            if (!canRetry ||
                 !RETRYABLE_STATUSES.has(response.status) ||
-                delayMs > MAX_RETRY_DELAY_MS) {
+                delayMs > MAX_RETRY_DELAY_MS ||
+                delayMs >= endsAt - Date.now()) {
                 const body = (await response.text()).slice(0, 200);
-                throw new DecisionError(KIND_BY_STATUS[response.status] ?? 'request-failed', input.model, `${input.model} ${response.status}: ${body}`, response.status);
+                throw failure(kindOf(response.status, body), `${input.model} ${response.status}: ${body}`, response.status);
             }
             // An unread body holds its connection until garbage collection.
             await response.body?.cancel().catch(() => { });
-            await new Promise((resolve) => setTimeout(resolve, delayMs));
         }
         catch (error) {
             if (error instanceof DecisionError)
@@ -171,15 +229,47 @@ async function postWithRetry(input) {
             if (input.signal?.aborted)
                 throw failure('aborted', messageOf(error));
             if (timeout.aborted) {
-                throw failure('timeout', `No answer within ${input.timeoutMs} ms`);
+                // The deadline itself, or the last attempt: nothing left to try.
+                if (attemptMs >= remainingMs || !canRetry)
+                    throw timedOut();
+                continue;
+            }
+            if (!canRetry || RETRY_DELAY_MS >= endsAt - Date.now()) {
+                throw failure('request-failed', messageOf(error));
             }
-            throw error;
         }
         finally {
             release();
         }
+        await pause(delayMs, input.signal).catch(() => {
+            throw failure('aborted', 'Aborted by the caller');
+        });
     }
 }
+/** The kind a refused response maps to; anything unlisted is `request-failed`. */
+function kindOf(status, body) {
+    if (status === 413 || (status === 400 && /max_tokens_exceeded/.test(body))) {
+        return 'request-too-large';
+    }
+    return KIND_BY_STATUS[status] ?? 'request-failed';
+}
+/** Waits `ms`, or rejects as soon as `signal` aborts. */
+function pause(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            if (signal?.aborted)
+                reject(signal.reason);
+            else
+                resolve();
+        }
+    });
+}
 /** The pause a response asks for, in seconds or as a date; our own without one. */
 function retryDelayMs(response) {
     const header = response.headers.get('retry-after')?.trim();