@parcha/agentrun-jev 0.1.0-beta.17 → 0.1.0-beta.19

package/README.md

@@ -2,7 +2,7 @@
 
 Optional [TypeSafe Jev](https://docs.typesafe.ai/) support for AgentRun DSL. Jev answers focused questions with typed values and probability distributions. The workflow decides how to use them.
 
-Beta: `0.1.0-beta.4`. Requires Node.js 22.19 or later.
+Beta, on npm under the `beta` dist-tag (`npm view @parcha/agentrun-jev dist-tags`). Requires Node.js 22.19 or later.
 
 ```sh
 npm install @parcha/agentrun-dsl@beta @parcha/agentrun-jev@beta
@@ -102,7 +102,7 @@ const { answers, usage, cost_usd } = await judge({
 ```
 
 - `assets` maps each reference, a string that appears literally in `state` or in a question's `instructions` or `criteria`, to the image. The runner builds the SDK's image from the bytes and sends it as a multipart file part. Each reference must appear inside a string value of the state, an instruction or a criterion (a question id or an option name does not count), or the request is refused.
-- A Box question needs `model: 'jev-1.14.0'` (or `'jev-preview'`); `jev-latest` is 1.13 and does not answer it. A Box on any other model, or a Box with no image, is refused with `JevError` code `invalid_request` before any request. `model` can also be named per call.
+- A Box question needs a model named for it: `model: 'jev-1.14.0'`, a later version, or `'jev-preview'`. The runner checks the name, so it refuses a Box on `jev-latest` whatever version that alias points at. A Box on any other model, or a Box with no image, is refused with `JevError` code `invalid_request` before any request. `model` can also be named per call.
 - Before any request, the runner also refuses what Jev would reject: a file that is not PNG or JPEG (the bytes are checked against `mime`), an empty file, a file over 16 MiB, a reference nothing uses. It does not check pixel dimensions (each side 280 to 1568, total 78,400 to 2,458,624 pixels) or the 32 MiB request limit; Jev rejects those with a 400 or 413, which surfaces as a typed `http` error.
 - Images are billed as input tokens at the text price, and `usage.input_tokens` counts them. `cost_usd` is as for text: the provider's reported cost, else your `pricing` applied to the counted tokens, else `null`. `request_sha256` names each image by its own SHA-256, so the same request hashes the same and a different image does not.
 - A Box answer is always a box (there is no "not found"): ask a noul question in the same request to check presence. Edges and confidence are checked to lie in [0, 1] and the box to run forward (`top <= bottom`, `left <= right`); a confidence the provider omits is `null`.

package/dist/index.d.ts

@@ -19,7 +19,7 @@ type RunJudge = NonNullable<WorkflowDeps["runJudge"]>;
  *  every reference must appear, and a Box question needs at least one image. */
 export type JevJudgeParams = Parameters<RunJudge>[0] & {
     assets?: Record<string, JevImage>;
-    /** Names the model for this call, over the runner's `model`. A Box question needs `jev-1.14.0` or `jev-preview`; the default `jev-latest` is 1.13. */
+    /** Names the model for this call, over the runner's `model`. A Box question needs `jev-1.14.0` (or later) or `jev-preview` by name; the default `jev-latest` is refused for it whatever version that alias points at. */
     model?: string;
 };
 /** The typed answers (choice, noul, score with their probabilities; box with its edges and confidence), the model that answered, its token usage, and

package/dist/index.js

@@ -12,7 +12,7 @@ export function jevProviderFromEnv(env = process.env) {
 const IMAGE_HEADER = "TypeSafe-Danger-Zone-Images";
 const MAX_IMAGE_BYTES = 16 * 1024 * 1024;
 const BOX_MODEL = "jev-1.14.0";
-/** Models that answer a Box question: Jev 1.14 and later by name, and the preview alias. `jev-latest` is 1.13 and does not. */
+/** Models that answer a Box question: Jev 1.14 and later by name, and the preview alias. The check is by name, so `jev-latest` is refused whatever version it points at. */
 function answersBox(model) {
     if (model === "jev-preview")
         return true;
@@ -82,6 +82,16 @@ function wait(ms, signal, error) {
             abort();
     });
 }
+/** A server's Retry-After in milliseconds from now, given as delta-seconds or an HTTP date; undefined when absent or unparseable. */
+function retryAfterMs(headers) {
+    const value = headers instanceof Headers ? headers.get("retry-after")?.trim() : undefined;
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
 export function createJevRunner(options = {}) {
     const timeoutMs = options.timeoutMs === null ? null : (options.timeoutMs ?? 30_000);
     const maxStateBytes = options.maxStateBytes ?? null;
@@ -173,7 +183,7 @@ export function createJevRunner(options = {}) {
             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: ${BOX_MODEL} (or jev-preview); jev-latest is 1.13. No request was sent.`);
+                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;
@@ -200,6 +210,8 @@ export function createJevRunner(options = {}) {
                 body = JSON.stringify({ ...JSON.parse(body), assets: assetDigests });
             }
             const headers = carriesImage || hasBox ? { [IMAGE_HEADER]: "true" } : undefined;
+            // 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++) {
                 if (signal.aborted)
                     throw abortError();
@@ -214,10 +226,23 @@ export function createJevRunner(options = {}) {
                         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;
+                    if (retryable && status !== 429 && billable === undefined)
+                        billable = status === undefined ? {} : { status };
                     if (retryable && attempt < maxAttempts) {
-                        await wait(Math.min(retryMaxMs, retryBaseMs * 2 ** (attempt - 1)), signal, abortError);
-                        continue;
+                        const backoff = Math.min(retryMaxMs, retryBaseMs * 2 ** (attempt - 1));
+                        const asked = error instanceof APIError && (status === 429 || status === 503) ? retryAfterMs(error.headers) : undefined;
+                        const delay = asked === undefined ? backoff : Math.max(asked, backoff);
+                        // A server's wait is kept in full or the loop gives up now: it never runs past the deadline, or past the longest timer when there is none, so no
+                        // retry is sent with no time left to answer (a request that times out has a cost no one knows).
+                        const left = timeoutMs === null ? 2_147_483_647 : timeoutMs - (Date.now() - started);
+                        if (asked === undefined || delay < left) {
+                            await wait(delay, signal, abortError);
+                            continue;
+                        }
                     }
+                    // HTTP 429 means every attempt was refused unanswered; after one that may have been billed, the give-up names that one instead.
+                    if (status === 429 && billable)
+                        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)

package/package.json

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