@dereekb/openrouter 13.37.0

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

@@ -0,0 +1,87 @@
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterProviderConfig } from './openrouter.config';
+import { type OpenRouterCore, type RequestOptions } from './openrouter.sdk';
+import { type OpenRouterModelId } from './openrouter.type';
+/**
+ * Params for {@link openRouterEmbeddings}.
+ */
+export interface OpenRouterEmbeddingsParams {
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * The embeddings model to use.
+     */
+    readonly model: OpenRouterModelId;
+    /**
+     * Text(s) to embed.
+     */
+    readonly input: string | string[];
+    /**
+     * Output dimensionality, when the model supports reducing it.
+     */
+    readonly dimensions?: Maybe<number>;
+    /**
+     * Input type hint (e.g. `search_query`, `search_document`) for models that distinguish them.
+     */
+    readonly inputType?: Maybe<string>;
+    /**
+     * Provider routing — the same pinning that matters everywhere else applies here.
+     */
+    readonly provider?: Maybe<OpenRouterProviderConfig>;
+    /**
+     * Additional request options.
+     */
+    readonly options?: Maybe<RequestOptions>;
+}
+/**
+ * One embedding vector.
+ */
+export interface OpenRouterEmbedding {
+    /**
+     * Index of this embedding in the input list.
+     */
+    readonly index: number;
+    /**
+     * The vector.
+     */
+    readonly embedding: number[];
+}
+/**
+ * Result of an embeddings request.
+ */
+export interface OpenRouterEmbeddingsResult {
+    readonly model: string;
+    readonly embeddings: OpenRouterEmbedding[];
+    readonly promptTokens?: Maybe<number>;
+    readonly totalTokens?: Maybe<number>;
+}
+/**
+ * Generates embeddings.
+ *
+ * Base64-encoded embeddings are decoded to numbers before being returned, so a caller never has to
+ * branch on the encoding the model happened to use.
+ *
+ * @param params - The client, model, input, and routing options.
+ * @returns The embeddings.
+ */
+export declare function openRouterEmbeddings(params: OpenRouterEmbeddingsParams): Promise<OpenRouterEmbeddingsResult>;
+/**
+ * Decodes a base64 string to bytes.
+ *
+ * `atob` is a WHATWG global, present on Node ≥16 and in every browser, so no Node-only `Buffer` is assumed.
+ * Anything outside the base64 alphabet — padding, embedded newlines from a wrapped response — is stripped
+ * first, which is what makes the input tolerant rather than strict.
+ *
+ * @param base64 - The base64 string. Padding is optional.
+ * @returns The decoded bytes.
+ */
+export declare function openRouterDecodeBase64(base64: string): Uint8Array;
+/**
+ * Normalizes an embedding to a number array, decoding the base64 (little-endian float32) form.
+ *
+ * @param embedding - The embedding as returned.
+ * @returns The vector.
+ */
+export declare function openRouterEmbeddingVector(embedding: number[] | string): number[];

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

@@ -0,0 +1,46 @@
+import { type Maybe } from '@dereekb/util';
+import { type GenerationContentData, type GenerationResponseData, type OpenRouterCore, type RequestOptions } from './openrouter.sdk';
+import { type OpenRouterGenerationId } from './openrouter.type';
+/**
+ * Params for {@link openRouterGeneration} and {@link openRouterGenerationContent}.
+ */
+export interface OpenRouterGenerationParams {
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * The generation id, as stored on a run task's `gi`.
+     */
+    readonly id: OpenRouterGenerationId;
+    /**
+     * Additional request options.
+     */
+    readonly options?: Maybe<RequestOptions>;
+}
+/**
+ * Loads a generation's metadata — finish reason, cancellation, BYOK, latency, and the full token/cost
+ * breakdown, which is finalised server-side and so can be more complete than the usage the response
+ * carried.
+ *
+ * This is an AUDIT surface, never the system of record. What it returns is tied to account logging
+ * settings (nothing is retained under ZDR / logging-disabled), its retention is undocumented, and it is
+ * keyed per generation rather than per conversation — which is why a run task stores its own output and
+ * keeps `gi (generationIds)` only for lookups like this one.
+ *
+ * @param params - The client and generation id.
+ * @returns The generation metadata.
+ * @throws {Error} When the lookup fails, including the 404 a generation that was never retained produces.
+ */
+export declare function openRouterGeneration(params: OpenRouterGenerationParams): Promise<GenerationResponseData>;
+/**
+ * Loads a generation's stored content — prompt, completion, reasoning, and output.
+ *
+ * Subject to every caveat on {@link openRouterGeneration}: this reloads what OpenRouter happened to
+ * retain, not what the run produced.
+ *
+ * @param params - The client and generation id.
+ * @returns The stored content.
+ * @throws {Error} When the lookup fails.
+ */
+export declare function openRouterGenerationContent(params: OpenRouterGenerationParams): Promise<GenerationContentData>;

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

