@nemesis-oss/ollama-sdk 1.13.0 → 1.14.0

package/dist/testing.d.cts

@@ -0,0 +1,336 @@
+/**
+ * In-memory Ollama mock server for deterministic, zero-network CI testing.
+ *
+ * This is the SDK's own mock engine, promoted from the internal test fixture
+ * (`test/mocks/ollama-mock-server.ts`) to a public entry point
+ * (`@nemesis-oss/ollama-sdk/testing`) so consumers don't have to hand-roll
+ * ad-hoc HTTP stubs to test their Ollama integrations — see ADR 0029.
+ * The internal fixture re-exports this module, so the SDK's own test suite
+ * exercises the exact same code consumers get.
+ *
+ * The VCR cassette system (`test/vcr.ts` in the repo) replays recorded HTTP
+ * interactions, but cassettes are static. This mock server covers what
+ * cassettes can't:
+ *
+ *   - programmable inter-chunk delays (backpressure handling)
+ *   - mid-stream **in-band error injection** — an `{"error": "..."}` NDJSON
+ *     frame emitted mid-response with HTTP 200 still, exactly how a real
+ *     Ollama daemon reports GPU OOM / driver crashes mid-generation
+ *   - connection drops mid-stream (`dropConnectionMidStream`)
+ *   - 503/502/429 error status codes with custom bodies
+ *   - arbitrary NDJSON chunk payloads (tool calls, thinking, partial frames)
+ *
+ * On top of the raw engine, the public surface adds the conveniences a
+ * consumer test suite wants on day one:
+ *
+ *   - {@link createMockOllamaServer} factory (the recommended entry point)
+ *   - built-in **default routes** — the official liveness probe (`HEAD /`
+ *     and `GET /` → "Ollama is running") and `GET /api/version` — so
+ *     `client.ping()` and friends work before any route is registered.
+ *     Explicit `register()` calls always win.
+ *   - **request recording** (`server.requests`, `clearRequests()`) for
+ *     wire-level assertions without per-route callbacks
+ *   - NDJSON **chunk builders** ({@link mockChatChunk}, {@link mockTextChunks},
+ *     {@link mockToolCallChunks}) that produce correctly-shaped `/api/chat`
+ *     frames — including parallel tool calls in one frame, the documented
+ *     native behavior
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createMockOllamaServer, mockToolCallChunks } from '@nemesis-oss/ollama-sdk/testing';
+ * import { OllamaClient } from '@nemesis-oss/ollama-sdk';
+ *
+ * const server = createMockOllamaServer(); // ephemeral port, default routes on
+ * await server.start();
+ *
+ * server.register('/api/chat', {
+ *   chunks: mockToolCallChunks([
+ *     { name: 'get_weather', arguments: { city: 'Tokyo' } },
+ *     { name: 'get_time', arguments: { tz: 'Asia/Tokyo' } },
+ *   ]),
+ * });
+ *
+ * const client = new OllamaClient({ baseUrl: server.baseUrl });
+ * // ... exercise the client; assert on server.requests ...
+ *
+ * await server.stop();
+ * ```
+ *
+ * ## Environment
+ *
+ * Node.js only — the module builds on `node:http`, which is why it lives in
+ * a dedicated subpath export: importing it from the browser/Edge-safe main
+ * entry would drag a Node built-in into every bundle. Never re-export this
+ * module from `src/index.ts`; the Edge Runtime verification
+ * (`npm run verify:edge-runtime`) exists to catch exactly that.
+ *
+ * Designed for Vitest/Jest: `start()` resolves once the server listens and
+ * `stop()` is idempotent, so `beforeEach`/`afterEach` hooks manage the
+ * lifecycle without tracking whether `start()` ran.
+ */
+/** One recorded incoming request, for wire-level test assertions. */
+interface MockRequestRecord {
+    /** HTTP method (`GET`, `POST`, `HEAD`, ...). */
+    readonly method: string;
+    /** Request path with the query string stripped. */
+    readonly path: string;
+    /** Parsed request body (JSON-parsed when possible, raw string otherwise); `undefined` for body-less methods. */
+    readonly body?: unknown;
+    /** ISO-8601 timestamp of when the request arrived. */
+    readonly timestamp: string;
+}
+/**
+ * A single mock route handler. The server matches on the request path
+ * (query string stripped — Ollama's API doesn't use query params for the
+ * routes we care about).
+ *
+ * All fields optional except `chunks` (which defaults to `[]` — useful for
+ * testing the "stream closed without any data" case).
+ */
+interface MockEndpointOptions {
+    /** HTTP status code. Defaults to 200. */
+    readonly status?: number | undefined;
+    /**
+     * NDJSON chunks to emit, in order. Each chunk is emitted as a separate
+     * `res.write()` call followed by `\n`. Pass `[]` to emit no body (useful
+     * for testing the "stream closed without data" case).
+     */
+    readonly chunks?: readonly string[] | undefined;
+    /**
+     * Delay (ms) before emitting each chunk. Defaults to 0 (no delay). Set to
+     * a small value (5-50ms) to test backpressure handling; set to a large
+     * value (10_000ms) to test timeout/cancellation.
+     */
+    readonly chunkDelayMs?: number | undefined;
+    /**
+     * Custom response headers. Defaults to
+     * `{ 'content-type': 'application/x-ndjson' }` for streaming endpoints.
+     * Override for non-JSON responses (e.g. blob uploads).
+     */
+    readonly headers?: Record<string, string> | undefined;
+    /**
+     * When `true`, the server closes the connection mid-stream after emitting
+     * the first chunk. Use this to test connection-drop recovery. Defaults to
+     * `false`.
+     */
+    readonly dropConnectionMidStream?: boolean | undefined;
+    /**
+     * Emit this exact string as the whole response body — no NDJSON newline
+     * framing. Overrides `chunks` (use it for non-JSON responses such as the
+     * plain-text liveness body or raw blob bytes).
+     */
+    readonly rawBody?: string | undefined;
+    /**
+     * Inject an in-band error frame — `{"error": "<message>"}` — into the
+     * NDJSON response while the HTTP status stays 200. This is how a real
+     * Ollama daemon reports mid-generation failures (GPU OOM, driver crash,
+     * context overflow): the status code never changes, the parser has to
+     * catch the frame. The SDK's stream readers raise `OllamaStreamError` on
+     * it.
+     *
+     * `after` is the number of chunks emitted before the error frame. The
+     * default is `chunks.length - 1` — every content chunk, then the error
+     * frame, with the final `done` frame never emitted, exactly what a
+     * mid-generation crash looks like on the wire (an error frame *after* the
+     * done frame would be unread: the stream has already completed cleanly).
+     * `after: 0` errors before any content; an explicit `after >=
+     * chunks.length` emits every chunk and then the error. Chunks at or after
+     * the injection point are never emitted: the server "crashed".
+     */
+    readonly injectErrorFrame?: {
+        readonly after?: number | undefined;
+        readonly message: string;
+    } | undefined;
+    /**
+     * Optional callback fired when a request arrives at this route. Receives
+     * the parsed request body (or `undefined` if the body wasn't valid JSON).
+     * Useful for assertions like "the client sent the right `model` field".
+     * For global capture across routes see {@link OllamaMockServer.requests}.
+     */
+    readonly onRequest?: ((body: unknown) => void) | undefined;
+}
+/** Options for {@link createMockOllamaServer} and the `OllamaMockServer` constructor. */
+interface MockServerOptions {
+    /** TCP port to listen on. `0` (the default) picks an ephemeral port. */
+    readonly port?: number | undefined;
+    /**
+     * Serve the built-in default routes when no route is explicitly registered
+     * for a path: `HEAD /` and `GET /` → `200` (the official liveness probe —
+     * `GET /` answers the plain-text body "Ollama is running") and
+     * `GET /api/version` → `200 {"version": "<version>"}`. Defaults to `true`.
+     * Explicit `register()` calls always take precedence.
+     */
+    readonly defaultRoutes?: boolean | undefined;
+    /** Version reported by the default `GET /api/version` route. Defaults to `'0.14.0'`. */
+    readonly version?: string | undefined;
+}
+/** Shape accepted by {@link mockToolCallChunks} for each tool call. */
+interface MockToolCallSpec {
+    /** Tool-call id; auto-generated (`call-0`, `call-1`, …) when omitted. */
+    readonly id?: string | undefined;
+    /** Tool name, as the model would emit it. */
+    readonly name: string;
+    /** Tool arguments — an object (stringified by the builder) or a pre-encoded string. */
+    readonly arguments: Record<string, unknown> | string;
+}
+/** Options for {@link mockTextChunks}. */
+interface MockTextChunksOptions {
+    /** Split the text into content frames of at most this many characters. Default: one frame with the whole text. */
+    readonly chunkSize?: number | undefined;
+    /** Model name stamped on each frame. Defaults to `'mock-model'`. */
+    readonly model?: string | undefined;
+}
+/** Options for {@link mockToolCallChunks}. */
+interface MockToolCallChunksOptions {
+    /** Model name stamped on each frame. Defaults to `'mock-model'`. */
+    readonly model?: string | undefined;
+    /** Assistant text to carry on the tool-call frame (some models emit a preamble). Defaults to `''`. */
+    readonly content?: string | undefined;
+}
+/**
+ * One `/api/chat` NDJSON frame as a ready-to-emit string. Sensible defaults:
+ * `model: 'mock-model'`, a fresh `created_at`, `done: false`.
+ *
+ * ```ts
+ * server.register('/api/chat', {
+ *   chunks: [
+ *     mockChatChunk({ content: 'Hel' }),
+ *     mockChatChunk({ content: 'lo' }),
+ *     mockChatChunk({ done: true, evalCount: 2, evalDurationNs: 20_000_000 }),
+ *   ],
+ * });
+ * ```
+ */
+declare function mockChatChunk(frame: {
+    readonly content?: string | undefined;
+    readonly toolCalls?: readonly MockToolCallSpec[] | undefined;
+    readonly done?: boolean | undefined;
+    readonly model?: string | undefined;
+    readonly evalCount?: number | undefined;
+    readonly evalDurationNs?: number | undefined;
+    readonly promptEvalCount?: number | undefined;
+    readonly promptEvalDurationNs?: number | undefined;
+    readonly promptEvalCachedCount?: number | undefined;
+    readonly totalDurationNs?: number | undefined;
+    readonly loadDurationNs?: number | undefined;
+}): string;
+/**
+ * Content frames + a final `done` frame for a plain-text `/api/chat` reply.
+ * With `chunkSize`, the text is split into that many characters per frame —
+ * the shape streaming code needs to exercise incremental assembly.
+ *
+ * ```ts
+ * server.register('/api/chat', {
+ *   chunks: mockTextChunks('Hello, world!', { chunkSize: 5 }),
+ * });
+ * ```
+ */
+declare function mockTextChunks(text: string, opts?: MockTextChunksOptions): string[];
+/**
+ * Tool-call frames for `/api/chat` — the documented native shape: tool calls
+ * arrive **complete in one frame** (parallel calls = one array with several
+ * entries), followed by a final `done` frame. Pair with an `Agent` or tool
+ * loop for deterministic tool-execution tests.
+ *
+ * ```ts
+ * // Parallel tool calls, one round trip:
+ * server.register('/api/chat', {
+ *   chunks: mockToolCallChunks([
+ *     { name: 'get_weather', arguments: { city: 'Tokyo' } },
+ *     { name: 'get_time', arguments: { tz: 'Asia/Tokyo' } },
+ *   ]),
+ * });
+ * ```
+ */
+declare function mockToolCallChunks(toolCalls: readonly MockToolCallSpec[], opts?: MockToolCallChunksOptions): string[];
+/**
+ * Lightweight in-memory Ollama mock server.
+ *
+ * Spawns a real `node:http` server on a free port (or a fixed port if you
+ * pass one). Tests register route handlers via `register()`, then point an
+ * `OllamaClient` at `server.baseUrl`. The server emits the registered chunks
+ * with the configured delay, status, and connection behavior; when no route
+ * is registered the built-in liveness + version defaults answer (see
+ * {@link MockServerOptions.defaultRoutes}).
+ *
+ * Prefer the {@link createMockOllamaServer} factory; the class is exported
+ * for typed references and back-compatibility with the SDK's own suite.
+ *
+ * The server is **single-process** — it doesn't fork or use workers. It's
+ * intended for unit/integration tests, not load testing.
+ */
+declare class OllamaMockServer {
+    private readonly server;
+    private readonly routes;
+    private readonly requestLog;
+    private readonly defaultsEnabled;
+    private readonly defaultVersion;
+    private port;
+    /**
+     * @param portOrOptions Either a TCP port (pass `0` for an ephemeral port —
+     *        recommended for parallel test runs) or a {@link MockServerOptions}
+     *        object. The actual port is exposed via {@link baseUrl} after
+     *        {@link start}.
+     */
+    constructor(portOrOptions?: number | MockServerOptions);
+    /**
+     * Register a route handler. Replaces any existing handler for the same
+     * path (including a built-in default). The path is matched against
+     * `req.url` exactly (query string stripped, no template matching — for
+     * `/api/blobs/{digest}`, register each specific digest value).
+     */
+    register(path: string, options: MockEndpointOptions): void;
+    /** Clear all registered routes (built-in defaults remain). Useful in `beforeEach` hooks. */
+    clear(): void;
+    /**
+     * Every request this server has served, in arrival order — method, path,
+     * parsed body, timestamp — including 404s and default-route hits. Assert
+     * on what the client actually put on the wire; clear with
+     * {@link clearRequests} (e.g. in `beforeEach`).
+     */
+    get requests(): readonly MockRequestRecord[];
+    /** Empty the request log ({@link requests}). Routes are unaffected. */
+    clearRequests(): void;
+    /**
+     * Base URL to point an `OllamaClient` at. Only meaningful after
+     * {@link start} has resolved.
+     */
+    get baseUrl(): string;
+    /**
+     * Start listening. Resolves once the server is ready to accept
+     * connections.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop listening and close all active connections. Resolves once the
+     * server is fully closed (no lingering sockets). Idempotent — calling
+     * `stop()` on an already-stopped server resolves cleanly rather than
+     * throwing `ERR_SERVER_NOT_RUNNING`.
+     */
+    stop(): Promise<void>;
+    /**
+     * Built-in default handler for a path, or `undefined` when defaults are
+     * disabled or the path isn't one of the official liveness surfaces.
+     * Registered routes are checked first and always win.
+     */
+    private defaultRouteFor;
+    private handleRequest;
+}
+/**
+ * Create an in-memory Ollama mock server — the recommended entry point for
+ * consumer test suites. Ephemeral port, built-in liveness + version
+ * defaults on, empty request log. Call `await server.start()` before
+ * pointing an `OllamaClient` at `server.baseUrl`, and `await server.stop()`
+ * in teardown.
+ *
+ * ```ts
+ * const server = createMockOllamaServer();
+ * await server.start();
+ * // defaults already answer: HEAD / (ping) and GET /api/version
+ * server.register('/api/chat', { chunks: mockTextChunks('Hi!') });
+ * ```
+ */
+declare function createMockOllamaServer(options?: MockServerOptions): OllamaMockServer;
+
+export { type MockEndpointOptions, type MockRequestRecord, type MockServerOptions, type MockTextChunksOptions, type MockToolCallChunksOptions, type MockToolCallSpec, OllamaMockServer, createMockOllamaServer, mockChatChunk, mockTextChunks, mockToolCallChunks };

package/dist/testing.d.ts

@@ -0,0 +1,336 @@
+/**
+ * In-memory Ollama mock server for deterministic, zero-network CI testing.
+ *
+ * This is the SDK's own mock engine, promoted from the internal test fixture
+ * (`test/mocks/ollama-mock-server.ts`) to a public entry point
+ * (`@nemesis-oss/ollama-sdk/testing`) so consumers don't have to hand-roll
+ * ad-hoc HTTP stubs to test their Ollama integrations — see ADR 0029.
+ * The internal fixture re-exports this module, so the SDK's own test suite
+ * exercises the exact same code consumers get.
+ *
+ * The VCR cassette system (`test/vcr.ts` in the repo) replays recorded HTTP
+ * interactions, but cassettes are static. This mock server covers what
+ * cassettes can't:
+ *
+ *   - programmable inter-chunk delays (backpressure handling)
+ *   - mid-stream **in-band error injection** — an `{"error": "..."}` NDJSON
+ *     frame emitted mid-response with HTTP 200 still, exactly how a real
+ *     Ollama daemon reports GPU OOM / driver crashes mid-generation
+ *   - connection drops mid-stream (`dropConnectionMidStream`)
+ *   - 503/502/429 error status codes with custom bodies
+ *   - arbitrary NDJSON chunk payloads (tool calls, thinking, partial frames)
+ *
+ * On top of the raw engine, the public surface adds the conveniences a
+ * consumer test suite wants on day one:
+ *
+ *   - {@link createMockOllamaServer} factory (the recommended entry point)
+ *   - built-in **default routes** — the official liveness probe (`HEAD /`
+ *     and `GET /` → "Ollama is running") and `GET /api/version` — so
+ *     `client.ping()` and friends work before any route is registered.
+ *     Explicit `register()` calls always win.
+ *   - **request recording** (`server.requests`, `clearRequests()`) for
+ *     wire-level assertions without per-route callbacks
+ *   - NDJSON **chunk builders** ({@link mockChatChunk}, {@link mockTextChunks},
+ *     {@link mockToolCallChunks}) that produce correctly-shaped `/api/chat`
+ *     frames — including parallel tool calls in one frame, the documented
+ *     native behavior
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createMockOllamaServer, mockToolCallChunks } from '@nemesis-oss/ollama-sdk/testing';
+ * import { OllamaClient } from '@nemesis-oss/ollama-sdk';
+ *
+ * const server = createMockOllamaServer(); // ephemeral port, default routes on
+ * await server.start();
+ *
+ * server.register('/api/chat', {
+ *   chunks: mockToolCallChunks([
+ *     { name: 'get_weather', arguments: { city: 'Tokyo' } },
+ *     { name: 'get_time', arguments: { tz: 'Asia/Tokyo' } },
+ *   ]),
+ * });
+ *
+ * const client = new OllamaClient({ baseUrl: server.baseUrl });
+ * // ... exercise the client; assert on server.requests ...
+ *
+ * await server.stop();
+ * ```
+ *
+ * ## Environment
+ *
+ * Node.js only — the module builds on `node:http`, which is why it lives in
+ * a dedicated subpath export: importing it from the browser/Edge-safe main
+ * entry would drag a Node built-in into every bundle. Never re-export this
+ * module from `src/index.ts`; the Edge Runtime verification
+ * (`npm run verify:edge-runtime`) exists to catch exactly that.
+ *
+ * Designed for Vitest/Jest: `start()` resolves once the server listens and
+ * `stop()` is idempotent, so `beforeEach`/`afterEach` hooks manage the
+ * lifecycle without tracking whether `start()` ran.
+ */
+/** One recorded incoming request, for wire-level test assertions. */
+interface MockRequestRecord {
+    /** HTTP method (`GET`, `POST`, `HEAD`, ...). */
+    readonly method: string;
+    /** Request path with the query string stripped. */
+    readonly path: string;
+    /** Parsed request body (JSON-parsed when possible, raw string otherwise); `undefined` for body-less methods. */
+    readonly body?: unknown;
+    /** ISO-8601 timestamp of when the request arrived. */
+    readonly timestamp: string;
+}
+/**
+ * A single mock route handler. The server matches on the request path
+ * (query string stripped — Ollama's API doesn't use query params for the
+ * routes we care about).
+ *
+ * All fields optional except `chunks` (which defaults to `[]` — useful for
+ * testing the "stream closed without any data" case).
+ */
+interface MockEndpointOptions {
+    /** HTTP status code. Defaults to 200. */
+    readonly status?: number | undefined;
+    /**
+     * NDJSON chunks to emit, in order. Each chunk is emitted as a separate
+     * `res.write()` call followed by `\n`. Pass `[]` to emit no body (useful
+     * for testing the "stream closed without data" case).
+     */
+    readonly chunks?: readonly string[] | undefined;
+    /**
+     * Delay (ms) before emitting each chunk. Defaults to 0 (no delay). Set to
+     * a small value (5-50ms) to test backpressure handling; set to a large
+     * value (10_000ms) to test timeout/cancellation.
+     */
+    readonly chunkDelayMs?: number | undefined;
+    /**
+     * Custom response headers. Defaults to
+     * `{ 'content-type': 'application/x-ndjson' }` for streaming endpoints.
+     * Override for non-JSON responses (e.g. blob uploads).
+     */
+    readonly headers?: Record<string, string> | undefined;
+    /**
+     * When `true`, the server closes the connection mid-stream after emitting
+     * the first chunk. Use this to test connection-drop recovery. Defaults to
+     * `false`.
+     */
+    readonly dropConnectionMidStream?: boolean | undefined;
+    /**
+     * Emit this exact string as the whole response body — no NDJSON newline
+     * framing. Overrides `chunks` (use it for non-JSON responses such as the
+     * plain-text liveness body or raw blob bytes).
+     */
+    readonly rawBody?: string | undefined;
+    /**
+     * Inject an in-band error frame — `{"error": "<message>"}` — into the
+     * NDJSON response while the HTTP status stays 200. This is how a real
+     * Ollama daemon reports mid-generation failures (GPU OOM, driver crash,
+     * context overflow): the status code never changes, the parser has to
+     * catch the frame. The SDK's stream readers raise `OllamaStreamError` on
+     * it.
+     *
+     * `after` is the number of chunks emitted before the error frame. The
+     * default is `chunks.length - 1` — every content chunk, then the error
+     * frame, with the final `done` frame never emitted, exactly what a
+     * mid-generation crash looks like on the wire (an error frame *after* the
+     * done frame would be unread: the stream has already completed cleanly).
+     * `after: 0` errors before any content; an explicit `after >=
+     * chunks.length` emits every chunk and then the error. Chunks at or after
+     * the injection point are never emitted: the server "crashed".
+     */
+    readonly injectErrorFrame?: {
+        readonly after?: number | undefined;
+        readonly message: string;
+    } | undefined;
+    /**
+     * Optional callback fired when a request arrives at this route. Receives
+     * the parsed request body (or `undefined` if the body wasn't valid JSON).
+     * Useful for assertions like "the client sent the right `model` field".
+     * For global capture across routes see {@link OllamaMockServer.requests}.
+     */
+    readonly onRequest?: ((body: unknown) => void) | undefined;
+}
+/** Options for {@link createMockOllamaServer} and the `OllamaMockServer` constructor. */
+interface MockServerOptions {
+    /** TCP port to listen on. `0` (the default) picks an ephemeral port. */
+    readonly port?: number | undefined;
+    /**
+     * Serve the built-in default routes when no route is explicitly registered
+     * for a path: `HEAD /` and `GET /` → `200` (the official liveness probe —
+     * `GET /` answers the plain-text body "Ollama is running") and
+     * `GET /api/version` → `200 {"version": "<version>"}`. Defaults to `true`.
+     * Explicit `register()` calls always take precedence.
+     */
+    readonly defaultRoutes?: boolean | undefined;
+    /** Version reported by the default `GET /api/version` route. Defaults to `'0.14.0'`. */
+    readonly version?: string | undefined;
+}
+/** Shape accepted by {@link mockToolCallChunks} for each tool call. */
+interface MockToolCallSpec {
+    /** Tool-call id; auto-generated (`call-0`, `call-1`, …) when omitted. */
+    readonly id?: string | undefined;
+    /** Tool name, as the model would emit it. */
+    readonly name: string;
+    /** Tool arguments — an object (stringified by the builder) or a pre-encoded string. */
+    readonly arguments: Record<string, unknown> | string;
+}
+/** Options for {@link mockTextChunks}. */
+interface MockTextChunksOptions {
+    /** Split the text into content frames of at most this many characters. Default: one frame with the whole text. */
+    readonly chunkSize?: number | undefined;
+    /** Model name stamped on each frame. Defaults to `'mock-model'`. */
+    readonly model?: string | undefined;
+}
+/** Options for {@link mockToolCallChunks}. */
+interface MockToolCallChunksOptions {
+    /** Model name stamped on each frame. Defaults to `'mock-model'`. */
+    readonly model?: string | undefined;
+    /** Assistant text to carry on the tool-call frame (some models emit a preamble). Defaults to `''`. */
+    readonly content?: string | undefined;
+}
+/**
+ * One `/api/chat` NDJSON frame as a ready-to-emit string. Sensible defaults:
+ * `model: 'mock-model'`, a fresh `created_at`, `done: false`.
+ *
+ * ```ts
+ * server.register('/api/chat', {
+ *   chunks: [
+ *     mockChatChunk({ content: 'Hel' }),
+ *     mockChatChunk({ content: 'lo' }),
+ *     mockChatChunk({ done: true, evalCount: 2, evalDurationNs: 20_000_000 }),
+ *   ],
+ * });
+ * ```
+ */
+declare function mockChatChunk(frame: {
+    readonly content?: string | undefined;
+    readonly toolCalls?: readonly MockToolCallSpec[] | undefined;
+    readonly done?: boolean | undefined;
+    readonly model?: string | undefined;
+    readonly evalCount?: number | undefined;
+    readonly evalDurationNs?: number | undefined;
+    readonly promptEvalCount?: number | undefined;
+    readonly promptEvalDurationNs?: number | undefined;
+    readonly promptEvalCachedCount?: number | undefined;
+    readonly totalDurationNs?: number | undefined;
+    readonly loadDurationNs?: number | undefined;
+}): string;
+/**
+ * Content frames + a final `done` frame for a plain-text `/api/chat` reply.
+ * With `chunkSize`, the text is split into that many characters per frame —
+ * the shape streaming code needs to exercise incremental assembly.
+ *
+ * ```ts
+ * server.register('/api/chat', {
+ *   chunks: mockTextChunks('Hello, world!', { chunkSize: 5 }),
+ * });
+ * ```
+ */
+declare function mockTextChunks(text: string, opts?: MockTextChunksOptions): string[];
+/**
+ * Tool-call frames for `/api/chat` — the documented native shape: tool calls
+ * arrive **complete in one frame** (parallel calls = one array with several
+ * entries), followed by a final `done` frame. Pair with an `Agent` or tool
+ * loop for deterministic tool-execution tests.
+ *
+ * ```ts
+ * // Parallel tool calls, one round trip:
+ * server.register('/api/chat', {
+ *   chunks: mockToolCallChunks([
+ *     { name: 'get_weather', arguments: { city: 'Tokyo' } },
+ *     { name: 'get_time', arguments: { tz: 'Asia/Tokyo' } },
+ *   ]),
+ * });
+ * ```
+ */
+declare function mockToolCallChunks(toolCalls: readonly MockToolCallSpec[], opts?: MockToolCallChunksOptions): string[];
+/**
+ * Lightweight in-memory Ollama mock server.
+ *
+ * Spawns a real `node:http` server on a free port (or a fixed port if you
+ * pass one). Tests register route handlers via `register()`, then point an
+ * `OllamaClient` at `server.baseUrl`. The server emits the registered chunks
+ * with the configured delay, status, and connection behavior; when no route
+ * is registered the built-in liveness + version defaults answer (see
+ * {@link MockServerOptions.defaultRoutes}).
+ *
+ * Prefer the {@link createMockOllamaServer} factory; the class is exported
+ * for typed references and back-compatibility with the SDK's own suite.
+ *
+ * The server is **single-process** — it doesn't fork or use workers. It's
+ * intended for unit/integration tests, not load testing.
+ */
+declare class OllamaMockServer {
+    private readonly server;
+    private readonly routes;
+    private readonly requestLog;
+    private readonly defaultsEnabled;
+    private readonly defaultVersion;
+    private port;
+    /**
+     * @param portOrOptions Either a TCP port (pass `0` for an ephemeral port —
+     *        recommended for parallel test runs) or a {@link MockServerOptions}
+     *        object. The actual port is exposed via {@link baseUrl} after
+     *        {@link start}.
+     */
+    constructor(portOrOptions?: number | MockServerOptions);
+    /**
+     * Register a route handler. Replaces any existing handler for the same
+     * path (including a built-in default). The path is matched against
+     * `req.url` exactly (query string stripped, no template matching — for
+     * `/api/blobs/{digest}`, register each specific digest value).
+     */
+    register(path: string, options: MockEndpointOptions): void;
+    /** Clear all registered routes (built-in defaults remain). Useful in `beforeEach` hooks. */
+    clear(): void;
+    /**
+     * Every request this server has served, in arrival order — method, path,
+     * parsed body, timestamp — including 404s and default-route hits. Assert
+     * on what the client actually put on the wire; clear with
+     * {@link clearRequests} (e.g. in `beforeEach`).
+     */
+    get requests(): readonly MockRequestRecord[];
+    /** Empty the request log ({@link requests}). Routes are unaffected. */
+    clearRequests(): void;
+    /**
+     * Base URL to point an `OllamaClient` at. Only meaningful after
+     * {@link start} has resolved.
+     */
+    get baseUrl(): string;
+    /**
+     * Start listening. Resolves once the server is ready to accept
+     * connections.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop listening and close all active connections. Resolves once the
+     * server is fully closed (no lingering sockets). Idempotent — calling
+     * `stop()` on an already-stopped server resolves cleanly rather than
+     * throwing `ERR_SERVER_NOT_RUNNING`.
+     */
+    stop(): Promise<void>;
+    /**
+     * Built-in default handler for a path, or `undefined` when defaults are
+     * disabled or the path isn't one of the official liveness surfaces.
+     * Registered routes are checked first and always win.
+     */
+    private defaultRouteFor;
+    private handleRequest;
+}
+/**
+ * Create an in-memory Ollama mock server — the recommended entry point for
+ * consumer test suites. Ephemeral port, built-in liveness + version
+ * defaults on, empty request log. Call `await server.start()` before
+ * pointing an `OllamaClient` at `server.baseUrl`, and `await server.stop()`
+ * in teardown.
+ *
+ * ```ts
+ * const server = createMockOllamaServer();
+ * await server.start();
+ * // defaults already answer: HEAD / (ping) and GET /api/version
+ * server.register('/api/chat', { chunks: mockTextChunks('Hi!') });
+ * ```
+ */
+declare function createMockOllamaServer(options?: MockServerOptions): OllamaMockServer;
+
+export { type MockEndpointOptions, type MockRequestRecord, type MockServerOptions, type MockTextChunksOptions, type MockToolCallChunksOptions, type MockToolCallSpec, OllamaMockServer, createMockOllamaServer, mockChatChunk, mockTextChunks, mockToolCallChunks };