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

package/dist/index.js

@@ -7,8 +7,8 @@ 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,6 +95,119 @@ 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;
@@ -103,19 +216,19 @@ export function createJevRunner(options = {}) {
     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 || 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(hostClient === undefined || (options.apiKey === undefined && options.baseURL === undefined && options.fetch === undefined && options.provider === undefined), "Supply either client or transport options, not both.");
+    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);
@@ -142,82 +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;
-            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 (!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")
-                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++) {
@@ -256,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}`;
@@ -268,38 +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;
-                // Checked against the questions as they were sent: a value JSON cannot carry (an undefined criterion) was never asked.
-                try {
-                    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.");
-                }
-                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.23",
+  "version": "0.1.0-beta.27",
   "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.23",
+    "@parcha/agentrun-dsl": "0.1.0-beta.27",
     "@typesafe-ai/sdk": "0.7.0"
   },
   "repository": {