@@ -0,0 +1,238 @@
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterFileAnnotation, type OpenRouterFileReference } from './openrouter.type';
+/**
+ * Role of an input message.
+ */
+export type OpenRouterInputRole = 'user' | 'system' | 'assistant' | 'developer';
+/**
+ * A text content part.
+ */
+export interface OpenRouterInputTextPart {
+    readonly type: 'input_text';
+    readonly text: string;
+}
+/**
+ * An image content part.
+ *
+ * Images go in as ordinary image parts — there is no need to wrap one in a PDF the way OpenAI's
+ * background-mode file bug forced.
+ */
+export interface OpenRouterInputImagePart {
+    readonly type: 'input_image';
+    readonly imageUrl: string;
+    readonly detail: 'auto' | 'low' | 'high' | 'original';
+}
+/**
+ * A file content part.
+ *
+ * OpenRouter takes the file inline in the message — there is no upload step and nothing to clean up
+ * afterwards. `fileUrl` is preferred (OpenRouter's docs: "Send publicly accessible PDFs directly
+ * without downloading or encoding"); `fileData` is the base64 fallback for an object we will not
+ * expose by URL, at the cost of bloating both the request and the stored run task.
+ *
+ * `fileId` (the OpenRouter Files blob store) is deliberately not modeled: it reintroduces exactly the
+ * "files live on their servers and are never deleted" problem this package removes.
+ */
+export interface OpenRouterInputFilePart {
+    readonly type: 'input_file';
+    readonly fileUrl?: Maybe<string>;
+    readonly fileData?: Maybe<string>;
+    readonly filename?: Maybe<string>;
+}
+/**
+ * Any input content part.
+ */
+export type OpenRouterInputContentPart = OpenRouterInputTextPart | OpenRouterInputImagePart | OpenRouterInputFilePart;
+/**
+ * A single input message.
+ */
+export interface OpenRouterInputMessage {
+    readonly role: OpenRouterInputRole;
+    readonly content: string | OpenRouterInputContentPart[];
+}
+/**
+ * Input to a request: a bare string (shorthand for a single user message) or a list of messages.
+ */
+export type OpenRouterInput = string | OpenRouterInputMessage[];
+/**
+ * Normalizes input to a message array.
+ *
+ * @param input - The input to normalize.
+ * @returns The messages, empty when no input was given.
+ */
+export declare function openRouterInputMessages(input: Maybe<OpenRouterInput>): OpenRouterInputMessage[];
+/**
+ * Builds a text content part.
+ *
+ * @param text - The text.
+ * @returns The content part.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterInputTextPart(text: string): OpenRouterInputTextPart;
+/**
+ * Builds an image content part.
+ *
+ * @param imageUrl - The image url (a signed url, a data url, or any publicly reachable url).
+ * @param detail - Detail level. Defaults to `auto`.
+ * @returns The content part.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterInputImagePart(imageUrl: string, detail?: OpenRouterInputImagePart['detail']): OpenRouterInputImagePart;
+/**
+ * Builds a file content part from a url.
+ *
+ * @param fileUrl - The url the parser will dereference. Must be reachable from the public internet.
+ * @param filename - Filename to present; its extension is what tells OpenRouter how to treat the file.
+ * @returns The content part.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterInputFileUrlPart(fileUrl: string, filename: string): OpenRouterInputFilePart;
+/**
+ * Builds a file content part from base64 data.
+ *
+ * @param base64 - Base64 content, with or without a `data:` prefix.
+ * @param filename - Filename to present.
+ * @param contentType - Mime type used to build the `data:` prefix when the input lacks one. Defaults to `application/pdf`.
+ * @returns The content part.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterInputFileDataPart(base64: string, filename: string, contentType?: string): OpenRouterInputFilePart;
+/**
+ * A file reference paired with however it is being carried on THIS attempt.
+ *
+ * Exactly one of `fileUrl` / `fileData` is expected. Which one depends on whether the object is
+ * reachable from the public internet: a signed url is cheap and keeps the request small, and inline
+ * base64 is the fallback for an object OpenRouter cannot dereference — most notably anything living in
+ * the Firebase storage emulator, where "signed" urls point at localhost.
+ */
+export interface OpenRouterAttachedFileReference {
+    readonly file: OpenRouterFileReference;
+    /**
+     * The signed url, minted for THIS attempt.
+     *
+     * Never persist this — see {@link OpenRouterFileReference} for why a url cannot outlive the attempt that
+     * minted it.
+     */
+    readonly fileUrl?: Maybe<string>;
+    /**
+     * A `data:<mime>;base64,…` url carrying the file inline on THIS attempt.
+     *
+     * Never persist this either, for a different reason: it is the whole file, re-read on every attempt,
+     * and a run task document has a 1 MiB ceiling.
+     */
+    readonly fileData?: Maybe<string>;
+}
+/**
+ * Expands attached file references into file content parts.
+ *
+ * @param files - The attached file references.
+ * @returns One content part per file.
+ */
+export declare function openRouterInputFilePartsForAttachedFiles(files: Maybe<OpenRouterAttachedFileReference[]>): OpenRouterInputFilePart[];
+/**
+ * Rewrites the `input_file` parts of an already-assembled conversation with the attachment resolved for
+ * THIS attempt, matching on filename.
+ *
+ * A conversation persisted mid-run carries whatever the attempt that persisted it was carrying —
+ * a url that has since expired, or (with inline attachments stripped on save) nothing at all. Replaying
+ * it unchanged is the failure mode most likely to reach production unnoticed, because it only shows up
+ * on a retry or a deferred resume. Resolving fresh per attempt is only half the fix; the other half is
+ * making sure the stored history is re-pointed at the fresh attachment too.
+ *
+ * The field the attachment does NOT carry is REMOVED rather than left alone: a stored `fileUrl` sitting
+ * next to a fresh `fileData` would send OpenRouter both, and it is not defined which one wins. Removed
+ * rather than nulled, because this output goes on the wire — the SDK validates `input_file` against a
+ * schema where an explicit `null` is not a legal absent value.
+ *
+ * A part whose filename matches nothing in `files` is left alone: it came from somewhere other than
+ * this task's file list, and guessing at it would be worse than leaving it.
+ *
+ * @param messages - The assembled conversation.
+ * @param files - The files attached for this attempt.
+ * @returns The conversation with fresh attachments, or the input unchanged when there is nothing to rewrite.
+ */
+export declare function openRouterMessagesWithFreshFileAttachments<T extends {
+    readonly role: string;
+    readonly content: unknown;
+}>(messages: Maybe<T[]>, files: Maybe<OpenRouterAttachedFileReference[]>): T[];
+/**
+ * Strips the attachment payload off every `input_file` part, keeping `filename` as the rejoin key.
+ *
+ * Applied on the way INTO Firestore. An attachment is resolved per attempt and is meaningless the
+ * moment that attempt ends — a signed url has expired, and inline base64 is the whole file, on a
+ * document with a 1 MiB ceiling and a `msg` field that already grows without bound. Nothing is lost:
+ * {@link openRouterMessagesWithFreshFileAttachments} re-points the stored parts on the way back out.
+ *
+ * @param messages - The conversation about to be persisted.
+ * @returns The conversation with attachment payloads removed.
+ */
+export declare function openRouterMessagesWithoutFileAttachmentData<T extends {
+    readonly role: string;
+    readonly content: unknown;
+}>(messages: Maybe<T[]>): T[];
+/**
+ * An assistant message echoing `file-parser` annotations back to OpenRouter.
+ *
+ * `annotations` is not part of the modeled input-message shape, so this is its own type. It is carried
+ * through the request builder as-is.
+ */
+export interface OpenRouterFileAnnotationEchoMessage {
+    readonly role: 'assistant';
+    readonly content: string;
+    readonly annotations: readonly {
+        readonly type: 'file';
+        readonly file: {
+            readonly hash: string;
+            readonly name?: Maybe<string>;
+            readonly content?: Maybe<unknown>;
+        };
+    }[];
+}
+/**
+ * Renders one cached annotation as message text.
+ *
+ * @param annotation - The cached annotation.
+ * @returns The text carrying the parse.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterFileAnnotationText(annotation: OpenRouterFileAnnotation): string;
+/**
+ * Builds the assistant message that carries cached `file-parser` output back, so an already-parsed file
+ * is not parsed again.
+ *
+ * It carries the parse TWICE, deliberately, and for an empirical reason rather than a defensive one:
+ *
+ *  - `annotations` is OpenRouter's own documented echo format, so the shape is kept and the mechanism
+ *    starts working the day the Responses API models it. Today it does not: the SDK validates the request
+ *    body against a closed union whose message variants have no `annotations` field, so the property is
+ *    STRIPPED during outbound serialization. Verified against the wire, not assumed.
+ *  - The parse is therefore ALSO rendered into `content`, as ordinary text, which does survive. Paired
+ *    with the request builder dropping the file part for an already-parsed file, that is what makes the
+ *    cache real today.
+ *
+ * @param annotations - The cached annotations.
+ * @returns The message, or undefined when there is nothing cached to resubmit.
+ */
+export declare function openRouterFileAnnotationMessage(annotations: Maybe<OpenRouterFileAnnotation[]>): Maybe<OpenRouterFileAnnotationEchoMessage>;
+/**
+ * Drops the files whose parse is already cached.
+ *
+ * Not re-sending the document is what actually prevents a re-parse. The annotation echo alone cannot:
+ * the SDK strips it, and even where it survives it is a hint the provider is free to ignore, so a run
+ * that relied on it would pay for the parse again with no error to show for it.
+ *
+ * A file is matched to its cached parse by filename, which is the only handle both sides share — the
+ * annotation's `hash` is assigned by OpenRouter and the reference's `storagePath` is ours.
+ *
+ * @param files - The files attached for this attempt.
+ * @param annotations - The cached annotations.
+ * @returns The files that still need sending.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function openRouterUnparsedAttachedFiles(files: Maybe<OpenRouterAttachedFileReference[]>, annotations: Maybe<OpenRouterFileAnnotation[]>): OpenRouterAttachedFileReference[];

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

@@ -0,0 +1,79 @@
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterModelConfig } from './openrouter.config';
+import { type OpenRouterInputRole } from './openrouter.input';
+import { type OpenRouterPromptKey, type OpenRouterPromptVersionNumber } from './openrouter.type';
+/**
+ * A seed message stored on a prompt version.
+ *
+ * These are the STATIC half of a prompt — the part that is identical on every call. They are emitted
+ * before the caller's dynamic input so a prompt-cache prefix hit stays possible.
+ */
+export interface OpenRouterPromptSeedMessage {
+    readonly role: OpenRouterInputRole;
+    readonly content: string;
+}
+/**
+ * A prompt version resolved to everything needed to build a request.
+ *
+ * This is the replacement for an OpenAI `pmpt_…` id: instead of a dashboard-hosted object referenced
+ * by an opaque id, the content, the model, and the output format are values we hold.
+ *
+ * There is deliberately NO variables model. Dynamic content is passed as `input` from typed
+ * TypeScript — which is what OpenRouter requires (no server-side substitution) and what OpenAI's own
+ * migration guide prescribes: "Replace prompt variables with function arguments."
+ */
+export interface OpenRouterResolvedPrompt {
+    /**
+     * The prompt this was resolved from.
+     */
+    readonly promptKey: OpenRouterPromptKey;
+    /**
+     * The version that was resolved — either the caller's pin, or the prompt's active version.
+     *
+     * Recorded on every run so a result can always be traced back to the exact prompt text that
+     * produced it, and so a historical run can be replayed against it.
+     */
+    readonly version: OpenRouterPromptVersionNumber;
+    /**
+     * System prompt.
+     */
+    readonly instructions?: Maybe<string>;
+    /**
+     * Static seed messages.
+     */
+    readonly messages?: Maybe<OpenRouterPromptSeedMessage[]>;
+    /**
+     * The version's model config.
+     */
+    readonly config: OpenRouterModelConfig;
+}
+/**
+ * A prompt defined in CODE rather than published to Firestore.
+ *
+ * This is the backup half of prompt resolution: an app ships its prompts as definitions, so a fresh
+ * environment — a new emulator, a test, a project that has never been seeded — can serve them without a
+ * manual seeding step first. Once the same prompt is published to Firestore the stored version takes
+ * over, which is what keeps prompt authoring a runtime concern rather than a deploy-shaped one.
+ *
+ * A definition IS an {@link OpenRouterResolvedPrompt}, so serving one needs no conversion. The extra
+ * fields are the authoring metadata a seeder needs to create the stored prompt from this same value,
+ * rather than restating the name and description alongside it.
+ */
+export interface OpenRouterPromptDefinition extends OpenRouterResolvedPrompt {
+    /**
+     * The version this code ships.
+     *
+     * Compared against the stored prompt's active version to decide which one wins, so this is the one
+     * knob that controls drift: bump it when the definition's text or config changes and the definition
+     * takes over again, even from an environment that was already seeded at a lower version.
+     */
+    readonly version: OpenRouterPromptVersionNumber;
+    /**
+     * Human-readable name, used when this definition is published to Firestore.
+     */
+    readonly name: string;
+    /**
+     * What this prompt is for, used when this definition is published to Firestore.
+     */
+    readonly description?: Maybe<string>;
+}

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

