@tangleai/models 0.21.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @tangleai/models
+
+## 0.21.1
+
+### Patch Changes
+
+- Update the exact Jaren foundation dependencies and source pin to the published
+  0.84.3 release after verifying its AI-free archives against source-built bytes.
+  Retain Tangle's model, context and agent ownership and align the development
+  Node pin with 24.20.0. Tangle publication remains a manual author action.
+  Allow release preparation after an already committed local release while
+  preserving its record and rejecting unprepared version edits.
+
+## 0.21.0
+
+### Minor Changes
+
+- Add independent model transport, evidence-backed context, and bounded agent/program packages. Preserve the JavaScript/JSDoc APIs, strict result contracts and injected host services, with JavaScript distributions and checked declarations. Toolbox browser registration delegates to Jaren's shared WebMCP contract.
+
+The source transfer is locally qualified before its first coordinated release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joham (jklarenbeek@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# @tangleai/models
+
+Injected model clients, provider adapters, embeddings, replay, routing and structured generation.
+
+This package keeps its JS/JSDoc implementation and deterministic tests. Inject
+fetch, storage and compiler services at the existing seams. The public source
+exports and emitted npm JavaScript share one implementation.
+
+## Public entries
+
+- `@tangleai/models`
+- `@tangleai/models/providers`
+- `@tangleai/models/sse`
+- `@tangleai/models/client`
+- `@tangleai/models/embed`
+- `@tangleai/models/structured`
+- `@tangleai/models/errors`
+- `@tangleai/models/check`
+- `@tangleai/models/routing`
+- `@tangleai/models/grammar`
+- `@tangleai/models/replay`
+- `@tangleai/models/package.json`
+
+See [ownership and verification](../../docs/JAREN_AI_MIGRATION.md) for source
+provenance, installation mode, unchanged serialized identities and qualification.
+
+## The client
+
+```js
+import { createChatClient } from '@tangleai/models/client';
+
+const client = createChatClient({
+  provider: 'openrouter',            // 'openrouter' | 'ollama' | 'lmstudio' | 'custom'
+  apiKey: userKey,                   // omit for local runtimes
+  model: 'qwen/qwen3-4b',
+});
+
+const { message } = await client.complete({
+  messages: [{ role: 'user', content: 'Say hi.' }],
+  onDelta: (text) => process.stdout.write(text),   // streamed by default
+});
+```
+
+Base URLs are forgiving: `http://localhost:11434` becomes `http://localhost:11434/v1`, a
+pasted `…/chat/completions` suffix is stripped (in any case), and a query string or
+fragment is refused with `AI0001` rather than spliced into the middle of every endpoint.
+The resolved base is `endpoint.base`; `/chat/completions` and `/models` are both composed
+from it, never re-derived from one another. `fetch` is injectable
+(`createChatClient({ fetch: myFetch })`) so the client runs identically in the browser, in
+Node, and in tests against a scripted stub. Failures carry stable codes: `AI0001` (caller
+error), `AI0002` (HTTP error status), `AI0003` (malformed payload).
+
+**Token limits are configurable.** `maxTokens` sets the client's default budget;
+`complete({ maxTokens })` overrides its amount for one call. The client option
+`maxTokensField` selects the JSON field: `'max_tokens'` by default for existing
+compatible providers, or `'max_completion_tokens'` for OpenAI Chat Completions.
+The client sends exactly one of these fields when a budget is set, and neither
+when it is unset. Selection is explicit, independent of the URL and model.
+
+```js
+import { createChatClient } from '@tangleai/models/client';
+
+const client = createChatClient({
+  provider: 'custom',
+  baseUrl: 'https://api.openai.com/v1',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: process.env.OPENAI_MODEL,
+  maxTokens: 3000,
+  maxTokensField: 'max_completion_tokens',
+});
+const reply = await client.complete({
+  messages: [{ role: 'user', content: 'Say hi.' }],
+  stream: false,
+});
+```
+
+OpenAI's `max_completion_tokens` bounds visible output **and reasoning tokens**;
+3,000 is their combined budget, not a promise of 3,000 visible tokens. OpenAI
+documents `max_tokens` as deprecated and incompatible with o-series models.
+Both parameters belong to Chat Completions; the Responses API is a different
+endpoint. No OpenAI SDK is needed for this client. Other options still depend on
+the selected model: `temperature` is omitted unless supplied, and `reasoning`
+is a provider-specific passthrough, not a translation to OpenAI's
+`reasoning_effort`. See the [OpenAI Chat Completions reference](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create).
+
+**Retries are built in.** Transient failures — network errors, 408, 429, 5xx,
+and malformed HTTP 200 payloads in either streaming mode — back off
+exponentially with full jitter and try again (`retry: { attempts, baseMs, maxMs }`,
+default 3 total tries; `attempts: 1` disables). A provider `Retry-After` header (seconds
+or HTTP-date) overrides the computed delay, capped at `maxMs`. Two hard rules: a request
+never retries once `onDelta` or `onReasoning` has received output, and an abort cancels the
+backoff immediately, preserving the signal's exact cancellation reason. The final
+transport `AI0002` reports `status`, `attempts`, and `retryAfterMs`; an exhausted
+malformed reply reports `AI0003` with `attempts`.
+
+**Reasoning models are first-class.** Thinking streamed as `delta.reasoning` (or
+`reasoning_details`) reaches the caller through `onReasoning`, and the final message
+carries a `reasoning` member — so a reasoning-only turn (empty `content`, non-empty
+`reasoning`) is distinguishable from an empty one instead of rendering as a blank bubble.
+The agent attaches `reasoning` to the **returned** message only: the transcript it
+accumulates never carries it, so a host that persists `messages` and sends them back next
+turn keeps a clean wire history.
+
+**Thinking can be turned off** — `reasoning` is forwarded verbatim, as a client-level
+default or per request: `createChatClient({ …, reasoning: { effort: 'none' } })`, and
+`{ enabled: false }` does the same. (`{ exclude: true }` only HIDES the thinking; the
+model still thinks and you still pay for it.) On a short, non-agentic call this is a large
+win — measured on a hybrid Qwen model, a one-line answer went from 140 completion tokens
+and 28.8s to 2 tokens and 0.5s. **Do not reach for it in an agent loop.** The same models,
+asked to author a document through tools with thinking off, roughly doubled their tool
+calls and stopped converging (2/3 then 0/3 runs reaching a green result, several hitting
+the round limit): they plan the document in the reasoning channel, so removing it removes
+the planning. Turn it off for classification, extraction and rewriting; leave it on for
+tool use.
+
+**A replay is a seam, and the client keys it.** `createChatClient({ …, cache })` takes
+`{ get(key), set(key, value) }` — each sync or async, a `Map` in a test, SQLite or a
+directory of files in a host — and answers a repeated request from it with **zero**
+transport calls. The client builds the key, not the host: after endpoint resolution and
+default application, from the exact credential-free body it would POST — provider,
+normalized base, model, messages, tools, `tool_choice`, `temperature`, the selected token-limit field,
+`reasoning`, `response_format` — canonicalized collision-free (`semanticKey` from
+`@jarenjs/core/object`). `stream`, the signal, the callbacks and the headers never enter
+it, and because the key is the body rather than an allow-list, an option added later
+cannot alias an old key. A replay comes back marked `replayed: { ms }` with the
+purchase's wall time and the purchase's `usage`, and fires `onDelta`/`onReasoning` once
+each with the whole text, so a streaming caller sees one code path; a purchase is
+remembered as `{ value, ms }`. The seam **fails closed**: an adapter that throws fails the
+call, a stored entry that does not verify is `AI0003`, a request that cannot be keyed (a
+function inside `tools`) is `AI0001` before any wire call — an adapter that wants to keep
+buying while its storage is broken catches its own errors and answers `undefined`. The key
+is the complete canonical request; an adapter that needs a fixed-width id hashes it with a
+cryptographic hash, never a 32-bit one, or two prompts a token apart will one day share an
+answer. A call ceiling counts wire calls at the injected `fetch`, which a replay never
+reaches.
+
+```js
+const store = new Map();
+const client = createChatClient({ provider: 'ollama', model: 'qwen3:4b',
+  cache: { get: (key) => store.get(key), set: (key, value) => { store.set(key, value); } } });
+const bought = await client.complete({ messages });        // one wire call, remembered
+const replay = await client.complete({ messages });        // zero wire calls
+replay.replayed;                                           // { ms: <the purchase's wall time> }
+```
+
+**Probe before the first turn.** `probeProvider({ provider, baseUrl, apiKey })` GETs the
+provider's `/models` listing with exactly the auth a chat call would use and never throws:
+`{ ok: true, models }` or `{ ok: false, status?, error }` — the contract a settings UI
+wants for a "Test connection" button and a model picker.
+
+
+## Embeddings
+
+The same providers serve the OpenAI-compatible `/embeddings` wire beside `/chat/completions`
+— OpenRouter at `/api/v1/embeddings`, Ollama and LM Studio at `/v1/embeddings` — and
+`createEmbeddingClient` speaks it from the same resolved base, with the same key, headers,
+`fetch` injection and retry policy as the chat client:
+
+```js
+import { createEmbeddingClient, probeEmbeddings } from '@tangleai/models/embed';
+import { cosineSimilarity } from '@jarenjs/core/vector';
+
+const embedder = createEmbeddingClient({
+  provider: 'ollama',                // the chat client's providers, keys and base URLs
+  model: 'nomic-embed-text',         // required — it is half of every vector's identity
+});
+
+const [a, b] = await embedder.embed(['a cat on a mat', 'quarterly revenue']);
+cosineSimilarity(a, b);              // Float32Arrays in; higher is better
+embedder.dims;                       // the width, settled by the first reply (or pass `dims`)
+```
+
+**The reply is verified, not trusted.** An `/embeddings` reply carries
+`data: [{ index, embedding }]`, and providers do answer a batch out of order. The client
+reassembles the items by `index` into input order and refuses the reply — `AI0003`, naming
+the input — unless exactly one non-empty vector of finite numbers, of the expected width,
+arrived per input. Components must stay finite after Float32 conversion, on the wire and
+from replay; numbers that overflow that range are refused with `AI0003`.
+An embedding attached to the wrong text is worse than an error, and this
+is the one place in the suite that rule is enforced.
+
+**A vector never travels without its identity.** Vectors from two models are pairwise
+meaningless and compare into plausible garbage, so the client carries `model` and `dims`:
+`dims` is either configured up front or fixed by the first reply, and every later reply is
+held to it — a model that changed width under the same name is refused, never mixed.
+
+**Retries and timeouts follow `complete()`.** Transient failures (network, 408, 429, 5xx, a
+malformed 200) back off with the same `retry` option and the same `Retry-After` cap; an abort
+ends everything at once. There is no default timeout, as `complete()` has none — a batch of
+long texts on a local runtime legitimately takes a while; `timeoutMs` bounds each attempt when
+you want one, and a timed-out attempt retries like a network failure.
+
+**Replays are per text.** `createEmbeddingClient({ …, cache })` takes the same seam the chat
+client documents and keys every input separately — the credential-free endpoint, the model
+and the text — so a batch that repeats three of five texts fetches two: the remembered
+vectors are placed, the rest travel in one wire call in input order, and every bought vector
+is remembered as `{ vector: number[], ms }` (the batch's wall time; the array is JSON-only,
+so a file or a SQL column stores it as it is). A call whose every text is remembered makes
+no wire call, and its first replay settles `dims` exactly as a first reply would — a stored
+vector of another width is `AI0003`, never mixed. Replays are observable at the seam (every
+`set` is a purchase, every answering `get` a replay); `probeEmbeddings` never consults one.
+
+**Probe before relying on it.** `probeEmbeddings({ provider, baseUrl, apiKey, model })` embeds
+one word in one attempt (5 000 ms, as `probeProvider`) and never throws:
+`{ ok: true, model, dims }` or `{ ok: false, status?, error }` — the contract for a settings
+UI, and the live proof that a provider really serves `/embeddings`.
+
+**The seam.** Everything in this package that consumes embeddings is written against three
+members — `{ embed(texts, { signal }) → Promise<Float32Array[]>, model, dims }` — and anything
+that implements them plugs in: the wire client above, a local transformer runtime, a native
+embedding library. The contract a host implementation keeps: `embed` returns a Promise and
+**rejects, never throws** (a synchronous throw escapes `.catch` and `Promise.all` alike — the
+consumers here call it inside their own `try` so a host that slips is still caught, but the
+contract is the rejection); one vector per input, in input order, all of one finite width;
+`model` a non-empty string; `dims` the width, or `undefined` until a first reply settles it.
+The ledger's `recall({ near })` and `embedMissing()` (§Compaction that moves) are the
+consumers. This package ships no model weights, no tokenizer and no download, and publishes
+no opinion on which embedding model is good; embedding *quality* belongs to the provider and
+the host.
+
+**The reference embedder is demo-grade, and says so.** `createHashEmbedder({ dims = 64 })`
+implements the seam with hashed character trigrams (FNV-1a into `dims` buckets, l2-normalized)
+— deterministic, dependency-free, network-free, identity `hash-trigram-<dims>`. It is
+**lexical, not semantic**: two texts score high when they share letters, not when they mean the
+same thing. It exists so that tests and offline demos exercise retrieval *mechanics* without a
+network; it is not a substitute for a model.
+
+The arithmetic — dot, cosine and Euclidean similarity (higher-is-better, a malformed pair
+scores 0 and never throws), l2 normalization, the packed little-endian Float32 form and the
+`isVector` shape guard — lives in [`@jarenjs/core/vector`](https://github.com/jklarenbeek/jarenjs/blob/main/packages/core/README.md#vectors), the
+suite's one home for it.
+
+
+## Structured output
+
+```js
+import { createStructuredOutput } from '@tangleai/models/structured';
+import schema from '@jarenjs/json/schemas/jaren-query.llm-profile.schema.json' with { type: 'json' };
+
+const out = createStructuredOutput({ client, schema, name: 'jaren_query' });
+const result = await out.generate([{ role: 'user', content: 'books over €10' }]);
+if ('value' in result) compileJsonQuery(result.value);   // validated, ready to compile
+else console.log(result.errors);                          // instancePath'd, model-readable
+```
+
+One call, every provider tier: where the provider speaks
+`response_format: json_schema` the schema constrains decoding; where it only has JSON
+mode, or nothing, the schema travels in a system instruction. Either way the reply is
+parsed (accidental code fences stripped) and **validated locally** by `@jarenjs/validate`
+— the provider is an accelerator, never the authority — and a failed round goes back to
+the model with the instancePath'd errors for a bounded number of repairs (`maxRepairs`,
+default 1). The query/JSLT grammars ship LLM-profile twins built for exactly this
+(see `@jarenjs/json`'s README).

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@tangleai/models",
+  "version": "0.21.1",
+  "description": "Injected model clients, provider adapters, embeddings, replay, routing and structured generation.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./providers": {
+      "types": "./src/providers.d.ts",
+      "import": "./src/providers.js",
+      "default": "./src/providers.js"
+    },
+    "./sse": {
+      "types": "./src/sse.d.ts",
+      "import": "./src/sse.js",
+      "default": "./src/sse.js"
+    },
+    "./client": {
+      "types": "./src/client.d.ts",
+      "import": "./src/client.js",
+      "default": "./src/client.js"
+    },
+    "./embed": {
+      "types": "./src/embed.d.ts",
+      "import": "./src/embed.js",
+      "default": "./src/embed.js"
+    },
+    "./structured": {
+      "types": "./src/structured.d.ts",
+      "import": "./src/structured.js",
+      "default": "./src/structured.js"
+    },
+    "./errors": {
+      "types": "./src/errors.d.ts",
+      "import": "./src/errors.js",
+      "default": "./src/errors.js"
+    },
+    "./check": {
+      "types": "./src/check.d.ts",
+      "import": "./src/check.js",
+      "default": "./src/check.js"
+    },
+    "./routing": {
+      "types": "./src/routing.d.ts",
+      "import": "./src/routing.js",
+      "default": "./src/routing.js"
+    },
+    "./grammar": {
+      "types": "./src/grammar.d.ts",
+      "import": "./src/grammar.js",
+      "default": "./src/grammar.js"
+    },
+    "./replay": {
+      "types": "./src/replay.d.ts",
+      "import": "./src/replay.js",
+      "default": "./src/replay.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@jarenjs/core": "0.84.3",
+    "@jarenjs/validate": "0.84.3"
+  },
+  "private": false,
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/tangleai.git",
+    "directory": "packages/models"
+  }
+}

