@orkestrel/ollama 0.0.13 → 0.0.14

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

@@ -1,21 +1,44 @@
-import { ContextFormatInterface } from '@orkestrel/agent';
-import { MessageInterface } from '@orkestrel/agent';
+import { ContextFormat } from '@orkestrel/agent';
+import { Message } from '@orkestrel/agent';
 import { ProviderDelta } from '@orkestrel/agent';
 import { ProviderInterface } from '@orkestrel/agent';
 import { ProviderResult } from '@orkestrel/agent';
 import { ProviderStreamOptions } from '@orkestrel/agent';
+import { ThinkSplitterInterface } from '@orkestrel/agent';
 import { TimeoutInterface } from '@orkestrel/timeout';
+import { TokenUsage } from '@orkestrel/budget';
+import { ToolCall } from '@orkestrel/tool';
 import { ToolDefinition } from '@orkestrel/tool';
 
 /**
- * Create a local Ollama inference provider — a {@link ProviderInterface} over the
+ * Builds a provider result 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`). Both calls take an
  * `AbortSignal` to bound the request; a `stream` cancelled mid-flight throws a
  * `ProviderAbortError` carrying the partial result.
  *
@@ -23,12 +46,12 @@ import { ToolDefinition } from '@orkestrel/tool';
  * 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).
+ * 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
+ * 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 two are unrelated despite
  * the shared word. Omitted ⇒ the provider is framing-agnostic (core's built-in defaults).
@@ -40,7 +63,7 @@ import { ToolDefinition } from '@orkestrel/tool';
  * @example
  * ```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 abort = createAbort()
@@ -48,7 +71,7 @@ import { ToolDefinition } from '@orkestrel/tool';
  * ```
  *
  * @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',
@@ -77,50 +100,171 @@ 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
+ * Names 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.
+ *
+ * @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 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 —
+ * Names the per-call deadline in milliseconds 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}.
  *
  * @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 two reasoning carriers 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 two 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 cap, in characters, 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
+ * without limit. `2048` characters is generous enough to carry a
  * useful diagnostic snippet while staying well short of any practical size
  * concern.
  */
 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. Narrow a caught value with
+ * {@link isOllamaHTTPError}.
  *
  * @example
  * ```ts
@@ -134,100 +278,124 @@ 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
+ * (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.
      */
     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
      * 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 ⇒
+     * 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. NOTE:
      * 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
+ *   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,
  *   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.
@@ -244,7 +412,8 @@ export declare interface OllamaOptions {
  *   `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,11 +425,18 @@ 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
+     * 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`
@@ -274,21 +450,21 @@ export declare class OllamaProvider implements ProviderInterface {
      * 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;
+    generate(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
+    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.
+ * 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 `#fetch` itself clears on a failed/aborted request); `combined` is the
+ * (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.
  */
@@ -299,13 +475,33 @@ export declare interface OllamaResponse {
 }
 
 /**
- * The exact `POST /api/chat` request body `OllamaProvider` sends — the internal typed
+ * 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 `#plain` builds (`role` / `content`, plus
+ * `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.
  */
@@ -335,7 +531,7 @@ export declare interface WireChatRequest {
         };
     }>;
     /**
-     * The `/api/chat` structured-output constraint — a JSON-Schema object forwarded
+     * 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`.