@corbits/system-one 0.3.1 → 0.4.0

package/README.md

@@ -18,6 +18,16 @@ bun add @corbits/system-one @intx/inference@^0.4.0 @intx/types@^0.4.0
 
 Runs on Bun >= 1.2 or Node >= 24.
 
+To consume an exact Git commit before it is published, enable the package's
+source condition because Git dependencies do not run `prepack`:
+
+```bash
+bun add github:corbitsdev/corbits-system-one#<commit>
+bun --conditions=corbits-system-one-src your-script.ts
+```
+
+Published consumers continue to use the built `dist` entry by default.
+
 ## Quickstart
 
 Needs `TYPESAFE_API_KEY` set.
@@ -60,6 +70,10 @@ Boolean questions answer as `noul`, a probability from 0 to 1 that the answer is
 | Export                            | Description                                                                         |
 | --------------------------------- | ----------------------------------------------------------------------------------- |
 | `evaluate(input, options?)`       | Runs one evaluation. Returns `EvaluateResult`: decisions or a `FallbackResult`.     |
+| `systemOne(input, options?)`      | Keyed decisions. Returns `answers` by question name, or the same fallback.          |
+| `choice`, `noul`, `score`, `box`  | Build one keyed question. `box` locates a region and needs model `jev-preview`.     |
+| `image`, `Image.fromBase64`       | PNG or JPEG bytes, a `Blob`, or base64. Other formats are rejected before send.     |
+| `withAssets`                      | Tag a template so interpolated images are sent. Also `withAssets.join`.             |
 | `createSystemOneAdapter(config?)` | Returns a `ProviderAdapter` for `runInference`. `config` is an `EvaluateConfig`.    |
 | `createSystemOneAdapterFactory`   | Interchange `AdapterFactory` for `SIDECAR_ADAPTER_MANIFEST`; takes offering quirks. |
 | `SYSTEM_ONE_PROVIDER`             | The `"corbits-system-one"` provider id.                                             |
@@ -72,24 +86,59 @@ Boolean questions answer as `noul`, a probability from 0 to 1 that the answer is
 
 ### Questions
 
-| `type`    | Fields                                                                          | Decision fields                                  |
-| --------- | ------------------------------------------------------------------------------- | ------------------------------------------------ |
-| `choice`  | `instructions`, `criteria` (option name → description or `null`, 1–255 options) | `choice`, `probabilities`, `confidence`          |
-| `score`   | `instructions`, `criteria` (2–10 descriptions)                                  | `score`, `legend`, `probabilities`, `confidence` |
-| `boolean` | `instructions`, optional `criteria: { true?, false? }`                          | `noul`                                           |
-| `noul`    | Same as `boolean`                                                               | `noul`                                           |
+| `type`    | Fields                                                                          | Decision fields                                                     |
+| --------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `choice`  | `instructions`, `criteria` (option name → description or `null`, 1–255 options) | `choice`, `probabilities`, `confidence`                             |
+| `score`   | `instructions`, `criteria` (2–10 descriptions)                                  | `score`, `legend`, `probabilities`, `confidence`                    |
+| `boolean` | `instructions`, optional `criteria: { true?, false? }`                          | `noul`                                                              |
+| `noul`    | Same as `boolean`                                                               | `noul`                                                              |
+| `box`     | `instructions` describing what to locate. Use model `jev-preview`.              | `box` (`top`, `bottom`, `left`, `right` as fractions), `confidence` |
+
+Every list question has an `id`, unique within the list. `box` edges outside `[0, 1]` are rejected.
+
+### Keyed questions
+
+`systemOne` takes the same state and a record of questions built with `choice`, `noul`, `score`, and `box`. The names are the answer keys. Those helpers compile to the list `evaluate` already sends. The same fallback reasons apply, and those failures do not throw. The helpers are also exported from `@corbits/system-one/decisions`.
+
+```ts
+import { choice, noul, score, systemOne } from "@corbits/system-one";
+
+const result = await systemOne({
+  state: { document: "I was charged twice." },
+  questions: {
+    category: choice("What is this?", { billing: null, technical: null }),
+    escalate: noul("Must this be escalated?"),
+    severity: score("How severe?", ["none", "cosmetic", "unusable"]),
+  },
+});
+```
+
+On success, read `result.answers.category.choice` (plus `probabilities` and `confidence`), `result.answers.escalate.noul`, and `result.answers.severity.score`.
+
+`image()` accepts a `Blob` or `Uint8Array`. `Image.fromBase64()` accepts base64 file bytes. Only PNG and JPEG are sent. Place an image in `state`, instructions, or criteria, or interpolate it with `withAssets` (and `withAssets.join` for a list). An image in an ordinary template string is rejected before the request. `assets` maps a name to an image for plain strings; every name must appear as its own token in the request. A request with any image is `multipart/form-data` and sends `TypeSafe-Danger-Zone-Images: true`. Otherwise the body stays JSON.
+
+```ts
+import { box, image, systemOne, withAssets } from "@corbits/system-one";
+
+const photo = image(pngBytes);
+const result = await systemOne({
+  state: withAssets`Returned item: ${photo}`,
+  questions: { damage: box("The damaged area") },
+  model: "jev-preview",
+});
+```
 
