@tangleai/models 0.21.1 → 0.24.1

package/src/embed.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * Embeddings: the `/embeddings` wire of the same OpenAI-compatible
  * provider family the chat client speaks, and the seam every consumer
@@ -28,203 +27,133 @@
  * client that trusts reply order gets exactly that from a provider
  * that answers a batch out of order.
  */
-
 import { fnv1a } from '@jarenjs/core/string';
 import { l2Normalize } from '@jarenjs/core/vector';
-
-import { AiError } from './errors.js';
-import { verifyEmbeddingComponents } from './embedding-vector.js';
-import { resolveEndpoint } from './providers.js';
-import { normalizeRetry, withRetry, isTransientFailure, httpFailure, transportFailure, abortError } from './retry.js';
-import { normalizeCache, replayKey, verifyEmbeddingEntry, now } from './replay.js';
-
+import { AiError } from "./errors.js";
+import { verifyEmbeddingComponents } from "./embedding-vector.js";
+import { resolveEndpoint } from "./providers.js";
+import { normalizeRetry, withRetry, isTransientFailure, httpFailure, transportFailure, abortError } from "./retry.js";
+import { normalizeCache, replayKey, verifyEmbeddingEntry, now } from "./replay.js";
+/** The embedder seam: what every consumer of embeddings in this package
+ * takes, and what a host implements to bring its own. */
 /**
- * The embedder seam: what every consumer of embeddings in this package
- * takes, and what a host implements to bring its own.
- * @typedef {Object} Embedder
- * @property {(texts: string[], options?: { signal?: AbortSignal }) => Promise<Float32Array[]>} embed
- *   - one vector per input, in input order; rejects `AI0001` for
- *   anything but a non-empty array of strings
- * @property {string} model - the name half of a vector's identity
- * @property {number | undefined} dims - the width half; the wire client
- *   leaves it undefined until its first reply settles it, unless the
- *   caller configured it
- */
-
-/**
- * @param {unknown} texts
- * @returns {asserts texts is string[]}
  */
 function assertTexts(texts) {
-  if (!Array.isArray(texts) || texts.length === 0 || !texts.every((text) => typeof text === 'string'))
-    throw new AiError('AI0001', 'embed() needs a non-empty array of strings');
+    if (!Array.isArray(texts) || texts.length === 0 || !texts.every((text) => typeof text === 'string'))
+        throw new AiError('AI0001', 'embed() needs a non-empty array of strings');
 }