package/src/check.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The one rejection shape every schema-guarded boundary in this package
+ * answers with: `{ error, errors, inputSchema }`, never a throw. The
+ * model (or the caller) reads the errors, re-reads the schema, and
+ * retries — which only works if every boundary answers the same way, so
+ * this is the single implementation and both the toolbox and the ledger
+ * call it rather than each shaping its own.
+ *
+ * Member order is part of the shape: `error`, `errors`, any `extra`
+ * (the toolbox's `hint`), then `inputSchema` last, because the schema is
+ * the biggest member and a reader scans the message first.
+ *
+ * @param {string} what - what was being validated (`add`, `memory`, …)
+ * @param {{ errors: any[] }} outcome - a normalized {@link checkOutcome}
+ * @param {any} inputSchema - the schema to re-read
+ * @param {Record<string, any>} [extra] - boundary-specific members
+ * @returns {{ error: string, errors: any[], inputSchema: any }}
+ */
+export function invalidInput(what: string, outcome: {
+    errors: any[];
+}, inputSchema: any, extra?: Record<string, any>): {
+    error: string;
+    errors: any[];
+    inputSchema: any;
+};
+/** Model-facing validation feedback over the shared strict check contract. */
+/** Validation errors reported back per rejected write — enough to fix
+ * from, few enough to stay readable in a model's context. */
+export const MAX_INPUT_ERRORS: 8;

package/src/check.js

@@ -0,0 +1,37 @@
+//@ts-check
+/** Model-facing validation feedback over the shared strict check contract. */
+
+/** Validation errors reported back per rejected write — enough to fix
+ * from, few enough to stay readable in a model's context. */
+export const MAX_INPUT_ERRORS = 8;
+
+/**
+ * The one rejection shape every schema-guarded boundary in this package
+ * answers with: `{ error, errors, inputSchema }`, never a throw. The
+ * model (or the caller) reads the errors, re-reads the schema, and
+ * retries — which only works if every boundary answers the same way, so
+ * this is the single implementation and both the toolbox and the ledger
+ * call it rather than each shaping its own.
+ *
+ * Member order is part of the shape: `error`, `errors`, any `extra`
+ * (the toolbox's `hint`), then `inputSchema` last, because the schema is
+ * the biggest member and a reader scans the message first.
+ *
+ * @param {string} what - what was being validated (`add`, `memory`, …)
+ * @param {{ errors: any[] }} outcome - a normalized {@link checkOutcome}
+ * @param {any} inputSchema - the schema to re-read
+ * @param {Record<string, any>} [extra] - boundary-specific members
+ * @returns {{ error: string, errors: any[], inputSchema: any }}
+ */
+export function invalidInput(what, outcome, inputSchema, extra = {}) {
+  return {
+    error: `invalid input for ${what}`,
+    errors: outcome.errors.slice(0, MAX_INPUT_ERRORS).map((e) => ({
+      instancePath: e.instancePath ?? '',
+      keyword: e.keyword ?? '',
+      message: e.message ?? 'invalid',
+    })),
+    ...extra,
+    inputSchema,
+  };
+}

package/src/client.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The reasoning text one streamed chunk carries: the OpenRouter/`o`-
+ * family `delta.reasoning` string, or the `reasoning_details` text
+ * entries some providers emit instead.
+ * @param {any} delta
+ * @returns {string}
+ */
+export function reasoningOf(delta: any): string;
+/**
+ * Accumulates OpenAI streaming chunks (`choices[0].delta`) into one
+ * normalized assistant message. Tool-call fragments merge by `index`;
+ * argument strings concatenate across chunks; reasoning deltas
+ * accumulate into `message.reasoning` (absent when the model emitted
+ * none) so a reasoning-only turn is distinguishable from an empty one.
+ * @returns {{ push: (chunk: any) => string, result: () => any }}
+ *   `push` returns the text delta this chunk contributed (may be '').
+ */
+export function createStreamAccumulator(): {
+    push: (chunk: any) => string;
+    result: () => any;
+};
+/**
+ * @typedef {Object} ChatRequest
+ * @property {any[]} messages - OpenAI wire-shape messages
+ * @property {any[]} [tools] - OpenAI function-tool definitions
+ * @property {any} [toolChoice] - `tool_choice` passthrough
+ * @property {string} [model] - overrides the client's configured model
+ * @property {number} [temperature]
+ * @property {number} [maxTokens] - token ceiling for this reply, sent under
+ *   the client's `maxTokensField`. Overrides the client default; when
+ *   both are unset, the provider chooses the limit. With
+ *   `max_completion_tokens`, reasoning tokens share this budget with
+ *   visible output tokens.
+ * @property {boolean} [stream] - default true
+ * @property {{ name?: string, schema?: any, strict?: boolean, type?: 'json' }} [responseFormat]
+ *   - structured output: `{ name, schema, strict? }` emits the OpenAI
+ *   `response_format: { type: "json_schema", … }` wire shape (strict
+ *   defaults to true); `{ type: 'json' }` emits `json_object` mode
+ * @property {{ effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high',
+ *   enabled?: boolean, exclude?: boolean, max_tokens?: number }} [reasoning]
+ *   - the provider-normalized thinking control, forwarded verbatim.
+ *   `{ effort: 'none' }` (or `{ enabled: false }`) turns a hybrid
+ *   thinking model OFF: it answers directly, which on a short task is
+ *   dramatically cheaper and faster. `{ exclude: true }` only HIDES the
+ *   thinking — the model still thinks and you still pay for it.
+ *   Overrides the client-level default.
+ * @property {AbortSignal} [signal]
+ * @property {(text: string) => void} [onDelta] - streamed text callback
+ * @property {(text: string) => void} [onReasoning] - streamed reasoning
+ *   callback (reasoning models emit thinking before/instead of content)
+ */
+/**
+ * @param {{ provider?: string, baseUrl?: string, apiKey?: string,
+ *   model?: string, headers?: Record<string, string>,
+ *   fetch?: typeof fetch, maxTokens?: number,
+ *   maxTokensField?: 'max_tokens' | 'max_completion_tokens',
+ *   reasoning?: { effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high',
+ *     enabled?: boolean, exclude?: boolean, max_tokens?: number },
+ *   retry?: import('./retry.js').RetryOptions,
+ *   cache?: import('./replay.js').ReplayCache }} [options]
+ *   - `maxTokensField` selects the wire field for client and request
+ *     `maxTokens` budgets (default `'max_tokens'`). Select
+ *     `'max_completion_tokens'` for OpenAI Chat Completions, including
+ *     reasoning models. The selection is explicit, not inferred from
+ *     the URL or model; exactly one field is sent when a budget is set.
+ *   - `reasoning` is the default thinking control for every request (see
+ *     `ChatRequest.reasoning`); a per-request value overrides it.
+ *   - `cache` is the replay seam: `{ get(key), set(key, value) }`, each
+ *     sync or async. The client keys every request by its effective
+ *     credential-free wire body after endpoint resolution and default
+ *     application (`stream`, the signal and the callbacks never enter
+ *     the key), answers a remembered reply with ZERO transport calls,
+ *     marked `replayed: { ms }` — the wall time of the purchase — with
+ *     `onDelta`/`onReasoning` fired once each with the whole text, and
+ *     remembers a bought reply as `{ value, ms }`. The seam fails closed:
+ *     an adapter that throws fails the call; a stored entry that does not
+ *     verify is `AI0003`; a request that cannot be keyed (a function
+ *     inside `tools`) is `AI0001` before any wire call. The key is the
+ *     complete canonical request — an adapter wanting a fixed-width id
+ *     hashes it cryptographically, never with a 32-bit hash.
+ *   - `retry.attempts` is the TOTAL number of tries (default 3; 1
+ *     disables retrying); backoff is exponential with full jitter,
+ *     capped at `maxMs`. A provider `Retry-After` (seconds or HTTP-date)
+ *     wins over the computed delay, capped at `maxMs` too: a provider
+ *     asking for a minute gets the cap (8 000 ms by default), and the
+ *     value it asked for rides the final error as `retryAfterMs` for
+ *     the caller to honour. `random` and `sleep` exist for deterministic
+ *     tests.
+ * @returns {{ endpoint: { provider: string, base: string, url: string,
+ *   headers: Record<string, string>, model: string },
+ *   complete: (request: ChatRequest) => Promise<any> }}
+ */
+export function createChatClient(options?: {
+    provider?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+    maxTokens?: number;
+    maxTokensField?: "max_tokens" | "max_completion_tokens";
+    reasoning?: {
+        effort?: "none" | "minimal" | "low" | "medium" | "high";
+        enabled?: boolean;
+        exclude?: boolean;
+        max_tokens?: number;
+    };
+    retry?: import("./retry.js").RetryOptions;
+    cache?: import("./replay.js").ReplayCache;
+}): {
+    endpoint: {
+        provider: string;
+        base: string;
+        url: string;
+        headers: Record<string, string>;
+        model: string;
+    };
+    complete: (request: ChatRequest) => Promise<any>;
+};
+export type ChatRequest = {
+    /**
+     * - OpenAI wire-shape messages
+     */
+    messages: any[];
+    /**
+     * - OpenAI function-tool definitions
+     */
+    tools?: any[];
+    /**
+     * - `tool_choice` passthrough
+     */
+    toolChoice?: any;
+    /**
+     * - overrides the client's configured model
+     */
+    model?: string;
+    temperature?: number;
+    /**
+     * - token ceiling for this reply, sent under
+     * the client's `maxTokensField`. Overrides the client default; when
+     * both are unset, the provider chooses the limit. With
+     * `max_completion_tokens`, reasoning tokens share this budget with
+     * visible output tokens.
+     */
+    maxTokens?: number;
+    /**
+     * - default true
+     */
+    stream?: boolean;
+    /**
+     * - structured output: `{ name, schema, strict? }` emits the OpenAI
+     * `response_format: { type: "json_schema", … }` wire shape (strict
+     * defaults to true); `{ type: 'json' }` emits `json_object` mode
+     */
+    responseFormat?: {
+        name?: string;
+        schema?: any;
+        strict?: boolean;
+        type?: "json";
+    };
+    /**
+     * - the provider-normalized thinking control, forwarded verbatim.
+     * `{ effort: 'none' }` (or `{ enabled: false }`) turns a hybrid
+     * thinking model OFF: it answers directly, which on a short task is
+     * dramatically cheaper and faster. `{ exclude: true }` only HIDES the
+     * thinking — the model still thinks and you still pay for it.
+     * Overrides the client-level default.
+     */
+    reasoning?: {
+        effort?: "none" | "minimal" | "low" | "medium" | "high";
+        enabled?: boolean;
+        exclude?: boolean;
+        max_tokens?: number;
+    };
+    signal?: AbortSignal;
+    /**
+     * - streamed text callback
+     */
+    onDelta?: (text: string) => void;
+    /**
+     * - streamed reasoning
+     * callback (reasoning models emit thinking before/instead of content)
+     */
+    onReasoning?: (text: string) => void;
+};