@dereekb/openrouter 13.37.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dereekb/openrouter",
+  "version": "13.37.0",
+  "exports": {
+    "./firebase": {
+      "module": "./firebase/index.esm.js",
+      "types": "./firebase/index.d.ts",
+      "import": "./firebase/index.cjs.mjs",
+      "default": "./firebase/index.cjs.js"
+    },
+    "./firebase-server": {
+      "module": "./firebase-server/index.esm.js",
+      "types": "./firebase-server/index.d.ts",
+      "import": "./firebase-server/index.cjs.mjs",
+      "default": "./firebase-server/index.cjs.js"
+    },
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "peerDependencies": {
+    "@dereekb/util": "13.37.0",
+    "@openrouter/sdk": "^1.2.26"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/src/lib/index.d.ts

@@ -0,0 +1,10 @@
+export * from './openrouter.call';
+export * from './openrouter.config';
+export * from './openrouter.embedding';
+export * from './openrouter.generation';
+export * from './openrouter.input';
+export * from './openrouter.prompt';
+export * from './openrouter.request';
+export * from './openrouter.sdk';
+export * from './openrouter.tool';
+export * from './openrouter.type';

package/src/lib/openrouter.call.d.ts

@@ -0,0 +1,268 @@
+import { type Maybe } from '@dereekb/util';
+import { type CallModelInput, type OpenResponsesResult, type OpenRouterCore, type RequestOptions, type StateAccessor, type Tool, ModelResult } from './openrouter.sdk';
+import { type OpenRouterHostedToolConfig, type OpenRouterModelConfig } from './openrouter.config';
+import { type OpenRouterPromptRequest } from './openrouter.request';
+import { type OpenRouterGenerationId, type OpenRouterRunError, type OpenRouterRunUsage } from './openrouter.type';
+/**
+ * A model config split into the part that goes on the request and the part that controls how the
+ * request is executed.
+ */
+export interface OpenRouterSplitModelConfig {
+    /**
+     * The parameters to spread onto the request.
+     */
+    readonly requestConfig: Record<string, unknown>;
+    /**
+     * Ceiling on tool-call steps, when the config set one.
+     */
+    readonly maxSteps?: Maybe<number>;
+    /**
+     * Per-request wall-clock timeout, when the config set one.
+     */
+    readonly requestTimeoutMs?: Maybe<number>;
+}
+/**
+ * Splits a model config into request parameters and execution controls.
+ *
+ * Forwarding one of ours is not harmless: OpenRouter validates the request body, so leaving `maxSteps` on
+ * it risks a 400 on the whole call. Which keys are ours is expressed by naming them in a rest-destructure
+ * rather than in a list of strings, so TypeScript checks the names against
+ * {@link OpenRouterModelConfig} and a rename cannot leave a stale entry behind.
+ *
+ * @param config - The merged model config.
+ * @returns The split config.
+ */
+export declare function splitOpenRouterModelConfig(config: Maybe<OpenRouterModelConfig>): OpenRouterSplitModelConfig;
+/**
+ * The hosted (server-executed) tool entries a config carries, e.g. `file_search`, `web_search`, `mcp`.
+ *
+ * These are NOT client tools and must never be handed to `callModel`: it destructures `tools` off the
+ * request and runs every entry through `convertToolsToAPIFormat`, which reads `tool.function.name` — so
+ * a hosted entry is dropped outright when no client tools are present and throws a
+ * `Cannot read properties of undefined` from inside the SDK when they are. They are dispatched instead
+ * by {@link sendOpenRouterResponsesRequest} or merged in after conversion by
+ * {@link openRouterModelResultForRequest}.
+ *
+ * @param config - The merged model config.
+ * @returns The hosted tool entries, or an empty array.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterHostedTools(config: Maybe<OpenRouterModelConfig>): OpenRouterHostedToolConfig[];
+/**
+ * A normalized result of one OpenRouter call.
+ *
+ * Deliberately flat and provider-agnostic: this is what a run task stores and what a caller reads,
+ * so it must not require the caller to walk the SDK's response union.
+ */
+export interface OpenRouterCallResult {
+    /**
+     * The output text.
+     */
+    readonly outputText?: Maybe<string>;
+    /**
+     * The output parsed as JSON, when it parsed as an object.
+     */
+    readonly outputJson?: Maybe<Record<string, unknown>>;
+    /**
+     * Generation ids produced by the call, for auditing via `getGeneration` / `listGenerationContent`.
+     *
+     * OpenRouter can reload a generation's output later, keyed by generation id — but that surface is
+     * tied to account logging settings (nothing is retained under ZDR / logging-disabled) and its
+     * retention is undocumented. Treat it as audit/debug, never the system of record.
+     */
+    readonly generationIds: OpenRouterGenerationId[];
+    /**
+     * Token/cost usage.
+     */
+    readonly usage?: Maybe<OpenRouterRunUsage>;
+    /**
+     * The model that actually served the request.
+     */
+    readonly model?: Maybe<string>;
+    /**
+     * The error reported by OpenRouter, when the response carried one.
+     */
+    readonly error?: Maybe<OpenRouterRunError>;
+    /**
+     * The raw response, for anything the normalized shape drops.
+     */
+    readonly response: OpenResponsesResult;
+}
+/**
+ * Params for {@link openRouterCallModelInput}.
+ */
+export interface OpenRouterCallModelInputParams<TTools extends readonly Tool[] = readonly Tool[]> {
+    /**
+     * The built request.
+     */
+    readonly request: OpenRouterPromptRequest;
+    /**
+     * Client-side tools to make available.
+     */
+    readonly tools?: Maybe<TTools>;
+    /**
+     * Conversation state backend, for a multi-step or deferred-tool run.
+     */
+    readonly state?: Maybe<StateAccessor<TTools>>;
+}
+/**
+ * Converts a built request into the `/responses` request body.
+ *
+ * This is the whole wire body minus the SDK-only keys (`tools`/`state`/`stopWhen` on the `callModel`
+ * path), so both dispatch paths assemble the request the same way and cannot drift.
+ *
+ * @param request - The built request.
+ * @returns The request body, in the SDK's camelCase request surface.
+ */
+export declare function openRouterResponsesRequestBody(request: OpenRouterPromptRequest): Record<string, unknown>;
+/**
+ * Converts a built request into the `callModel` input.
+ *
+ * Any hosted tools on the config are STRIPPED here rather than passed through: `callModel` owns the
+ * `tools` key and converts every entry as a client function tool. Hosted entries are re-attached after
+ * that conversion by {@link openRouterModelResultForRequest}.
+ *
+ * @param params - The request, tools, and state accessor.
+ * @returns The `callModel` input.
+ */
+export declare function openRouterCallModelInput<TTools extends readonly Tool[] = readonly Tool[]>(params: OpenRouterCallModelInputParams<TTools>): CallModelInput<TTools>;
+/**
+ * Params for {@link callModelForOpenRouterRequest}.
+ */
+export interface CallModelForOpenRouterRequestParams<TTools extends readonly Tool[] = readonly Tool[]> extends OpenRouterCallModelInputParams<TTools> {
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * Additional request options, merged under the config's `requestTimeoutMs`.
+     */
+    readonly options?: Maybe<RequestOptions>;
+}
+/**
+ * Header `callModel` stamps on every request it dispatches, so OpenRouter can tell an agent-loop request
+ * apart from a plain one. Replicated on the merged hosted-tool path, which is a `callModel` request in
+ * everything but the entry point.
+ */
+export declare const OPENROUTER_CALL_MODEL_HEADER = "x-openrouter-callmodel";
+/**
+ * Params for {@link sendOpenRouterResponsesRequest}.
+ */
+export interface SendOpenRouterResponsesRequestParams {
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * The built request.
+     */
+    readonly request: OpenRouterPromptRequest;
+    /**
+     * Additional request options, merged under the config's `requestTimeoutMs`.
+     */
+    readonly options?: Maybe<RequestOptions>;
+}
+/**
+ * Sends a built request straight to `/responses`, bypassing `callModel` entirely.
+ *
+ * This is the path hosted (server-executed) tools take. `callModel` cannot carry them — it converts
+ * every `tools` entry as a client function tool — and there is nothing for its loop to do on a run whose
+ * tools are executed upstream anyway. Going direct also keeps the response VERBATIM: the request is
+ * non-streaming, so the returned `OpenResponsesResult` is the body OpenRouter sent rather than one
+ * reassembled from stream events, which is what preserves hosted-tool output items such as a
+ * `file_search_call` and the chunks `include: ['file_search_call.results']` asked for.
+ *
+ * @param params - The client, request, and options.
+ * @returns The response.
+ * @throws {Error} When the request fails, or when a streaming response comes back for a non-streaming request.
+ */
+export declare function sendOpenRouterResponsesRequest(params: SendOpenRouterResponsesRequestParams): Promise<OpenResponsesResult>;
+/**
+ * Starts a call for a built request and returns the SDK's `ModelResult` without consuming it.
+ *
+ * Use this when the caller needs the streaming / tool-event surface. Most callers want
+ * {@link callModelForOpenRouterRequest}, which consumes the result into a normalized value.
+ *
+ * Hosted tools and client tools are NOT mutually exclusive here. When a config carries hosted tools this
+ * assembles the `ModelResult` itself — client tools converted to API format exactly as `callModel` would,
+ * with the hosted entries appended after that conversion — so a run can search a vector store AND drive
+ * the client-side tool loop. `callModel` cannot express that: it owns the `tools` key and there is no
+ * seam between its conversion and dispatch. Everything else about the run is unchanged, including the
+ * `x-openrouter-callmodel` header and the `stopWhen` step ceiling.
+ *
+ * @param params - The client, request, tools, state, and options.
+ * @returns The in-flight model result.
+ */
+export declare function openRouterModelResultForRequest<TTools extends readonly Tool[] = readonly Tool[]>(params: CallModelForOpenRouterRequestParams<TTools>): ModelResult<TTools>;
+/**
+ * Runs a built request to completion and normalizes the response.
+ *
+ * Routes to the direct `/responses` path for a hosted-tool run that needs no client-side tool loop, and
+ * to `ModelResult` otherwise. The caller does not choose: which transport a request needs is a property
+ * of the request, and making it a parameter would only create a way to get it wrong.
+ *
+ * @param params - The client, request, tools, state, and options.
+ * @returns The normalized call result.
+ */
+export declare function callModelForOpenRouterRequest<TTools extends readonly Tool[] = readonly Tool[]>(params: CallModelForOpenRouterRequestParams<TTools>): Promise<OpenRouterCallResult>;
+/**
+ * Normalizes an OpenRouter response into an {@link OpenRouterCallResult}.
+ *
+ * @param response - The response to normalize.
+ * @returns The normalized result.
+ */
+export declare function openRouterCallResultFromResponse(response: OpenResponsesResult): OpenRouterCallResult;
+/**
+ * Reads the assistant text out of a response.
+ *
+ * The convenience `output_text` field is NOT populated by OpenRouter's `/responses` API — verified live,
+ * on both a streaming and a non-streaming request: the body carries `output` items (`reasoning`, then
+ * `message`) and no `output_text` at all. Reading that field alone therefore returns undefined for every
+ * real call, so a run task would store an empty `o` on a call that answered perfectly well and was
+ * charged for.
+ *
+ * Text is concatenated across ALL message items rather than just the first, since nothing guarantees a
+ * response is limited to one.
+ *
+ * @param response - The response.
+ * @returns The output text, or undefined when the response carried none.
+ */
+export declare function openRouterOutputTextFromResponse(response: OpenResponsesResult): Maybe<string>;
+/**
+ * Flattens the SDK's nested usage object.
+ *
+ * A measurement the response did not report is OMITTED rather than carried as `undefined` or `null`.
+ *
+ * @param usage - The SDK usage object.
+ * @returns The flattened usage.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterRunUsageFromResponseUsage(usage: NonNullable<OpenResponsesResult['usage']>): OpenRouterRunUsage;
+/**
+ * Flattens the error an OpenRouter response reports in its body.
+ *
+ * Named rather than inlined at the one call site for the same reason
+ * {@link openRouterRunUsageFromResponseUsage} is: a library that exports `OpenRouterRunError` as a type
+ * should let a caller holding a raw `OpenResponsesResult` produce one without transcribing its shape.
+ *
+ * `code` goes through `String()` because OpenRouter reports a NUMERIC code here (the HTTP status), while
+ * `OpenRouterRunError.code` is a string — the same field an SDK-thrown error fills with `ECONNRESET`.
+ *
+ * @param error - The error reported on the response.
+ * @returns The flattened error.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterRunErrorFromResponseError(error: NonNullable<OpenResponsesResult['error']>): OpenRouterRunError;
+/**
+ * Parses model output as a JSON object.
+ *
+ * Returns undefined rather than throwing on anything that is not a JSON object: a model asked for
+ * text can and will return prose, and that is not an error.
+ *
+ * @param outputText - The output text.
+ * @returns The parsed object, or undefined when the output is not a JSON object.
+ */
+export declare function parseOpenRouterJsonOutput(outputText: Maybe<string>): Maybe<Record<string, unknown>>;

package/src/lib/openrouter.config.d.ts

@@ -0,0 +1,314 @@
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterModelId } from './openrouter.type';
+/**
+ * Reasoning effort accepted by OpenRouter's `reasoning.effort`.
+ */
+export type OpenRouterReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * Reasoning mode accepted by OpenRouter's `reasoning.mode`.
+ */
+export type OpenRouterReasoningMode = 'standard' | 'pro';
+/**
+ * Reasoning summary verbosity accepted by OpenRouter's `reasoning.summary`.
+ */
+export type OpenRouterReasoningSummary = 'auto' | 'concise' | 'detailed';
+/**
+ * Output verbosity accepted by OpenRouter's `text.verbosity`.
+ *
+ * This is the OpenAI-dashboard "Verbosity" control.
+ */
+export type OpenRouterVerbosity = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * Reasoning configuration. Replaces the OpenAI dashboard's reasoning mode / effort / summary
+ * controls.
+ */
+export interface OpenRouterReasoningConfig {
+    readonly enabled?: Maybe<boolean>;
+    readonly effort?: Maybe<OpenRouterReasoningEffort>;
+    readonly mode?: Maybe<OpenRouterReasoningMode>;
+    readonly summary?: Maybe<OpenRouterReasoningSummary>;
+    /**
+     * Named `max_tokens` on the wire — the SDK does not camelCase this one.
+     */
+    readonly max_tokens?: Maybe<number>;
+}
+/**
+ * A JSON-schema output format, replacing the OpenAI dashboard's structured-output setting.
+ */
+export interface OpenRouterJsonSchemaFormat {
+    readonly type: 'json_schema';
+    readonly name: string;
+    readonly strict?: Maybe<boolean>;
+    readonly schema: Record<string, unknown>;
+}
+/**
+ * Output format, replacing the OpenAI dashboard's "Text format" setting.
+ */
+export type OpenRouterTextFormat = {
+    readonly type: 'text';
+} | {
+    readonly type: 'json_object';
+} | OpenRouterJsonSchemaFormat;
+/**
+ * Text/output configuration — OpenRouter's `text` object.
+ */
+export interface OpenRouterTextConfig {
+    readonly format?: Maybe<OpenRouterTextFormat>;
+    readonly verbosity?: Maybe<OpenRouterVerbosity>;
+}
+/**
+ * Provider routing configuration — OpenRouter's `provider` object.
+ *
+ * Pinning matters more than it looks: without `requireParameters`, OpenRouter's docs state
+ * "providers will receive only the parameters they support, and ignore the rest", so an unpinned
+ * call can silently drop a parameter and return a confidently wrong answer with no error.
+ */
+export interface OpenRouterProviderConfig {
+    readonly only?: Maybe<string[]>;
+    readonly order?: Maybe<string[]>;
+    readonly ignore?: Maybe<string[]>;
+    readonly allowFallbacks?: Maybe<boolean>;
+    readonly requireParameters?: Maybe<boolean>;
+    readonly dataCollection?: Maybe<'allow' | 'deny'>;
+    readonly sort?: Maybe<string | Record<string, unknown>>;
+    readonly quantizations?: Maybe<string[]>;
+    readonly zdr?: Maybe<boolean>;
+    readonly maxPrice?: Maybe<Record<string, string>>;
+}
+/**
+ * PDF parsing engine for the `file-parser` plugin.
+ *
+ * - `native` — the model provider parses the PDF itself (OpenAI, on our BYOK key), billed as input
+ *   tokens, with no image cap. ONLY valid on a model with native file input: OpenRouter forwards the
+ *   raw file part upstream, and a text-only model rejects the whole request with a 400
+ *   (`Provider returned error`, wrapping the provider's own `Unknown part type: file`). Verified live
+ *   against `nvidia/nemotron-nano-9b-v2:free`.
+ * - `pdf-text` — OpenRouter extracts the PDF's embedded text itself. Free, and valid on EVERY model
+ *   because the model only ever sees text. Yields nothing for a scanned/image-only PDF, so the model
+ *   answers ungrounded with no error — which is why it is not the default.
+ * - `mistral-ocr` — Mistral's OCR service, billed by OpenRouter per page, capped at 8 images per PDF
+ *   with the surplus silently dropped.
+ * - `cloudflare-ai` — Cloudflare Workers AI, free, PDF to markdown.
+ */
+export type OpenRouterPdfParserEngine = 'native' | 'pdf-text' | 'mistral-ocr' | 'cloudflare-ai';
+/**
+ * The `file-parser` plugin. Replaces OpenAI's code-interpreter/file-upload path for PDF input.
+ */
+export interface OpenRouterFileParserPluginConfig {
+    readonly id: 'file-parser';
+    readonly enabled?: Maybe<boolean>;
+    readonly pdf?: Maybe<{
+        readonly engine?: Maybe<OpenRouterPdfParserEngine>;
+    }>;
+}
+/**
+ * Any OpenRouter plugin entry. Only `file-parser` is modeled precisely; the rest are passed through.
+ */
+export type OpenRouterPluginConfig = OpenRouterFileParserPluginConfig | ({
+    readonly id: string;
+} & Record<string, unknown>);
+/**
+ * A hosted (server-executed) tool entry, e.g. a `file_search` or `mcp` tool.
+ */
+export type OpenRouterHostedToolConfig = {
+    readonly type: string;
+} & Record<string, unknown>;
+/**
+ * The hosted `file_search` tool.
+ *
+ * Field names are CAMELCASE, matching the SDK's request surface rather than the wire. That is not a
+ * style choice: `@openrouter/sdk` validates the request body against a closed schema that names this
+ * field `vectorStoreIds` and remaps it to `vector_store_ids` on the way out — so a config authored with
+ * the wire name is dropped during serialization, and the call goes out with a `file_search` tool that
+ * searches nothing. OpenRouter answers it anyway, confidently and ungrounded, with no error.
+ */
+export interface OpenRouterFileSearchToolConfig {
+    readonly type: 'file_search';
+    /**
+     * The OpenAI vector stores to search. A `vs_…` id resolves only for the org that owns it, so this
+     * works only where OpenRouter authenticates upstream with a BYOK key from that org.
+     *
+     * The passthrough itself is verified: OpenRouter forwards the tool to OpenAI, which resolves the id.
+     * See `openrouter.filesearch.spike.spec.ts`.
+     */
+    readonly vectorStoreIds: string[];
+    readonly maxNumResults?: Maybe<number>;
+    readonly rankingOptions?: Maybe<{
+        readonly ranker?: Maybe<string>;
+        readonly scoreThreshold?: Maybe<number>;
+    }>;
+    readonly filters?: Maybe<Record<string, unknown>>;
+    /**
+     * Passthrough for anything the hosted tool grows that this interface does not yet name.
+     */
+    readonly [key: string]: unknown;
+}
+/**
+ * Builds a hosted `file_search` tool entry with the field names the SDK actually forwards.
+ *
+ * @param vectorStoreIds - The `vs_…` ids to search.
+ * @param maxNumResults - Optional cap on returned chunks.
+ * @returns The hosted tool entry.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterFileSearchTool(vectorStoreIds: string[], maxNumResults?: Maybe<number>): OpenRouterFileSearchToolConfig;
+/**
+ * The default PDF parser engine this package pins.
+ *
+ * Pinned because the alternative is silent: with no engine named, OpenRouter downgrades any model it
+ * believes lacks native file support to `mistral-ocr`, inheriting its 8-image cap and per-page billing with
+ * no error — which on a multi-page document quietly truncates content.
+ *
+ * `native` rather than the equally-free `pdf-text` because it fails LOUDLY. It requires a model with
+ * native file input and 400s on one without, where `pdf-text` would hand a scanned PDF to the model as
+ * empty text and let it answer ungrounded. A caller on a text-only model wants
+ * `openRouterFileParserPlugin('pdf-text')` — see {@link OpenRouterPdfParserEngine}.
+ */
+export declare const DEFAULT_OPENROUTER_PDF_PARSER_ENGINE: OpenRouterPdfParserEngine;
+/**
+ * The `file-parser` plugin entry with the PDF engine pinned.
+ *
+ * @param engine - Engine to pin. Defaults to {@link DEFAULT_OPENROUTER_PDF_PARSER_ENGINE}.
+ * @returns The plugin config entry.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterFileParserPlugin(engine?: OpenRouterPdfParserEngine): OpenRouterFileParserPluginConfig;
+/**
+ * A provider config that pins routing to a single provider with fallbacks off and parameter support
+ * required — the configuration that makes a BYOK request actually reach the intended upstream with
+ * every parameter intact.
+ *
+ * @param provider - The provider slug to pin to (e.g. `openai`).
+ * @returns The provider routing config.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterProviderPinnedTo(provider: string): OpenRouterProviderConfig;
+/**
+ * Model configuration for an OpenRouter prompt version, or a per-run override of one.
+ *
+ * Field names follow the `@openrouter/sdk` request surface (camelCase), because a merged config is
+ * spread directly into `callModel`. The SDK converts them to the wire's snake_case names.
+ *
+ * This interface exists for autocomplete and optional call-time validation ONLY — the persisted
+ * value is passthrough JSON, deliberately not a strict Firestore converter. OpenRouter's parameter
+ * surface moves fast (the previously pinned `0.12.79` SDK was already missing several params present
+ * in `1.2.x`), and a strict converter would silently drop unknown fields on every release. Strict
+ * types in code, loose storage: hence the index signature.
+ *
+ * Concepts with no OpenRouter equivalent are deliberately absent. OpenAI's "Store logs" is one —
+ * OpenRouter is stateless and `store` is type-pinned to `false`.
+ */
+export interface OpenRouterModelConfig {
+    /**
+     * Primary model to route to.
+     */
+    readonly model?: Maybe<OpenRouterModelId>;
+    /**
+     * Fallback chain, tried in order when the primary model is unavailable.
+     */
+    readonly models?: Maybe<OpenRouterModelId[]>;
+    /**
+     * Output format + verbosity.
+     */
+    readonly text?: Maybe<OpenRouterTextConfig>;
+    /**
+     * Reasoning mode / effort / summary.
+     */
+    readonly reasoning?: Maybe<OpenRouterReasoningConfig>;
+    /**
+     * Provider routing — where BYOK pinning goes.
+     */
+    readonly provider?: Maybe<OpenRouterProviderConfig>;
+    /**
+     * Plugins: `file-parser`, `web`, `context-compression`.
+     */
+    readonly plugins?: Maybe<OpenRouterPluginConfig[]>;
+    /**
+     * Hosted (server-executed) tools, e.g. `file_search`, `mcp`, `web_search`.
+     *
+     * A config carrying any of these is dispatched off the `callModel` path — `callModel` converts every
+     * `tools` entry as a client function tool — and goes either straight to `/responses` or through a
+     * `ModelResult` that appends them after client-tool conversion. See `openRouterHostedTools`.
+     */
+    readonly tools?: Maybe<OpenRouterHostedToolConfig[]>;
+    readonly toolChoice?: Maybe<unknown>;
+    readonly parallelToolCalls?: Maybe<boolean>;
+    readonly maxToolCalls?: Maybe<number>;
+    /**
+     * Extra response parts to include, e.g. `file_search_call.results`.
+     */
+    readonly include?: Maybe<string[]>;
+    readonly maxOutputTokens?: Maybe<number>;
+    readonly temperature?: Maybe<number>;
+    readonly topP?: Maybe<number>;
+    readonly topK?: Maybe<number>;
+    readonly seed?: Maybe<number>;
+    readonly stop?: Maybe<string | string[]>;
+    readonly frequencyPenalty?: Maybe<number>;
+    readonly presencePenalty?: Maybe<number>;
+    readonly promptCacheKey?: Maybe<string>;
+    readonly truncation?: Maybe<string>;
+    readonly user?: Maybe<string>;
+    /**
+     * Ceiling on tool-call steps, passed to the Agent SDK's `stopWhen`.
+     *
+     * NOTE: this bounds the number of tool-call rounds, NOT the duration of one inference. A single
+     * inference is atomic and cannot be interrupted — use {@link requestTimeoutMs} for that.
+     */
+    readonly maxSteps?: Maybe<number>;
+    /**
+     * Per-request wall-clock timeout in milliseconds.
+     *
+     * The one bound on a single inference. Required in practice for the run-task sweeper: without it,
+     * one unusually slow call can overrun the sweep's time budget and delay every other workload
+     * sharing the runner.
+     */
+    readonly requestTimeoutMs?: Maybe<number>;
+    /**
+     * Passthrough for parameters this interface does not yet name.
+     */
+    readonly [key: string]: unknown;
+}
+/**
+ * Merges model configs left-to-right, so the last input wins.
+ *
+ * Merging is SHALLOW by key: an override that supplies `provider` replaces the whole provider object
+ * rather than merging into it. That is the behaviour a caller wants — a half-overridden `provider`
+ * (say, `only` from the override and `allowFallbacks` from the version) is a configuration nobody
+ * wrote down and nobody can reason about.
+ *
+ * `undefined` values do not overwrite; an explicit `null` does (it is how a caller clears a value
+ * the version set).
+ *
+ * @param configs - Configs to merge, lowest priority first.
+ * @returns The merged config.
+ */
+export declare function mergeOpenRouterModelConfig(configs: Maybe<OpenRouterModelConfig>[]): OpenRouterModelConfig;
+/**
+ * Result of validating an {@link OpenRouterModelConfig}.
+ */
+export interface OpenRouterModelConfigValidation {
+    /**
+     * Whether the config is usable as-is.
+     */
+    readonly valid: boolean;
+    /**
+     * Problems that make the config unusable.
+     */
+    readonly errors: string[];
+    /**
+     * Problems that do not prevent the call but will very likely produce a wrong result.
+     */
+    readonly warnings: string[];
+}
+/**
+ * Validates a merged model config, catching the misconfigurations that fail silently at runtime
+ * rather than loudly.
+ *
+ * @param config - The merged config to check.
+ * @returns The validation result.
+ */
+export declare function validateOpenRouterModelConfig(config: Maybe<OpenRouterModelConfig>): OpenRouterModelConfigValidation;