@@ -0,0 +1,91 @@
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterModelConfig } from './openrouter.config';
+import { type OpenRouterAttachedFileReference, type OpenRouterFileAnnotationEchoMessage, type OpenRouterInput, type OpenRouterInputMessage, openRouterFileAnnotationMessage } from './openrouter.input';
+import { type OpenRouterResolvedPrompt } from './openrouter.prompt';
+import { type OpenRouterRunTaskKey } from './openrouter.type';
+/**
+ * Trace metadata attached to a request.
+ *
+ * OpenRouter includes custom metadata from the `trace` field as span attributes in the OTLP payload
+ * its broadcast webhook posts, so this is the correlation handle that lets a completion trace be
+ * matched back to the run that produced it — the same job `metadata.taskKey` does on OpenAI today.
+ */
+export interface OpenRouterRequestTrace {
+    /**
+     * The run task this request belongs to.
+     */
+    readonly runTaskKey?: Maybe<OpenRouterRunTaskKey>;
+    /**
+     * Any additional properties to carry through as span attributes.
+     */
+    readonly [key: string]: unknown;
+}
+/**
+ * Params for {@link openRouterPromptRequest}.
+ */
+export interface OpenRouterPromptRequestParams {
+    /**
+     * The resolved prompt version supplying instructions, seed messages, and base config.
+     */
+    readonly prompt: OpenRouterResolvedPrompt;
+    /**
+     * The caller's dynamic input.
+     */
+    readonly input?: Maybe<OpenRouterInput>;
+    /**
+     * Per-run config overrides, applied on top of the version's config.
+     */
+    readonly overrides?: Maybe<OpenRouterModelConfig>;
+    /**
+     * Files to attach, each already resolved to a url or inline data for THIS attempt.
+     */
+    readonly files?: Maybe<OpenRouterAttachedFileReference[]>;
+    /**
+     * Cached `file-parser` annotations to echo back so an already-parsed file is not re-parsed.
+     */
+    readonly fileAnnotations?: Maybe<Parameters<typeof openRouterFileAnnotationMessage>[0]>;
+    /**
+     * Prior conversation history to continue from.
+     *
+     * This is what replaces `previous_response_id`: OpenRouter is stateless, so continuing a
+     * conversation means resending its history.
+     */
+    readonly history?: Maybe<OpenRouterInputMessage[]>;
+    /**
+     * Trace metadata for cost/usage reconciliation.
+     */
+    readonly trace?: Maybe<OpenRouterRequestTrace>;
+}
+/**
+ * A built request: the merged config plus the assembled input, ready to spread into `callModel`.
+ */
+export interface OpenRouterPromptRequest {
+    /**
+     * The merged model config (version config with overrides applied).
+     */
+    readonly config: OpenRouterModelConfig;
+    /**
+     * The system prompt.
+     */
+    readonly instructions?: Maybe<string>;
+    /**
+     * The assembled input messages, static content first.
+     */
+    readonly input: (OpenRouterInputMessage | OpenRouterFileAnnotationEchoMessage)[];
+    /**
+     * Trace metadata, when any was supplied.
+     */
+    readonly trace?: Maybe<OpenRouterRequestTrace>;
+}
+/**
+ * Builds a request from a resolved prompt version plus a caller's dynamic input.
+ *
+ * Content is emitted STATIC FIRST — seed messages, then annotation echoes, then continued history,
+ * then the caller's input, with attached files appended to the final user message. That ordering is
+ * not cosmetic: a prompt cache only hits on a shared prefix, so putting the per-call content last is
+ * what keeps the static prefix cacheable across runs of the same prompt.
+ *
+ * @param params - The prompt, input, overrides, files, history, and trace.
+ * @returns The built request.
+ */
+export declare function openRouterPromptRequest(params: OpenRouterPromptRequestParams): OpenRouterPromptRequest;

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