-Every question has an `id`, unique within the list.
+`providerOptions.systemOne.questions` accepts this keyed record as well as a question list.
 
 ### Config
 
 `input.config` for `evaluate`, or the argument to `createSystemOneAdapter`:
 
-| Field       | Type             | Default                | Description                                                                      |
-| ----------- | ---------------- | ---------------------- | -------------------------------------------------------------------------------- |
-| `endpoint`  | `EndpointConfig` | `{ kind: "official" }` | `official`, `gateway`, or `custom` with a `url`. Each takes an optional `model`. |
-| `timeoutMs` | `number`         | `1500`                 | Bound for the whole round trip.                                                  |
-| `apiKey`    | `string`         | from the environment   | Overrides the environment key.                                                   |
+| Field       | Type             | Default                | Description                                                                                                       |
+| ----------- | ---------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `endpoint`  | `EndpointConfig` | `{ kind: "official" }` | `official`, `gateway`, or `custom` with a `url`. Each takes an optional `model`. `custom` may set `auth: "none"`. |
+| `timeoutMs` | `number`         | `1500`                 | Bound for the whole round trip.                                                                                   |
+| `apiKey`    | `string`         | from the environment   | Overrides the environment key.                                                                                    |
 
 ### Endpoints and keys
 
@@ -97,19 +146,20 @@ Every question has an `id`, unique within the list.
 | ---------- | ---------------------------------------------------- | ----------------- | ---------------------------------------------- |
 | `official` | `https://api.typesafe.ai/v1/systemone`               | `jev-latest`      | `TYPESAFE_API_KEY`                             |
 | `gateway`  | `https://ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | `AI_GATEWAY_API_KEY`, then `VERCEL_OIDC_TOKEN` |
-| `custom`   | `url`                                                | `typesafe-ai/jev` | `SYSTEM_ONE_API_KEY`                           |
+| `custom`   | `url`                                                | `typesafe-ai/jev` | `SYSTEM_ONE_API_KEY`, unless `auth: "none"`    |
 
 `SYSTEM_ONE_API_KEY` is also a supported alias on every endpoint, read after the endpoint's own key.
+A custom endpoint with `auth: "none"` does not require a key and does not send `Authorization`. Official and gateway always require a key. Any other `auth` value is invalid input and throws.
 
 ### Fallback reasons
 
-| `reason`      | When                                                          |
-| ------------- | ------------------------------------------------------------- |
-| `no-key`      | No key in `apiKey` or the environment. No request is sent.    |
-| `timeout`     | The round trip, including the body read, exceeds `timeoutMs`. |
-| `network`     | The request fails before a response.                          |
-| `http-error`  | Non-2xx response. `httpStatus` holds the status.              |
-| `parse-error` | The body is not JSON or fails validation.                     |
+| `reason`      | When                                                                                                           |
+| ------------- | -------------------------------------------------------------------------------------------------------------- |
+| `no-key`      | No key in `apiKey` or the environment, and the endpoint is not custom with `auth: "none"`. No request is sent. |
+| `timeout`     | The round trip, including the body read, exceeds `timeoutMs`.                                                  |
+| `network`     | The request fails before a response.                                                                           |
+| `http-error`  | Non-2xx response. `httpStatus` holds the status.                                                               |
+| `parse-error` | The body is not JSON or fails validation.                                                                      |
 
 `detail` carries the underlying message.
 
@@ -198,7 +248,7 @@ The hub offering's `quirks` are validated and all optional:
 }
 ```
 
