@tangleai/models 0.21.1

package/src/retry.js

@@ -0,0 +1,182 @@
+//@ts-check
+/**
+ * The transport policy every client in this package shares: which
+ * failures are transient, how long to wait before trying again, what a
+ * provider's `Retry-After` is worth, and how an abort cuts a wait
+ * short. The chat wire and the embeddings wire fail alike at the
+ * transport — a network error, a 408, a 429, a 5xx, a 200 whose body is
+ * not what the wire promised — and differ only in what a good reply
+ * must carry. So the loop lives here, once, and each client keeps its
+ * own reading of a reply: one implementation of retry, two wire shapes.
+ *
+ * Everything here is internal to the package; the public surface is
+ * the `retry` option each client documents.
+ */
+
+import { AiError } from './errors.js';
+import { backoffDelay, parseRetryAfter, sleep as defaultSleep, abortError } from '@jarenjs/core/retry';
+export { abortError };
+
+/**
+ * The `retry` option of every client.
+ * @typedef {Object} RetryOptions
+ * @property {number} [attempts] - the TOTAL number of tries (default 3;
+ *   1 disables retrying)
+ * @property {number} [baseMs] - the first backoff (default 500); each
+ *   later one doubles, with full jitter
+ * @property {number} [maxMs] - the ceiling on any single wait (default
+ *   8 000) — a provider `Retry-After` included: a provider asking for a
+ *   minute gets the cap, and the value it asked for rides the final
+ *   error as `retryAfterMs` for the caller to honour
+ * @property {() => number} [random] - the jitter source, for
+ *   deterministic tests
+ * @property {(ms: number, signal?: AbortSignal) => Promise<void>} [sleep]
+ *   - the wait itself, for deterministic tests; the default is a timer
+ *   that rejects with the abort reason the moment `signal` aborts
+ */
+
+/**
+ * The option with its defaults filled in.
+ * @typedef {Object} RetryPolicy
+ * @property {number} attempts
+ * @property {number} baseMs
+ * @property {number} maxMs
+ * @property {() => number} random
+ * @property {(ms: number, signal?: AbortSignal) => Promise<void>} sleep
+ */
+
+/**
+ * @param {RetryOptions | undefined} retry
+ * @returns {RetryPolicy}
+ */
+export function normalizeRetry(retry) {
+  return {
+    attempts: Math.max(1, retry?.attempts ?? 3),
+    baseMs: retry?.baseMs ?? 500,
+    maxMs: retry?.maxMs ?? 8000,
+    random: retry?.random ?? Math.random,
+    sleep: retry?.sleep ?? defaultSleep,
+  };
+}
+
+/** Statuses worth a retry: timeout, rate limit, server-side failure. */
+function isRetryableStatus(status) {
+  return status === 0 || status === 408 || status === 429 || status >= 500;
+}
+
+/**
+ * Whether a failure is the transient kind. A transport error with a
+ * retryable status is (a network failure before any response counts
+ * as status 0); so is a malformed 200 — a reply that carried none of
+ * what the wire promised is a provider hiccup, common on busy cheap
+ * tiers, and safe to retry precisely because nothing was delivered.
+ * Anything else — a caller error, a 401, a 404 — is final on the first
+ * try.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isTransientFailure(err) {
+  if (!(err instanceof AiError)) return false;
+  return err.code === 'AI0003'
+    || (err.code === 'AI0002' && isRetryableStatus(err.status ?? -1));
+}
+
+/**
+ * The wait before the next try: exponential backoff with full jitter,
+ * capped at `maxMs` — unless the provider named a `Retry-After`, which
+ * wins up to the same cap.
+ * @param {RetryPolicy} policy
+ * @param {number} attempt - the try that just failed, counted from 1
+ * @param {number | undefined} retryAfter - the provider's ask, in ms
+ * @returns {number} milliseconds
+ */
+export function retryDelay(policy, attempt, retryAfter) {
+  return backoffDelay({ ...policy, policy: 'ai-compat' }, attempt, retryAfter);
+}
+
+/**
+ * Run `once` until it settles. A failure `retryable` accepts backs off
+ * and tries again while tries remain; anything else is thrown as it
+ * came, and a coded transport failure (`AI0002`, `AI0003`) carries the
+ * number of tries as `attempts`. The wait honours `signal`: an abort
+ * during backoff rejects with the abort reason, exactly like an abort
+ * during the request — nothing is ever retried past an abort.
+ * @template T
+ * @param {RetryPolicy} policy
+ * @param {() => Promise<T>} once - one request/response cycle
+ * @param {{ signal?: AbortSignal, retryable: (failure: AiError) => boolean }} options
+ *   - `retryable` is the wire's own judgment over a coded failure (the
+ *   chat client, for one, stops retrying once a streamed delta has
+ *   reached the caller); it is never asked about an uncoded error
+ * @returns {Promise<T>}
+ */
+export async function withRetry(policy, once, options) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await once();
+    }
+    catch (err) {
+      if (options.signal?.aborted) throw abortError(options.signal);
+      const failure = /** @type {any} */ (err);
+      const coded = failure instanceof AiError;
+      if (!(coded && options.retryable(failure) && attempt < policy.attempts)) {
+        if (coded && (failure.code === 'AI0002' || failure.code === 'AI0003'))
+          failure.attempts = attempt;
+        throw err;
+      }
+      await policy.sleep(retryDelay(policy, attempt, failure.retryAfterMs), options.signal);
+    }
+  }
+}
+
+/**
+ * The `AI0002` for a response that is not ok: the status, a short
+ * excerpt of the body, and the provider's `Retry-After` in ms.
+ * @param {any} response
+ * @param {string} url
+ * @returns {Promise<AiError>}
+ */
+export async function httpFailure(response, url) {
+  const excerpt = await readErrorExcerpt(response);
+  return new AiError('AI0002',
+    `HTTP ${response.status} from ${url}${excerpt === '' ? '' : `: ${excerpt}`}`,
+    { status: response.status, retryAfterMs: retryAfterMs(response) });
+}
+
+/**
+ * What to throw when `fetch` itself threw: an abort exactly as it came
+ * (the caller's own signal, never retried, never rewrapped); anything
+ * else the `AI0002` of a failure before any response, status 0.
+ * @param {any} err
+ * @param {string} url
+ * @returns {any}
+ */
+export function transportFailure(err, url) {
+  if (err?.name === 'AbortError') return err;
+  return new AiError('AI0002',
+    `network error calling ${url}: ${err?.message ?? err}`,
+    { status: 0, cause: err });
+}
+
+/**
+ * Parse a `Retry-After` header (delta-seconds or HTTP-date) into ms.
+ * @param {any} response
+ * @returns {number | undefined}
+ */
+export function retryAfterMs(response) {
+  return parseRetryAfter(response?.headers?.get?.('retry-after'));
+}
+
+/**
+ * @param {any} response
+ * @returns {Promise<string>} a short excerpt of the error body
+ */
+async function readErrorExcerpt(response) {
+  try {
+    const text = await response.text();
+    return text.length > 300 ? `${text.slice(0, 300)}…` : text;
+  }
+  catch {
+    return '';
+  }
+}

