@x12i/openrouter-runtime 1.0.6 → 1.4.0

package/dist/index.d.cts

@@ -1,13 +1,26 @@
 type ApiMode = "chat" | "responses" | "auto";
 type ResolvedApiMode = "chat" | "responses";
 type ToolMode = "disabled" | "allowed" | "required";
+interface RuntimeCallOptions {
+    /** Merged onto the compiled JSON body after known fields are assembled. */
+    finalizeBody?: (body: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Reads reasoning text from one chat delta.
+     * Returned text is emitted as `stream.reasoning.delta` and is not copied into answer text.
+     */
+    extractStreamReasoning?: (delta: unknown) => string | undefined;
+    /** When true, fusion/advisor/subagent tools do not inherit `request.reasoning`. */
+    suppressNestedReasoningFallback?: boolean;
+}
 interface OpenRouterRuntime {
-    run(request: RuntimeRequest): Promise<RuntimeResponse>;
+    compile(request: RuntimeRequest, call?: RuntimeCallOptions): CompiledOpenRouterRequest;
+    run(request: RuntimeRequest, call?: RuntimeCallOptions): Promise<RuntimeResponse>;
     /**
-     * Streaming chat entrypoint. Separate from `run()` by design.
+     * Explicit streaming chat API. Separate from `run()` by design — never an argument, never the default.
+     * Always sends OpenRouter Chat Completions with `stream: true` and yields typed SSE events.
      * The old `stream()` name was removed so mistaken/old clients break loudly.
      */
-    executeStreamingChat(request: RuntimeRequest): AsyncIterable<RuntimeStreamEvent>;
+    executeStreamingChat(request: RuntimeRequest, call?: RuntimeCallOptions): AsyncIterable<RuntimeStreamEvent>;
 }
 interface OpenRouterRuntimeOptions {
     apiKey?: string;
@@ -58,6 +71,16 @@ interface RuntimeRequest {
     functionTools?: RuntimeFunctionToolDefinition[];
     toolChoice?: RuntimeToolChoice;
     execution?: RuntimeExecutionPolicy;
+    /**
+     * Optional agent id for this call.
+     * OpenRouter sends it as the activity-log App name (`X-Title` and `X-OpenRouter-Title`).
+     * It is also stored in the provider metadata record as `agentId`.
+     */
+    agentId?: string;
+    /**
+     * Optional metadata. String, number, and boolean values are stored in the one provider
+     * metadata record. Objects and arrays stay on the normalized response.
+     */
     metadata?: Record<string, unknown>;
     rawOpenRouterOverrides?: Record<string, unknown>;
 }
@@ -178,6 +201,7 @@ interface FusionPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 interface AdvisorPolicy {
@@ -191,6 +215,7 @@ interface AdvisorPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 interface SubagentPolicy {
@@ -201,6 +226,7 @@ interface SubagentPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 type NestedOpenRouterServerToolPolicy = {
@@ -364,15 +390,75 @@ interface RuntimePolicyViolation {
     details?: unknown;
 }
 interface RuntimeStreamEvent {
-    type: string;
+    type: RuntimeStreamEventType;
+    requestId: string;
     data?: unknown;
 }
+type RuntimeStreamEventType = "stream.start" | "stream.text.delta" | "stream.reasoning.delta" | "stream.tool_call.delta" | "stream.usage" | "stream.warning" | "stream.error" | "stream.done";
+interface RuntimeStreamStartEvent extends RuntimeStreamEvent {
+    type: "stream.start";
+    data: {
+        model: string;
+        apiMode: "chat";
+        entrypoint: "executeStreamingChat";
+    };
+}
+interface RuntimeStreamTextDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.text.delta";
+    data: {
+        text: string;
+    };
+}
+interface RuntimeStreamReasoningDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.reasoning.delta";
+    data: {
+        text: string;
+    };
+}
+interface RuntimeStreamToolCallDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.tool_call.delta";
+    data: {
+        index: number;
+        id?: string;
+        name?: string;
+        argumentsDelta?: string;
+    };
+}
+interface RuntimeStreamUsageEvent extends RuntimeStreamEvent {
+    type: "stream.usage";
+    data: {
+        usage: RuntimeUsage;
+    };
+}
+interface RuntimeStreamWarningEvent extends RuntimeStreamEvent {
+    type: "stream.warning";
+    data: {
+        warning: RuntimeWarning;
+    };
+}
+interface RuntimeStreamErrorEvent extends RuntimeStreamEvent {
+    type: "stream.error";
+    data: {
+        error: RuntimeError;
+    };
+}
+interface RuntimeStreamDoneEvent extends RuntimeStreamEvent {
+    type: "stream.done";
+    data: {
+        text: string;
+        finishReason?: string;
+        model: string;
+    };
+}
 type RuntimePatchApplier = (patch: RuntimePatchProposal) => Promise<unknown> | unknown;
 
 declare function createOpenRouterRuntime(options: OpenRouterRuntimeOptions): OpenRouterRuntime;
 
 interface RuntimeCompileContext {
     streaming: boolean;
+    finalizeBody?: (body: Record<string, unknown>) => Record<string, unknown>;
+    /** When set, nested tools do not inherit the parent request reasoning object. */
+    suppressNestedReasoningFallback?: boolean;
 }
 interface OpenRouterTool {
     type: string;
@@ -409,9 +495,30 @@ declare class OpenRouterHttpError extends Error {
     constructor(status: number, code: ProviderFailureCode, message: string, body?: unknown | undefined, retryable?: boolean, providerAttempts?: ProviderAttemptError[]);
 }
 
-declare function buildOpenRouterServerTools(policy?: RuntimeServerToolsPolicy): OpenRouterTool[];
+declare function buildOpenRouterServerTools(policy?: RuntimeServerToolsPolicy, fallbackReasoning?: RuntimeReasoningConfig): OpenRouterTool[];
 
 declare function isRuntimeLoggingEnabled(env?: Record<string, string | undefined> | undefined): boolean;
 declare function createConsoleLogger(): RuntimeLogger;
 
-export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeError, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeLogger, type RuntimeMessage, type RuntimePatchProposal, type RuntimePolicyViolation, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeStreamEvent, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type RuntimeWarning, type ServerToolKey, type ServerToolUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createConsoleLogger, createOpenRouterRuntime, isRuntimeLoggingEnabled };
+interface ProviderMetadataLimits {
+    maxPairs: number;
+    maxKeyLength: number;
+    maxValueLength: number;
+    keyPattern?: RegExp;
+    valuePattern?: RegExp;
+}
+/** OpenRouter and OpenAI metadata: 16 pairs, 64-character keys, 512-character values. */
+declare const OPENROUTER_METADATA_LIMITS: ProviderMetadataLimits;
+/**
+ * One provider metadata record.
+ * Callers pass `metadata` and `agentId`. Every provider stores the same `m.0`, `m.1`, ...
+ * pairs: base64 of the UTF-8 JSON string map, 256 characters per pair, at most 16 pairs.
+ * `decodeProviderMetadata` restores that map from any provider log.
+ * `limits` stays on the signature for existing callers. The record uses the strictest
+ * provider limits, so the pairs do not change between providers.
+ */
+declare function toProviderMetadata(metadata: Record<string, unknown> | undefined, agentId: string | undefined, _limits: ProviderMetadataLimits, base: Record<string, unknown> | undefined): Record<string, string> | undefined;
+/** Restores the string map from the `m.0`, `m.1`, ... pairs stored on a provider log. */
+declare function decodeProviderMetadata(wire: unknown): Record<string, string>;
+
+export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OPENROUTER_METADATA_LIMITS, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type ProviderMetadataLimits, type RuntimeCallOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeError, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeLogger, type RuntimeMessage, type RuntimePatchProposal, type RuntimePolicyViolation, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeStreamDoneEvent, type RuntimeStreamErrorEvent, type RuntimeStreamEvent, type RuntimeStreamEventType, type RuntimeStreamReasoningDeltaEvent, type RuntimeStreamStartEvent, type RuntimeStreamTextDeltaEvent, type RuntimeStreamToolCallDeltaEvent, type RuntimeStreamUsageEvent, type RuntimeStreamWarningEvent, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type RuntimeWarning, type ServerToolKey, type ServerToolUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createConsoleLogger, createOpenRouterRuntime, decodeProviderMetadata, isRuntimeLoggingEnabled, toProviderMetadata };

package/dist/index.d.ts

@@ -1,13 +1,26 @@
 type ApiMode = "chat" | "responses" | "auto";
 type ResolvedApiMode = "chat" | "responses";
 type ToolMode = "disabled" | "allowed" | "required";
+interface RuntimeCallOptions {
+    /** Merged onto the compiled JSON body after known fields are assembled. */
+    finalizeBody?: (body: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Reads reasoning text from one chat delta.
+     * Returned text is emitted as `stream.reasoning.delta` and is not copied into answer text.
+     */
+    extractStreamReasoning?: (delta: unknown) => string | undefined;
+    /** When true, fusion/advisor/subagent tools do not inherit `request.reasoning`. */
+    suppressNestedReasoningFallback?: boolean;
+}
 interface OpenRouterRuntime {
-    run(request: RuntimeRequest): Promise<RuntimeResponse>;
+    compile(request: RuntimeRequest, call?: RuntimeCallOptions): CompiledOpenRouterRequest;
+    run(request: RuntimeRequest, call?: RuntimeCallOptions): Promise<RuntimeResponse>;
     /**
-     * Streaming chat entrypoint. Separate from `run()` by design.
+     * Explicit streaming chat API. Separate from `run()` by design — never an argument, never the default.
+     * Always sends OpenRouter Chat Completions with `stream: true` and yields typed SSE events.
      * The old `stream()` name was removed so mistaken/old clients break loudly.
      */
-    executeStreamingChat(request: RuntimeRequest): AsyncIterable<RuntimeStreamEvent>;
+    executeStreamingChat(request: RuntimeRequest, call?: RuntimeCallOptions): AsyncIterable<RuntimeStreamEvent>;
 }
 interface OpenRouterRuntimeOptions {
     apiKey?: string;
@@ -58,6 +71,16 @@ interface RuntimeRequest {
     functionTools?: RuntimeFunctionToolDefinition[];
     toolChoice?: RuntimeToolChoice;
     execution?: RuntimeExecutionPolicy;
+    /**
+     * Optional agent id for this call.
+     * OpenRouter sends it as the activity-log App name (`X-Title` and `X-OpenRouter-Title`).
+     * It is also stored in the provider metadata record as `agentId`.
+     */
+    agentId?: string;
+    /**
+     * Optional metadata. String, number, and boolean values are stored in the one provider
+     * metadata record. Objects and arrays stay on the normalized response.
+     */
     metadata?: Record<string, unknown>;
     rawOpenRouterOverrides?: Record<string, unknown>;
 }
@@ -178,6 +201,7 @@ interface FusionPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 interface AdvisorPolicy {
@@ -191,6 +215,7 @@ interface AdvisorPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 interface SubagentPolicy {
@@ -201,6 +226,7 @@ interface SubagentPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 type NestedOpenRouterServerToolPolicy = {
@@ -364,15 +390,75 @@ interface RuntimePolicyViolation {
     details?: unknown;
 }
 interface RuntimeStreamEvent {
-    type: string;
+    type: RuntimeStreamEventType;
+    requestId: string;
     data?: unknown;
 }
+type RuntimeStreamEventType = "stream.start" | "stream.text.delta" | "stream.reasoning.delta" | "stream.tool_call.delta" | "stream.usage" | "stream.warning" | "stream.error" | "stream.done";
+interface RuntimeStreamStartEvent extends RuntimeStreamEvent {
+    type: "stream.start";
+    data: {
+        model: string;
+        apiMode: "chat";
+        entrypoint: "executeStreamingChat";
+    };
+}
+interface RuntimeStreamTextDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.text.delta";
+    data: {
+        text: string;
+    };
+}
+interface RuntimeStreamReasoningDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.reasoning.delta";
+    data: {
+        text: string;
+    };
+}
+interface RuntimeStreamToolCallDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.tool_call.delta";
+    data: {
+        index: number;
+        id?: string;
+        name?: string;
+        argumentsDelta?: string;
+    };
+}
+interface RuntimeStreamUsageEvent extends RuntimeStreamEvent {
+    type: "stream.usage";
+    data: {
+        usage: RuntimeUsage;
+    };
+}
+interface RuntimeStreamWarningEvent extends RuntimeStreamEvent {
+    type: "stream.warning";
+    data: {
+        warning: RuntimeWarning;
+    };
+}
+interface RuntimeStreamErrorEvent extends RuntimeStreamEvent {
+    type: "stream.error";
+    data: {
+        error: RuntimeError;
+    };
+}
+interface RuntimeStreamDoneEvent extends RuntimeStreamEvent {
+    type: "stream.done";
+    data: {
+        text: string;
+        finishReason?: string;
+        model: string;
+    };
+}
 type RuntimePatchApplier = (patch: RuntimePatchProposal) => Promise<unknown> | unknown;
 
 declare function createOpenRouterRuntime(options: OpenRouterRuntimeOptions): OpenRouterRuntime;
 
 interface RuntimeCompileContext {
     streaming: boolean;
+    finalizeBody?: (body: Record<string, unknown>) => Record<string, unknown>;
+    /** When set, nested tools do not inherit the parent request reasoning object. */
+    suppressNestedReasoningFallback?: boolean;
 }
 interface OpenRouterTool {
     type: string;
@@ -409,9 +495,30 @@ declare class OpenRouterHttpError extends Error {
     constructor(status: number, code: ProviderFailureCode, message: string, body?: unknown | undefined, retryable?: boolean, providerAttempts?: ProviderAttemptError[]);
 }
 
-declare function buildOpenRouterServerTools(policy?: RuntimeServerToolsPolicy): OpenRouterTool[];
+declare function buildOpenRouterServerTools(policy?: RuntimeServerToolsPolicy, fallbackReasoning?: RuntimeReasoningConfig): OpenRouterTool[];
 
 declare function isRuntimeLoggingEnabled(env?: Record<string, string | undefined> | undefined): boolean;
 declare function createConsoleLogger(): RuntimeLogger;
 
-export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeError, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeLogger, type RuntimeMessage, type RuntimePatchProposal, type RuntimePolicyViolation, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeStreamEvent, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type RuntimeWarning, type ServerToolKey, type ServerToolUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createConsoleLogger, createOpenRouterRuntime, isRuntimeLoggingEnabled };
+interface ProviderMetadataLimits {
+    maxPairs: number;
+    maxKeyLength: number;
+    maxValueLength: number;
+    keyPattern?: RegExp;
+    valuePattern?: RegExp;
+}
+/** OpenRouter and OpenAI metadata: 16 pairs, 64-character keys, 512-character values. */
+declare const OPENROUTER_METADATA_LIMITS: ProviderMetadataLimits;
+/**
+ * One provider metadata record.
+ * Callers pass `metadata` and `agentId`. Every provider stores the same `m.0`, `m.1`, ...
+ * pairs: base64 of the UTF-8 JSON string map, 256 characters per pair, at most 16 pairs.
+ * `decodeProviderMetadata` restores that map from any provider log.
+ * `limits` stays on the signature for existing callers. The record uses the strictest
+ * provider limits, so the pairs do not change between providers.
+ */
+declare function toProviderMetadata(metadata: Record<string, unknown> | undefined, agentId: string | undefined, _limits: ProviderMetadataLimits, base: Record<string, unknown> | undefined): Record<string, string> | undefined;
+/** Restores the string map from the `m.0`, `m.1`, ... pairs stored on a provider log. */
+declare function decodeProviderMetadata(wire: unknown): Record<string, string>;
+
+export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OPENROUTER_METADATA_LIMITS, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type ProviderMetadataLimits, type RuntimeCallOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeError, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeLogger, type RuntimeMessage, type RuntimePatchProposal, type RuntimePolicyViolation, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeStreamDoneEvent, type RuntimeStreamErrorEvent, type RuntimeStreamEvent, type RuntimeStreamEventType, type RuntimeStreamReasoningDeltaEvent, type RuntimeStreamStartEvent, type RuntimeStreamTextDeltaEvent, type RuntimeStreamToolCallDeltaEvent, type RuntimeStreamUsageEvent, type RuntimeStreamWarningEvent, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type RuntimeWarning, type ServerToolKey, type ServerToolUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createConsoleLogger, createOpenRouterRuntime, decodeProviderMetadata, isRuntimeLoggingEnabled, toProviderMetadata };