@@ -0,0 +1,37 @@
+/**
+ * The single boundary between this package and `@openrouter/sdk`.
+ *
+ * The SDK publishes its agent surface (`callModel`, tools, conversation state, stop conditions) from
+ * deep subpaths rather than its root, so those import specifiers are inherently brittle. They are
+ * confined to this one file: an SDK reorganisation is then a change here rather than across the
+ * package.
+ *
+ * `@openrouter/agent` is deliberately NOT used. It declares `"@openrouter/sdk": "^0.13.7"`, so npm nests a
+ * second copy of the SDK — and the two `OpenRouterCore` classes are distinct nominal types (different
+ * `#private` brands), so a client built from the 1.2.x SDK cannot be passed to its `callModel` at all. The
+ * only thing it adds is a first-class deferred-tool API, and the 1.2.x SDK's manual tools
+ * (`execute: false`) plus `ConversationState.pendingToolCalls` / `unsentToolResults` already provide that
+ * mechanism. See `openrouter.tool.ts`.
+ *
+ * `responsesSend` / `ModelResult` / `convertToolsToAPIFormat` are what make hosted (server-executed) tools
+ * deliverable: `callModel` owns the `tools` key and converts every entry as a client function tool, so
+ * taking its transport and its tool loop directly is what lets `openrouter.call.ts` put an
+ * already-converted tool array on the request. See `openRouterModelResultForRequest`.
+ */
+export { callModel } from '@openrouter/sdk/funcs/call-model';
+export { responsesSend } from '@openrouter/sdk/funcs/responsesSend';
+export { unsentResultsToAPIFormat } from '@openrouter/sdk/lib/conversation-state';
+export { embeddingsGenerate } from '@openrouter/sdk/funcs/embeddingsGenerate';
+export { generationsGetGeneration } from '@openrouter/sdk/funcs/generationsGetGeneration';
+export { generationsListGenerationContent } from '@openrouter/sdk/funcs/generationsListGenerationContent';
+export { ModelResult } from '@openrouter/sdk/lib/model-result';
+export { tool } from '@openrouter/sdk/lib/tool';
+export { convertToolsToAPIFormat } from '@openrouter/sdk/lib/tool-executor';
+export { finishReasonIs, hasToolCall, maxCost, maxTokensUsed, stepCountIs } from '@openrouter/sdk/lib/stop-conditions';
+export { isManualTool, ToolType } from '@openrouter/sdk/lib/tool-types';
+export type { OpenRouterCore } from '@openrouter/sdk/core';
+export type { CallModelInput } from '@openrouter/sdk/lib/async-params';
+export type { RequestOptions } from '@openrouter/sdk/lib/sdks';
+export type { ConversationState, ConversationStatus, ParsedToolCall, StateAccessor, StopWhen, Tool, UnsentToolResult } from '@openrouter/sdk/lib/tool-types';
+export type { FunctionCallOutputItem, GenerationContentData, GenerationResponseData, InputsUnion, OpenResponsesResult, ResponsesRequest, Usage } from '@openrouter/sdk/models';
+export type { CreateEmbeddingsRequest, CreateEmbeddingsResponseBody, CreateResponsesResponse } from '@openrouter/sdk/models/operations';

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