package/src/routing.d.ts

@@ -0,0 +1,32 @@
+/** @typedef {{ deadlineMs?: number, outputTokens?: number, reasoningTokens?: number }} ModelLimits */
+/** @typedef {{ purpose: 'author'|'subcall'|'embedding'|'stylesheet', grammar?: string, depth?: number, limits?: ModelLimits }} ModelContext */
+/** A selector returns a route or ordered fallback routes: `{client, identity}`.
+ * A route identity is host data; it never controls provider policy. Embedding callers
+ * use their embedding API directly: this chat wrapper refuses that purpose so a
+ * fallback cannot silently change an index's embedding identity.
+ * @param {{ client: any, selectModel?: (context: ModelContext) => any,
+ *   limits?: ModelLimits, onRoute?: (event: any) => void, account?: any }} options
+ * @param {ModelContext} context */
+export function createRoutedClient(options: {
+    client: any;
+    selectModel?: (context: ModelContext) => any;
+    limits?: ModelLimits;
+    onRoute?: (event: any) => void;
+    account?: any;
+}, context: ModelContext): {
+    endpoint: any;
+    complete(request: any): Promise<any>;
+};
+/** Optional host routing for model-only calls. No tools execute inside this boundary. */
+export const MODEL_PURPOSES: readonly string[];
+export type ModelLimits = {
+    deadlineMs?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+};
+export type ModelContext = {
+    purpose: "author" | "subcall" | "embedding" | "stylesheet";
+    grammar?: string;
+    depth?: number;
+    limits?: ModelLimits;
+};