-Without `endpoint`, the adapter posts to the catalog provider's `baseURL` + `/systemone`, the host the offering's credential was issued for. A `model` quirk (top level or on `endpoint`) is the model sent on the wire, so one catalog model can be served by providers that name it differently. `questions` and `state` are per-call defaults; `providerOptions.systemOne` on a call wins field by field. Unknown keys throw. The adapter sends the bearer sentinel and the harness injects the offering's credential.
+Without `endpoint`, the adapter posts to the catalog provider's `baseURL` + `/systemone`, the host the offering's credential was issued for. A `model` quirk (top level or on `endpoint`) is the model sent on the wire, so one catalog model can be served by providers that name it differently. `questions` and `state` are per-call defaults; `providerOptions.systemOne` on a call wins field by field. Unknown keys throw. The adapter sends the bearer sentinel and the harness injects the offering's credential, except a custom endpoint with `auth: "none"`, which omits `Authorization` so the host does not attach a key.
 
 | Provider          | Provider `baseURL`                         | `model` quirk                 |
 | ----------------- | ------------------------------------------ | ----------------------------- |
@@ -211,7 +261,7 @@ Without `endpoint`, the adapter posts to the catalog provider's `baseURL` + `/sy
 
 - `createSystemOneAdapterFactory` without an `endpoint` quirk now posts to the catalog provider's `baseURL` + `/systemone` instead of the official TypeSafe URL. Set the provider `baseURL` to the API root (for example `https://api.typesafe.ai/v1`), or keep the old behavior with `{"endpoint":{"kind":"official"}}`. The harness sends the offering's credential to whatever URL the adapter returns, so only set an explicit `endpoint` on a host that credential belongs to.
 - A `model` quirk now overrides the model the harness passes (the catalog canonical name).
-- `createSystemOneAdapter` and `evaluate` are unchanged.
+- `createSystemOneAdapter` and `evaluate` accept `auth: "none"` on a custom endpoint and omit `Authorization`. Any other `auth` value throws `SystemOneError` before a request is built.
 
 ## Upgrading from 0.1
 

package/dist/adapter.d.ts

@@ -1,5 +1,5 @@
 import { type AdapterFactory, type ProviderAdapter } from "@intx/inference";
-import { type EvaluateConfig } from "./schemas.js";
+import { EvaluateConfig } from "./schemas.js";
 /** Provider id this package serves. */
 export declare const SYSTEM_ONE_PROVIDER = "corbits-system-one";
 export declare function createSystemOneAdapter(config?: EvaluateConfig): ProviderAdapter;

package/dist/adapter.js

@@ -1,7 +1,8 @@
 import { type } from "arktype";
 import { BEARER_CREDENTIAL_SENTINEL, ProtocolMismatchError, } from "@intx/inference";
 import { resolveEndpoint } from "./config.js";
-import { Decision, toDecision, toWireQuestions, WireResponseBody, EndpointConfig, QuestionList, State, } from "./schemas.js";
+import { SystemOneError } from "./errors.js";
+import { Decision, DecisionQuestionRecord, toDecision, toWireQuestions, WireResponseBody, boxEdgesOutOfRange, EndpointConfig, EvaluateConfig, QuestionList, State, } from "./schemas.js";
 // ---------------------------------------------------------------------------
 // Adapter
 // ---------------------------------------------------------------------------
@@ -22,9 +23,10 @@ export const SYSTEM_ONE_PROVIDER = "corbits-system-one";
 // `state` replaces the transcript-derived default; `questions` replaces the
 // single-question default. Both are validated, never cast — `QuestionList`
 // carries the same non-empty/unique-id contract as `EvaluateInput`.
+const QuestionsInput = QuestionList.or(DecisionQuestionRecord);
 const SystemOneProviderOptions = type({
     "state?": State,
-    "questions?": QuestionList,
+    "questions?": QuestionsInput,
     "+": "reject",
 });
 // The Jev evaluate response body is the shared `WireResponseBody` envelope
@@ -51,6 +53,19 @@ const DEFAULT_QUESTIONS = [
         instructions: "Does this turn respond to the conversation?",
     },
 ];