-
-/**
- * The OpenAI-compatible `/embeddings` client over the existing provider
- * set. The endpoint is `${base}/embeddings` from the same resolved base
- * the chat client uses, with the same auth and headers; the request is
- * one non-streaming POST of `{ model, input }`.
- *
- * Retries follow the chat client exactly: transient transport failures
- * (network, 408, 429, 5xx) and a malformed 200 back off with full
- * jitter and try again, `Retry-After` wins up to `maxMs`, an abort ends
- * everything at once. A structurally wrong reply — the wrong width for
- * a fixed model — is therefore reported after `attempts` tries; a probe
- * that wants a fast answer sets `retry: { attempts: 1 }`.
- *
- * @param {{ provider?: string, baseUrl?: string, apiKey?: string,
- *   model?: string, dims?: number, headers?: Record<string, string>,
- *   fetch?: typeof fetch, timeoutMs?: number,
- *   retry?: import('./retry.js').RetryOptions,
- *   cache?: import('./replay.js').ReplayCache }} [options]
- *   - `model` is required: it is half of every vector's identity.
- *   - `cache` is the replay seam (`createChatClient` documents the
- *     contract). Here it is PER TEXT: each input is keyed by the
- *     credential-free endpoint, the model and the text; the texts the
- *     adapter remembers come back from it, only the rest travel — in one
- *     wire call, in input order — and every bought vector is remembered
- *     as `{ vector: number[], ms }` (the wall time of the batch). A
- *     call whose every text is remembered makes no wire call at all, and
- *     its first replay settles `dims` exactly as a first reply would.
- *   - `dims` pins the other half up front; left out, the width of the
- *     first reply becomes the client's, and every later reply must
- *     match it. Give it when the identity must be known before the
- *     first call.
- *   - `timeoutMs` bounds each attempt, and a timed-out attempt retries
- *     like a network failure. Unset means no timeout, as `complete()`
- *     has none — a batch of long texts on a local runtime legitimately
- *     takes a while; `probeEmbeddings` sets 5 000 ms, as `probeProvider`
- *     does.
- *   - `retry` is the chat client's option, unchanged (see
- *     `createChatClient`).
- * @returns {Embedder & { provider: string }} the seam, plus the
- *   resolved provider name; `dims` is the settled width
- */
 export function createEmbeddingClient(options = {}) {
-  const endpoint = resolveEndpoint(options);
-  const model = endpoint.model;
-  if (typeof model !== 'string' || model === '')
-    throw new AiError('AI0001', 'createEmbeddingClient needs a model — it is half of every vector\'s identity');
-  if (options.dims !== undefined && !(Number.isInteger(options.dims) && options.dims > 0))
-    throw new AiError('AI0001', `dims must be a positive integer, got ${String(options.dims)}`);
-  const timeoutMs = options.timeoutMs;
-  if (timeoutMs !== undefined && !(Number.isFinite(timeoutMs) && timeoutMs > 0))
-    throw new AiError('AI0001', `timeoutMs must be a positive number, got ${String(timeoutMs)}`);
-  const url = `${endpoint.base}/embeddings`;
-  const fetchFn = options.fetch ?? ((u, init) => globalThis.fetch(u, init));
-  const retry = normalizeRetry(options.retry);
-  const cache = normalizeCache(options.cache);
-  /** @type {number | undefined} */
-  let dims = options.dims;
-
-  /**
-   * One request/response cycle.
-   * @param {string[]} texts
-   * @param {AbortSignal | undefined} signal
-   * @returns {Promise<Float32Array[]>}
-   */
-  async function attemptOnce(texts, signal) {
-    // the attempt's own deadline rides beside the caller's signal; which
-    // of the two fired decides whether the failure is a retryable
-    // timeout or the caller's abort
-    /** @type {AbortController | null} */
-    let deadline = null;
-    /** @type {any} */
-    let timer;
-    let requestSignal = signal;
-    if (timeoutMs !== undefined) {
-      deadline = new AbortController();
-      timer = setTimeout(() => /** @type {AbortController} */ (deadline).abort(), timeoutMs);
-      requestSignal = signal === undefined ? deadline.signal : AbortSignal.any([signal, deadline.signal]);
-    }
-    /** @type {string} */
-    let text;
-    try {
-      const response = await fetchFn(url, {
-        method: 'POST',
-        headers: endpoint.headers,
-        body: JSON.stringify({ model, input: texts }),
-        signal: requestSignal,
-      });
-      if (response.ok !== true) throw await httpFailure(response, url);
-      text = await response.text();
+    const endpoint = resolveEndpoint(options);
+    const model = endpoint.model;
+    if (typeof model !== 'string' || model === '')
+        throw new AiError('AI0001', 'createEmbeddingClient needs a model — it is half of every vector\'s identity');
+    if (options.dims !== undefined && !(Number.isInteger(options.dims) && options.dims > 0))
+        throw new AiError('AI0001', `dims must be a positive integer, got ${String(options.dims)}`);
+    const timeoutMs = options.timeoutMs;
+    if (timeoutMs !== undefined && !(Number.isFinite(timeoutMs) && timeoutMs > 0))
+        throw new AiError('AI0001', `timeoutMs must be a positive number, got ${String(timeoutMs)}`);
+    const url = `${endpoint.base}/embeddings`;
+    const fetchFn = options.fetch ?? ((u, init) => globalThis.fetch(u, init));
+    const retry = normalizeRetry(options.retry);
+    const cache = normalizeCache(options.cache);
+    let dims = options.dims;
+    /**
+     * One request/response cycle.
+     */
+    async function attemptOnce(texts, signal) {
+        // the attempt's own deadline rides beside the caller's signal; which
+        // of the two fired decides whether the failure is a retryable
+        // timeout or the caller's abort
+        let deadline = null;
+        let timer;
+        let requestSignal = signal;
+        if (timeoutMs !== undefined) {
+            deadline = new AbortController();
+            timer = setTimeout(() => deadline.abort(), timeoutMs);
+            requestSignal = signal === undefined ? deadline.signal : AbortSignal.any([signal, deadline.signal]);
+        }
+        let text;
+        try {
+            const response = await fetchFn(url, {
+                method: 'POST',
+                headers: endpoint.headers,
+                body: JSON.stringify({ model, input: texts }),
+                signal: requestSignal,
+            });
+            if (response.ok !== true)
+                throw await httpFailure(response, url);
+            text = await response.text();
+        }
+        catch (err) {
+            if (err instanceof AiError)
+                throw err;
+            if (deadline !== null && deadline.signal.aborted && signal?.aborted !== true)
+                throw new AiError('AI0002', `no answer from ${url} within ${timeoutMs} ms`, { status: 0, cause: err });
+            throw transportFailure(err, url);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            throw new AiError('AI0003', `malformed embeddings reply: ${text.slice(0, 120)}`);
+        }
+        const vectors = reassemble(payload, texts.length, dims);
+        // the first reply settles the width; from here every reply must match
+        if (dims === undefined)
+            dims = vectors[0].length;
+        return vectors;
     }
-    catch (err) {
-      if (err instanceof AiError) throw err;
-      if (deadline !== null && deadline.signal.aborted && signal?.aborted !== true)
-        throw new AiError('AI0002', `no answer from ${url} within ${timeoutMs} ms`, { status: 0, cause: err });
-      throw transportFailure(err, url);
+    /**
+     * @param [options]
+     */
+    async function embed(texts, options = {}) {
+        assertTexts(texts);
+        const { signal } = options;
+        /** @param batch */
+        const buy = (batch) => withRetry(retry, () => attemptOnce(batch, signal), { signal, retryable: isTransientFailure });
+        if (cache === null)
+            return buy(texts);
+        // per text: what the adapter remembers is placed, what it does not
+        // is bought in one call and remembered; a remembered vector's width
+        // is held to the settled one, and settles it when nothing has
+        const keys = texts.map((text) => replayKey('embeddings', endpoint, { model, input: text }));
+        const out = new Array(texts.length);
+        const missing = [];
+        for (let i = 0; i < texts.length; i++) {
+            const hit = await cache.get(keys[i]);
+            if (hit === undefined) {
+                missing.push(i);
+                continue;
+            }
+            const vector = verifyEmbeddingEntry(hit, dims);
+            if (dims === undefined)
+                dims = vector.length;
+            out[i] = vector;
+        }
+        if (missing.length > 0) {
+            const started = now();
+            const vectors = await buy(missing.map((i) => texts[i]));
+            const ms = now() - started;
+            for (let j = 0; j < missing.length; j++) {
+                out[missing[j]] = vectors[j];
+                await cache.set(keys[missing[j]], { vector: Array.from(vectors[j]), ms });
+            }
+        }
+        return out;
     }
-    finally {
-      clearTimeout(timer);
-    }
-    /** @type {any} */
-    let payload;
-    try {
-      payload = JSON.parse(text);
-    }
-    catch {
-      throw new AiError('AI0003', `malformed embeddings reply: ${text.slice(0, 120)}`);
-    }
-    const vectors = reassemble(payload, texts.length, dims);
-    // the first reply settles the width; from here every reply must match
-    if (dims === undefined) dims = vectors[0].length;
-    return vectors;
-  }
-
-  /**
-   * @param {string[]} texts
-   * @param {{ signal?: AbortSignal }} [options]
-   * @returns {Promise<Float32Array[]>}
-   */
-  async function embed(texts, options = {}) {
-    assertTexts(texts);
-    const { signal } = options;
-    /** @param {string[]} batch */
-    const buy = (batch) => withRetry(retry, () => attemptOnce(batch, signal), { signal, retryable: isTransientFailure });
-    if (cache === null) return buy(texts);
-
-    // per text: what the adapter remembers is placed, what it does not
-    // is bought in one call and remembered; a remembered vector's width
-    // is held to the settled one, and settles it when nothing has
-    const keys = texts.map((text) => replayKey('embeddings', endpoint, { model, input: text }));
-    /** @type {Float32Array[]} */
-    const out = new Array(texts.length);
-    /** @type {number[]} */
-    const missing = [];
-    for (let i = 0; i < texts.length; i++) {
-      const hit = await cache.get(keys[i]);
-      if (hit === undefined) {
-        missing.push(i);
-        continue;
-      }
-      const vector = verifyEmbeddingEntry(hit, dims);
-      if (dims === undefined) dims = vector.length;
-      out[i] = vector;
-    }
-    if (missing.length > 0) {
-      const started = now();
-      const vectors = await buy(missing.map((i) => texts[i]));
-      const ms = now() - started;
-      for (let j = 0; j < missing.length; j++) {
-        out[missing[j]] = vectors[j];
-        await cache.set(keys[missing[j]], { vector: Array.from(vectors[j]), ms });
-      }
-    }
-    return out;
-  }
-
-  return {
-    embed,
-    model,
-    provider: endpoint.provider,
-    get dims() {
-      return dims;
-    },
-  };
+    return {
+        embed,
+        model,
+        provider: endpoint.provider,
+        get dims() {
+            return dims;
+        },
+    };
 }
-
 /**
  * The verification: `data[]` reassembled by each item's `index`, every
  * input filled exactly once, every vector a non-empty array of finite
@@ -232,44 +161,40 @@ export function createEmbeddingClient(options = {}) {
  * that failed. Nothing is guessed: an item without a usable index is
  * refused rather than placed by position, and a vector of the wrong
  * width is refused rather than cut or padded.
- * @param {any} payload
- * @param {number} count - the number of inputs sent
- * @param {number | undefined} dims - the width every vector must have,
+ * @param count - the number of inputs sent
+ * @param dims - the width every vector must have,
  *   or undefined to let input 0's vector settle it for this reply
- * @returns {Float32Array[]}
  */
 function reassemble(payload, count, dims) {
-  const data = payload?.data;
-  if (!Array.isArray(data))
-    throw new AiError('AI0003', 'malformed embeddings reply: no data[] in the response');
-  if (data.length !== count)
-    throw new AiError('AI0003', `embeddings reply carried ${data.length} items for ${count} inputs`);
-  /** @type {any[]} */
-  const slots = new Array(count);
-  for (let i = 0; i < count; i++) {
-    const item = data[i];
-    const index = item?.index;
-    if (!Number.isInteger(index) || index < 0 || index >= count)
-      throw new AiError('AI0003',
-        `embeddings reply item ${i} carries no usable index for ${count} inputs (got ${JSON.stringify(index)})`);
-    if (slots[index] !== undefined)
-      throw new AiError('AI0003', `input ${index} received two embeddings`);
-    slots[index] = item.embedding;
-  }
-  // `count` items over `count` distinct indices: every slot is filled
-  const out = new Array(count);
-  for (let i = 0; i < count; i++) {
-    const embedding = slots[i];
-    if (!Array.isArray(embedding) || embedding.length === 0)
-      throw new AiError('AI0003', `input ${i} received an empty embedding`);
-    if (dims === undefined) dims = embedding.length;
-    if (embedding.length !== dims)
-      throw new AiError('AI0003', `input ${i} received ${embedding.length} dimensions, expected ${dims}`);
-    out[i] = verifyEmbeddingComponents(embedding, `input ${i} received`);
-  }
-  return out;
+    const data = payload?.data;
+    if (!Array.isArray(data))
+        throw new AiError('AI0003', 'malformed embeddings reply: no data[] in the response');
+    if (data.length !== count)
+        throw new AiError('AI0003', `embeddings reply carried ${data.length} items for ${count} inputs`);
+    const slots = new Array(count);
+    for (let i = 0; i < count; i++) {
+        const item = data[i];
+        const index = item?.index;
+        if (!Number.isInteger(index) || index < 0 || index >= count)
+            throw new AiError('AI0003', `embeddings reply item ${i} carries no usable index for ${count} inputs (got ${JSON.stringify(index)})`);
+        if (slots[index] !== undefined)
+            throw new AiError('AI0003', `input ${index} received two embeddings`);
+        slots[index] = item.embedding;
+    }
+    // `count` items over `count` distinct indices: every slot is filled
+    const out = new Array(count);
+    for (let i = 0; i < count; i++) {
+        const embedding = slots[i];
+        if (!Array.isArray(embedding) || embedding.length === 0)
+            throw new AiError('AI0003', `input ${i} received an empty embedding`);
+        if (dims === undefined)
+            dims = embedding.length;
+        if (embedding.length !== dims)
+            throw new AiError('AI0003', `input ${i} received ${embedding.length} dimensions, expected ${dims}`);
+        out[i] = verifyEmbeddingComponents(embedding, `input ${i} received`);
+    }
+    return out;
 }
-
 /**
  * Probe the embeddings wire before relying on it: can this key/URL/model
  * embed at all, and at what width? Embeds one word with exactly the
@@ -277,43 +202,37 @@ function reassemble(payload, count, dims) {
  * (default 5 000, as `probeProvider`). Never throws — the result object
  * is the settings-UI contract, and the live proof that a provider
  * really serves `/embeddings` beside `/chat/completions`.
- * @param {{ provider?: string, baseUrl?: string, apiKey?: string,
- *   model?: string, dims?: number, headers?: Record<string, string>,
- *   fetch?: typeof fetch, timeoutMs?: number }} [options]
- * @returns {Promise<{ ok: true, model: string, dims: number } |
- *   { ok: false, status?: number, error: string }>}
+ * @param [options]
  */
 export async function probeEmbeddings(options = {}) {
-  /** @type {ReturnType<typeof createEmbeddingClient>} */
-  let client;
-  try {
-    // never through a cache: a probe's job is to prove the wire answers today
-    client = createEmbeddingClient({
-      ...options,
-      cache: undefined,
-      retry: { attempts: 1 },
-      timeoutMs: options.timeoutMs ?? 5000,
-    });
-  }
-  catch (err) {
-    return { ok: false, error: /** @type {Error} */ (err).message };
-  }
-  try {
-    const [vector] = await client.embed(['probe']);
-    return { ok: true, model: client.model, dims: vector.length };
-  }
-  catch (err) {
-    const status = err instanceof AiError && typeof err.status === 'number' && err.status > 0
-      ? err.status
-      : undefined;
-    return {
-      ok: false,
-      ...(status === undefined ? {} : { status }),
-      error: /** @type {any} */ (err)?.message ?? String(err),
-    };
-  }
+    let client;
+    try {
+        // never through a cache: a probe's job is to prove the wire answers today
+        client = createEmbeddingClient({
+            ...options,
+            cache: undefined,
+            retry: { attempts: 1 },
+            timeoutMs: options.timeoutMs ?? 5000,
+        });
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+    try {
+        const [vector] = await client.embed(['probe']);
+        return { ok: true, model: client.model, dims: vector.length };
+    }
+    catch (err) {
+        const status = err instanceof AiError && typeof err.status === 'number' && err.status > 0
+            ? err.status
+            : undefined;
+        return {
+            ok: false,
+            ...(status === undefined ? {} : { status }),
+            error: err?.message ?? String(err),
+        };
+    }
 }
-
 /**
  * The deterministic reference embedder — demo-grade, for tests and
  * offline demos. Each text becomes the bag of its case-folded character
@@ -325,38 +244,34 @@ export async function probeEmbeddings(options = {}) {
  * thing — so it exercises retrieval mechanics (does the right memory
  * reach the prompt?) without saying anything about embedding quality,
  * which belongs to a real model behind the same seam.
- * @param {{ dims?: number }} [options] - the width (default 64); the
+ * @param [options] - the width (default 64); the
  *   identity is `hash-trigram-<dims>`, so two widths never mix
- * @returns {Embedder & { dims: number }}
  */
 export function createHashEmbedder(options = {}) {
-  const dims = options.dims ?? 64;
-  if (!(Number.isInteger(dims) && dims > 0))
-    throw new AiError('AI0001', `createHashEmbedder needs a positive integer dims, got ${String(dims)}`);
-  const model = `hash-trigram-${dims}`;
-
-  /**
-   * @param {string} text
-   * @returns {Float32Array}
-   */
-  function trigramVector(text) {
-    const counts = new Float32Array(dims);
-    const padded = ` ${text.toLowerCase()} `;
-    for (let i = 0; i + 3 <= padded.length; i++)
-      counts[fnv1a(padded.slice(i, i + 3)) % dims] += 1;
-    // counts is finite and non-empty, so this is never null; a text
-    // without a single trigram stays the zero vector, which scores 0
-    // against everything rather than NaN
-    return /** @type {Float32Array} */ (l2Normalize(counts));
-  }
-
-  return {
-    model,
-    dims,
-    async embed(texts, options = {}) {
-      assertTexts(texts);
-      if (options.signal?.aborted) throw abortError(options.signal);
-      return texts.map(trigramVector);
-    },
-  };
+    const dims = options.dims ?? 64;
+    if (!(Number.isInteger(dims) && dims > 0))
+        throw new AiError('AI0001', `createHashEmbedder needs a positive integer dims, got ${String(dims)}`);
+    const model = `hash-trigram-${dims}`;
+    /**
+     */
+    function trigramVector(text) {
+        const counts = new Float32Array(dims);
+        const padded = ` ${text.toLowerCase()} `;
+        for (let i = 0; i + 3 <= padded.length; i++)
+            counts[fnv1a(padded.slice(i, i + 3)) % dims] += 1;
+        // counts is finite and non-empty, so this is never null; a text
+        // without a single trigram stays the zero vector, which scores 0
+        // against everything rather than NaN
+        return l2Normalize(counts);
+    }
+    return {
+        model,
+        dims,
+        async embed(texts, options = {}) {
+            assertTexts(texts);
+            if (options.signal?.aborted)
+                throw abortError(options.signal);
+            return texts.map(trigramVector);
+        },
+    };
 }

package/src/embedding-vector.d.ts

@@ -1,9 +1,14 @@
+/**
+ * The embeddings wire and replay share one AI0003 conversion policy:
+ * each component must remain finite in the Float32Array the client
+ * returns. Shape and width are checked by the caller, which also
+ * supplies the subject naming the input or stored entry that failed.
+ */
 /**
  * Verify embedding components into a fresh Float32Array, refusing
  * non-numbers, non-finite values and finite numbers that overflow
  * Float32. The source array is never changed.
- * @param {any[]} components - an array whose shape and width were checked
- * @param {string} subject - the subject and verb of a refusal
- * @returns {Float32Array}
+ * @param components - an array whose shape and width were checked
+ * @param subject - the subject and verb of a refusal
  */
-export function verifyEmbeddingComponents(components: any[], subject: string): Float32Array;
+export declare function verifyEmbeddingComponents(components: any[], subject: string): Float32Array;

package/src/embedding-vector.js

@@ -1,30 +1,26 @@
-//@ts-check
 /**
  * The embeddings wire and replay share one AI0003 conversion policy:
  * each component must remain finite in the Float32Array the client
  * returns. Shape and width are checked by the caller, which also
  * supplies the subject naming the input or stored entry that failed.
  */
-
-import { AiError } from './errors.js';
-
+import { AiError } from "./errors.js";
 /**
  * Verify embedding components into a fresh Float32Array, refusing
  * non-numbers, non-finite values and finite numbers that overflow
  * Float32. The source array is never changed.
- * @param {any[]} components - an array whose shape and width were checked
- * @param {string} subject - the subject and verb of a refusal
- * @returns {Float32Array}
+ * @param components - an array whose shape and width were checked
+ * @param subject - the subject and verb of a refusal
  */
 export function verifyEmbeddingComponents(components, subject) {
-  const vector = new Float32Array(components.length);
-  for (let i = 0; i < components.length; i++) {
-    const x = components[i];
-    if (typeof x !== 'number' || !Number.isFinite(x))
-      throw new AiError('AI0003', `${subject} a component that is not a finite number at ${i}`);
-    vector[i] = x;
-    if (!Number.isFinite(vector[i]))
-      throw new AiError('AI0003', `${subject} a component outside the finite Float32 range at ${i}`);
-  }
-  return vector;
+    const vector = new Float32Array(components.length);
+    for (let i = 0; i < components.length; i++) {
+        const x = components[i];
+        if (typeof x !== 'number' || !Number.isFinite(x))
+            throw new AiError('AI0003', `${subject} a component that is not a finite number at ${i}`);
+        vector[i] = x;
+        if (!Number.isFinite(vector[i]))
+            throw new AiError('AI0003', `${subject} a component outside the finite Float32 range at ${i}`);
+    }
+    return vector;
 }

package/src/errors.d.ts

@@ -1,11 +1,32 @@
-export class AiError extends CodedError {
+/**
+ * The model transport error type. Every failure the package itself raises
+ * carries a stable code, like the rest of the suite:
+ *
+ *   AI0001 — invalid configuration or request (caller error)
+ *   AI0002 — the provider answered with an HTTP error status
+ *   AI0003 — the provider answered with a malformed payload
+ *
+ * Tool execution and the agent loop never throw for content-level
+ * problems (an unknown tool, invalid tool input, a tool that throws) —
+ * those come back as `{ error }` results the model can read and
+ * recover from. AiError is reserved for the transport and for misuse.
+ *
+ * Refinement (`refine.ts`) rejects with its own `AI01xx` codes, enumerated
+ * there. They are the same idea one step further out: never thrown, they
+ * travel as records with a pointer, because their reader is a model
+ * repairing its own proposal.
+ */
+import { CodedError } from '@jarenjs/core/errors';
+export declare class AiError extends CodedError {
+    status?: number;
+    attempts?: number;
+    retryAfterMs?: number;
     /**
-     * @param {string} code - stable error code ('AI0001' | 'AI0002' | 'AI0003')
-     * @param {string} reason - The bare reason; `message` is composed as
+     * @param code - stable error code ('AI0001' | 'AI0002' | 'AI0003')
+     * @param reason - The bare reason; `message` is composed as
      *   `${code}: ${reason}` per the coded contract (transport errors
      *   have no document, so there is never a location).
-     * @param {{ status?: number, attempts?: number, retryAfterMs?: number,
-     *   cause?: unknown }} [meta] - transport metadata: the HTTP status
+     * @param [meta] - transport metadata: the HTTP status
      *   (`0` for a network failure before any response), how many tries
      *   the client made, and the provider's `Retry-After` in ms
      */
@@ -15,8 +36,4 @@ export class AiError extends CodedError {
         retryAfterMs?: number;
         cause?: unknown;
     });
-    status: number;
-    attempts: number;
-    retryAfterMs: number;
 }
-import { CodedError } from '@jarenjs/core/errors';