@@ -0,0 +1,99 @@
+import { type Maybe } from '@dereekb/util';
+import { type ConversationState, type FunctionCallOutputItem, type ParsedToolCall, type Tool, type UnsentToolResult } from './openrouter.sdk';
+import { type OpenRouterDeferredToolTaskId } from './openrouter.type';
+/**
+ * The tool-call id the SDK assigns to one invocation.
+ */
+export type OpenRouterToolCallId = string;
+/**
+ * A tool call that is waiting on a result from outside this process.
+ *
+ * A deferred tool is a MANUAL tool (`execute: false`): the SDK emits the call, does not run it, and
+ * pauses. Some other system — a human, a queue worker, an inbound webhook — produces the result and
+ * hands it back via {@link openRouterResolvedDeferredToolResults}, at which point the run continues.
+ *
+ * `taskId` is ours, not OpenRouter's. Nothing upstream allocates it, so a caller that wants to
+ * correlate a pause with a ticket in its own system simply uses that ticket's id.
+ */
+export interface OpenRouterPendingDeferredToolCall {
+    readonly callId: OpenRouterToolCallId;
+    readonly name: string;
+    /**
+     * The task id the resolving system will quote. Defaults to `callId` when the caller supplies none.
+     */
+    readonly taskId: OpenRouterDeferredToolTaskId;
+    /**
+     * The arguments the model called the tool with.
+     */
+    readonly arguments?: Maybe<Record<string, unknown>>;
+}
+/**
+ * A resolution for one pending deferred tool call: either a successful output or an error.
+ */
+export type OpenRouterDeferredToolResolution = {
+    readonly taskId: OpenRouterDeferredToolTaskId;
+    readonly output: unknown;
+    readonly error?: never;
+} | {
+    readonly taskId: OpenRouterDeferredToolTaskId;
+    readonly error: string;
+    readonly output?: never;
+};
+/**
+ * Extracts the deferred (manual) tool calls from a conversation state.
+ *
+ * Only manual tools can be pending on resume: a tool with an `execute` function was run in-process
+ * before the state was ever saved.
+ *
+ * @param state - The conversation state.
+ * @param tools - The tool set the run was configured with, used to tell manual tools from executable ones.
+ * @returns The pending deferred tool calls.
+ */
+export declare function openRouterPendingDeferredToolCalls<TTools extends readonly Tool[] = readonly Tool[]>(state: Maybe<ConversationState<TTools>>, tools: Maybe<TTools>): OpenRouterPendingDeferredToolCall[];
+/**
+ * Converts an SDK parsed tool call into a pending deferred tool call.
+ *
+ * @param call - The parsed tool call.
+ * @param taskId - Optional task id to associate. Defaults to the call id.
+ * @returns The pending deferred tool call.
+ */
+export declare function openRouterPendingDeferredToolCallFromParsedCall(call: ParsedToolCall<Tool>, taskId?: Maybe<OpenRouterDeferredToolTaskId>): OpenRouterPendingDeferredToolCall;
+/**
+ * Turns resolutions into the `unsentToolResults` entries the SDK replays on the next call.
+ *
+ * A resolution whose `taskId` matches no pending call is DROPPED rather than throwing. Deferred
+ * resolutions arrive from outside this process and may be replayed — an unmatched one means the task
+ * was already settled, which must be a no-op, not a failure.
+ *
+ * @param pending - The currently pending deferred tool calls.
+ * @param resolutions - The resolutions received.
+ * @returns The unsent tool results, in the order the resolutions were given.
+ */
+export declare function openRouterResolvedDeferredToolResults<TTools extends readonly Tool[] = readonly Tool[]>(pending: Maybe<OpenRouterPendingDeferredToolCall[]>, resolutions: Maybe<OpenRouterDeferredToolResolution[]>): UnsentToolResult<TTools>[];
+/**
+ * Whether a conversation state is paused waiting on a deferred tool result.
+ *
+ * @param state - The conversation state.
+ * @returns True when the state has pending tool calls it cannot resolve itself.
+ */
+export declare function isOpenRouterStateAwaitingDeferredTools(state: Maybe<ConversationState>): boolean;
+/**
+ * Converts recorded tool results into the `function_call_output` items that get appended to the
+ * conversation before the run is resumed.
+ *
+ * This is how a deferred pause is un-paused, and it is done HERE rather than through the SDK on
+ * purpose. `@openrouter/sdk@1.2.x` only knows how to resume a pause by re-running the tool locally
+ * (`approveToolCalls` calls the tool's `execute`, and a manual tool has none) or by rejecting it — so
+ * a result produced by another process has no route back in through the SDK's own API. Appending the
+ * outputs to the persisted conversation and re-sending it does have one, and it is the same wire
+ * format the SDK would have produced itself.
+ *
+ * @param results - The recorded results, in the persisted `callId` / `name` / `output` / `error` shape.
+ * @returns The `function_call_output` items to append to the conversation.
+ */
+export declare function openRouterFunctionCallOutputItems(results: Maybe<readonly {
+    readonly callId: string;
+    readonly name: string;
+    readonly output?: unknown;
+    readonly error?: Maybe<string>;
+}[]>): FunctionCallOutputItem[];