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

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,6 +1,6 @@
 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";
@@ -101,12 +101,14 @@ export function createJevRunner(options = {}) {
     const maxAttempts = options.maxAttempts ?? 3;
     const retryBaseMs = options.retryBaseMs ?? 500;
     const retryMaxMs = options.retryMaxMs ?? 5_000;
+    // A JavaScript caller's `client: null` is no client, the same as an absent one.
+    const hostClient = options.client ?? undefined;
     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(timeoutMs !== null || hostClient !== 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.");
+    configuration(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.");
     const pricing = options.pricing ? { ...options.pricing } : undefined;
@@ -117,10 +119,11 @@ export function createJevRunner(options = {}) {
     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.
@@ -150,24 +153,25 @@ export function createJevRunner(options = {}) {
             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;
+            const state = params.state;
             let serializedState;
             try {
-                if (typeof state !== "string" && state !== null && typeof state !== "object")
+                // 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, an array or null.");
+                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("invalid_questions", "model must be a nonempty string; no request was sent.");
+                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);
@@ -184,7 +188,7 @@ export function createJevRunner(options = {}) {
                 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)
+            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.`);
@@ -226,7 +230,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;
@@ -265,8 +271,9 @@ export function createJevRunner(options = {}) {
                 if (!record(result))
                     throw invalidResponse("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(params.questions, answers);
+                    validateAnswers(request.questions, answers);
                 }
                 catch (error) {
                     throw invalidResponse(error instanceof SystemOneError && isSystemOneResponseReason(error.responseReason) ? error.responseReason : "answer_validation", "Jev returned invalid answers or probability distributions.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/agentrun-jev",
-  "version": "0.1.0-beta.21",
+  "version": "0.1.0-beta.23",
   "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.23",
     "@typesafe-ai/sdk": "0.7.0"
   },
   "repository": {