+function asQuestionList(questions) {
+    if (Array.isArray(questions))
+        return questions;
+    const compiled = Object.entries(questions).map(([id, question]) => ({
+        id,
+        ...question,
+    }));
+    const parsed = QuestionList(compiled);
+    if (parsed instanceof type.errors) {
+        throw new ProtocolMismatchError(`${SYSTEM_ONE_PROVIDER} buildRequest: invalid providerOptions.systemOne questions: ${parsed.summary}`, questions);
+    }
+    return parsed;
+}
 function transcriptText(turns) {
     const texts = [];
     for (const turn of turns) {
@@ -94,6 +109,14 @@ function parseDecisions(body, provider) {
             throw new ProtocolMismatchError(`${provider} parseJSONResponse: answer id "${id}" vanished during parsing`, parsed);
         }
         try {
+            if (answer.type === "box") {
+                if (answer.box === undefined) {
+                    throw new Error(`answer "${id}" is missing box`);
+                }
+                const violation = boxEdgesOutOfRange(id, answer.box);
+                if (violation !== undefined)
+                    throw new Error(violation);
+            }
             return toDecision(id, answer);
         }
         catch (cause) {
@@ -107,7 +130,9 @@ function parseDecisions(body, provider) {
  * host's single copy of `@intx/inference` (peer dependency, never vendored).
  * The optional `config` pins the endpoint (official by default, gateway, or
  * a custom URL) and the per-call model default; the inference call's own
- * `model` argument wins for the request body.
+ * `model` argument wins for the request body. Official and gateway requests
+ * carry `authorization: BEARER_CREDENTIAL_SENTINEL` so the host injects a
+ * key. A custom endpoint with `auth: "none"` omits that header.
  */
 function createSystemOneProviderAdapter(config, source) {
     const endpoint = resolveEndpoint(config?.endpoint);
@@ -127,15 +152,18 @@ function createSystemOneProviderAdapter(config, source) {
             }
             if (overrides.state !== undefined)
                 state = overrides.state;
-            if (overrides.questions !== undefined)
-                questions = overrides.questions;
+            if (overrides.questions !== undefined) {
+                questions = asQuestionList(overrides.questions);
+            }
         }
         const requestModel = model || endpoint.model;
         const headers = {
             "content-type": "application/json",
             accept: "application/json",
-            authorization: BEARER_CREDENTIAL_SENTINEL,
         };
+        if (endpoint.auth !== "none") {
+            headers["authorization"] = BEARER_CREDENTIAL_SENTINEL;
+        }
         return {
             url: endpoint.url,
             headers,
@@ -197,7 +225,13 @@ function createSystemOneProviderAdapter(config, source) {
     };
 }
 export function createSystemOneAdapter(config) {
-    return createSystemOneProviderAdapter(config);
+    if (config === undefined)
+        return createSystemOneProviderAdapter();
+    const parsed = EvaluateConfig(config);
+    if (parsed instanceof type.errors) {
+        throw new SystemOneError("parse-error", `createSystemOneAdapter: invalid config: ${parsed.summary}`);
+    }
+    return createSystemOneProviderAdapter(parsed);
 }
 // Deployment quirks a hub offering carries for this provider. `questions`
 // and `state` are per-call defaults: a call's own `providerOptions.systemOne`

package/dist/assets.d.ts

@@ -0,0 +1,36 @@
+export declare const contentTypeOf: (bytes: Uint8Array) => string;
+/** A PNG or JPEG image. Create one with `image` or `Image.fromBase64`. */
+export declare class Image {
+    #private;
+    readonly type = "image";
+    readonly data: Uint8Array | Blob;
+    constructor(data: Blob | ArrayBuffer | ArrayBufferView);
+    /** Decode base64 file bytes. Do not include a `data:` URL prefix. */
+    static fromBase64(text: string): Image;
+    toString(): string;
+    toJSON(): string;
+}
+declare class TextWithAssets {
+    readonly text: string;
+    readonly assets: Image[];
+    constructor(text: string, assets: Image[]);
+    toString(): string;
+    toJSON(): string;
+}
+export type TextWithAssetsValue = TextWithAssets;
+/** Create an image from file bytes or a Blob. PNG and JPEG only, checked before send. */
+export declare const image: (data: Blob | ArrayBuffer | ArrayBufferView) => Image;
+/**
+ * Tag a template so interpolated images are sent with the text.
+ * An image in an untagged template is rejected before the request is sent.
+ */
+export declare const withAssets: ((strings: TemplateStringsArray, ...values: unknown[]) => TextWithAssets) & {
+    join: (values: readonly unknown[], separator: string) => TextWithAssets;
+};
+export type SerializedRequest = {
+    json: string;
+    assets: Record<string, Image> | undefined;
+};
+/** Replace images with references and reject dangling or unused asset names. */
+export declare function serializeRequest(payload: unknown, assets?: Record<string, Image>): SerializedRequest;
+export {};

package/dist/assets.js

@@ -0,0 +1,232 @@
+import { SystemOneError } from "./errors.js";
+const CONTENT_TYPES = [
+    ["image/png", [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]],
+    ["image/jpeg", [0xff, 0xd8, 0xff]],
+];
+const REFERENCE = /<image:[0-9a-f]{32}>/g;
+const IMAGE = Symbol.for("@typesafe-ai/sdk/image");
+const TEXT_WITH_ASSETS = Symbol.for("@typesafe-ai/sdk/text-with-assets");
+const randomHex = () => Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+const isImage = (value) => IMAGE in value;
+const isTextWithAssets = (value) => TEXT_WITH_ASSETS in value;
+function fail(message) {
+    throw new SystemOneError("parse-error", message);
+}
+const toBytes = (data) => {
+    if (!ArrayBuffer.isView(data) &&
+        Object.prototype.toString.call(data) !== "[object ArrayBuffer]") {
+        fail("Image data must be file bytes or a Blob.");
+    }
+    return ArrayBuffer.isView(data)
+        ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+        : new Uint8Array(data);
+};
+export const contentTypeOf = (bytes) => {
+    for (const [contentType, signature] of CONTENT_TYPES) {
+        if (signature.every((byte, index) => bytes[index] === byte)) {
+            return contentType;
+        }
+    }
+    return "application/octet-stream";
+};
+/** A PNG or JPEG image. Create one with `image` or `Image.fromBase64`. */
+export class Image {
+    type = "image";
+    data;
+    #reference = `<image:${randomHex()}>`;
+    constructor(data) {
+        this.data = data instanceof Blob ? data : toBytes(data);
+        const size = this.data instanceof Blob ? this.data.size : this.data.byteLength;
+        if (size === 0)
+            fail("Image data is empty.");
+    }
+    /** Decode base64 file bytes. Do not include a `data:` URL prefix. */
+    static fromBase64(text) {
+        let binary;
+        try {
+            binary = atob(text);
+        }
+        catch (cause) {
+            const error = new SystemOneError("parse-error", "Image data must contain valid base64 text.");
+            error.cause = cause;
+            throw error;
+        }
+        return new Image(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+    }
+    toString() {
+        return this.#reference;
+    }
+    toJSON() {
+        return this.#reference;
+    }
+}
+Object.defineProperty(Image.prototype, IMAGE, { value: true });
+class TextWithAssets {
+    text;
+    assets;
+    constructor(text, assets) {
+        this.text = text;
+        this.assets = assets;
+    }
+    toString() {
+        return this.text;
+    }
+    toJSON() {
+        return this.text;
+    }
+}
+Object.defineProperty(TextWithAssets.prototype, TEXT_WITH_ASSETS, {
+    value: true,
+});
+/** Create an image from file bytes or a Blob. PNG and JPEG only, checked before send. */
+export const image = (data) => new Image(data);
+const collectAssets = (value, found, visited) => {
+    if (typeof value !== "object" || value === null || visited.has(value))
+        return;
+    visited.add(value);
+    if (isImage(value))
+        found.set(String(value), value);
+    else if (isTextWithAssets(value)) {
+        for (const asset of value.assets)
+            found.set(String(asset), asset);
+    }
+    else {
+        for (const item of Object.values(value))
+            collectAssets(item, found, visited);
+    }
+};
+const textWithAssets = (text, values) => {
+    const interpolated = new Map();
+    collectAssets(values, interpolated, new Set());
+    const assets = new Map();
+    for (const [reference] of text.matchAll(REFERENCE)) {
+        const asset = interpolated.get(reference);
+        if (asset !== undefined)
+            assets.set(reference, asset);
+    }
+    return new TextWithAssets(text, [...assets.values()]);
+};
+/**
+ * Tag a template so interpolated images are sent with the text.
+ * An image in an untagged template is rejected before the request is sent.
+ */
+export const withAssets = Object.assign((strings, ...values) => textWithAssets(strings.reduce((joined, piece, index) => joined + String(values[index - 1]) + piece), values), {
+    join: (values, separator) => textWithAssets(values.join(separator), values),
+});
+/** Replace images with references and reject dangling or unused asset names. */
+export function serializeRequest(payload, assets = {}) {
+    const names = new Map(Object.entries(assets).map(([name, asset]) => [asset, name]));
+    const known = new Map(Object.values(assets).map((asset) => [String(asset), asset]));
+    const json = JSON.stringify(payload, function (key, value) {
+        if (typeof value === "number" && !Number.isFinite(value))
+            return String(value);
+        const holder = this;
+        const original = holder[key];
+        if (typeof original !== "object" || original === null)
+            return value;
+        if (isImage(original)) {
+            const name = names.get(original);
+            if (name !== undefined)
+                return name;
+            known.set(String(original), original);
+        }
+        else if (isTextWithAssets(original)) {
+            let text = original.text;
+            for (const asset of original.assets) {
+                const name = names.get(asset);
+                if (name === undefined)
+                    known.set(String(asset), asset);
+                else
+                    text = text.replaceAll(String(asset), name);
+            }
+            return text;
+        }
+        return value;
+    });
+    const unreferenced = Object.keys(assets).filter((name) => !jsonValueHasToken(json, name));
+    if (unreferenced.length > 0) {
+        fail(`Assets not referenced in the request: ${unreferenced.join(", ")}. Write each name in \`assets\` into state, question instructions, or criteria.`);
+    }
+    const sent = new Map(Object.entries(assets));
+    const missing = new Set();
+    for (const [reference] of json.matchAll(REFERENCE)) {
+        if (sent.has(reference))
+            continue;
+        const asset = known.get(reference);
+        if (asset === undefined)
+            missing.add(reference);
+        else
+            sent.set(reference, asset);
+    }
+    if (missing.size > 0) {
+        fail(`Image references without an attached image: ${[...missing].join(", ")}. Tag template literals that interpolate images with \`withAssets\`.`);
+    }
+    return {
+        json,
+        assets: sent.size === 0 ? undefined : Object.fromEntries(sent),
+    };
+}
+const IDENT = /[0-9A-Za-z_]/;
+/** True when `name` is its own token in state, instructions, or criteria. */
+function jsonValueHasToken(json, name) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return false;
+    }
+    return requestReferencesName(parsed, name);
+}
+function own(value, key) {
+    if (!Object.hasOwn(value, key))
+        return undefined;
+    return Object.getOwnPropertyDescriptor(value, key)?.value;
+}
+/** Question `type` and other fields are not references. Keys are not either. */
+function requestReferencesName(payload, name) {
+    if (typeof payload !== "object" || payload === null)
+        return false;
+    if (valueHasToken(own(payload, "state"), name))
+        return true;
+    const questions = own(payload, "questions");
+    if (typeof questions !== "object" || questions === null)
+        return false;
+    for (const question of Object.values(questions)) {
+        if (typeof question !== "object" || question === null)
+            continue;
+        if (valueHasToken(own(question, "instructions"), name))
+            return true;
+        if (valueHasToken(own(question, "criteria"), name))
+            return true;
+    }
+    return false;
+}
+function valueHasToken(value, name) {
+    if (typeof value === "string")
+        return hasToken(value, name);
+    if (Array.isArray(value))
+        return value.some((item) => valueHasToken(item, name));
+    if (typeof value === "object" && value !== null) {
+        return Object.values(value).some((item) => valueHasToken(item, name));
+    }
+    return false;
+}
+function hasToken(text, name) {
+    if (name.length === 0)
+        return false;
+    // `<image:hex>` is one generated reference, not a use of an asset named `image`.
+    const visible = text.replace(/<image:[0-9a-f]{32}>/g, (reference) => " ".repeat(reference.length));
+    let from = 0;
+    while (from <= visible.length) {
+        const at = visible.indexOf(name, from);
+        if (at < 0)
+            return false;
+        const before = at === 0 ? "" : (visible[at - 1] ?? "");
+        const after = visible[at + name.length] ?? "";
+        if (!IDENT.test(before) && !IDENT.test(after))
+            return true;
+        from = at + 1;
+    }
+    return false;
+}

package/dist/client.d.ts

@@ -3,6 +3,11 @@ import { type Dependencies } from "@intx/inference";
 export type PostEvaluateOptions = {
     timeoutMs?: number;
     apiKey?: string;
+    imageParts?: {
+        name: string;
+        bytes: Uint8Array;
+        contentType: "image/png" | "image/jpeg";
+    }[];
 };
 /** Transport dependencies: the `fetch` to POST with and the timeout scheduler. */
 export type EvaluateDeps = Pick<Dependencies, "fetch" | "scheduler">;

package/dist/client.js

@@ -1,6 +1,58 @@
 import { classifyHTTPError, classifyNetworkError, classifyProtocolMismatch, } from "@intx/inference";
 import { DEFAULT_TIMEOUT_MS } from "./config.js";
 import { SystemOneError, TransportError } from "./errors.js";
+function bodyHasBoxQuestion(body) {
+    if (typeof body !== "object" || body === null)
+        return false;
+    if (!Object.hasOwn(body, "questions"))
+        return false;
+    const questions = Object.getOwnPropertyDescriptor(body, "questions")?.value;
+    if (typeof questions !== "object" || questions === null)
+        return false;
+    return Object.values(questions).some((question) => {
+        if (typeof question !== "object" || question === null)
+            return false;
+        if (!Object.hasOwn(question, "type"))
+            return false;
+        return Object.getOwnPropertyDescriptor(question, "type")?.value === "box";
+    });
+}
+function encodeMultipart(payload, parts) {
+    const boundary = Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const encoder = new TextEncoder();
+    const chunks = [];
+    const fields = [
+        {
+            name: "request",
+            contentType: "application/json",
+            content: encoder.encode(JSON.stringify(payload)),
+        },
+        ...parts.map((part) => ({
+            name: part.name,
+            contentType: part.contentType,
+            content: part.bytes,
+            filename: part.name,
+        })),
+    ];
+    for (const field of fields) {
+        const disposition = field.filename === undefined
+            ? `name="${field.name}"`
+            : `name="${field.name}"; filename="${field.filename}"`;
+        chunks.push(encoder.encode(`--${boundary}\r\nContent-Disposition: form-data; ${disposition}\r\nContent-Type: ${field.contentType}\r\n\r\n`), field.content, encoder.encode("\r\n"));
+    }
+    chunks.push(encoder.encode(`--${boundary}--\r\n`));
+    const size = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
+    const body = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return {
+        body,
+        contentType: `multipart/form-data; boundary=${boundary}`,
+    };
+}
 /**
  * POSTs an evaluation payload and returns the decoded JSON body. Sends
  * `Authorization: Bearer <apiKey>` only when a key is present; aborts the
@@ -14,8 +66,17 @@ import { SystemOneError, TransportError } from "./errors.js";
  */
 export async function postEvaluate(url, body, options, deps) {
     let serialized;
+    const imageParts = options.imageParts;
+    let contentType = "application/json";
     try {
-        serialized = JSON.stringify(body);
+        if (imageParts !== undefined && imageParts.length > 0) {
+            const encoded = encodeMultipart(body, imageParts);
+            serialized = encoded.body;
+            contentType = encoded.contentType;
+        }
+        else {
+            serialized = JSON.stringify(body);
+        }
     }
     catch {
         throw new SystemOneError("parse-error", "postEvaluate: request body is not JSON-serializable");
@@ -39,9 +100,13 @@ export async function postEvaluate(url, body, options, deps) {
     };
     try {
         const headers = {
-            "content-type": "application/json",
+            "content-type": contentType,
             accept: "application/json",
         };
+        if ((imageParts !== undefined && imageParts.length > 0) ||
+            bodyHasBoxQuestion(body)) {
+            headers["TypeSafe-Danger-Zone-Images"] = "true";
+        }
         if (options.apiKey !== undefined && options.apiKey !== "") {
             headers["authorization"] = `Bearer ${options.apiKey}`;
         }

package/dist/config.d.ts

@@ -30,6 +30,8 @@ export type ResolvedEndpoint = {
     url: string;
     backend: "corbits-system-one" | "gateway" | "custom";
     model: string;
+    /** `none` only when a custom endpoint explicitly opts out of a key. */
+    auth: "key" | "none";
 };
 /**
  * Resolves an evaluation endpoint to a concrete POST target. A per-call
@@ -39,5 +41,7 @@ export type ResolvedEndpoint = {
  * distinguishes caller-routed traffic from the official endpoint —
  * `'gateway'` is reserved for the proxy quirks path. The model always
  * resolves here: a `custom` target without one sends `typesafe-ai/jev`.
+ * `auth` is `"none"` only when the caller set `auth: "none"` on a custom
+ * endpoint; every other target still requires a key.
  */
 export declare function resolveEndpoint(endpoint?: EndpointConfig): ResolvedEndpoint;