@orkestrel/ollama 0.0.13 → 0.0.15

package/dist/src/server/index.d.ts

@@ -1,54 +1,84 @@
-import { ContextFormatInterface } from '@orkestrel/agent';
-import { MessageInterface } from '@orkestrel/agent';
-import { ProviderDelta } from '@orkestrel/agent';
-import { ProviderInterface } from '@orkestrel/agent';
-import { ProviderResult } from '@orkestrel/agent';
-import { ProviderStreamOptions } from '@orkestrel/agent';
-import { TimeoutInterface } from '@orkestrel/timeout';
-import { ToolDefinition } from '@orkestrel/tool';
+import type { ContextFormat } from '@orkestrel/agent';
+import type { Message } from '@orkestrel/agent';
+import type { ProviderDelta } from '@orkestrel/agent';
+import type { ProviderInterface } from '@orkestrel/agent';
+import type { ProviderResult } from '@orkestrel/agent';
+import type { ProviderStreamOptions } from '@orkestrel/agent';
+import type { ThinkSplitterInterface } from '@orkestrel/agent';
+import type { TimeoutInterface } from '@orkestrel/timeout';
+import type { TokenUsage } from '@orkestrel/budget';
+import type { ToolCall } from '@orkestrel/tool';
+import type { ToolDefinition } from '@orkestrel/tool';
 
 /**
- * Create a local Ollama inference provider — a {@link ProviderInterface} over the
+ * Builds a `ProviderResult` from a turn's content, reasoning, tool calls, and usage.
+ *
+ * @remarks
+ * Only the present optionals are set: no empty `thinking`, no empty `tools`, and no
+ * `usage` unless the wire reported one.
+ *
+ * @param content - The clean assistant content the splitter accumulated
+ * @param thinking - The joined reasoning, empty when the turn produced none
+ * @param tools - The tool calls collected across the turn
+ * @param usage - The token usage, or `undefined` when the wire reported none
+ * @returns The result carrying only its populated fields
+ *
+ * @example
+ * ```ts
+ * buildResult('ok', '', [], undefined) // { content: 'ok' }
+ * ```
+ */
+export declare function buildResult(content: string, thinking: string, tools: readonly ToolCall[], usage: TokenUsage | undefined): ProviderResult;
+
+/**
+ * Creates a local Ollama inference provider — a {@link ProviderInterface} over the
  * daemon's `POST /api/chat`, supporting non-streaming `generate` and streaming
  * `stream`.
  *
  * @remarks
  * Only `model` is required; `url` defaults to the local daemon, `keepAlive` to `'5m'`,
  * `timeout` to `120_000`ms, and `options` is forwarded verbatim as sampling
- * parameters (`temperature` / `seed` / `num_predict` / …). Both calls take an
+ * parameters (`temperature`, `seed`, and `num_predict`). Each call takes an
  * `AbortSignal` to bound the request; a `stream` cancelled mid-flight throws a
  * `ProviderAbortError` carrying the partial result.
  *
  * The optional `fetch` + `headers` form a transport seam (see {@link OllamaOptions}):
  * point `url` at your own server, inject a custom `fetch`, and have `headers` attach a
  * generated/obfuscated bearer token your server validates — so a browser runtime
- * reaches the LLM through your middleware WITHOUT this library ever handling the real API
- * key. Both omitted ⇒ today's behaviour (the global `fetch`, only a JSON content type).
+ * reaches the LLM through your middleware without this library ever handling the real API
+ * key. Both omitted ⇒ the global `fetch` and only a JSON content type.
  *
- * The optional `format` is the provider's context-framing default — the PROVIDER-DEFAULT
- * level of `AgentContext`'s format cascade (see [agents.md]; beaten by a manager-options
- * or per-item override, beating the managers' built-in framing), declaring how this
- * provider's models prefer context sections framed (e.g. XML group wrappers vs. Markdown
- * headers). It is EXPOSED on the provider for the Agent's `build()` and is NOT Ollama's
- * `/api/chat` `format` wire parameter (structured output) — the two are unrelated despite
- * the shared word. Omitted ⇒ the provider is framing-agnostic (core's built-in defaults).
+ * The optional `format` is the provider's context-framing default — the provider-default
+ * level of `AgentContext`'s format cascade (beaten by a manager-options or per-item
+ * override, beating the managers' built-in framing), declaring how this
+ * provider's models prefer context sections framed (for example XML group wrappers vs. Markdown
+ * headers). It is exposed on the provider for the Agent's `build()` and is not Ollama's
+ * `/api/chat` `format` wire parameter (structured output) — the framing default and that
+ * wire parameter are unrelated despite the shared word. Omitted ⇒ the provider is
+ * framing-agnostic (core's built-in defaults).
  *
  * @param options - `model` (required), and optional `url` / `keepAlive` / `timeout` /
  *   `options` / `fetch` / `headers` / `format` (see {@link OllamaOptions})
  * @returns A working {@link ProviderInterface} backed by Ollama
  *
- * @example
+ * @example createOllama + generate
  * ```ts
  * import { createAbort } from '@orkestrel/abort'
- * import { createOllama } from '@src/server'
+ * import { createOllama } from '@orkestrel/ollama'
  *
- * const provider = createOllama({ model: 'qwen3.5:2b-q4_K_M' })
+ * const provider = createOllama({ model: 'qwen3.5:2b-q4_K_M', options: { temperature: 0 } })
  * const abort = createAbort()
+ * const messages = [
+ * 	{ id: '1', role: 'user', content: 'Summarize the release notes for version 2.0.' },
+ * ] as const
+ *
  * const result = await provider.generate(messages, abort.signal)
+ * console.log(result.content)
+ * if (result.usage) charge(result.usage) // fold into a token budget
  * ```
  *
  * @example
- * Route through your own server with an obfuscated token (deployment scenario S2):
+ * Route through your own server with an obfuscated token:
  * ```ts
  * const provider = createOllama({
  *   model: 'qwen3.5:2b-q4_K_M',
@@ -60,7 +90,7 @@ import { ToolDefinition } from '@orkestrel/tool';
  *
  * @example
  * Declare a context-framing default — wrap the instructions section in an XML group (the
- * provider-default level of `AgentContext`'s cascade; NOT the wire `format`):
+ * provider-default level of `AgentContext`'s cascade; not the wire `format`):
  * ```ts
  * const provider = createOllama({
  *   model: 'qwen3.5:2b-q4_K_M',
@@ -77,50 +107,180 @@ import { ToolDefinition } from '@orkestrel/tool';
 export declare function createOllama(options: OllamaOptions): ProviderInterface;
 
 /**
- * How long the model stays resident after a call when `OllamaOptions.keepAlive` is
- * omitted — Ollama's own `keep_alive` default, expressed as a duration string.
+ * Names how long the model stays resident after a call — `'5m'` when
+ * `OllamaOptions.keepAlive` is omitted, Ollama's own `keep_alive` default, expressed as a
+ * duration string.
+ *
+ * @remarks
+ * The name mirrors the Ollama `/api/chat` `keep_alive` field this value is sent as, so
+ * the constant, the `OllamaOptions.keepAlive` key, and the wire member read as one term.
  */
 export declare const DEFAULT_KEEP_ALIVE = "5m";
 
