@nemesis-oss/ollama-sdk 1.0.0 → 1.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { M as Message, C as ChatResponse, G as GenerateResponse, T as ToolCall, P as ProgressResponse, a as ModelResponse, S as ShowRequestOptions, b as ShowResponse, c as PullRequestOptions, d as PushRequestOptions, e as CreateRequestOptions, D as DeleteRequestOptions, f as StatusResponse, g as CopyRequestOptions, h as PsResponse, V as VersionResponse, i as ChatRequestOptions, j as GenerateRequestOptions, E as EmbedRequestOptions, k as EmbedResponse, l as EmbeddingsRequestOptions, m as EmbeddingsResponse, W as WebSearchRequestOptions, n as WebSearchResponse, o as WebFetchRequestOptions, p as WebFetchResponse, q as ToolHandler, r as Tool, A as AnyTool, s as ToolRegistry, t as ToolExecutionResult, u as ModelOptions, v as ToolDefinition } from './compose-DC11aDJn.cjs';
-export { w as AppliedSkillResult, x as ApplySkillOptions, F as FormatOption, L as ListResponse, y as ModelDetails, z as ParsedFrontmatter, R as RequestCancellationOptions, B as Role, H as Skill, I as SkillFrontmatter, J as SkillSummary, K as ToolCallFunction, N as ToolExecutionContext, O as ToolExecutionFailure, Q as ToolExecutionSuccess, U as ToolFunctionDefinition, X as ToolProperty, Y as ToolRegistryOptions, Z as WebSearchResult, _ as applySkill, $ as parseFrontmatter } from './compose-DC11aDJn.cjs';
+import { M as Message, C as ChatResponse, G as GenerateResponse, T as ToolCall, P as ProgressResponse, a as ModelResponse, S as ShowRequestOptions, b as ShowResponse, c as PullRequestOptions, d as PushRequestOptions, e as CreateRequestOptions, D as DeleteRequestOptions, f as StatusResponse, g as CopyRequestOptions, h as PsResponse, V as VersionResponse, i as ChatRequestOptions, j as GenerateRequestOptions, E as EmbedRequestOptions, k as EmbedResponse, l as EmbeddingsRequestOptions, m as EmbeddingsResponse, W as WebSearchRequestOptions, n as WebSearchResponse, o as WebFetchRequestOptions, p as WebFetchResponse, q as ToolHandler, r as Tool, A as AnyTool, s as ToolRegistry, t as ToolExecutionResult, u as ModelOptions, v as ToolDefinition } from './compose-CDWq8oxJ.cjs';
+export { w as AppliedSkillResult, x as ApplySkillOptions, F as FormatOption, L as ListResponse, y as Logprob, z as LogprobToken, B as ModelDetails, H as ParsedFrontmatter, R as RequestCancellationOptions, I as Role, J as Skill, K as SkillFrontmatter, N as SkillSummary, O as ToolCallFunction, Q as ToolExecutionContext, U as ToolExecutionFailure, X as ToolExecutionSuccess, Y as ToolFunctionDefinition, Z as ToolProperty, _ as ToolRegistryOptions, $ as WebSearchResult, a0 as applySkill, a1 as parseFrontmatter } from './compose-CDWq8oxJ.cjs';
 import { z } from 'zod';
 import * as Otel from '@opentelemetry/api';
 
@@ -52,6 +52,22 @@ declare class OllamaRateLimitError extends OllamaClientError {
         retryAfterMs?: number | undefined;
     }) | undefined);
 }
+/**
+ * Thrown client-side, before a network request is made, by `QuotaManager.assertCanProceed`
+ * (see `src/quota.ts`) when issuing the request would exceed a configured usage budget for
+ * one of its rolling windows. This is distinct from `OllamaRateLimitError`, which reflects
+ * the server's own 429 response — Ollama Cloud does not expose account-level quota via the
+ * API, so `QuotaManager` tracks usage against budgets the caller configures locally and
+ * fails fast rather than waiting for the server to reject the request.
+ */
+declare class OllamaQuotaExceededError extends OllamaClientError {
+    readonly windowId: string;
+    readonly resetAt: number;
+    constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code' | 'retryable'> & {
+        windowId: string;
+        resetAt: number;
+    });
+}
 declare class OllamaServerError extends OllamaClientError {
     constructor(message: string, options?: Omit<OllamaClientErrorOptions, 'code' | 'retryable'> | undefined);
 }
@@ -88,6 +104,22 @@ declare class OllamaUnsupportedCapabilityError extends OllamaClientError {
         capability: string;
     });
 }
