@parcha/agentrun-jev 0.1.0-beta.21 → 0.1.0-beta.26

package/README.md

@@ -77,7 +77,7 @@ const result = await runJudge({
 console.log(result.answers.team);
 ```
 
-Without a key, `createJevRunner()` throws `JevError` (code `configuration`: "Could not configure Jev. Supply apiKey or set TYPESAFE_API_KEY, and check transport options.") on that line, before any request is made. The same holds for `provider: "openrouter"` without `OPENROUTER_API_KEY`.
+Without a key, or with an `apiKey` that is blank, `createJevRunner()` throws `JevError` (code `configuration`: "Could not configure Jev. Supply apiKey or set TYPESAFE_API_KEY, and check transport options.") on that line, before any request is made. The same holds for `provider: "openrouter"` without `OPENROUTER_API_KEY`.
 
 `judge`, `pick`, `sift`, `route`, semantic predicates, and judgment verification use the same `runJudge` adapter. Choice, Noul, and Score answers retain their raw probabilities. The core validates answer IDs, probability keys and normalization, score rubrics, and value ranges before consuming a result. A typed answer records the model's decision. It does not prove that a real-world claim is true.
 
@@ -115,7 +115,7 @@ Cost: when the response reports `usage.cost` (USD) it is `cost_usd`; otherwise a
 
 The official `@typesafe-ai/sdk` resolves `TYPESAFE_API_KEY` and `TYPESAFE_BASE_URL`. Explicit `apiKey` and `baseURL` options take precedence. An API root ends before `/v1/systemone`. Set `fetch` for a custom transport, or supply a `client` with a `systemOne(request, options)` method. A custom client must honor the request signal and disable its own retries; it owns its credentials and cannot be combined with transport options.
 
-The adapter retries transient HTTP 408, 429, 5xx responses and connection failures with bounded exponential delays. On a 429 or 503 with a `Retry-After` (seconds or an HTTP date), it waits the larger of that and its own delay, and gives up at once, with attempts left, when that wait would not end before the timeout. When the attempts end on a 429 after an earlier 408, 5xx or lost connection, the error reports the first of those failures (its HTTP `status`, or code `connection`), since that attempt may have been billed; an `http` error with status 429 means every attempt was refused. SDK retries are disabled. Validation failures and other HTTP errors do not retry. The deadline and either the runner or per-call signal interrupt both requests and backoff. Cancellation bounds when the adapter returns; an uncooperative custom client can still continue its own work.
+The adapter retries transient HTTP 408, 429, 5xx responses and connection failures with bounded exponential delays. On a 429 or 503 with a `Retry-After` (seconds or an HTTP date), it waits the larger of that and its own delay, and gives up at once, with attempts left, when that wait would not end before the timeout. When the attempts end on a 429 after an earlier 408, 5xx or lost connection, the error reports the first of those failures (its HTTP `status`, or code `connection`), since that attempt may have been billed; an `http` error with status 429 means every attempt was refused. SDK retries are disabled. Validation failures and other HTTP errors do not retry. The deadline and either the runner or per-call signal interrupt both requests and backoff. A call the deadline ends is `timeout`, whether the runner's timer or the SDK's per-attempt timer fired first, and is not retried. Cancellation bounds when the adapter returns; an uncooperative custom client can still continue its own work.
 
 Request state has no local byte cap by default. Set `maxStateBytes` to a positive safe integer to reject serialized UTF-8 JSON state exceeding that host-owned limit before transport; omission or `null` disables this guard. This is a byte guard, not a token estimate. [Provider model context limits](https://docs.typesafe.ai/models.md) still apply. The adapter never truncates or splits state or questions.
 

package/dist/index.js

@@ -1,14 +1,14 @@
 import { createHash } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
-import { APIConnectionError, APIError, Image, TypeSafeClient } from "@typesafe-ai/sdk";
+import { APIConnectionError, APIError, APITimeoutError, Image, TypeSafeClient } from "@typesafe-ai/sdk";
 import { validateAnswers, SystemOneError, isSystemOneResponseReason } from "@parcha/agentrun-dsl";
 const keyVariable = { typesafe: "TYPESAFE_API_KEY", openrouter: "OPENROUTER_API_KEY" };
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api";
 const OPENROUTER_DEFAULT_MODEL = "~typesafe/jev-latest";
 /** The provider an environment's keys select: OpenRouter only when `OPENROUTER_API_KEY` is set and `TYPESAFE_API_KEY` is not. The runner itself never reads this. */
 export function jevProviderFromEnv(env = process.env) {
-    const set = (name) => typeof env[name] === "string" && env[name].trim().length > 0;
-    return set(keyVariable.openrouter) && !set(keyVariable.typesafe) ? "openrouter" : "typesafe";
+    const isSet = (name) => typeof env[name] === "string" && env[name].trim().length > 0;
+    return isSet(keyVariable.openrouter) && !isSet(keyVariable.typesafe) ? "openrouter" : "typesafe";
 }
 const IMAGE_HEADER = "TypeSafe-Danger-Zone-Images";
 const MAX_IMAGE_BYTES = 16 * 1024 * 1024;
@@ -30,7 +30,7 @@ function* stringValues(value) {
     else if (Array.isArray(value))
         for (const each of value)
             yield* stringValues(each);
-    else if (record(value))
+    else if (isRecord(value))
         for (const each of Object.values(value))
             yield* stringValues(each);
 }
@@ -58,13 +58,13 @@ export class JevError extends Error {
             this.responseDiagnostic = { reason: responseDiagnostic.reason };
     }
 }
-const configuration = (condition, message) => {
+const requireConfig = (condition, message) => {
     if (!condition)
         throw new JevError("configuration", message);
 };
-const milliseconds = (n, allowZero = false) => Number.isSafeInteger(n) && n >= (allowZero ? 0 : 1) && n <= MAX_TIMER_MS;
-const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-const tokens = (n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+const isTimerMs = (n, allowZero = false) => Number.isSafeInteger(n) && n >= (allowZero ? 0 : 1) && n <= MAX_TIMER_MS;
+const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isTokenCount = (n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
 function abortable(promise, signal, error) {
     return new Promise((resolve, reject) => {
         const abort = () => { signal.removeEventListener("abort", abort); reject(error()); };
@@ -95,32 +95,148 @@ function retryAfterMs(headers) {
     const date = Date.parse(value);
     return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
 }
+/** What one call sends: the request, the body its hash is taken over, and the image header when it carries an image or a Box. All of it is
+ *  checked before anything is sent: a request that cannot be valid throws the `invalid_request` JevError that names why. */
+function prepareRequest(params, model, maxStateBytes, provider) {
+    let body;
+    let request;
+    const invalid = (reason, message, stateBytes) => new JevError("invalid_request", message, 0, undefined, { reason,
+        ...(typeof params.label === "string" ? { label: params.label.slice(0, 200) } : {}),
+        ...(stateBytes === undefined || maxStateBytes === null ? {} : { stateBytes, maxStateBytes }) });
+    const state = params.state;
+    let serializedState;
+    try {
+        // The SDK refuses a request with no state, so a null or missing state is refused here, before anything is sent.
+        if (typeof state !== "string" && (typeof state !== "object" || state === null))
+            throw new Error();
+        serializedState = JSON.stringify(state);
+        if (typeof serializedState !== "string")
+            throw new Error();
+    }
+    catch {
+        throw invalid("invalid_state", "Jev state must be JSON-serializable text, an object or an array.");
+    }
+    const stateBytes = Buffer.byteLength(serializedState, "utf8");
+    if (maxStateBytes !== null && stateBytes > maxStateBytes)
+        throw invalid("state_too_large", `Jev assembled state is ${stateBytes} UTF-8 bytes; configured host limit is ${maxStateBytes} bytes. No request was sent.`, stateBytes);
+    const callModel = params.model ?? model;
+    if (typeof callModel !== "string" || callModel.trim().length === 0)
+        throw invalid("unsupported_model", "model must be a nonempty string; no request was sent.");
+    try {
+        body = JSON.stringify({ state: JSON.parse(serializedState), model: callModel, questions: params.questions });
+        request = JSON.parse(body);
+        if (!isRecord(request.questions) || Object.keys(request.questions).length === 0)
+            throw new Error();
+    }
+    catch {
+        throw invalid("invalid_questions", "Jev requires a nonempty JSON question map; no request was sent.");
+    }
+    // Images and Box questions: validated whole before any send; the header goes with exactly these requests.
+    const hasBox = Object.values(request.questions).some(question => isRecord(question) && question.type === "box");
+    const given = params.assets ?? {};
+    if (!isRecord(given))
+        throw invalid("invalid_assets", "assets must map each reference to an image; no request was sent.");
+    const references = Object.keys(given);
+    const carriesImage = references.length > 0;
+    if ((carriesImage || hasBox) && provider !== "typesafe")
+        throw invalid("unsupported_provider", "Images and Box questions are sent to TypeSafe's own API only; the OpenRouter path is not verified for them. No request was sent.");
+    if (hasBox && !answersBox(callModel))
+        throw invalid("unsupported_model", `A Box question needs a model that answers it, by name: ${BOX_MODEL} or later, or jev-preview; jev-latest is refused whatever version it points at. No request was sent.`);
+    if (hasBox && !carriesImage)
+        throw invalid("invalid_assets", "A Box question locates something in an image, and the request carries none. No request was sent.");
+    let assets;
+    let assetDigests;
+    if (carriesImage) {
+        // A reference is replaced where it sits inside a string value of the state, an instruction or a criterion; keys (question ids, option names) are never replaced.
+        const texts = [...stringValues(request.state), ...Object.values(request.questions).flatMap(question => isRecord(question) ? [...stringValues(question.instructions), ...stringValues(question.criteria)] : [])];
+        assets = Object.create(null);
+        assetDigests = Object.create(null);
+        for (const reference of references) {
+            const image = given[reference];
+            const sound = reference.length > 0 && Buffer.byteLength(reference, "utf8") <= MAX_REFERENCE_BYTES && !/["\\\u0000-\u001f]/.test(reference)
+                && isRecord(image) && image.bytes instanceof Uint8Array && (image.mime === "image/png" || image.mime === "image/jpeg")
+                && image.bytes.byteLength > 0 && image.bytes.byteLength <= MAX_IMAGE_BYTES && startsWith(image.bytes, imageMagic[image.mime]);
+            if (!sound)
+                throw invalid("invalid_assets", `Each image is a PNG or JPEG file of at most ${MAX_IMAGE_BYTES / 1024 / 1024} MiB, with bytes that are that type and a plain reference. No request was sent.`);
+            if (!texts.some(text => text.includes(reference)))
+                throw invalid("invalid_assets", "Every image reference must appear in the state or a question. No request was sent.");
+            assets[reference] = new Image(image.bytes);
+            assetDigests[reference] = { sha256: createHash("sha256").update(image.bytes).digest("hex"), mime: image.mime, bytes: image.bytes.byteLength };
+        }
+        // The hash names the images by their own digests, so it identifies the request that was sent without holding the bytes.
+        body = JSON.stringify({ ...request, assets: assetDigests });
+        request = { ...request, assets };
+    }
+    const headers = carriesImage || hasBox ? { [IMAGE_HEADER]: "true" } : undefined;
+    return { request, body, ...(headers ? { headers } : {}) };
+}
+/** The runner's result from what the client returned at `attempt`, or the `invalid_response` JevError for the first rule it breaks.
+ *  `questions` are the questions as they were sent. */
+function readResponse(result, questions, body, pricing, attempt) {
+    const invalid = (reason, message) => new JevError("invalid_response", message, attempt, undefined, undefined, { reason });
+    if (!isRecord(result))
+        throw invalid("response_shape", "Jev returned an invalid response.");
+    const answers = result.answers;
+    // Checked against the questions as they were sent: a value JSON cannot carry (an undefined criterion) was never asked.
+    try {
+        validateAnswers(questions, answers);
+    }
+    catch (error) {
+        throw invalid(error instanceof SystemOneError && isSystemOneResponseReason(error.responseReason) ? error.responseReason : "answer_validation", "Jev returned invalid answers or probability distributions.");
+    }
+    const usage = result.usage;
+    // Usage carries token counts, a provider-reported cost (USD), or both; a half pair of counts or a bad cost is invalid.
+    const counted = isRecord(usage) && isTokenCount(usage.input_tokens) && isTokenCount(usage.output_tokens);
+    const reported = isRecord(usage) && usage.cost !== undefined && usage.cost !== null;
+    const reportedCost = reported && typeof usage.cost === "number" && Number.isFinite(usage.cost) && usage.cost >= 0 ? usage.cost : undefined;
+    const noCounts = isRecord(usage) && usage.input_tokens === undefined && usage.output_tokens === undefined;
+    // Accepted: no usage; both counts; or a valid cost with both counts or with neither.
+    const usageValid = usage == null || (isRecord(usage) && (reported ? reportedCost !== undefined && (counted || noCounts) : counted));
+    if (!usageValid)
+        throw invalid("token_usage", "Jev returned invalid token usage.");
+    if (result.model != null && (typeof result.model !== "string" || !result.model.trim())) {
+        throw invalid("model_identifier", "Jev returned an invalid model identifier.");
+    }
+    const metering = counted ? { input_tokens: usage.input_tokens, output_tokens: usage.output_tokens } : null;
+    // The provider's own cost wins; else the configured estimate; else unknown (null), never 0.
+    const cost = reportedCost !== undefined ? reportedCost : pricing && metering ? (metering.input_tokens * pricing.inputUsdPerMillionTokens + metering.output_tokens * pricing.outputUsdPerMillionTokens) / 1_000_000 : null;
+    if (cost !== null && !Number.isFinite(cost))
+        throw invalid("cost_range", "Jev cost estimate exceeded the numeric range.");
+    return {
+        answers, model: typeof result.model === "string" ? result.model : null,
+        usage: metering, cost_usd: cost,
+        request_sha256: createHash("sha256").update(body).digest("hex"),
+    };
+}
 export function createJevRunner(options = {}) {
     const timeoutMs = options.timeoutMs === null ? null : (options.timeoutMs ?? 30_000);
     const maxStateBytes = options.maxStateBytes ?? null;
     const maxAttempts = options.maxAttempts ?? 3;
     const retryBaseMs = options.retryBaseMs ?? 500;
     const retryMaxMs = options.retryMaxMs ?? 5_000;
-    configuration(timeoutMs === null || milliseconds(timeoutMs), `timeoutMs must be null or a positive integer of at most ${MAX_TIMER_MS}.`);
-    configuration(maxStateBytes === null || (Number.isSafeInteger(maxStateBytes) && maxStateBytes > 0), "maxStateBytes must be null or a positive safe integer.");
-    configuration(timeoutMs !== null || options.client !== undefined, "The TypeSafe SDK requires a finite timeout. For timeoutMs: null, supply a cancellation-only host client.");
-    configuration(Number.isInteger(maxAttempts) && maxAttempts >= 1 && maxAttempts <= 10, "maxAttempts must be an integer from 1 to 10.");
-    configuration(milliseconds(retryBaseMs, true) && milliseconds(retryMaxMs, true) && retryBaseMs <= retryMaxMs, "Retry delays must be nonnegative integers; retryBaseMs cannot exceed retryMaxMs.");
-    configuration(!options.client || (options.apiKey === undefined && options.baseURL === undefined && options.fetch === undefined && options.provider === undefined), "Supply either client or transport options, not both.");
+    // A JavaScript caller's `client: null` is no client, the same as an absent one.
+    const hostClient = options.client ?? undefined;
+    requireConfig(timeoutMs === null || isTimerMs(timeoutMs), `timeoutMs must be null or a positive integer of at most ${MAX_TIMER_MS}.`);
+    requireConfig(maxStateBytes === null || (Number.isSafeInteger(maxStateBytes) && maxStateBytes > 0), "maxStateBytes must be null or a positive safe integer.");
+    requireConfig(timeoutMs !== null || hostClient !== undefined, "The TypeSafe SDK requires a finite timeout. For timeoutMs: null, supply a cancellation-only host client.");
+    requireConfig(Number.isInteger(maxAttempts) && maxAttempts >= 1 && maxAttempts <= 10, "maxAttempts must be an integer from 1 to 10.");
+    requireConfig(isTimerMs(retryBaseMs, true) && isTimerMs(retryMaxMs, true) && retryBaseMs <= retryMaxMs, "Retry delays must be nonnegative integers; retryBaseMs cannot exceed retryMaxMs.");
+    requireConfig(hostClient === undefined || (options.apiKey === undefined && options.baseURL === undefined && options.fetch === undefined && options.provider === undefined), "Supply either client or transport options, not both.");
     const provider = options.provider ?? "typesafe";
-    configuration(provider === "typesafe" || provider === "openrouter", "provider must be typesafe or openrouter.");
+    requireConfig(provider === "typesafe" || provider === "openrouter", "provider must be typesafe or openrouter.");
     const pricing = options.pricing ? { ...options.pricing } : undefined;
     if (pricing)
-        configuration([pricing.inputUsdPerMillionTokens, pricing.outputUsdPerMillionTokens].every(n => Number.isFinite(n) && n >= 0), "Configured token prices must be finite nonnegative numbers.");
+        requireConfig([pricing.inputUsdPerMillionTokens, pricing.outputUsdPerMillionTokens].every(n => Number.isFinite(n) && n >= 0), "Configured token prices must be finite nonnegative numbers.");
     const model = options.model ?? (provider === "openrouter" ? OPENROUTER_DEFAULT_MODEL : "jev-latest");
-    configuration(typeof model === "string" && model.trim().length > 0, "model must be a nonempty string.");
+    requireConfig(typeof model === "string" && model.trim().length > 0, "model must be a nonempty string.");
     let client;
     try {
         const key = options.apiKey ?? (provider === "openrouter" ? process.env[keyVariable.openrouter] : undefined);
-        // The SDK falls back to TYPESAFE_API_KEY when given no key: for OpenRouter that would send one provider's key to another.
-        if (provider === "openrouter" && (typeof key !== "string" || key.trim().length === 0))
+        // A blank key is refused on either provider: the SDK would send it as an empty bearer token. Given no key, the SDK falls back to
+        // TYPESAFE_API_KEY, so for OpenRouter an absent key is refused too: that would send one provider's key to another.
+        if ((key !== undefined || provider === "openrouter") && (typeof key !== "string" || key.trim().length === 0))
             throw new Error("no key");
-        client = options.client ?? new TypeSafeClient({
+        client = hostClient ?? new TypeSafeClient({
             apiKey: key, baseURL: options.baseURL ?? (provider === "openrouter" ? OPENROUTER_BASE_URL : undefined), fetch: options.fetch,
             defaultModel: model, retry: { maxRetries: 0 }, timeout: timeoutMs ?? undefined, logLevel: "off",
             // Bodies go as they always have: uncompressed JSON, which a host's own fetch, a gateway and OpenRouter all read.
@@ -139,81 +255,12 @@ export function createJevRunner(options = {}) {
         const abortError = () => (runnerSignal?.aborted || params.signal?.aborted)
             ? new JevError("aborted", "Jev request was cancelled.", attempt)
             : new JevError("timeout", "Jev request exceeded its total deadline.", attempt);
-        const invalidResponse = (reason, message) => new JevError("invalid_response", message, attempt, undefined, undefined, { reason });
         if (signal.aborted)
             throw abortError();
         const timer = timeoutMs === null ? undefined : setTimeout(() => deadline.abort(), timeoutMs);
         const started = Date.now();
         try {
-            let body;
-            let request;
-            const invalid = (reason, message, stateBytes) => new JevError("invalid_request", message, 0, undefined, { reason,
-                ...(typeof params.label === "string" ? { label: params.label.slice(0, 200) } : {}),
-                ...(stateBytes === undefined || maxStateBytes === null ? {} : { stateBytes, maxStateBytes }) });
-            const state = params.state ?? null;
-            let serializedState;
-            try {
-                if (typeof state !== "string" && state !== null && typeof state !== "object")
-                    throw new Error();
-                serializedState = JSON.stringify(state);
-                if (typeof serializedState !== "string")
-                    throw new Error();
-            }
-            catch {
-                throw invalid("invalid_state", "Jev state must be JSON-serializable text, an object, an array or null.");
-            }
-            const stateBytes = Buffer.byteLength(serializedState, "utf8");
-            if (maxStateBytes !== null && stateBytes > maxStateBytes)
-                throw invalid("state_too_large", `Jev assembled state is ${stateBytes} UTF-8 bytes; configured host limit is ${maxStateBytes} bytes. No request was sent.`, stateBytes);
-            const callModel = params.model ?? model;
-            if (typeof callModel !== "string" || callModel.trim().length === 0)
-                throw invalid("invalid_questions", "model must be a nonempty string; no request was sent.");
-            try {
-                body = JSON.stringify({ state: JSON.parse(serializedState), model: callModel, questions: params.questions });
-                request = JSON.parse(body);
-                if (!record(request.questions) || Object.keys(request.questions).length === 0)
-                    throw new Error();
-            }
-            catch {
-                throw invalid("invalid_questions", "Jev requires a nonempty JSON question map; no request was sent.");
-            }
-            // Images and Box questions: validated whole before any send; the header goes with exactly these requests.
-            const hasBox = Object.values(request.questions).some(question => record(question) && question.type === "box");
-            const given = params.assets ?? {};
-            if (!record(given))
-                throw invalid("invalid_assets", "assets must map each reference to an image; no request was sent.");
-            const references = Object.keys(given);
-            const carriesImage = references.length > 0;
-            if ((carriesImage || hasBox) && provider !== "typesafe" && options.client === undefined)
-                throw invalid("unsupported_provider", "Images and Box questions are sent to TypeSafe's own API only; the OpenRouter path is not verified for them. No request was sent.");
-            if (hasBox && !answersBox(callModel))
-                throw invalid("unsupported_model", `A Box question needs a model that answers it, by name: ${BOX_MODEL} or later, or jev-preview; jev-latest is refused whatever version it points at. No request was sent.`);
-            if (hasBox && !carriesImage)
-                throw invalid("invalid_assets", "A Box question locates something in an image, and the request carries none. No request was sent.");
-            let assets;
-            let assetDigests;
-            if (carriesImage) {
-                // A reference is replaced where it sits inside a string value of the state, an instruction or a criterion; keys (question ids, option names) are never replaced.
-                const texts = [...stringValues(JSON.parse(serializedState)), ...Object.values(request.questions).flatMap(question => record(question) ? [...stringValues(question.instructions), ...stringValues(question.criteria)] : [])];
-                assets = Object.create(null);
-                assetDigests = Object.create(null);
-                for (const reference of references) {
-                    const image = given[reference];
-                    const sound = reference.length > 0 && Buffer.byteLength(reference, "utf8") <= MAX_REFERENCE_BYTES && !/["\\\u0000-\u001f]/.test(reference)
-                        && record(image) && image.bytes instanceof Uint8Array && (image.mime === "image/png" || image.mime === "image/jpeg")
-                        && image.bytes.byteLength > 0 && image.bytes.byteLength <= MAX_IMAGE_BYTES && startsWith(image.bytes, imageMagic[image.mime]);
-                    if (!sound)
-                        throw invalid("invalid_assets", `Each image is a PNG or JPEG file of at most ${MAX_IMAGE_BYTES / 1024 / 1024} MiB, with bytes that are that type and a plain reference. No request was sent.`);
-                    if (!texts.some(text => text.includes(reference)))
-                        throw invalid("invalid_assets", "Every image reference must appear in the state or a question. No request was sent.");
-                    assets[reference] = new Image(image.bytes);
-                    assetDigests[reference] = { sha256: createHash("sha256").update(image.bytes).digest("hex"), mime: image.mime, bytes: image.bytes.byteLength };
-                }
-                request = { ...request, assets };
-                // The hash names the images by their own digests, so it identifies the request that was sent without holding the bytes.
-                body = JSON.stringify({ ...JSON.parse(body), assets: assetDigests });
-            }
-            const headers = carriesImage || hasBox ? { [IMAGE_HEADER]: "true" } : undefined;
+            const { request, body, headers } = prepareRequest(params, model, maxStateBytes, provider);
             // The first attempt that failed in a way the server may have billed (a lost answer, a 408, a 5xx). A later 429 does not make the call free: the give-up reports this one.
             let billable;
             for (attempt = 1;; attempt++) {
@@ -226,7 +273,9 @@ export function createJevRunner(options = {}) {
                     }), signal, abortError);
                 }
                 catch (error) {
-                    if (signal.aborted)
+                    // Each attempt's timeout is the call's remaining budget, so the client's timer and the deadline end together: whichever fires first,
+                    // the deadline ended the call. A timed-out request may have been billed, and its code is what says so.
+                    if (signal.aborted || (timeoutMs !== null && error instanceof APITimeoutError))
                         throw abortError();
                     const status = error instanceof APIError ? error.status : undefined;
                     const retryable = status === 408 || status === 429 || (status !== undefined && status >= 500 && status <= 599) || error instanceof APIConnectionError;
@@ -250,7 +299,7 @@ export function createJevRunner(options = {}) {
                         throw billable.status === undefined ? new JevError("connection", "Jev transport failed.", attempt) : new JevError("http", `Jev returned HTTP ${billable.status}.`, attempt, billable.status);
                     if (status !== undefined) {
                         const safeStatus = Number.isInteger(status) && status >= 100 && status <= 599 ? status : undefined;
-                        const capacity = error instanceof APIError && record(error.body) && record(error.body.detail)
+                        const capacity = error instanceof APIError && isRecord(error.body) && isRecord(error.body.detail)
                             && error.body.detail.error_type === "max_tokens_exceeded";
                         // Only the structured reason is named; the provider's body text never reaches the message.
                         const returned = safeStatus === undefined ? "Jev returned an HTTP failure" : `Jev returned HTTP ${safeStatus}`;
@@ -262,37 +311,7 @@ export function createJevRunner(options = {}) {
                         throw new JevError("connection", "Jev transport failed.", attempt);
                     throw new JevError("invalid_request", "Jev could not process the request. Check question and transport configuration.", attempt);
                 }
-                if (!record(result))
-                    throw invalidResponse("response_shape", "Jev returned an invalid response.");
-                const answers = result.answers;
-                try {
-                    validateAnswers(params.questions, answers);
-                }
-                catch (error) {
-                    throw invalidResponse(error instanceof SystemOneError && isSystemOneResponseReason(error.responseReason) ? error.responseReason : "answer_validation", "Jev returned invalid answers or probability distributions.");
-                }
-                const usage = result.usage;
-                // Usage carries token counts, a provider-reported cost (USD), or both; a half pair of counts or a bad cost is invalid.
-                const counted = record(usage) && tokens(usage.input_tokens) && tokens(usage.output_tokens);
-                const reported = record(usage) && usage.cost !== undefined && usage.cost !== null;
-                const reportedCost = reported && typeof usage.cost === "number" && Number.isFinite(usage.cost) && usage.cost >= 0 ? usage.cost : undefined;
-                const noCounts = record(usage) && usage.input_tokens === undefined && usage.output_tokens === undefined;
-                if (usage != null && (!record(usage) || (reported ? reportedCost === undefined || !(counted || noCounts) : !counted))) {
-                    throw invalidResponse("token_usage", "Jev returned invalid token usage.");
-                }
-                if (result.model != null && (typeof result.model !== "string" || !result.model.trim())) {
-                    throw invalidResponse("model_identifier", "Jev returned an invalid model identifier.");
-                }
-                const metering = counted ? { input_tokens: usage.input_tokens, output_tokens: usage.output_tokens } : null;
-                // The provider's own cost wins; else the configured estimate; else unknown (null), never 0.
-                const cost = reportedCost !== undefined ? reportedCost : pricing && metering ? (metering.input_tokens * pricing.inputUsdPerMillionTokens + metering.output_tokens * pricing.outputUsdPerMillionTokens) / 1_000_000 : null;
-                if (cost !== null && !Number.isFinite(cost))
-                    throw invalidResponse("cost_range", "Jev cost estimate exceeded the numeric range.");
-                return {
-                    answers, model: typeof result.model === "string" ? result.model : null,
-                    usage: metering, cost_usd: cost,
-                    request_sha256: createHash("sha256").update(body).digest("hex"),
-                };
+                return readResponse(result, request.questions, body, pricing, attempt);
             }
         }
         finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/agentrun-jev",
-  "version": "0.1.0-beta.21",
+  "version": "0.1.0-beta.26",
   "description": "Optional Jev system one decisions for AgentRun workflows",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,7 +27,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@parcha/agentrun-dsl": "0.1.0-beta.21",
+    "@parcha/agentrun-dsl": "0.1.0-beta.26",
     "@typesafe-ai/sdk": "0.7.0"
   },
   "repository": {