-/** The local Ollama daemon base URL assumed when `OllamaOptions.url` is omitted. */
+/**
+ * Names the local Ollama daemon base URL, `'http://localhost:11434'`, assumed when
+ * `OllamaOptions.url` is omitted.
+ */
 export declare const DEFAULT_OLLAMA_URL = "http://localhost:11434";
 
 /**
- * The per-call deadline in milliseconds when `OllamaOptions.timeout` is omitted —
- * generous enough that a cold model load does not trip it.
+ * Names the per-call deadline in milliseconds, `120_000`, when `OllamaOptions.timeout` is
+ * omitted — generous enough that a cold model load does not trip it.
  */
 export declare const DEFAULT_PROVIDER_TIMEOUT = 120000;
 
 /**
- * Whether a value is an {@link OllamaHTTPError}.
+ * Extracts a wire `arguments` value as a record.
+ *
+ * @remarks
+ * Total: an object passes through, a JSON string is parsed when it yields a record, and
+ * a malformed string yields `{}` rather than throwing.
+ *
+ * @param value - The wire's `function.arguments` value, of unknown shape
+ * @returns The argument record, or `{}` when the value carries none
+ *
+ * @example
+ * ```ts
+ * extractArguments('{"city":"Oslo"}') // { city: 'Oslo' }
+ * ```
+ */
+export declare function extractArguments(value: unknown): Readonly<Record<string, unknown>>;
+
+/**
+ * Extracts the assistant text of one wire record.
+ *
+ * @param record - One parsed `/api/chat` record — a non-stream body or an NDJSON line
+ * @returns The record's `message.content` when it is a string, else `''`
+ *
+ * @example
+ * ```ts
+ * extractContent({ message: { content: 'ok' } }) // 'ok'
+ * ```
+ */
+export declare function extractContent(record: Readonly<Record<string, unknown>>): string;
+
+/**
+ * Extracts the daemon-side reasoning of one wire record.
+ *
+ * @remarks
+ * `message.thinking` is the `think: true` wire shape. It is read whatever the configured
+ * flag says, because a daemon may separate reasoning on its own.
+ *
+ * @param record - One parsed `/api/chat` record — a non-stream body or an NDJSON line
+ * @returns The record's `message.thinking` when it is a string, else `''`
+ *
+ * @example
+ * ```ts
+ * extractThinking({ message: { thinking: 'weighing it' } }) // 'weighing it'
+ * ```
+ */
+export declare function extractThinking(record: Readonly<Record<string, unknown>>): string;
+
+/**
+ * Extracts the tool calls of one wire record's `message.tool_calls`.
+ *
+ * @remarks
+ * Each entry narrows to `{ id, name, arguments }`: the entry and its `function` must be
+ * records and `name` a string, else the entry is dropped. An id is minted when the wire
+ * omits one.
+ *
+ * @param record - One parsed `/api/chat` record — a non-stream body or an NDJSON line
+ * @returns The narrowed tool calls, empty when the record carries none
+ *
+ * @example
+ * ```ts
+ * extractTools({ message: { tool_calls: [{ function: { name: 'weather' } }] } })
+ * // [{ id: '…', name: 'weather', arguments: {} }]
+ * ```
+ */
+export declare function extractTools(record: Readonly<Record<string, unknown>>): readonly ToolCall[];
+
+/**
+ * Extracts the token usage of one wire record.
+ *
+ * @remarks
+ * Both counts must be numbers, which is true of the non-stream body and the stream's
+ * `done: true` line. A delta line carries neither, so it yields `undefined`.
+ *
+ * @param record - One parsed `/api/chat` record — a non-stream body or an NDJSON line
+ * @returns The `TokenUsage` shape, or `undefined` when either count is absent
+ *
+ * @example
+ * ```ts
+ * extractUsage({ prompt_eval_count: 3, eval_count: 4 })
+ * // { prompt: 3, completion: 4, total: 7 }
+ * ```
+ */
+export declare function extractUsage(record: Readonly<Record<string, unknown>>): TokenUsage | undefined;
+
+/**
+ * Checks whether a value is an {@link OllamaHTTPError}.
+ *
+ * @remarks
+ * The check is an `instanceof` test, so it narrows a caught `unknown` to the error class
+ * without parsing the thrown message.
  *
  * @param value - The value to test
- * @returns `true` when `value` is an `OllamaHTTPError`
+ * @returns True if `value` is an `OllamaHTTPError`; false otherwise
  */
 export declare function isOllamaHTTPError(value: unknown): value is OllamaHTTPError;
 
 /**
- * The cap, in characters, on how much of a non-OK response body is
+ * Joins a call's reasoning carriers — the splitter's separated in-content spans and the
+ * accumulated wire-side `message.thinking` — into the result's `thinking`.
+ *
+ * @param splitter - The per-call splitter holding the separated in-content spans
+ * @param wired - The accumulated wire-side `message.thinking` text
+ * @returns The carriers separated by a blank line, or whichever one is non-empty
+ *
+ * @example
+ * ```ts
+ * joinThinking(createThinkSplitter(), 'from the wire') // 'from the wire'
+ * ```
+ */
+export declare function joinThinking(splitter: ThinkSplitterInterface, wired: string): string;
+
+/**
+ * Maps conversation turns onto the `/api/chat` wire's minimal message shape.
+ *
+ * @remarks
+ * `tool_calls` is emitted only on a turn that replays them and `images` only on a
+ * multimodal turn, so an empty optional never reaches the wire.
+ *
+ * @param messages - The conversation turns to send
+ * @returns The wire `messages` array, one entry per turn, in order
+ *
+ * @example
+ * ```ts
+ * mapMessages([{ id: '1', role: 'user', content: 'Say hello.' }])
+ * // [{ role: 'user', content: 'Say hello.' }]
+ * ```
+ */
+export declare function mapMessages(messages: readonly Message[]): WireChatRequest['messages'];
+
+/**
+ * Names the character cap, `2048`, on how much of a non-OK response body is
  * incorporated into a thrown {@link OllamaHTTPError}'s message.
  *
  * @remarks
  * Bounds the excerpt so a defensive proxy or a misbehaving daemon handing
  * back an unbounded response body cannot inflate the thrown error's message
- * without limit (§14). `2048` characters is generous enough to carry a
- * useful diagnostic snippet while staying well short of any practical size
- * concern.
+ * without limit, while the cap stays generous enough to carry a useful
+ * diagnostic snippet.
  */
 export declare const MAX_ERROR_BODY_LENGTH = 2048;
 
 /**
- * An error thrown when the Ollama `/api/chat` HTTP transport fails.
+ * Represents an error thrown when the Ollama `/api/chat` HTTP transport fails.
  *
  * @remarks
- * Carries the response `status` (0 when no HTTP response was received at all,
- * e.g. a `null` body). Thrown by {@link OllamaProvider} at its two HTTP
- * failure sites — the non-OK status branch and the null-body branch — so a
- * caller can branch on `error.status` instead of parsing the message. Narrow
- * a caught value with {@link isOllamaHTTPError}.
+ * Carries the machine-readable `code` `'HTTP'` and the response `status` (0 when no
+ * HTTP response was received at all, for example a `null` body). Thrown by
+ * {@link OllamaProvider} at its HTTP failure sites — the non-OK status branch and the
+ * null-body branch — so a caller can branch on `error.code` and read `error.status`
+ * for the HTTP number instead of parsing the message. The message carries a body excerpt
+ * bounded to {@link MAX_ERROR_BODY_LENGTH} — `2048` characters. Narrow a caught value with
+ * {@link isOllamaHTTPError}.
  *
  * @example
  * ```ts
@@ -134,117 +294,142 @@ export declare const MAX_ERROR_BODY_LENGTH = 2048;
  * ```
  */
 export declare class OllamaHTTPError extends Error {
+    /**
+     * Names the machine-readable condition this error reports — `'HTTP'`: an `/api/chat`
+     * transport, status, or body failure.
+     */
+    readonly code: "HTTP";
     readonly status: number;
-    constructor(message: string, status: number, options?: {
-        readonly cause?: unknown;
-    });
+    constructor(message: string, status: number, options?: OllamaHTTPErrorOptions);
 }
 
 /**
- * Options for `createOllama` — the local Ollama backend's configuration.
+ * Represents the options a thrown {@link OllamaHTTPError} accepts beside its message and status —
+ * the standard error `cause` link, named so a consumer can reference the shape.
+ *
+ * @remarks
+ * `cause` is the underlying value that produced the HTTP failure: the transport or
+ * body-read rejection the provider caught before rethrowing. It is `unknown` because a
+ * thrown value is unconstrained. Omitted ⇒ the error carries no cause.
+ */
+export declare interface OllamaHTTPErrorOptions {
+    readonly cause?: unknown;
+}
+
+/**
+ * Represents the configuration `createOllama` accepts for the local Ollama backend.
  *
  * @remarks
  * Only `model` is required. `url` defaults to the local daemon, `keepAlive` controls
  * how long the model stays resident after a call, `timeout` is the per-call deadline
  * in milliseconds, and `options` is a passthrough bag of sampling parameters
- * (`temperature` / `seed` / `num_predict` / …) forwarded verbatim to the wire.
+ * (`temperature`, `seed`, and `num_predict`) forwarded verbatim to the wire.
  *
  * The optional `fetch` + `headers` form a **transport seam**: by default the provider
  * talks straight to a local daemon over `globalThis.fetch` with only a JSON content
- * type, but a browser-side runtime can inject a custom transport AND a dynamic header
- * (e.g. an obfuscated bearer token) so requests route through the developer's OWN
+ * type, but a browser-side runtime can inject both a custom transport and a dynamic header
+ * (for example an obfuscated bearer token) so requests route through the developer's own
  * server, which validates that header and forwards to the real LLM. Your app never
  * holds a real API key — the real key lives only on the developer's server; the
  * `headers` hook supplies whatever short-lived/obfuscated token that server expects.
  */
 export declare interface OllamaOptions {
     readonly model: string;
-    /** The daemon base URL; defaults to `'http://localhost:11434'`. */
+    /** Sets the daemon base URL; defaults to `'http://localhost:11434'`. */
     readonly url?: string;
-    /** How long the model stays resident after a call; defaults to `'5m'`. */
+    /**
+     * Sets how long the model stays resident after a call; defaults to `'5m'`. Mirrors the
+     * Ollama `/api/chat` `keep_alive` field, whose value this key carries verbatim onto
+     * {@link WireChatRequest.keep_alive}.
+     */
     readonly keepAlive?: string | number;
-    /** The per-call deadline in milliseconds; defaults to `120_000`. */
+    /** Sets the per-call deadline in milliseconds; defaults to `120_000`. */
     readonly timeout?: number;
-    /** Passthrough sampling options (`temperature` / `seed` / `num_predict` / …). */
+    /**
+     * Carries passthrough sampling parameters (`temperature`, `seed`, and `num_predict`).
+     * Mirrors the Ollama `/api/chat` `options` field, whose value this key carries verbatim
+     * onto {@link WireChatRequest.options}.
+     */
     readonly options?: Readonly<Record<string, unknown>>;
     /**
-     * The `/api/chat` `think` wire flag; defaults to `false`. When `true`, a thinking-capable
-     * model (e.g. `qwen3`) separates its reasoning NATIVELY at the wire — the daemon returns it
+     * Sets the `/api/chat` `think` wire flag; defaults to `false`. When `true`, a thinking-capable
+     * model (for example `qwen3`) separates its reasoning natively at the wire — the daemon returns it
      * on the distinct `message.thinking` channel (surfaced on `ProviderResult.thinking`) rather
-     * than inline in `message.content`. The default stays `false` so a general-purpose provider
-     * is backward-compatible and immediate for non-thinking models; the per-call ThinkSplitter
+     * than inline in `message.content`. The default is `false`, so a non-thinking model needs no
+     * configuration and answers immediately; the per-call ThinkSplitter
      * remains the defensive fallback for daemons/models that still inline `<think>` tags either
-     * way. Set it `true` for a thinking model whose reasoning you intend to DISPLAY separately.
+     * way. Set it `true` for a thinking model whose reasoning you intend to display separately.
      */
     readonly think?: boolean;
     /**
-     * A custom `fetch` implementation for every request; defaults to
+     * Sets a custom `fetch` implementation for every request; defaults to
      * `globalThis.fetch`. Lets a runtime inject its own transport (a browser fetch
-     * pointed at the developer's server, an instrumented wrapper, …) without changing
+     * pointed at the developer's server, an instrumented wrapper) without changing
      * the wire protocol. Omitted ⇒ the global `fetch`.
      */
     readonly fetch?: typeof globalThis.fetch;
     /**
-     * A dynamic, possibly-async header injector called once per request; its returned
+     * Sets a dynamic, possibly-async header injector called once per request; its returned
      * headers are merged into the request on top of the base `Content-Type`. Use it to
-     * attach an authorization header — e.g. an obfuscated/generated bearer token the
+     * attach an authorization header — for example an obfuscated/generated bearer token the
      * developer's server validates before relaying to the real LLM — so a browser
-     * runtime can authenticate WITHOUT your app ever handling a real API key. Async so a
+     * runtime can authenticate without your app ever handling a real API key. Async so a
      * token can be refreshed/fetched per call. A returned `Content-Type` overrides the
      * default; other headers add to it. Omitted ⇒ only `Content-Type: application/json`.
      */
-    readonly headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    readonly headers?: () => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
     /**
-     * The provider's OPTIONAL context-framing default — the PROVIDER-DEFAULT level of
+     * Sets the provider's optional context-framing default — the provider-default level of
      * `AgentContext`'s format cascade (beaten by a manager-options or per-item override,
      * beating the managers' built-in framing). Declares how this provider's models prefer
-     * context sections framed (e.g. XML group wrappers vs. Markdown headers). Omitted ⇒
-     * the provider is framing-agnostic and core's built-in defaults apply unchanged. NOTE:
-     * this is the prompt-CONTEXT framing consumed by `AgentContext.build()` — it is NOT
+     * context sections framed (for example XML group wrappers vs. Markdown headers). Omitted ⇒
+     * the provider is framing-agnostic and core's built-in defaults apply unchanged. This
+     * is the prompt-context framing consumed by `AgentContext.build()` — it is not
      * Ollama's `/api/chat` `format` wire parameter (structured-output / JSON schema),
-     * which this provider does not currently send; the two are unrelated despite the
-     * shared word.
+     * which this provider sends only when a call supplies a `schema`; the two are unrelated
+     * despite the shared word.
      */
-    readonly format?: ContextFormatInterface;
+    readonly format?: ContextFormat;
 }
 
 /**
- * The local Ollama inference boundary — a {@link ProviderInterface} over Ollama's
+ * Implements the local Ollama inference boundary — a {@link ProviderInterface} over Ollama's
  * `POST /api/chat`, both non-streaming (`generate`) and streaming NDJSON (`stream`).
  *
  * @remarks
  * - **Wire protocol.** Posts `{ model, messages, stream, keep_alive, think }` plus
  *   passthrough sampling `options` and mapped function `tools`. The `think` flag is
- *   CONFIGURABLE via {@link OllamaOptions.think} (default `false`). Non-stream parses
+ *   configurable through {@link OllamaOptions.think} (default `false`). Non-stream parses
  *   one JSON body; stream consumes NDJSON (one JSON object per `\n`-terminated line) —
  *   deltas carry `message.content`, the final `done: true` line carries the token usage.
- * - **Think separation (H4).** The wire `think` flag is configurable
+ * - **Think separation.** The wire `think` flag is configurable
  *   ({@link OllamaOptions.think}, default `false`). With `think: true` a thinking model's
- *   daemon separates reasoning NATIVELY — returning it on the distinct `message.thinking`
- *   channel (read here via `#thinking`) instead of inline in `message.content`. EITHER
+ *   daemon separates reasoning natively — returning it on the distinct `message.thinking`
+ *   channel (read here through `extractThinking`) instead of inline in `message.content`. Either
  *   way the per-call {@link ThinkSplitterInterface} is the defensive guarantee: a daemon
  *   may ignore `think: false` for a thinking model and inline `<think>` tags, so every
- *   content delta routes through the splitter, only CLEAN content is yielded / assembled,
+ *   content delta routes through the splitter, only clean content is yielded / assembled,
  *   and the separated reasoning (plus any daemon-side `message.thinking` deltas) lands on
  *   `ProviderResult.thinking`, never in the conversation.
- * - **Boundary narrowing (§14).** Every wire value arrives as `unknown` and is
+ * - **Boundary narrowing.** Every wire value arrives as `unknown` and is
  *   narrowed through guards (`isRecord` / `isString` / `isNumber`) — never `as`. A
  *   missing / malformed field degrades to a sensible default (empty content, no
  *   usage, `{}` arguments), never a throw.
  * - **Bounded.** Each call arms a {@link Timeout} for `OllamaOptions.timeout` and
  *   passes `AbortSignal.any([timeout.signal, signal])` to `fetch`, so the caller's
- *   signal AND the deadline both cancel the request. The timeout is always cleared —
+ *   signal and the deadline both cancel the request. The timeout is always cleared —
  *   in `#fetch` if the request fails/aborts, otherwise in the consuming call's `finally`.
  * - **Abort recovers partial.** A `stream` cancelled mid-flight throws a
  *   `ProviderAbortError` carrying the partial result assembled so far; pairing the
- *   `TextDecoder({ stream: true })` with the {@link NDJSONParser} parser keeps multi-byte
+ *   `TextDecoder({ stream: true })` with the `createNDJSONParser` parser keeps multi-byte
  *   UTF-8 splits and partial lines honest.
  * - **Event-free.** A pure functional boundary — no Emitter, no events.
  * - **Transport seam.** {@link OllamaOptions.fetch} swaps the transport (default
  *   `globalThis.fetch`) and {@link OllamaOptions.headers} is a per-request, possibly
  *   async header injector merged over the base `Content-Type` — so a browser runtime
  *   can route through the developer's own server with an obfuscated bearer token,
- *   without this library ever handling a real API key. Both omitted ⇒ today's behaviour.
+ *   without this library ever handling a real API key. Both omitted ⇒ the global `fetch`
+ *   and only a JSON content type.
  *   Orthogonal to the deadline: the hook is awaited inside `#fetch`'s try, so a hook
  *   rejection clears the armed timer like any other request failure.
  *
@@ -256,91 +441,157 @@ export declare interface OllamaOptions {
  */
 export declare class OllamaProvider implements ProviderInterface {
     #private;
-    readonly id: `${string}-${string}-${string}-${string}-${string}`;
     readonly name = "ollama";
     constructor(options: OllamaOptions);
     /**
-     * The provider's context-framing default — the PROVIDER-DEFAULT level of
-     * {@link import('@orkestrel/agent').AgentContextInterface.build}'s format cascade (it BEATS
-     * the managers' built-in framing, is BEATEN by a manager-options or per-item override).
-     * Satisfies the OPTIONAL {@link ProviderInterface.format} contract member: `undefined`
+     * Exposes this instance's identity — a fresh `crypto.randomUUID()` minted at
+     * construction, satisfying the {@link ProviderInterface.id} contract member. A second
+     * provider built from identical options carries a distinct id.
+     *
+     * @returns The instance's minted identifier
+     */
+    get id(): string;
+    /**
+     * Exposes the provider's context-framing default — the provider-default level of
+     * {@link import('@orkestrel/agent').AgentContextInterface.build}'s format cascade (it beats
+     * the managers' built-in framing, is beaten by a manager-options or per-item override).
+     * Satisfies the optional {@link ProviderInterface.format} contract member: `undefined`
      * when {@link OllamaOptions.format} was omitted (the framing-agnostic default ⇒ core's
      * built-in framing applies unchanged), else the exact configured framing the Agent
      * threads into `build()`.
      *
      * @remarks
-     * EXPOSE-ONLY — read by the Agent loop and consumed by core's cascade; it is NEVER sent
-     * on the `/api/chat` wire (it is absent from `#body` / the request). This is NOT Ollama's
-     * structured-output `format` wire parameter — that one IS sent in `#body`, but only when
+     * Expose-only — read by the Agent loop and consumed by core's cascade; it is never sent
+     * on the `/api/chat` wire (it is absent from `#body` / the request). This is not Ollama's
+     * structured-output `format` wire parameter — that one is sent in `#body`, but only when
      * a per-call `ProviderStreamOptions.schema` is supplied; only the word collides.
      *
-     * @returns The configured {@link ContextFormatInterface}, or `undefined` when none
+     * @returns The configured {@link ContextFormat}, or `undefined` when none
      */
-    get format(): ContextFormatInterface | undefined;
-    generate(messages: readonly MessageInterface[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
-    stream(messages: readonly MessageInterface[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
-}
+    get format(): ContextFormat | undefined;
+    /**
+     * Generates one complete turn and resolves the assembled result — the clean content,
+     * any separated reasoning, any tool calls, and any usage the wire reported.
+     *
+     * @remarks
+     * Sends `stream: false` and parses one JSON body. Content routes through a per-call
+     * think splitter, so the assembled content stays clean even where the daemon renders a
+     * thinking model's reasoning inline; the separated spans and any daemon-side
+     * `message.thinking` land on `thinking`. The caller's signal and the armed deadline
+     * both cancel the request, and the deadline is cleared once the body is read.
+     *
+     * @param messages - The conversation turns to send
+     * @param signal - The caller's bounding signal, folded with the armed deadline
+     * @param tools - The callable tools to advertise for this turn, when the caller passes any
+     * @param options - The per-call overrides, `think` and `schema` among them
+     * @returns The assembled result of the turn
+     * @throws {@link OllamaHTTPError} When the daemon answers a non-OK status.
+         */
+     generate(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
+     /**
+      * Streams one turn, yielding a channel-tagged delta per non-empty content or reasoning
+      * span and returning the assembled result when the stream completes.
+      *
+      * @remarks
+      * Sends `stream: true` and consumes NDJSON — one JSON object per newline-terminated
+      * line — pairing a streaming `TextDecoder` with the `NDJSONParser` so a record split
+      * across byte reads is reassembled. The returned result's content is the splitter's
+      * clean accumulation, beside any tool calls collected across lines and the usage the
+      * `done` line carries. A cancel mid-flight throws a `ProviderAbortError` carrying the
+      * partial assembled so far.
+      *
+      * @param messages - The conversation turns to send
+      * @param signal - The caller's bounding signal, folded with the armed deadline
+      * @param tools - The callable tools to advertise for this turn, when the caller passes any
+      * @param options - The per-call overrides, `think` and `schema` among them
+      * @returns The assembled result of the turn, after the last delta
+      * @throws {@link OllamaHTTPError} When the daemon answers a non-OK status or a `null` body.
+          */
+      stream(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
+     }
 
-/**
- * A live `fetch` to `/api/chat` with the deadline + combined signal that bound it —
- * the internal wire-shape `OllamaProvider.#fetch` hands back to a consuming call.
- *
- * @remarks
- * The `response` is the open `POST /api/chat` `Response`; `timeout` is the armed
- * {@link TimeoutInterface} the consuming call clears once it finishes reading the body
- * (or that `#fetch` itself clears on a failed/aborted request); `combined` is the
- * `AbortSignal.any([timeout.signal, callerSignal])` the request was issued under, which
- * the streaming path checks to tell a mid-stream cancel apart from any other error.
- */
-export declare interface OllamaResponse {
-    readonly response: Response;
-    readonly timeout: TimeoutInterface;
-    readonly combined: AbortSignal;
-}
+     /**
+      * Represents an open `POST /api/chat` response together with the deadline and the
+      * combined signal that bound the request.
+      *
+      * @remarks
+      * The `response` is the open `POST /api/chat` `Response`; `timeout` is the armed
+      * {@link TimeoutInterface} the consuming call clears once it finishes reading the body
+      * (or that the provider clears on a failed or aborted request); `combined` is the
+      * `AbortSignal.any([timeout.signal, callerSignal])` the request was issued under, which
+      * the streaming path checks to tell a mid-stream cancel apart from any other error.
+      */
+     export declare interface OllamaResponse {
+         readonly response: Response;
+         readonly timeout: TimeoutInterface;
+         readonly combined: AbortSignal;
+     }
 
-/**
- * The exact `POST /api/chat` request body `OllamaProvider` sends — the internal typed
- * wire contract.
- *
- * @remarks
- * This is the typed wire shape asserted against the official `ollama` client's
- * `ChatRequest` by the compile-time parity test; `src/` never imports `ollama` itself.
- * `messages` mirrors the minimal turn shape `#plain` builds (`role` / `content`, plus
- * `tool_calls` only on a turn that replays them and `images` only on a multimodal
- * turn); `options` and `tools` are only present when configured.
- */
-export declare interface WireChatRequest {
-    readonly model: string;
-    readonly messages: ReadonlyArray<{
-        readonly role: string;
-        readonly content: string;
-        readonly tool_calls?: ReadonlyArray<{
-            readonly function: {
-                readonly name: string;
-                readonly arguments: Readonly<Record<string, unknown>>;
-            };
-        }>;
-        readonly images?: readonly string[];
-    }>;
-    readonly stream: boolean;
-    readonly keep_alive: string | number;
-    readonly think: boolean;
-    readonly options?: Readonly<Record<string, unknown>>;
-    readonly tools?: ReadonlyArray<{
-        readonly type: 'function';
-        readonly function: {
-            readonly name: string;
-            readonly description?: string;
-            readonly parameters?: Readonly<Record<string, unknown>>;
-        };
-    }>;
-    /**
-     * The `/api/chat` structured-output constraint — a JSON-Schema object forwarded
-     * verbatim from the per-call `ProviderStreamOptions.schema`. This is NOT
-     * `OllamaOptions.format` (the unrelated prompt-context framing); only present
-     * when a call supplies a `schema`.
-     */
-    readonly format?: Readonly<Record<string, unknown>>;
-}
+     /**
+      * Parses a non-stream `/api/chat` response body into a wire record.
+      *
+      * @remarks
+      * Total by construction: an empty body, a body that is not JSON, and a body whose JSON is
+      * not an object all yield `undefined`, so a malformed daemon response never escapes as a
+      * `SyntaxError`. The call site supplies the empty-record default that reads as empty
+      * content and no usage.
+      *
+      * @param response - The 200-OK `/api/chat` response whose body is read as text
+      * @returns The parsed record, or `undefined` when the body is empty or malformed
+      *
+      * @example
+      * ```ts
+      * await parseBody(new Response('{"message":{"content":"ok"}}'))
+      * // { message: { content: 'ok' } }
+      * ```
+      */
+     export declare function parseBody(response: Response): Promise<Readonly<Record<string, unknown>> | undefined>;
+
+     /**
+      * Represents the exact `POST /api/chat` request body `OllamaProvider` sends — the internal typed
+      * wire contract.
+      *
+      * @remarks
+      * This is the typed wire shape asserted against the official `ollama` client's
+      * `ChatRequest` by the compile-time parity test; `src/` never imports `ollama` itself.
+      * `messages` mirrors the minimal turn shape `mapMessages` builds (`role` / `content`, plus
+      * `tool_calls` only on a turn that replays them and `images` only on a multimodal
+      * turn); `options` and `tools` are only present when configured. `format` carries the
+      * `/api/chat` structured-output constraint, forwarded verbatim from the per-call
+      * `ProviderStreamOptions.schema` and absent when no schema is supplied.
+      */
+     export declare interface WireChatRequest {
+         readonly model: string;
+         readonly messages: ReadonlyArray<{
+             readonly role: string;
+             readonly content: string;
+             readonly tool_calls?: ReadonlyArray<{
+                 readonly function: {
+                     readonly name: string;
+                     readonly arguments: Readonly<Record<string, unknown>>;
+                 };
+             }>;
+             readonly images?: readonly string[];
+         }>;
+         readonly stream: boolean;
+         readonly keep_alive: string | number;
+         readonly think: boolean;
+         readonly options?: Readonly<Record<string, unknown>>;
+         readonly tools?: ReadonlyArray<{
+             readonly type: 'function';
+             readonly function: {
+                 readonly name: string;
+                 readonly description?: string;
+                 readonly parameters?: Readonly<Record<string, unknown>>;
+             };
+         }>;
+         /**
+          * Holds the `/api/chat` structured-output constraint — a JSON-Schema object forwarded
+          * verbatim from the per-call `ProviderStreamOptions.schema`. This is not
+          * `OllamaOptions.format` (the unrelated prompt-context framing); only present
+          * when a call supplies a `schema`.
+          */
+         readonly format?: Readonly<Record<string, unknown>>;
+     }
 
-export { }
+     export { }