package/src/routing.js

@@ -0,0 +1,87 @@
+//@ts-check
+/** Optional host routing for model-only calls. No tools execute inside this boundary. */
+export const MODEL_PURPOSES = Object.freeze(['author', 'subcall', 'embedding', 'stylesheet']);
+
+/** @typedef {{ deadlineMs?: number, outputTokens?: number, reasoningTokens?: number }} ModelLimits */
+/** @typedef {{ purpose: 'author'|'subcall'|'embedding'|'stylesheet', grammar?: string, depth?: number, limits?: ModelLimits }} ModelContext */
+
+/** A selector returns a route or ordered fallback routes: `{client, identity}`.
+ * A route identity is host data; it never controls provider policy. Embedding callers
+ * use their embedding API directly: this chat wrapper refuses that purpose so a
+ * fallback cannot silently change an index's embedding identity.
+ * @param {{ client: any, selectModel?: (context: ModelContext) => any,
+ *   limits?: ModelLimits, onRoute?: (event: any) => void, account?: any }} options
+ * @param {ModelContext} context */
+export function createRoutedClient(options, context) {
+  if (!MODEL_PURPOSES.includes(context.purpose) || context.purpose === 'embedding')
+    throw new TypeError('chat routing requires author, stylesheet or subcall purpose');
+  const limits = { ...options.limits, ...context.limits };
+  for (const [name, value] of Object.entries(limits)) {
+    if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive integer`);
+  }
+  return {
+    endpoint: options.client.endpoint,
+    async complete(request) {
+      if (request.tools?.length || request.toolChoice !== undefined)
+        throw new TypeError('model routing does not retry tool-bearing requests');
+      const choice = options.selectModel ? await options.selectModel({ ...context, limits }) : null;
+      const routes = choice === null ? [{ client: options.client, identity: 'default' }]
+        : Array.isArray(choice) ? choice : [choice];
+      if (routes.length === 0) throw new TypeError('selectModel returned no routes');
+      let last;
+      for (const [index, route] of routes.entries()) {
+        if (!route?.client?.complete || typeof route.identity !== 'string' || !route.identity)
+          throw new TypeError('a model route needs client and identity');
+        request.signal?.throwIfAborted();
+        const stopped = options.account?.stop();
+        if (stopped) throw new Error(stopped);
+        const controller = new AbortController();
+        const remaining = options.account?.remaining?.().ms;
+        const deadline = Math.min(limits.deadlineMs ?? Infinity, remaining ?? Infinity);
+        const signal = request.signal
+          ? Number.isFinite(deadline) ? AbortSignal.any([request.signal, controller.signal]) : request.signal
+          : controller.signal;
+        let timer;
+        const started = performance.now();
+        const event = { ...context, identity: route.identity, fallback: index, limits, outcome: 'provider', ms: 0, usage: null,
+          schemaBytes: request.responseFormat?.schema ? new TextEncoder().encode(JSON.stringify(request.responseFormat.schema)).length : 0,
+          finishReason: null, errorCode: null };
+        try {
+          options.account?.reserve();
+          const bounded = { ...request, signal,
+            ...(limits.outputTokens ? { maxTokens: Math.min(request.maxTokens ?? Infinity, limits.outputTokens) } : {}),
+            ...(limits.reasoningTokens ? { reasoning: { ...request.reasoning,
+              max_tokens: Math.min(request.reasoning?.max_tokens ?? Infinity, limits.reasoningTokens) } } : {}),
+          };
+          const pending = Promise.resolve().then(() => route.client.complete(bounded));
+          const reply = await Promise.race([pending, new Promise((_, reject) => {
+            const abort = () => reject(signal.reason ?? new Error('aborted'));
+            signal.addEventListener('abort', abort, { once: true });
+            // Remove the listener when even an abort-ignoring client eventually settles.
+            pending.then(() => signal.removeEventListener('abort', abort), () => signal.removeEventListener('abort', abort));
+            if (Number.isFinite(deadline)) timer = setTimeout(() => controller.abort(new Error('model deadline')), deadline);
+          })]);
+          event.usage = reply.usage ?? null;
+          event.finishReason = reply.finishReason ?? null;
+          options.account?.settle(reply.usage, JSON.stringify(request.messages) + String(reply.message?.content ?? ''));
+          const usage = reply.usage;
+          if ((limits.outputTokens && usage?.completion_tokens > limits.outputTokens)
+            || (limits.reasoningTokens && usage?.completion_tokens_details?.reasoning_tokens > limits.reasoningTokens)) {
+            event.outcome = 'token-limit';
+            throw new Error('provider exceeded model token ceiling');
+          }
+          event.outcome = 'complete';
+          return reply;
+        }
+        catch (error) {
+          last = error;
+          event.errorCode = error?.code ?? error?.name ?? 'Error';
+          if (controller.signal.aborted) event.outcome = 'timeout';
+          if (request.signal?.aborted) { event.outcome = 'aborted'; throw error; }
+        }
+        finally { clearTimeout(timer); event.ms = performance.now() - started; options.onRoute?.(event); }
+      }
+      throw last;
+    },
+  };
+}

package/src/sse.d.ts

@@ -0,0 +1 @@
+export { createSseDecoder } from "@jarenjs/core/text/sse";

package/src/sse.js

@@ -0,0 +1,12 @@
+//@ts-check
+/**
+ * @file The `@tangleai/models/sse` subpath: the data-only Server-Sent-
+ * Events decoder the streaming client consumes — the one SSE codec of
+ * the suite, which lives in `@jarenjs/core/text/sse` and is re-exported
+ * here so this package's public surface is unchanged. Feed it network
+ * chunks in any split (mid-line, mid-event, CR/LF/CRLF); it yields the
+ * complete `data:` payloads in order; non-data fields and comments are
+ * ignored, multi-line data joins with a newline per the specification.
+ */
+
+export { createSseDecoder } from '@jarenjs/core/text/sse';

package/src/structured.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Strip an accidental markdown fence from a reply ("```json … ```") —
+ * the classic prompt-embedded-schema failure mode.
+ *
+ * Exported because every place this package parses a model's JSON has to
+ * make the same allowance, and two copies of "how forgiving are we about
+ * fences" is two answers to one question: `program.js`'s sub-calls parse
+ * replies the same way structured generation does.
+ * @param {string} text
+ */
+export function unfence(text: string): string;
+/**
+ * Create a structured-output generator over a chat client.
+ *
+ * @param {{ client: { endpoint: { provider: string }, complete: (request: any) => Promise<any> },
+ *   schema: any,
+ *   name?: string,
+ *   strict?: boolean,
+ *   validator?: (value: any) => any,
+ *   refs?: any[],
+ *   gate?: ((value: any) => any) | Array<(value: any) => any>,
+ *   stream?: boolean,
+ *   onAttempt?: (event: { attempt: number, outcome: string, errors: any[] }) => void,
+ *   maxRepairs?: number }} options
+ *   - `validator` overrides the internally compiled check (any
+ *     function returning a boolean or `{ valid, errors }`).
+ *   - `refs` are other JSON Schemas the `schema` references by `$id`,
+ *     registered before it is compiled — every Jaren engine-document
+ *     schema composes the published query/JSLT grammars by `$ref`, so
+ *     authoring an fsm/dag/app document needs them here (e.g. `refs:
+ *     [querySchema]`). Ignored when `validator` is given.
+ *   - `gate` is one or more extra checks run AFTER schema validation
+ *     (the schema still drives constrained decoding): the reliable way
+ *     to author an engine document — the schema keeps the *shape*, a
+ *     `compile` gate keeps the *semantics*. A gate is
+ *     `(doc) => { try { compile(doc); return true; } catch (e) {
+ *     return { valid: false, errors: [{ code: e.code, docPath:
+ *     e.docPath, message: e.reason ?? e.message }] }; } }`; its coded, docPath'd
+ *     errors go back to the model for repair (compile errors repair
+ *     well — they are precise). Composes with `validator` when both are
+ *     given (validator first). NOTE: a *quality/adequacy* gate — "needs
+ *     ≥N of something" — repairs poorly on weaker models (they patch
+ *     narrowly); enforce breadth in the prompt and reserve gates for
+ *     schema/compile correctness.
+ *   - `stream` sends the request streamed (default `false`). The parsed
+ *     value is identical either way — the accumulator reassembles the
+ *     reply before it is parsed — so this buys observability (a client's
+ *     `onDelta`/`onReasoning` fire) and nothing else. It is opt-in
+ *     because turning it on for every caller is a behaviour change for
+ *     callers who never asked for one.
+ *   - `maxRepairs` is how many failed rounds may go back to the model
+ *     with the validation errors (default 1).
+ * @returns {{ generate: (messages: any[], hooks?: { signal?: AbortSignal }) => Promise<
+ *   { value: any, raw: string, attempts: number } |
+ *   { errors: any[], raw: string, attempts: number }> }}
+ */
+export function createStructuredOutput(options: {
+    client: {
+        endpoint: {
+            provider: string;
+        };
+        complete: (request: any) => Promise<any>;
+    };
+    schema: any;
+    name?: string;
+    strict?: boolean;
+    validator?: (value: any) => any;
+    refs?: any[];
+    gate?: ((value: any) => any) | Array<(value: any) => any>;
+    stream?: boolean;
+    onAttempt?: (event: {
+        attempt: number;
+        outcome: string;
+        errors: any[];
+    }) => void;
+    maxRepairs?: number;
+}): {
+    generate: (messages: any[], hooks?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        value: any;
+        raw: string;
+        attempts: number;
+    } | {
+        errors: any[];
+        raw: string;
+        attempts: number;
+    }>;
+};

package/src/structured.js

@@ -0,0 +1,219 @@
+//@ts-check
+/**
+ * Structured output: schema in, validated JSON value out — on every
+ * provider tier.
+ *
+ * The helper sends one (non-streaming) chat request constrained by a
+ * JSON Schema, using the strongest mechanism the provider speaks
+ * (`response_format: json_schema` → JSON mode → schema embedded in a
+ * system instruction), parses the reply, and validates it locally with
+ * `@jarenjs/validate` — the same validator that guards the toolbox.
+ * Local validation is never optional: provider structured-output
+ * implementations enforce varying schema subsets, so the server is an
+ * accelerator, not an authority. On failure the instancePath'd errors
+ * go back to the model for a bounded number of repair rounds.
+ */
+
+import { JarenValidator } from '@jarenjs/validate';
+import { checkOutcome, composeChecks } from '@jarenjs/core/check';
+import { PROVIDERS } from './providers.js';
+
+/** Validation errors reported per failed generation: enough to repair. */
+const MAX_ERRORS = 8;
+
+/**
+ * Normalize an injected check's errors into the compact records a
+ * repair prompt carries. The default `JarenValidator` check reports
+ * `{ instancePath, keyword, message }`; a compiler check (a Jaren
+ * engine caught into an outcome) reports `{ code, docPath, reason }`.
+ * Both are the same idea — a location and a reason — so a compile error
+ * keeps its `code` and its `docPath` here rather than being flattened
+ * into a location-less message. `docPath` (the engine's pointer into
+ * the offending document) wins over `instancePath` when both appear;
+ * `''` is a real docPath (the document root) and only `undefined`
+ * falls through. `reason` (the bare text of a coded error) wins over
+ * `message` so the record never carries the code and the path twice —
+ * the composed `message` already contains both, and the fields beside
+ * it are the structured copies.
+ * @param {any[]} raw
+ */
+function normalizeErrors(raw) {
+  return raw.slice(0, MAX_ERRORS).map((e) => {
+    /** @type {any} */
+    const out = {
+      instancePath: e.docPath ?? e.instancePath ?? '',
+      keyword: e.code ?? e.keyword ?? '',
+      message: e.reason ?? e.message ?? 'invalid',
+    };
+    if (e.code !== undefined) out.code = e.code;
+    if (e.docPath !== undefined) out.docPath = e.docPath;
+    return out;
+  });
+}
+
+/**
+ * The system instruction for providers that cannot (fully) constrain
+ * decoding: the schema travels in the prompt and the reply must be the
+ * bare JSON value.
+ * @param {any} schema
+ */
+function schemaInstruction(schema) {
+  return [
+    'Reply with a single JSON value that validates against this JSON Schema.',
+    'Output ONLY the JSON — no prose, no code fences.',
+    '',
+    JSON.stringify(schema),
+  ].join('\n');
+}
+
+/**
+ * Strip an accidental markdown fence from a reply ("```json … ```") —
+ * the classic prompt-embedded-schema failure mode.
+ *
+ * Exported because every place this package parses a model's JSON has to
+ * make the same allowance, and two copies of "how forgiving are we about
+ * fences" is two answers to one question: `program.js`'s sub-calls parse
+ * replies the same way structured generation does.
+ * @param {string} text
+ */
+export function unfence(text) {
+  const trimmed = text.trim();
+  const match = /^```(?:json)?\s*([\s\S]*?)\s*```$/.exec(trimmed);
+  return match === null ? trimmed : match[1];
+}
+
+/**
+ * Compile a schema that may reference others by `$id`, registering the
+ * referenced schemas first. Every Jaren engine-document grammar
+ * (fsm/dag/app/JSLT) composes the query grammar by `$ref`, so a plain
+ * `.compile(schema)` on one of them throws "Can not resolve schema".
+ * @param {any} schema
+ * @param {any[]} [refs]
+ * @returns {(value: any) => any}
+ */
+function compileWithRefs(schema, refs) {
+  const v = new JarenValidator({ skipErrors: false, collectErrors: true });
+  for (const ref of refs ?? []) v.addSchema(ref);
+  return v.compile(schema);
+}
+
+/**
+ * Create a structured-output generator over a chat client.
+ *
+ * @param {{ client: { endpoint: { provider: string }, complete: (request: any) => Promise<any> },
+ *   schema: any,
+ *   name?: string,
+ *   strict?: boolean,
+ *   validator?: (value: any) => any,
+ *   refs?: any[],
+ *   gate?: ((value: any) => any) | Array<(value: any) => any>,
+ *   stream?: boolean,
+ *   onAttempt?: (event: { attempt: number, outcome: string, errors: any[] }) => void,
+ *   maxRepairs?: number }} options
+ *   - `validator` overrides the internally compiled check (any
+ *     function returning a boolean or `{ valid, errors }`).
+ *   - `refs` are other JSON Schemas the `schema` references by `$id`,
+ *     registered before it is compiled — every Jaren engine-document
+ *     schema composes the published query/JSLT grammars by `$ref`, so
+ *     authoring an fsm/dag/app document needs them here (e.g. `refs:
+ *     [querySchema]`). Ignored when `validator` is given.
+ *   - `gate` is one or more extra checks run AFTER schema validation
+ *     (the schema still drives constrained decoding): the reliable way
+ *     to author an engine document — the schema keeps the *shape*, a
+ *     `compile` gate keeps the *semantics*. A gate is
+ *     `(doc) => { try { compile(doc); return true; } catch (e) {
+ *     return { valid: false, errors: [{ code: e.code, docPath:
+ *     e.docPath, message: e.reason ?? e.message }] }; } }`; its coded, docPath'd
+ *     errors go back to the model for repair (compile errors repair
+ *     well — they are precise). Composes with `validator` when both are
+ *     given (validator first). NOTE: a *quality/adequacy* gate — "needs
+ *     ≥N of something" — repairs poorly on weaker models (they patch
+ *     narrowly); enforce breadth in the prompt and reserve gates for
+ *     schema/compile correctness.
+ *   - `stream` sends the request streamed (default `false`). The parsed
+ *     value is identical either way — the accumulator reassembles the
+ *     reply before it is parsed — so this buys observability (a client's
+ *     `onDelta`/`onReasoning` fire) and nothing else. It is opt-in
+ *     because turning it on for every caller is a behaviour change for
+ *     callers who never asked for one.
+ *   - `maxRepairs` is how many failed rounds may go back to the model
+ *     with the validation errors (default 1).
+ * @returns {{ generate: (messages: any[], hooks?: { signal?: AbortSignal }) => Promise<
+ *   { value: any, raw: string, attempts: number } |
+ *   { errors: any[], raw: string, attempts: number }> }}
+ */
+export function createStructuredOutput(options) {
+  const { client, schema } = options;
+  if (schema === null || typeof schema !== 'object')
+    throw new TypeError('createStructuredOutput needs a JSON Schema object');
+  const name = options.name ?? 'result';
+  const maxRepairs = options.maxRepairs ?? 1;
+  // Non-streaming stays the DEFAULT, and the reason is a behaviour change
+  // rather than a preference: a caller reading `raw` or counting attempts
+  // gets the same answer either way, but a caller that passed a client
+  // with `onDelta` wired sees deltas start arriving where none did
+  // before. The measurement that made this an option: the campaign's
+  // authoring timeouts were on STREAMED calls, so streaming is not the
+  // cure for a slow authoring turn — but it is how a long turn stays
+  // observable, and a caller who wants that should not have to wrap the
+  // client to get it.
+  const stream = options.stream ?? false;
+  const base = options.validator ?? compileWithRefs(schema, options.refs);
+  const gates = options.gate === undefined ? [] : [].concat(options.gate);
+  const check = composeChecks(...gates);
+  const tier = PROVIDERS[client.endpoint.provider]?.structured ?? null;
+
+  /**
+   * @param {any[]} messages - wire-shape conversation to answer
+   * @param {{ signal?: AbortSignal }} [hooks]
+   */
+  async function generate(messages, hooks = {}) {
+    /** @type {any} */
+    const request = { stream, signal: hooks.signal };
+    let turn = [...messages];
+    if (tier === 'json_schema') {
+      request.responseFormat = { name, schema, strict: options.strict ?? true };
+    }
+    else {
+      // JSON mode (or nothing): the schema travels in the prompt;
+      // local validation makes the weaker tiers safe
+      if (tier === 'json') request.responseFormat = { type: 'json' };
+      turn = [{ role: 'system', content: schemaInstruction(schema) }, ...turn];
+    }
+
+    let raw = '';
+    /** @type {any[]} */
+    let errors = [];
+    for (let attempt = 1; attempt <= 1 + maxRepairs; attempt++) {
+      const result = await client.complete({ ...request, messages: turn });
+      raw = result.message.content;
+      /** @type {any} */
+      let value;
+      try {
+        value = JSON.parse(unfence(raw));
+      }
+      catch (err) {
+        errors = [{ instancePath: '', keyword: 'parse', message: `the reply is not JSON: ${/** @type {Error} */ (err).message}` }];
+        options.onAttempt?.({ attempt, outcome: 'schema', errors });
+        turn = [...turn,
+          { role: 'assistant', content: raw },
+          { role: 'user', content: 'That reply was not parseable JSON. Reply again with ONLY the JSON value.' }];
+        continue;
+      }
+      const shape = checkOutcome(base(value));
+      const outcome = shape.valid ? checkOutcome(check(value)) : shape;
+      if (outcome.valid) {
+        options.onAttempt?.({ attempt, outcome: 'valid', errors: [] });
+        return { value, raw, attempts: attempt };
+      }
+      errors = normalizeErrors(outcome.errors);
+      options.onAttempt?.({ attempt, outcome: shape.valid ? 'gate' : 'schema', errors });
+      turn = [...turn,
+        { role: 'assistant', content: raw },
+        { role: 'user', content: `That JSON does not validate against the schema. Fix exactly these and reply with ONLY the corrected JSON value:\n${JSON.stringify(errors)}` }];
+    }
+    return { errors, raw, attempts: 1 + maxRepairs };
+  }
+
+  return { generate };
+}