@nemesis-oss/ollama-sdk 1.7.0 → 1.8.0

package/dist/{runtime-qwD72cpn.d.ts → runtime-C6UYtBRB.d.ts}

@@ -195,6 +195,61 @@ declare class OllamaRequestValidationError extends OllamaClientError {
         issues: readonly z.ZodIssue[];
     });
 }
+/**
+ * Thrown by `OllamaRuntime.invoke` BEFORE any HTTP request is made when the
+ * serialized request body exceeds the operation's declared
+ * `constraints.maxRequestBytes`. The Ollama server returns 413 for such
+ * payloads; this client-side check fails fast so the round-trip is avoided.
+ *
+ * Wave 12 (P0 #5): the IR has carried `maxRequestBytes` for System One
+ * (64 KiB) since v1.7.0, but the runtime never enforced it. This closes
+ * that contract/runtime gap.
+ */
+declare class OllamaRequestTooLargeError extends OllamaClientError {
+    readonly operationId: string;
+    readonly actualBytes: number;
+    readonly maxBytes: number;
+    constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code' | 'retryable' | 'status'> & {
+        operationId: string;
+        actualBytes: number;
+        maxBytes: number;
+    });
+}
+/**
+ * Thrown by `OllamaRuntime.invoke` AFTER the HTTP response is received
+ * when `validateResponses: true` is set and the response body fails Zod
+ * validation against the operation's registered response schema.
+ *
+ * Wave 13: the runtime previously never validated responses (see ADR
+ * 0020). This opt-in error gives callers a way to detect wire-format
+ * mismatches for operations where typed response semantics are critical
+ * (e.g. System One). The error carries the original Zod issues so
+ * callers can inspect which fields failed.
+ */
+declare class OllamaResponseValidationError extends OllamaClientError {
+    readonly operationId: string;
+    readonly issues: readonly z.ZodIssue[];
+    constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code' | 'retryable'> & {
+        operationId: string;
+        issues: readonly z.ZodIssue[];
+    });
+}
+/**
+ * Thrown by `OllamaRuntime.invoke` BEFORE any HTTP request is made when the
+ * operation declares `constraints.minOllamaVersion` and the runtime could
+ * not obtain a server version to compare against (e.g. `enforceVersion:
+ * 'strict'` was set and `/api/version` was unreachable). Distinct from
+ * {@link OllamaGenericClientError} so callers can branch on the failure
+ * mode rather than parsing the message.
+ */
+declare class OllamaServerVersionUnknownError extends OllamaClientError {
+    readonly operationId: string;
+    readonly minRequiredVersion: string;
+    constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code' | 'retryable'> & {
+        operationId: string;
+        minRequiredVersion: string;
+    });
+}
 declare class OllamaToolTimeoutError extends OllamaClientError {
     readonly toolName: string;
     readonly timeoutMs: number;
@@ -494,6 +549,21 @@ type CapabilitySupport = 'supported' | 'unsupported' | 'model-dependent' | 'vers
 interface SchemaRef {
     readonly $ref: string;
 }
+/**
+ * Wave 15 (P0): structural parameter on an operation. Mirrors
+ * {@link OperationParameter} from the canonical IR. Path parameters
+ * are substituted into the operation's path template at runtime;
+ * query and header parameters are attached to the HTTP request.
+ */
+interface OperationParameter {
+    readonly name: string;
+    readonly in: 'path' | 'query' | 'header';
+    readonly required: boolean;
+    readonly schema?: {
+        readonly type?: string;
+    };
+    readonly description?: string;
+}
 /** Behavioral contract a generated operation carries into the runtime. */
 interface OperationDefinition {
     readonly operationId: string;
@@ -505,6 +575,25 @@ interface OperationDefinition {
         readonly local: boolean;
         readonly cloud: boolean;
     };
+    /**
+     * Wave 12 (P1 #7): host this operation targets, when different from
+     * the runtime's default HttpClient base URL. Cloud-hosted capability
+     * endpoints (web search, web fetch) live at `https://ollama.com/api/...`
+     * rather than the local Ollama server. The runtime rejects operations
+     * with a non-default host when the runtime's HttpClient isn't
+     * configured for that host — callers must use OllamaClient.webSearch /
+     * OllamaClient.webFetch (which spin up a dedicated cloud HttpClient)
+     * for these operations.
+     */
+    readonly host?: string;
+    /**
+     * Wave 15 (P0): structural parameters derived from the path template
+     * and OpenAPI declarations. Path parameters are substituted into the
+     * URL at runtime; query and header parameters are attached to the
+     * HTTP request. The runtime uses this to URI-encode and substitute
+     * `{name}` segments in the path.
+     */
+    readonly parameters?: readonly OperationParameter[];
     readonly transport: {
         readonly mode: TransportMode;
         readonly streaming: boolean;
@@ -521,6 +610,8 @@ interface OperationDefinition {
     readonly constraints?: {
         readonly minOllamaVersion?: string;
         readonly maxRequestBytes?: number;
+        /** Wave 13: limit when body contains images (e.g. System One: 32 MiB). */
+        readonly maxRequestBytesWithImages?: number;
     };
     readonly status: {
         readonly documented: boolean;
@@ -544,6 +635,28 @@ interface InvokeRequest {
      * doesn't explicitly set `stream`.
      */
     readonly streamingDefault?: boolean;
+    /**
+     * Wave 15 (P0): path parameter values keyed by parameter name. The
+     * runtime substitutes these into the operation's path template
+     * (e.g. `{model}` → `gpt-4`) with URI encoding.
+     */
+    readonly pathParams?: Readonly<Record<string, string>>;
+    /**
+     * Wave 15 (P0): query parameter values keyed by parameter name.
+     * The runtime attaches these to the HTTP request URL.
+     */
+    readonly queryParams?: Readonly<Record<string, string>>;
+    /**
+     * Wave 15 (P0): header parameter values keyed by header name.
+     * The runtime attaches these to the HTTP request headers.
+     */
+    readonly headerParams?: Readonly<Record<string, string>>;
+    /**
+     * Wave 15 (P1): model name for routing. Extracted from the request
+     * body when possible; used by the failover layer to filter endpoints
+     * by `OllamaEndpoint.models` (credential-scoped routing).
+     */
+    readonly model?: string;
 }
 
 /**
@@ -570,9 +683,30 @@ interface InvokeRequest {
  * existing HttpClient.
  */
 
+/**
+ * Minimal HTTP client surface the runtime consumes. Either a full
+ * {@link HttpClient} or a {@link FailoverHttpClient} — the runtime only
+ * calls `request()`.
+ *
+ * Wave 14: widened from `HttpClient` to allow the failover-aware wrapper
+ * without breaking existing callers that pass a plain HttpClient.
+ */
+type RuntimeHttpBackend = Pick<HttpClient, 'baseUrl' | 'request'>;
 /** Constructor options for {@link OllamaRuntime}. */
 interface OllamaRuntimeOptions {
-    readonly http: HttpClient;
+    readonly http: RuntimeHttpBackend;
+    /**
+     * Wave 15 (P0): HTTP backend for operations that declare a non-default
+     * `host` (e.g. web search/fetch at `https://ollama.com`). When an
+     * operation has `host: 'https://ollama.com'` and `cloudHttp` is
+     * configured, the runtime routes the request through this backend
+     * instead of the default `http`. When `cloudHttp` is not configured
+     * and a host-bearing operation is invoked, the runtime throws.
+     *
+     * OllamaClient.runtime sets this to a dedicated cloud HttpClient
+     * pointed at `https://ollama.com` with the configured API key.
+     */
+    readonly cloudHttp?: RuntimeHttpBackend;
     /**
      * Whether this runtime is targeting a local Ollama instance. Defaults to
      * `true`. When `false`, operations marked `environment.cloud === false`
@@ -583,6 +717,10 @@ interface OllamaRuntimeOptions {
      * Server version, if known (typically from a prior `/api/version` call).
      * When set, operations with `constraints.minOllamaVersion` are checked
      * against this value at request time.
+     *
+     * Wave 12 (P0 #5): when unset, the runtime will lazily fetch and cache
+     * the server version the first time a version-gated operation is
+     * invoked. The fetch policy is controlled by {@link enforceVersion}.
      */
     readonly serverVersion?: string;
     /**
@@ -601,15 +739,75 @@ interface OllamaRuntimeOptions {
      *     `/v1/systemone`, OpenAI/Anthropic compat surfaces), validation is
      *     skipped silently.
      *
-     * Response validation is intentionally NOT enabled — see ADR 0020 for
-     * the rationale (forward-compat with wire-format extensions).
+     * Response validation is intentionally NOT enabled by default — see
+     * ADR 0020 for the rationale (forward-compat with wire-format
+     * extensions).
+     *
+     * Wave 13: an opt-in `validateResponses` option is now available for
+     * operations where typed response semantics are the entire point
+     * (e.g. System One). When enabled, the runtime validates the HTTP
+     * response body against the operation's registered response schema
+     * before returning it to the caller. On failure, throws
+     * {@link OllamaResponseValidationError}.
      */
     readonly validateRequests?: boolean;
+    /**
+     * Wave 13: when `true`, the runtime validates every response body
+     * against the operation's registered response schema before returning
+     * it. Defaults to `false` — opt-in. Only operations with a registered
+     * response schema are validated; others pass through unchanged.
+     *
+     * On validation failure, throws {@link OllamaResponseValidationError}
+     * with the Zod issues attached. The HTTP response is still consumed.
+     *
+     * Use this for operations where typed response semantics are critical
+     * (System One, structured output). Don't enable globally — legitimate
+     * forward-compat wire-format extensions would cause false rejections.
+     */
+    readonly validateResponses?: boolean;
+    /**
+     * Policy for enforcing `constraints.minOllamaVersion` when
+     * {@link serverVersion} is not explicitly supplied.
+     *
+     *   - `'auto'` (default): lazily fetch `/api/version` once and cache the
+     *     result; subsequent version-gated invocations reuse the cached
+     *     value. If the fetch fails, the operation is allowed through
+     *     (fail-open) — the server will reject it if it truly doesn't
+     *     support it.
+     *   - `'strict'`: same as `'auto'`, but if the version fetch fails the
+     *     invocation throws {@link OllamaServerVersionUnknownError} rather
+     *     than fail-open. Use this when the caller wants hard guarantees
+     *     that a version-gated operation will not be sent to a server that
+     *     can't handle it.
+     *   - `'off'`: never fetch `/api/version` automatically. The runtime
+     *     only enforces the version constraint when {@link serverVersion}
+     *     was explicitly supplied. Useful in tests that mock fetch and want
+     *     to avoid spurious version probes.
+     */
+    readonly enforceVersion?: 'auto' | 'strict' | 'off';
 }
 /** The runtime seam. */
 declare class OllamaRuntime {
     private readonly options;
+    /**
+     * Cached promise of the Ollama server version, populated lazily the first
+     * time a version-gated operation is invoked. `undefined` until then.
+     *
+     * Wave 12 (P0 #5): see {@link OllamaRuntimeOptions.enforceVersion}.
+     */
+    private serverVersionCache;
     constructor(options: OllamaRuntimeOptions);
+    /**
+     * Wave 15 (P0): resolve the HTTP backend for a given operation.
+     *
+     * Operations with a declared `host` (e.g. web search/fetch at
+     * https://ollama.com) must route to a HttpClient pointed at that host,
+     * not the default one. The runtime accepts an optional `cloudHttp`
+     * backend for this purpose — if the operation declares a host and no
+     * cloud backend is configured, the runtime throws rather than silently
+     * sending the request to the wrong server.
+     */
+    private resolveHttpBackend;
     /**
      * Invoke an operation. Called by every generated API method.
      *
@@ -618,6 +816,22 @@ declare class OllamaRuntime {
      * class's overloads pick the right return type at compile time.
      */
     invoke<T = unknown>(req: InvokeRequest): Promise<T>;
+    /**
+     * Apply environment + version guards before delegating to HttpClient.
+     *
+     * Throws {@link OllamaGenericClientError} when:
+     *   - The operation is local-only and the runtime is in cloud mode.
+     *   - The operation has `constraints.minOllamaVersion` and the server is older.
+     *
+     * Wave 12 (P0 #5): when `minOllamaVersion` is declared but the runtime's
+     * `serverVersion` is unknown AND `enforceVersion` is `'auto'` or
+     * `'strict'`, the runtime lazily fetches `/api/version` (cached on the
+     * runtime instance) so the constraint is actually enforced even when the
+     * caller didn't supply it. Previously the constraint was only enforced
+     * when `serverVersion` was manually supplied — meaning in practice it was
+     * almost never enforced.
+     */
+    private assertOperationAllowed;
 }
 
-export { OllamaServerError as $, type AbortableAsyncIterable as A, type BinaryBody as B, type ChatStreamResult as C, type DoneEvent as D, type ErrorEvent as E, type FetchLike as F, type GenerateStreamResult as G, HttpClient as H, type InvokeRequest as I, type OllamaErrorResponseContext as J, OllamaGenericClientError as K, type Logger as L, type Middleware as M, NANOS_PER_MS as N, OllamaRuntime as O, type ProgressStreamResult as P, OllamaIncompatibleModelError as Q, type RequestLifecycleHook as R, type SchemaRef as S, type TokenUsage as T, OllamaMcpError as U, OllamaModelRoutingError as V, OllamaNetworkError as W, OllamaNotFoundError as X, OllamaQuotaExceededError as Y, OllamaRateLimitError as Z, OllamaRequestValidationError as _, type OperationDefinition as a, OllamaSkillInvalidError as a0, OllamaSkillNotFoundError as a1, OllamaTimeoutError as a2, OllamaToolTimeoutError as a3, OllamaToolValidationError as a4, OllamaUnsupportedCapabilityError as a5, type RequestContext as a6, type RequestLifecycleEvent as a7, type ResponseContext as a8, type ThinkingEvent as a9, type TokenEvent as aa, type ToolCallEvent as ab, composeMiddleware as ac, createConsoleLogger as ad, extractUsage as ae, mapError as af, parseSseStream as ag, type OllamaRuntimeOptions as b, type OllamaStreamEvent as c, type OllamaStreamEventType as d, type SseEvent as e, OllamaClientError as f, type RawUsageSource as g, type HttpBody as h, type HttpClientOptions as i, type HttpRequestOptions as j, type LifecycleErrorEvent as k, type LifecycleRetryEvent as l, type LifecycleStartEvent as m, type LifecycleSuccessEvent as n, type LogFn as o, type MessageEvent as p, type MiddlewareContext as q, NANOS_PER_SECOND as r, NOOP_LOGGER as s, type NextFunction as t, OllamaAbortError as u, OllamaAgentMaxIterationsError as v, OllamaAgentMaxToolCallsError as w, OllamaAuthError as x, type OllamaClientErrorOptions as y, type OllamaErrorRequestContext as z };
+export { OllamaResponseValidationError as $, type AbortableAsyncIterable as A, type BinaryBody as B, type ChatStreamResult as C, type DoneEvent as D, type ErrorEvent as E, type FetchLike as F, type GenerateStreamResult as G, HttpClient as H, type InvokeRequest as I, OllamaGenericClientError as J, OllamaIncompatibleModelError as K, type Logger as L, type Middleware as M, NANOS_PER_MS as N, OllamaRuntime as O, type ProgressStreamResult as P, OllamaMcpError as Q, type RequestLifecycleHook as R, type SchemaRef as S, type TokenUsage as T, OllamaModelRoutingError as U, OllamaNetworkError as V, OllamaNotFoundError as W, OllamaQuotaExceededError as X, OllamaRateLimitError as Y, OllamaRequestTooLargeError as Z, OllamaRequestValidationError as _, type OperationDefinition as a, OllamaServerError as a0, OllamaServerVersionUnknownError as a1, OllamaSkillInvalidError as a2, OllamaSkillNotFoundError as a3, OllamaTimeoutError as a4, OllamaToolTimeoutError as a5, OllamaToolValidationError as a6, OllamaUnsupportedCapabilityError as a7, type RequestContext as a8, type RequestLifecycleEvent as a9, type ResponseContext as aa, type SseEvent as ab, type ThinkingEvent as ac, type TokenEvent as ad, type ToolCallEvent as ae, composeMiddleware as af, createConsoleLogger as ag, extractUsage as ah, mapError as ai, parseSseStream as aj, type OllamaRuntimeOptions as b, type OllamaStreamEvent as c, type OllamaStreamEventType as d, type RawUsageSource as e, type HttpBody as f, type HttpClientOptions as g, type HttpRequestOptions as h, type LifecycleErrorEvent as i, type LifecycleRetryEvent as j, type LifecycleStartEvent as k, type LifecycleSuccessEvent as l, type LogFn as m, type MessageEvent as n, type MiddlewareContext as o, NANOS_PER_SECOND as p, NOOP_LOGGER as q, type NextFunction as r, OllamaAbortError as s, OllamaAgentMaxIterationsError as t, OllamaAgentMaxToolCallsError as u, OllamaAuthError as v, OllamaClientError as w, type OllamaClientErrorOptions as x, type OllamaErrorRequestContext as y, type OllamaErrorResponseContext as z };

package/dist/{runtime-bQ48I-RC.d.cts → runtime-DTmUeU6K.d.cts}

@@ -195,6 +195,61 @@ declare class OllamaRequestValidationError extends OllamaClientError {
         issues: readonly z.ZodIssue[];
     });
 }
+/**
+ * Thrown by `OllamaRuntime.invoke` BEFORE any HTTP request is made when the
+ * serialized request body exceeds the operation's declared
+ * `constraints.maxRequestBytes`. The Ollama server returns 413 for such
+ * payloads; this client-side check fails fast so the round-trip is avoided.
+ *
+ * Wave 12 (P0 #5): the IR has carried `maxRequestBytes` for System One
+ * (64 KiB) since v1.7.0, but the runtime never enforced it. This closes
+ * that contract/runtime gap.
+ */
+declare class OllamaRequestTooLargeError extends OllamaClientError {
+    readonly operationId: string;
+    readonly actualBytes: number;
+    readonly maxBytes: number;
+    constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code' | 'retryable' | 'status'> & {
+        operationId: string;
+        actualBytes: number;
+        maxBytes: number;
+    });
+}
+/**
+ * Thrown by `OllamaRuntime.invoke` AFTER the HTTP response is received
+ * when `validateResponses: true` is set and the response body fails Zod
+ * validation against the operation's registered response schema.
+ *
+ * Wave 13: the runtime previously never validated responses (see ADR
+ * 0020). This opt-in error gives callers a way to detect wire-format
+ * mismatches for operations where typed response semantics are critical
+ * (e.g. System One). The error carries the original Zod issues so
+ * callers can inspect which fields failed.
+ */
+declare class OllamaResponseValidationError extends OllamaClientError {
+    readonly operationId: string;
+    readonly issues: readonly z.ZodIssue[];
+    constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code' | 'retryable'> & {
+        operationId: string;
+        issues: readonly z.ZodIssue[];
+    });
+}
+/**
+ * Thrown by `OllamaRuntime.invoke` BEFORE any HTTP request is made when the
+ * operation declares `constraints.minOllamaVersion` and the runtime could
+ * not obtain a server version to compare against (e.g. `enforceVersion:
+ * 'strict'` was set and `/api/version` was unreachable). Distinct from
+ * {@link OllamaGenericClientError} so callers can branch on the failure
+ * mode rather than parsing the message.
+ */
+declare class OllamaServerVersionUnknownError extends OllamaClientError {
+    readonly operationId: string;
+    readonly minRequiredVersion: string;
+    constructor(message: string, options: Omit<OllamaClientErrorOptions, 'code' | 'retryable'> & {
+        operationId: string;
+        minRequiredVersion: string;
+    });
+}
 declare class OllamaToolTimeoutError extends OllamaClientError {
     readonly toolName: string;
     readonly timeoutMs: number;
@@ -494,6 +549,21 @@ type CapabilitySupport = 'supported' | 'unsupported' | 'model-dependent' | 'vers
 interface SchemaRef {
     readonly $ref: string;
 }
+/**
+ * Wave 15 (P0): structural parameter on an operation. Mirrors
+ * {@link OperationParameter} from the canonical IR. Path parameters
+ * are substituted into the operation's path template at runtime;
+ * query and header parameters are attached to the HTTP request.
+ */
+interface OperationParameter {
+    readonly name: string;
+    readonly in: 'path' | 'query' | 'header';
+    readonly required: boolean;
+    readonly schema?: {
+        readonly type?: string;
+    };
+    readonly description?: string;
+}
 /** Behavioral contract a generated operation carries into the runtime. */
 interface OperationDefinition {
     readonly operationId: string;
@@ -505,6 +575,25 @@ interface OperationDefinition {
         readonly local: boolean;
         readonly cloud: boolean;
     };
+    /**
+     * Wave 12 (P1 #7): host this operation targets, when different from
+     * the runtime's default HttpClient base URL. Cloud-hosted capability
+     * endpoints (web search, web fetch) live at `https://ollama.com/api/...`
+     * rather than the local Ollama server. The runtime rejects operations
+     * with a non-default host when the runtime's HttpClient isn't
+     * configured for that host — callers must use OllamaClient.webSearch /
+     * OllamaClient.webFetch (which spin up a dedicated cloud HttpClient)
+     * for these operations.
+     */
+    readonly host?: string;
+    /**
+     * Wave 15 (P0): structural parameters derived from the path template
+     * and OpenAPI declarations. Path parameters are substituted into the
+     * URL at runtime; query and header parameters are attached to the
+     * HTTP request. The runtime uses this to URI-encode and substitute
+     * `{name}` segments in the path.
+     */
+    readonly parameters?: readonly OperationParameter[];
     readonly transport: {
         readonly mode: TransportMode;
         readonly streaming: boolean;
@@ -521,6 +610,8 @@ interface OperationDefinition {
     readonly constraints?: {
         readonly minOllamaVersion?: string;
         readonly maxRequestBytes?: number;
+        /** Wave 13: limit when body contains images (e.g. System One: 32 MiB). */
+        readonly maxRequestBytesWithImages?: number;
     };
     readonly status: {
         readonly documented: boolean;
@@ -544,6 +635,28 @@ interface InvokeRequest {
      * doesn't explicitly set `stream`.
      */
     readonly streamingDefault?: boolean;
+    /**
+     * Wave 15 (P0): path parameter values keyed by parameter name. The
+     * runtime substitutes these into the operation's path template
+     * (e.g. `{model}` → `gpt-4`) with URI encoding.
+     */
+    readonly pathParams?: Readonly<Record<string, string>>;
+    /**
+     * Wave 15 (P0): query parameter values keyed by parameter name.
+     * The runtime attaches these to the HTTP request URL.
+     */
+    readonly queryParams?: Readonly<Record<string, string>>;
+    /**
+     * Wave 15 (P0): header parameter values keyed by header name.
+     * The runtime attaches these to the HTTP request headers.
+     */
+    readonly headerParams?: Readonly<Record<string, string>>;
+    /**
+     * Wave 15 (P1): model name for routing. Extracted from the request
+     * body when possible; used by the failover layer to filter endpoints
+     * by `OllamaEndpoint.models` (credential-scoped routing).
+     */
+    readonly model?: string;
 }
 
 /**
@@ -570,9 +683,30 @@ interface InvokeRequest {
  * existing HttpClient.
  */
 
+/**
+ * Minimal HTTP client surface the runtime consumes. Either a full
+ * {@link HttpClient} or a {@link FailoverHttpClient} — the runtime only
+ * calls `request()`.
+ *
+ * Wave 14: widened from `HttpClient` to allow the failover-aware wrapper
+ * without breaking existing callers that pass a plain HttpClient.
+ */
+type RuntimeHttpBackend = Pick<HttpClient, 'baseUrl' | 'request'>;
 /** Constructor options for {@link OllamaRuntime}. */
 interface OllamaRuntimeOptions {
-    readonly http: HttpClient;
+    readonly http: RuntimeHttpBackend;
+    /**
+     * Wave 15 (P0): HTTP backend for operations that declare a non-default
+     * `host` (e.g. web search/fetch at `https://ollama.com`). When an
+     * operation has `host: 'https://ollama.com'` and `cloudHttp` is
+     * configured, the runtime routes the request through this backend
+     * instead of the default `http`. When `cloudHttp` is not configured
+     * and a host-bearing operation is invoked, the runtime throws.
+     *
+     * OllamaClient.runtime sets this to a dedicated cloud HttpClient
+     * pointed at `https://ollama.com` with the configured API key.
+     */
+    readonly cloudHttp?: RuntimeHttpBackend;
     /**
      * Whether this runtime is targeting a local Ollama instance. Defaults to
      * `true`. When `false`, operations marked `environment.cloud === false`
@@ -583,6 +717,10 @@ interface OllamaRuntimeOptions {
      * Server version, if known (typically from a prior `/api/version` call).
      * When set, operations with `constraints.minOllamaVersion` are checked
      * against this value at request time.
+     *
+     * Wave 12 (P0 #5): when unset, the runtime will lazily fetch and cache
+     * the server version the first time a version-gated operation is
+     * invoked. The fetch policy is controlled by {@link enforceVersion}.
      */
     readonly serverVersion?: string;
     /**
@@ -601,15 +739,75 @@ interface OllamaRuntimeOptions {
      *     `/v1/systemone`, OpenAI/Anthropic compat surfaces), validation is
      *     skipped silently.
      *
-     * Response validation is intentionally NOT enabled — see ADR 0020 for
-     * the rationale (forward-compat with wire-format extensions).
+     * Response validation is intentionally NOT enabled by default — see
+     * ADR 0020 for the rationale (forward-compat with wire-format
+     * extensions).
+     *
+     * Wave 13: an opt-in `validateResponses` option is now available for
+     * operations where typed response semantics are the entire point
+     * (e.g. System One). When enabled, the runtime validates the HTTP
+     * response body against the operation's registered response schema
+     * before returning it to the caller. On failure, throws
+     * {@link OllamaResponseValidationError}.
      */
     readonly validateRequests?: boolean;
+    /**
+     * Wave 13: when `true`, the runtime validates every response body
+     * against the operation's registered response schema before returning
+     * it. Defaults to `false` — opt-in. Only operations with a registered
+     * response schema are validated; others pass through unchanged.
+     *
+     * On validation failure, throws {@link OllamaResponseValidationError}
+     * with the Zod issues attached. The HTTP response is still consumed.
+     *
+     * Use this for operations where typed response semantics are critical
+     * (System One, structured output). Don't enable globally — legitimate
+     * forward-compat wire-format extensions would cause false rejections.
+     */
+    readonly validateResponses?: boolean;
+    /**
+     * Policy for enforcing `constraints.minOllamaVersion` when
+     * {@link serverVersion} is not explicitly supplied.
+     *
+     *   - `'auto'` (default): lazily fetch `/api/version` once and cache the
+     *     result; subsequent version-gated invocations reuse the cached
+     *     value. If the fetch fails, the operation is allowed through
+     *     (fail-open) — the server will reject it if it truly doesn't
+     *     support it.
+     *   - `'strict'`: same as `'auto'`, but if the version fetch fails the
+     *     invocation throws {@link OllamaServerVersionUnknownError} rather
+     *     than fail-open. Use this when the caller wants hard guarantees
+     *     that a version-gated operation will not be sent to a server that
+     *     can't handle it.
+     *   - `'off'`: never fetch `/api/version` automatically. The runtime
+     *     only enforces the version constraint when {@link serverVersion}
+     *     was explicitly supplied. Useful in tests that mock fetch and want
+     *     to avoid spurious version probes.
+     */
+    readonly enforceVersion?: 'auto' | 'strict' | 'off';
 }
 /** The runtime seam. */
 declare class OllamaRuntime {
     private readonly options;
+    /**
+     * Cached promise of the Ollama server version, populated lazily the first
+     * time a version-gated operation is invoked. `undefined` until then.
+     *
+     * Wave 12 (P0 #5): see {@link OllamaRuntimeOptions.enforceVersion}.
+     */
+    private serverVersionCache;
     constructor(options: OllamaRuntimeOptions);
+    /**
+     * Wave 15 (P0): resolve the HTTP backend for a given operation.
+     *
+     * Operations with a declared `host` (e.g. web search/fetch at
+     * https://ollama.com) must route to a HttpClient pointed at that host,
+     * not the default one. The runtime accepts an optional `cloudHttp`
+     * backend for this purpose — if the operation declares a host and no
+     * cloud backend is configured, the runtime throws rather than silently
+     * sending the request to the wrong server.
+     */
+    private resolveHttpBackend;
     /**
      * Invoke an operation. Called by every generated API method.
      *
@@ -618,6 +816,22 @@ declare class OllamaRuntime {
      * class's overloads pick the right return type at compile time.
      */
     invoke<T = unknown>(req: InvokeRequest): Promise<T>;
+    /**
+     * Apply environment + version guards before delegating to HttpClient.
+     *
+     * Throws {@link OllamaGenericClientError} when:
+     *   - The operation is local-only and the runtime is in cloud mode.
+     *   - The operation has `constraints.minOllamaVersion` and the server is older.
+     *
+     * Wave 12 (P0 #5): when `minOllamaVersion` is declared but the runtime's
+     * `serverVersion` is unknown AND `enforceVersion` is `'auto'` or
+     * `'strict'`, the runtime lazily fetches `/api/version` (cached on the
+     * runtime instance) so the constraint is actually enforced even when the
+     * caller didn't supply it. Previously the constraint was only enforced
+     * when `serverVersion` was manually supplied — meaning in practice it was
+     * almost never enforced.
+     */
+    private assertOperationAllowed;
 }
 
-export { OllamaServerError as $, type AbortableAsyncIterable as A, type BinaryBody as B, type ChatStreamResult as C, type DoneEvent as D, type ErrorEvent as E, type FetchLike as F, type GenerateStreamResult as G, HttpClient as H, type InvokeRequest as I, type OllamaErrorResponseContext as J, OllamaGenericClientError as K, type Logger as L, type Middleware as M, NANOS_PER_MS as N, OllamaRuntime as O, type ProgressStreamResult as P, OllamaIncompatibleModelError as Q, type RequestLifecycleHook as R, type SchemaRef as S, type TokenUsage as T, OllamaMcpError as U, OllamaModelRoutingError as V, OllamaNetworkError as W, OllamaNotFoundError as X, OllamaQuotaExceededError as Y, OllamaRateLimitError as Z, OllamaRequestValidationError as _, type OperationDefinition as a, OllamaSkillInvalidError as a0, OllamaSkillNotFoundError as a1, OllamaTimeoutError as a2, OllamaToolTimeoutError as a3, OllamaToolValidationError as a4, OllamaUnsupportedCapabilityError as a5, type RequestContext as a6, type RequestLifecycleEvent as a7, type ResponseContext as a8, type ThinkingEvent as a9, type TokenEvent as aa, type ToolCallEvent as ab, composeMiddleware as ac, createConsoleLogger as ad, extractUsage as ae, mapError as af, parseSseStream as ag, type OllamaRuntimeOptions as b, type OllamaStreamEvent as c, type OllamaStreamEventType as d, type SseEvent as e, OllamaClientError as f, type RawUsageSource as g, type HttpBody as h, type HttpClientOptions as i, type HttpRequestOptions as j, type LifecycleErrorEvent as k, type LifecycleRetryEvent as l, type LifecycleStartEvent as m, type LifecycleSuccessEvent as n, type LogFn as o, type MessageEvent as p, type MiddlewareContext as q, NANOS_PER_SECOND as r, NOOP_LOGGER as s, type NextFunction as t, OllamaAbortError as u, OllamaAgentMaxIterationsError as v, OllamaAgentMaxToolCallsError as w, OllamaAuthError as x, type OllamaClientErrorOptions as y, type OllamaErrorRequestContext as z };
+export { OllamaResponseValidationError as $, type AbortableAsyncIterable as A, type BinaryBody as B, type ChatStreamResult as C, type DoneEvent as D, type ErrorEvent as E, type FetchLike as F, type GenerateStreamResult as G, HttpClient as H, type InvokeRequest as I, OllamaGenericClientError as J, OllamaIncompatibleModelError as K, type Logger as L, type Middleware as M, NANOS_PER_MS as N, OllamaRuntime as O, type ProgressStreamResult as P, OllamaMcpError as Q, type RequestLifecycleHook as R, type SchemaRef as S, type TokenUsage as T, OllamaModelRoutingError as U, OllamaNetworkError as V, OllamaNotFoundError as W, OllamaQuotaExceededError as X, OllamaRateLimitError as Y, OllamaRequestTooLargeError as Z, OllamaRequestValidationError as _, type OperationDefinition as a, OllamaServerError as a0, OllamaServerVersionUnknownError as a1, OllamaSkillInvalidError as a2, OllamaSkillNotFoundError as a3, OllamaTimeoutError as a4, OllamaToolTimeoutError as a5, OllamaToolValidationError as a6, OllamaUnsupportedCapabilityError as a7, type RequestContext as a8, type RequestLifecycleEvent as a9, type ResponseContext as aa, type SseEvent as ab, type ThinkingEvent as ac, type TokenEvent as ad, type ToolCallEvent as ae, composeMiddleware as af, createConsoleLogger as ag, extractUsage as ah, mapError as ai, parseSseStream as aj, type OllamaRuntimeOptions as b, type OllamaStreamEvent as c, type OllamaStreamEventType as d, type RawUsageSource as e, type HttpBody as f, type HttpClientOptions as g, type HttpRequestOptions as h, type LifecycleErrorEvent as i, type LifecycleRetryEvent as j, type LifecycleStartEvent as k, type LifecycleSuccessEvent as l, type LogFn as m, type MessageEvent as n, type MiddlewareContext as o, NANOS_PER_SECOND as p, NOOP_LOGGER as q, type NextFunction as r, OllamaAbortError as s, OllamaAgentMaxIterationsError as t, OllamaAgentMaxToolCallsError as u, OllamaAuthError as v, OllamaClientError as w, type OllamaClientErrorOptions as x, type OllamaErrorRequestContext as y, type OllamaErrorResponseContext as z };