+/**
+ * Thrown client-side, before any network call, when `config.endpoints` uses
+ * `OllamaEndpoint.models` to scope endpoints/credentials to specific models and the
+ * requested `model` isn't in any configured endpoint's allow-list. This is a routing
+ * misconfiguration, not a connectivity problem — the SDK deliberately does not "probe"
+ * unauthorized endpoints to find one that happens to work (that would burn quota on keys
+ * that were never entitled to the model and produce non-deterministic startup behavior).
+ */
+declare class OllamaModelRoutingError extends OllamaClientError {
+    readonly model: string;
+    readonly availableModels: readonly string[];
+    constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code' | 'retryable'> & {
+        model: string;
+        availableModels: readonly string[];
+    });
+}
 declare class OllamaAgentMaxIterationsError extends OllamaClientError {
     readonly maxIterations: number;
     constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code'> & {
@@ -202,6 +234,8 @@ interface ChatStreamResult {
     readonly message: Message;
     readonly model: string;
     readonly done: boolean;
+    /** Mirrors the final chunk's `done_reason` (e.g. `"stop"`, `"load"`, `"unload"`). */
+    readonly doneReason?: string | undefined;
     readonly totalDurationMs?: number | undefined;
     readonly usage?: TokenUsage | undefined;
     readonly raw?: ChatResponse | undefined;
@@ -210,6 +244,8 @@ interface GenerateStreamResult {
     readonly response: string;
     readonly model: string;
     readonly done: boolean;
+    /** Mirrors the final chunk's `done_reason` (e.g. `"stop"`, `"load"`, `"unload"`). */
+    readonly doneReason?: string | undefined;
     readonly totalDurationMs?: number | undefined;
     readonly usage?: TokenUsage | undefined;
     readonly raw?: GenerateResponse | undefined;
@@ -369,17 +405,67 @@ interface OllamaEndpoint {
     readonly apiKey?: string | undefined;
     readonly headers?: Record<string, string> | undefined;
     readonly priority?: number | undefined;
+    /**
+     * Restricts this endpoint/credential to a specific set of models — for the common case
+     * of several Ollama Cloud API keys, each entitled to a different model. When set,
+     * `EndpointRegistry.candidates(model)` only returns this endpoint for a request whose
+     * `model` is in the list, so cross-endpoint failover never retries a request against a
+     * credential that isn't authorized for the requested model. Omit (the default) to make
+     * the endpoint eligible for every model, preserving prior behavior.
+     */
+    readonly models?: readonly string[] | undefined;
 }
 interface EndpointHealth {
     readonly endpoint: OllamaEndpoint;
     readonly failureCount: number;
     readonly lastFailureTimestamp?: number | undefined;
     readonly isCoolingDown: boolean;
+    /** In-flight requests currently attempting this endpoint — see `acquire`/`release`. */
+    readonly activeRequests: number;
 }
 interface EndpointRegistryOptions {
     readonly failureThreshold?: number | undefined;
     readonly cooldownMs?: number | undefined;
     readonly now?: (() => number) | undefined;
+    /**
+     * How candidates that share the same `priority` are ordered within `candidates()`.
+     * `'priority'` (the default) keeps them in registration order, so the same candidate is
+     * always tried first while it stays healthy. `'round-robin'` rotates each same-priority
+     * group by one position per `candidates()` call — i.e. per `chat`/`generate`/etc. call —
+     * so consecutive requests spread across a pool of interchangeable endpoints/credentials
+     * instead of always preferring the first one (the common case: several Ollama Cloud keys
+     * registered with no `models` restriction, meant to be used interchangeably). Endpoints
+     * at different priorities are unaffected either way — a higher-priority one is still
+     * always tried first, and failover to the rest of the group still applies if the
+     * rotated-to-front candidate fails.
+     *
+     * `'least-connections'` instead orders each same-priority group by ascending in-flight
+     * request count (tracked via `acquire`/`release`, ties broken by registration order),
+     * so a request always prefers whichever candidate currently has the fewest requests
+     * still in progress. Unlike `'round-robin'`, this remains correct under uneven or
+     * overlapping request durations — e.g. several Ollama Cloud accounts each limited to 1
+     * concurrent request: firing several requests at once (`Promise.all`) deterministically
+     * lands each on a different account rather than risking two landing on the same
+     * still-busy one, because `candidates()` and the subsequent `acquire()` for the chosen
+     * candidate run synchronously with no `await` in between — JS's single-threaded
+     * execution means no two concurrent calls can observe the same "0 active" snapshot for
+     * the same candidate.
+     */
+    readonly strategy?: 'priority' | 'round-robin' | 'least-connections' | undefined;
+    /**
+     * Caps in-flight requests per endpoint (tracked via `acquire`/`release`). Unset (the
+     * default) means no cap — candidates are never treated as saturated. When set, a
+     * request whose every otherwise-eligible candidate is already at this cap waits
+     * (`waitForCapacity`, FIFO per candidate) for one of them to free up, instead of being
+     * sent to an already-saturated candidate. Pairs naturally with `strategy:
+     * 'least-connections'` for a pool of accounts each limited to N concurrent requests —
+     * e.g. `maxConcurrentPerEndpoint: 1` for several Ollama Cloud free-tier accounts, so
+     * `N + 1` concurrent calls against `N` such accounts run `N` immediately and queue the
+     * rest, rather than the `(N+1)`th overrunning whichever account looks "least busy" at
+     * that instant. Waiting is bounded by the request's own timeout/`AbortSignal`, same as
+     * any other in-flight request — it never blocks indefinitely on its own.
+     */
+    readonly maxConcurrentPerEndpoint?: number | undefined;
 }
 declare class EndpointRegistry {
     private readonly endpoints;
@@ -388,11 +474,66 @@ declare class EndpointRegistry {
     private readonly failureThreshold;
     private readonly cooldownMs;
     private readonly now;
+    private readonly strategy;
+    private roundRobinCounter;
+    private readonly activeCounts;
+    private readonly maxConcurrentPerEndpoint;
+    private readonly waiters;
     constructor(endpoints: readonly OllamaEndpoint[], options?: EndpointRegistryOptions);
-    candidates(): OllamaEndpoint[];
+    /**
+     * Marks one more request as in-flight against `name`. Callers (`OllamaClient`) must
+     * pair every `acquire` with a `release` once that attempt finishes, success or not —
+     * see `OllamaClient.executeWithFailover`. Only affects candidate ordering when
+     * `strategy` is `'least-connections'`; harmless (just bookkeeping) otherwise, and
+     * always reflected in `status()`'s `activeRequests`.
+     */
+    acquire(name: string): void;
+    /** Releases one in-flight request marked via `acquire`, waking one waiter for `name` if any. */
+    release(name: string): void;
+    /**
+     * `candidates` filtered down to those currently under `maxConcurrentPerEndpoint` (all
+     * of them, unchanged, if that option is unset).
+     */
+    filterWithCapacity(candidates: readonly OllamaEndpoint[]): OllamaEndpoint[];
+    /**
+     * Resolves once any endpoint named in `names` has spare capacity under
+     * `maxConcurrentPerEndpoint` (a no-op resolve if that option is unset, or if one
+     * already does). Otherwise queues (FIFO per name) until a matching `release()` frees a
+     * slot, or rejects if `signal` aborts first — mirroring whatever aborted it
+     * (`OllamaTimeoutError`/the caller's own abort reason) so callers see the same error
+     * shape as any other in-flight request that times out or is cancelled. FIFO order is
+     * best-effort (a newly-arriving request can still win a race for a slot that just
+     * freed) — the capacity cap itself, not fairness, is the guarantee this exists for.
+     */
+    waitForCapacity(names: readonly string[], signal?: AbortSignal): Promise<void>;
+    /**
+     * Rotates each same-`priority` group in `sorted` (already sorted highest-priority-first)
+     * by one position further per call, wrapping around within the group. Priority tiers
+     * themselves are never reordered — only candidates that were already tied.
+     */
+    private applyRoundRobin;
+    /**
+     * Reorders each same-`priority` group in `sorted` by ascending in-flight request count
+     * (from `acquire`/`release`); a stable sort, so candidates tied on active count keep
+     * their relative (priority-then-registration) order. Priority tiers themselves are
+     * never reordered.
+     */
+    private applyLeastConnections;
+    /**
+     * Endpoints eligible for `model`, sorted healthy-first-by-priority (falling back to
+     * soonest-to-recover if every eligible endpoint is cooling down); same-priority
+     * candidates are further reordered per `options.strategy` (see
+     * `EndpointRegistryOptions.strategy`). When `model` is given, endpoints whose `models`
+     * allow-list doesn't include it are excluded entirely — see `OllamaEndpoint.models`.
+     * Omit `model` to consider every configured endpoint, regardless of any `models`
+     * restriction (used for non-model-scoped operations).
+     */
+    candidates(model?: string): OllamaEndpoint[];
     reportSuccess(name: string): void;
     reportFailure(name: string): void;
     list(): readonly OllamaEndpoint[];
+    /** True if any configured endpoint restricts itself to a `models` allow-list. */
+    hasModelScopedEndpoints(): boolean;
     status(): EndpointHealth[];
 }
 
@@ -402,6 +543,35 @@ declare class EndpointRegistry {
 
 declare const DEFAULT_BASE_URL = "http://localhost:11434";
 declare const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Fixed host for Ollama's hosted web tools (`/api/web_search`, `/api/web_fetch`) — see
+ * `OllamaClient.webSearch`/`webFetch`. These are an Ollama Cloud service reachable only
+ * at this host, independent of any locally-configured `baseUrl`/`endpoints`.
+ */
+declare const OLLAMA_CLOUD_BASE_URL = "https://ollama.com";
+/** One named credential for the `credentials`/`modelBindings` config shape. */
+interface OllamaCredentialConfig {
+    readonly apiKey: string;
+    /** Overrides `OllamaClientConfig.baseUrl` for requests made with this credential. */
+    readonly baseUrl?: string | undefined;
+    readonly headers?: Record<string, string> | undefined;
+}
+/**
+ * Builds synthetic `OllamaEndpoint`s (named `credential:<id>`) from `config.credentials` +
+ * `config.modelBindings` — an ergonomic, map-based alternative to writing out `endpoints`
+ * with per-entry `models` allow-lists directly. Both shapes feed the same
+ * `EndpointRegistry`/`executeWithFailover` routing engine; this is pure config sugar, not
+ * a separate routing mechanism. Returns `[]` if `config.credentials` is unset.
+ *
+ * A model bound to one credential (`modelBindings: { "minimax-m3": "coder" }`) scopes that
+ * credential to only that model, same as `OllamaEndpoint.models`. A model bound to several
+ * credentials (`modelBindings: { "gpt-oss:120b": ["key1", "key2"] }`) makes ordinary
+ * endpoint failover apply between them. `config.defaultCredential`, if set, is given a
+ * lower priority than explicitly-bound credentials and no `models` restriction, so it acts
+ * as a catch-all for any model without an explicit binding without ever pre-empting one
+ * that has.
+ */
+declare function resolveCredentialEndpoints(config: Pick<OllamaClientConfig, 'credentials' | 'modelBindings' | 'defaultCredential' | 'baseUrl'>): readonly OllamaEndpoint[];
 declare const DEFAULT_FAILOVER_CODES: readonly string[];
 interface OllamaClientConfig {
     /**
@@ -418,9 +588,49 @@ interface OllamaClientConfig {
     readonly apiKey?: string;
     /** Static headers merged into every request. */
     readonly headers?: Record<string, string>;
-    /** Multiple named endpoints for rotation and automatic failover. */
+    /**
+     * Multiple named endpoints for rotation and automatic failover. Each endpoint may
+     * carry its own `apiKey` and, via `models`, be scoped to only the models that
+     * credential is entitled to — see `OllamaEndpoint.models` for routing several
+     * per-model Ollama Cloud API keys through a single client.
+     */
     readonly endpoints?: readonly OllamaEndpoint[];
-    /** Tuning options for endpoint circuit breaker. */
+    /**
+     * Named credentials, keyed by an id you choose — an ergonomic alternative to writing
+     * out `endpoints` by hand for the common "several Ollama Cloud API keys, each entitled
+     * to different models" shape. Combine with `modelBindings` to scope each credential to
+     * the models it's authorized for; a credential with no binding (or set as
+     * `defaultCredential`) is eligible for every model, same as an `OllamaEndpoint` with no
+     * `models`. Merges additively with `endpoints` if both are given.
+     */
+    readonly credentials?: Readonly<Record<string, OllamaCredentialConfig>>;
+    /**
+     * Maps a model name to the `credentials` id (or ids, for several keys authorized for
+     * the same model — ordinary failover applies between them) that may serve it. Has no
+     * effect without `credentials`. Referencing an id not present in `credentials` throws
+     * at construction time.
+     */
+    readonly modelBindings?: Readonly<Record<string, string | readonly string[]>>;
+    /**
+     * The `credentials` id to fall back to for a model with no entry in `modelBindings`.
+     * Unset means such a model has no synthesized-from-`credentials` route — it still
+     * routes normally through any plain `endpoints` entry without a `models` restriction.
+     */
+    readonly defaultCredential?: string | undefined;
+    /**
+     * Tuning options for the endpoint circuit breaker, and candidate selection ordering —
+     * pass `{ strategy: 'round-robin' }` to spread requests across a pool of same-priority
+     * endpoints/credentials (e.g. several unbound `credentials`) instead of always
+     * preferring the first one, or `{ strategy: 'least-connections' }` to route each
+     * request to whichever candidate currently has the fewest requests in flight (e.g.
+     * several free-tier Ollama Cloud accounts, each capped at 1 concurrent request — this
+     * deterministically spreads concurrent `Promise.all`-style calls one-per-account rather
+     * than risking two landing on the same still-busy one), and `maxConcurrentPerEndpoint`
+     * to cap that at an exact number and queue (rather than overrun a saturated candidate)
+     * once every eligible one is at capacity — e.g. `{ strategy: 'least-connections',
+     * maxConcurrentPerEndpoint: 1 }` for accounts that only allow one request at a time.
+     * See `EndpointRegistryOptions`.
+     */
     readonly endpointHealth?: EndpointRegistryOptions;
     /** Error codes that trigger failover to the next candidate endpoint. */
     readonly failoverOn?: readonly string[];
@@ -519,6 +729,9 @@ type RequestRunner = <T>(op: (http: HttpClient, signal: AbortSignal) => Promise<
     signal?: AbortSignal | undefined;
     timeoutMs?: number | undefined;
     singleEndpoint?: boolean | undefined;
+    model?: string | undefined;
+    /** See `OllamaClient.executeWithFailover`'s `holdUntil` doc. */
+    holdUntil?: ((result: T) => Promise<unknown>) | undefined;
 }) => Promise<T>;
 /**
  * Every operation here targets one specific Ollama server's local model catalog or blob
@@ -568,13 +781,15 @@ declare class ModelsClient {
  *
  * @remarks
  * This is a typed pass-through to Ollama's own OpenAI-compatible `/v1` endpoints — it
- * implements the subset of the OpenAI Chat Completions API that Ollama documents as
- * supported (https://docs.ollama.com/api/openai-compatibility), not the full OpenAI
- * surface (Responses API, hosted tools like web/file search, computer use, code
- * interpreter, or server-side conversation state). Notably, `tools` is supported by
- * Ollama's compat layer but `tool_choice` and `parallel_tool_calls` are explicitly
- * **not** — deliberately omitted from {@link OpenAIChatCompletionRequest} rather than
- * typed as accepted-but-ignored.
+ * implements the subset of the OpenAI API surface that Ollama documents as supported
+ * (https://docs.ollama.com/api/openai-compatibility), not the full OpenAI surface (hosted
+ * tools like web/file search, computer use, code interpreter, or stateful server-side
+ * conversation state). Notably, `tools` is supported by Ollama's compat layer but
+ * `tool_choice` and `parallel_tool_calls` are not — both are still typed on
+ * {@link OpenAIChatCompletionRequest} (accepted-but-ignored) so consumers passing a
+ * standard OpenAI request object don't get spurious type errors; see the `@remarks` on
+ * each field. `/v1/responses` is supported non-statefully — see
+ * {@link OpenAIResponsesRequest}.
  */
 
 interface OpenAIToolCall {
@@ -621,6 +836,34 @@ interface OpenAIChatCompletionRequest {
     readonly frequency_penalty?: number | undefined;
     readonly user?: string | undefined;
     readonly tools?: readonly OpenAITool[] | undefined;
+    /**
+     * @remarks Accepted for OpenAI compatibility but ignored by Ollama — every tool the
+     * model is given remains callable regardless of this value.
+     */
+    readonly tool_choice?: 'none' | 'auto' | 'required' | {
+        readonly type: 'function';
+        readonly function: {
+            readonly name: string;
+        };
+    } | undefined;
+    /**
+     * @remarks Accepted for OpenAI compatibility but ignored by Ollama — Ollama does not
+     * control tool-call parallelism through this flag.
+     */
+    readonly parallel_tool_calls?: boolean | undefined;
+    /**
+     * Effort level for thinking models (e.g. `deepseek-r1`, `qwen3`). Equivalent to
+     * `reasoning.effort`; only effective for models that support reasoning/thinking.
+     */
+    readonly reasoning_effort?: 'high' | 'medium' | 'low' | 'max' | 'none' | undefined;
+    /**
+     * Effort level for thinking models (e.g. `deepseek-r1`, `qwen3`), nested OpenAI-style.
+     * Equivalent to `reasoning_effort`; only effective for models that support
+     * reasoning/thinking.
+     */
+    readonly reasoning?: {
+        readonly effort?: 'high' | 'medium' | 'low' | 'max' | 'none' | undefined;
+    } | undefined;
 }
 interface OpenAIChatCompletionChoice {
     readonly index: number;
@@ -649,12 +892,60 @@ interface OpenAIListModelsResponse {
     readonly object: 'list';
     readonly data: readonly OpenAIModelItem[];
 }
+/**
+ * Request body for OpenAI's Responses API (`/v1/responses`), added in Ollama v0.13.3.
+ *
+ * @remarks
+ * Ollama implements this **non-statefully**: every call is independent, so
+ * {@link previous_response_id} and {@link conversation} — OpenAI's mechanisms for
+ * resuming server-side conversation state — are accepted for compatibility but ignored.
+ * Send the full conversation in `input` on every call, the same as `/api/chat`.
+ */
+interface OpenAIResponsesRequest {
+    readonly model: string;
+    readonly input: string | readonly OpenAIMessage[];
+    readonly instructions?: string | undefined;
+    readonly tools?: readonly OpenAITool[] | undefined;
+    readonly stream?: boolean | undefined;
+    readonly temperature?: number | undefined;
+    readonly top_p?: number | undefined;
+    readonly max_output_tokens?: number | undefined;
+    /** @remarks Not supported by Ollama, which is stateless across calls — accepted but ignored. */
+    readonly previous_response_id?: string | undefined;
+    /** @remarks Not supported by Ollama, which is stateless across calls — accepted but ignored. */
+    readonly conversation?: string | undefined;
+    readonly truncation?: string | undefined;
+}
+interface OpenAIResponsesOutputTextContent {
+    readonly type: 'output_text';
+    readonly text: string;
+}
+interface OpenAIResponsesOutputMessage {
+    readonly type: 'message';
+    readonly role?: string | undefined;
+    readonly content: readonly OpenAIResponsesOutputTextContent[];
+}
+/** Non-stateful response shape for `/v1/responses`; see {@link OpenAIResponsesRequest}. */
+interface OpenAIResponsesResponse {
+    readonly id: string;
+    readonly object: 'response';
+    readonly created: number;
+    readonly model: string;
+    readonly output: readonly OpenAIResponsesOutputMessage[];
+    readonly usage?: {
+        readonly input_tokens: number;
+        readonly output_tokens: number;
+        readonly total_tokens: number;
+    } | undefined;
+}
 declare class OpenAICompatClient {
     private readonly http;
     constructor(http: HttpClient);
     createChatCompletion(request: OpenAIChatCompletionRequest, signal?: AbortSignal): Promise<OpenAIChatCompletionResponse>;
     chatCompletions(request: OpenAIChatCompletionRequest, signal?: AbortSignal): Promise<OpenAIChatCompletionResponse>;
     listModels(signal?: AbortSignal): Promise<OpenAIListModelsResponse>;
+    createResponses(request: OpenAIResponsesRequest, signal?: AbortSignal): Promise<OpenAIResponsesResponse>;
+    responses(request: OpenAIResponsesRequest, signal?: AbortSignal): Promise<OpenAIResponsesResponse>;
 }
 
 /**
@@ -719,6 +1010,14 @@ declare class OllamaClient {
     private readonly failoverCodes;
     private readonly fetchImpl;
     private readonly logger;
+    /**
+     * API key for Ollama's hosted web tools (`webSearch`/`webFetch`), which always target
+     * `OLLAMA_CLOUD_BASE_URL` regardless of `config.endpoints` — an Ollama account API key
+     * is inherently a single global credential, not tied to any one inference endpoint.
+     * Resolved the same way as a single-endpoint `apiKey` (`config.apiKey` falling back to
+     * `OLLAMA_API_KEY`), independent of whether `config.endpoints` was used instead.
+     */
+    private readonly cloudApiKey;
     constructor(config?: OllamaClientConfig);
     get modelsClient(): ModelsClient;
     /**
@@ -741,6 +1040,25 @@ declare class OllamaClient {
          * ADR 0008. Defaults to `false`, preserving normal failover for inference calls.
          */
         singleEndpoint?: boolean | undefined;
+        /**
+         * The model this request targets, used to filter candidates by
+         * `OllamaEndpoint.models` (credential-scoped routing — see that field's docs).
+         * Requests without a `model` (e.g. `listModels`) consider every configured
+         * endpoint, same as before this option existed.
+         */
+        model?: string | undefined;
+        /**
+         * For an operation whose real completion outlasts its own returned promise — a
+         * streaming response, specifically — defers releasing the endpoint's concurrency
+         * slot (see `EndpointRegistryOptions.maxConcurrentPerEndpoint`/`'least-connections'`)
+         * until the promise this returns settles, instead of releasing as soon as
+         * `operation` resolves. Pass `(stream) => stream.finalResult` for `chatStream`/
+         * `generateStream` so the slot stays held for as long as the underlying HTTP
+         * connection realistically does — until the stream is fully consumed, errors, or is
+         * aborted. Omit for anything whose returned promise already represents the whole
+         * request/response (the default, and correct for every non-streaming call).
+         */
+        holdUntil?: ((result: T) => Promise<unknown>) | undefined;
     }): Promise<T>;
     chat(req: ChatRequestOptions & {
         stream: true;
@@ -781,8 +1099,27 @@ declare class OllamaClient {
     readonly version: () => Promise<VersionResponse>;
     readonly createBlob: (digest: string, data: BinaryBody) => Promise<void>;
     readonly checkBlob: (digest: string) => Promise<boolean>;
+    /**
+     * Ollama's hosted web search tool (`POST https://ollama.com/api/web_search`) — a fixed
+     * Ollama Cloud service, unrelated to `config.endpoints`/`baseUrl` and not proxied
+     * through a local server. Requires an Ollama account API key: pass `apiKey` to the
+     * client constructor or set `OLLAMA_API_KEY`. Applies the same default `timeoutMs` and
+     * retry policy as inference calls, but never cross-endpoint-fails-over — there is only
+     * ever the one cloud endpoint to call.
+     */
     webSearch(req: WebSearchRequestOptions): Promise<WebSearchResponse>;
+    /**
+     * Ollama's hosted web fetch tool (`POST https://ollama.com/api/web_fetch`) — see
+     * {@link OllamaClient.webSearch} for the cloud-endpoint/auth/timeout/retry behavior,
+     * which applies identically here.
+     */
     webFetch(req: WebFetchRequestOptions): Promise<WebFetchResponse>;
+    /**
+     * Runs `operation` against the fixed Ollama Cloud host with this client's default
+     * timeout and retry policy — the same primitives `executeWithFailover` uses, minus the
+     * multi-candidate loop, since `webSearch`/`webFetch` only ever have the one endpoint.
+     */
+    private executeCloudRequest;
     capabilities(model: string): Promise<ModelCapabilities>;
     runtimeMode(): RuntimeMode;
     healthCheck(): Promise<EndpointHealthCheckResult[]>;
@@ -837,6 +1174,89 @@ declare function toDataStream<TChunk, TFinal>(stream: OllamaStream<TChunk, TFina
  */
 declare function toResponse<TChunk, TFinal>(stream: OllamaStream<TChunk, TFinal>, init?: ResponseInit): Response;
 
+/**
+ * Client-side usage budgeting.
+ *
+ * Ollama Cloud does not expose account-level quota or remaining-budget through the API —
+ * chat/generate responses carry only per-request token counts, and there is no header or
+ * endpoint that reports how much of your plan's session or weekly limit is left (the only
+ * way to see that today is the https://ollama.com dashboard or the 90%-usage email). See
+ * https://github.com/ollama/ollama/issues/15663.
+ *
+ * `QuotaManager` does not — and cannot — read Ollama's real limits. It tracks usage you
+ * record against budgets *you* configure over one or more rolling windows, and refuses to
+ * proceed once a window's budget is spent. Pair it with `OllamaRateLimitError` (thrown by
+ * `OllamaClient` on the server's actual 429) as the authoritative signal; treat
+ * `QuotaManager` as a local safety net that fails fast before the request is even sent.
+ */
+
+interface QuotaWindowConfig {
+    /** Identifies this window in status reports and thrown errors (e.g. "session", "weekly"). */
+    readonly id: string;
+    /** Length of the rolling window in milliseconds, after which usage resets to zero. */
+    readonly windowMs: number;
+    /** Token budget for the window. Omit to only track requests. */
+    readonly maxTokens?: number;
+    /** Request-count budget for the window. Omit to only track tokens. */
+    readonly maxRequests?: number;
+}
+interface QuotaWindowStatus extends QuotaWindowConfig {
+    readonly tokensUsed: number;
+    readonly requestsMade: number;
+    readonly windowStartedAt: number;
+    readonly windowResetAt: number;
+    readonly remainingTokens?: number;
+    readonly remainingRequests?: number;
+}
+interface QuotaManagerOptions {
+    readonly windows: readonly QuotaWindowConfig[];
+    /** Clock override for testing. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+declare class QuotaManager {
+    private readonly now;
+    private readonly windows;
+    constructor(options: QuotaManagerOptions);
+    private rollover;
+    /** Current usage, budgets, and reset time for every configured window. */
+    status(): readonly QuotaWindowStatus[];
+    /**
+     * True if one more request — optionally estimated at `estimatedTokens` — would stay
+     * within every configured window's budget. Read-only; does not record usage.
+     */
+    canProceed(estimatedTokens?: number): boolean;
+    /**
+     * Throws `OllamaQuotaExceededError` for the first window that `canProceed(estimatedTokens)`
+     * would fail on; otherwise a no-op. Call before issuing a request.
+     */
+    assertCanProceed(estimatedTokens?: number): void;
+    /** Records one request's actual usage — a raw API response or a pre-normalized `TokenUsage` — against every window. */
+    recordUsage(usage: RawUsageSource | TokenUsage): void;
+    /** Resets one window (by `id`) or, if omitted, all windows — zeroing usage and restarting their clocks. */
+    reset(windowId?: string): void;
+}
+interface OllamaCloudFreeTierQuotaBudgets {
+    /** Budget for the free tier's ~5-hour session window. Omit to skip tracking it. */
+    readonly session?: {
+        readonly maxTokens?: number;
+        readonly maxRequests?: number;
+    };
+    /** Budget for the free tier's 7-day weekly window. Omit to skip tracking it. */
+    readonly weekly?: {
+        readonly maxTokens?: number;
+        readonly maxRequests?: number;
+    };
+    readonly now?: () => number;
+}
+/**
+ * Convenience factory mirroring Ollama Cloud free-tier's documented reset cadence — a
+ * session window that resets every 5 hours and a weekly window that resets every 7 days
+ * (see https://ollama.com/pricing). Ollama does not publish the actual token/request
+ * ceilings for either window, so you must supply the budgets yourself (e.g. from your own
+ * observed usage) — this only wires up the window durations.
+ */
+declare function createOllamaCloudFreeTierQuota(budgets: OllamaCloudFreeTierQuotaBudgets): QuotaManager;
+
 /**
  * Zod schema conversion to JSON Schema for Ollama structured outputs.
  */
@@ -1041,4 +1461,19 @@ declare const ATTR_OLLAMA_AGENT_MAX_ITERATIONS = "ollama.agent.max_iterations";
 declare const ATTR_OLLAMA_AGENT_ITERATION = "ollama.agent.iteration";
 declare const GEN_AI_SYSTEM_OLLAMA = "ollama";
 
-export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, type AbortableAsyncIterable, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnthropicCacheControl, AnthropicCompatClient, type AnthropicContentBlock, type AnthropicMessage, type AnthropicMessagesRequest, type AnthropicMessagesResponse, AnyTool, type BackoffOptions, ChatRequestOptions, ChatResponse, type ChatStreamResult, CopyRequestOptions, CreateRequestOptions, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_FAILOVER_CODES, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type DefineToolOptions, DeleteRequestOptions, type DoneEvent, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, type ErrorEvent, type FetchLike, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, type GenerateStreamResult, type HttpBody, HttpClient, type HttpClientOptions, type HttpRequestOptions, type LifecycleErrorEvent, type LifecycleRetryEvent, type LifecycleStartEvent, type LifecycleSuccessEvent, type LoadMcpToolsOptions, type LogFn, type Logger, type McpCallToolResult, type McpClientLike, type McpContentBlock, type McpListToolsResult, type McpToolDescriptor, Message, type MessageEvent, type Middleware, type MiddlewareContext, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, type NextFunction, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAuthError, OllamaClient, type OllamaClientConfig, OllamaClientError, type OllamaClientErrorOptions, type OllamaEndpoint, type OllamaErrorRequestContext, type OllamaErrorResponseContext, OllamaGenericClientError, OllamaMcpError, OllamaNetworkError, OllamaNotFoundError, OllamaRateLimitError, OllamaServerError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, type OllamaStreamEvent, type OllamaStreamEventType, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, type OpenAIChatCompletionChoice, type OpenAIChatCompletionRequest, type OpenAIChatCompletionResponse, OpenAICompatClient, type OpenAIFunctionDefinition, type OpenAIListModelsResponse, type OpenAIMessage, type OpenAIModelItem, type OpenAIStreamOptions, type OpenAITool, type OpenAIToolCall, ProgressResponse, type ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, type RawUsageSource, type RequestContext, type RequestLifecycleEvent, type RequestLifecycleHook, type RequestRunner, type ResponseContext, type RetryConfig, type RuntimeMode, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type SupportedSchema, type ThinkingEvent, type TimeoutSignal, type TokenEvent, type TokenUsage, Tool, ToolCall, type ToolCallEvent, ToolDefinition, ToolExecutionResult, ToolHandler, ToolRegistry, VersionResponse, WebFetchRequestOptions, WebFetchResponse, WebSearchRequestOptions, WebSearchResponse, addSpanEvent, calculateBackoff, checkEndpointHealth, composeMiddleware, createConsoleLogger, createTimeoutSignal, defineTool, detectModelCapabilities, extractUsage, inferRuntimeMode, listAvailableModels, loadMcpTools, mapError, normalizeChatStream, normalizeGenerateStream, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
+/**
+ * Cross-runtime helpers with no Node.js API dependency, so they stay safe to import from
+ * the core client bundle (see ADR 0006 — Edge Runtime CI).
+ */
+/**
+ * Encodes an image to a base64 string, matching the wire format Ollama's `/api/chat` and
+ * `/api/generate` `images` arrays expect.
+ *
+ * - A `string` is assumed to already be base64-encoded and is returned unchanged.
+ * - A `Uint8Array` is base64-encoded using whichever universal primitive the runtime
+ *   exposes: `Buffer` on Node.js, `btoa` on browsers/Edge runtimes. Chunked so it doesn't
+ *   blow the engine's max call-stack/argument-count limits on large images.
+ */
+declare function encodeImage(image: Uint8Array | string): Promise<string>;
+
+export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, type AbortableAsyncIterable, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnthropicCacheControl, AnthropicCompatClient, type AnthropicContentBlock, type AnthropicMessage, type AnthropicMessagesRequest, type AnthropicMessagesResponse, AnyTool, type BackoffOptions, ChatRequestOptions, ChatResponse, type ChatStreamResult, CopyRequestOptions, CreateRequestOptions, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_FAILOVER_CODES, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type DefineToolOptions, DeleteRequestOptions, type DoneEvent, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, type ErrorEvent, type FetchLike, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, type GenerateStreamResult, type HttpBody, HttpClient, type HttpClientOptions, type HttpRequestOptions, type LifecycleErrorEvent, type LifecycleRetryEvent, type LifecycleStartEvent, type LifecycleSuccessEvent, type LoadMcpToolsOptions, type LogFn, type Logger, type McpCallToolResult, type McpClientLike, type McpContentBlock, type McpListToolsResult, type McpToolDescriptor, Message, type MessageEvent, type Middleware, type MiddlewareContext, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, type NextFunction, OLLAMA_CLOUD_BASE_URL, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAuthError, OllamaClient, type OllamaClientConfig, OllamaClientError, type OllamaClientErrorOptions, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, type OllamaErrorRequestContext, type OllamaErrorResponseContext, OllamaGenericClientError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaServerError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, type OllamaStreamEvent, type OllamaStreamEventType, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, type OpenAIChatCompletionChoice, type OpenAIChatCompletionRequest, type OpenAIChatCompletionResponse, OpenAICompatClient, type OpenAIFunctionDefinition, type OpenAIListModelsResponse, type OpenAIMessage, type OpenAIModelItem, type OpenAIResponsesOutputMessage, type OpenAIResponsesOutputTextContent, type OpenAIResponsesRequest, type OpenAIResponsesResponse, type OpenAIStreamOptions, type OpenAITool, type OpenAIToolCall, ProgressResponse, type ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, type RawUsageSource, type RequestContext, type RequestLifecycleEvent, type RequestLifecycleHook, type RequestRunner, type ResponseContext, type RetryConfig, type RuntimeMode, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type SupportedSchema, type ThinkingEvent, type TimeoutSignal, type TokenEvent, type TokenUsage, Tool, ToolCall, type ToolCallEvent, ToolDefinition, ToolExecutionResult, ToolHandler, ToolRegistry, VersionResponse, WebFetchRequestOptions, WebFetchResponse, WebSearchRequestOptions, WebSearchResponse, addSpanEvent, calculateBackoff, checkEndpointHealth, composeMiddleware, createConsoleLogger, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, encodeImage, extractUsage, inferRuntimeMode, listAvailableModels, loadMcpTools, mapError, normalizeChatStream, normalizeGenerateStream, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveCredentialEndpoints, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };