@x12i/openrouter-runtime 1.1.0 → 1.4.0

package/dist/index.d.cts

@@ -1,14 +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>;
     /**
      * 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;
@@ -59,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>;
 }
@@ -179,6 +201,7 @@ interface FusionPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 interface AdvisorPolicy {
@@ -192,6 +215,7 @@ interface AdvisorPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 interface SubagentPolicy {
@@ -202,6 +226,7 @@ interface SubagentPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 type NestedOpenRouterServerToolPolicy = {
@@ -369,7 +394,7 @@ interface RuntimeStreamEvent {
     requestId: string;
     data?: unknown;
 }
-type RuntimeStreamEventType = "stream.start" | "stream.text.delta" | "stream.tool_call.delta" | "stream.usage" | "stream.warning" | "stream.error" | "stream.done";
+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: {
@@ -384,6 +409,12 @@ interface RuntimeStreamTextDeltaEvent extends RuntimeStreamEvent {
         text: string;
     };
 }
+interface RuntimeStreamReasoningDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.reasoning.delta";
+    data: {
+        text: string;
+    };
+}
 interface RuntimeStreamToolCallDeltaEvent extends RuntimeStreamEvent {
     type: "stream.tool_call.delta";
     data: {
@@ -425,6 +456,9 @@ declare function createOpenRouterRuntime(options: OpenRouterRuntimeOptions): Ope
 
 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;
@@ -461,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 RuntimeStreamDoneEvent, type RuntimeStreamErrorEvent, type RuntimeStreamEvent, type RuntimeStreamEventType, 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, 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,14 +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>;
     /**
      * 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;
@@ -59,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>;
 }
@@ -179,6 +201,7 @@ interface FusionPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 interface AdvisorPolicy {
@@ -192,6 +215,7 @@ interface AdvisorPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 interface SubagentPolicy {
@@ -202,6 +226,7 @@ interface SubagentPolicy {
     maxToolCalls?: number;
     maxCompletionTokens?: number;
     reasoning?: RuntimeReasoningConfig;
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "max";
     temperature?: number;
 }
 type NestedOpenRouterServerToolPolicy = {
@@ -369,7 +394,7 @@ interface RuntimeStreamEvent {
     requestId: string;
     data?: unknown;
 }
-type RuntimeStreamEventType = "stream.start" | "stream.text.delta" | "stream.tool_call.delta" | "stream.usage" | "stream.warning" | "stream.error" | "stream.done";
+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: {
@@ -384,6 +409,12 @@ interface RuntimeStreamTextDeltaEvent extends RuntimeStreamEvent {
         text: string;
     };
 }
+interface RuntimeStreamReasoningDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.reasoning.delta";
+    data: {
+        text: string;
+    };
+}
 interface RuntimeStreamToolCallDeltaEvent extends RuntimeStreamEvent {
     type: "stream.tool_call.delta";
     data: {
@@ -425,6 +456,9 @@ declare function createOpenRouterRuntime(options: OpenRouterRuntimeOptions): Ope
 
 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;
@@ -461,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 RuntimeStreamDoneEvent, type RuntimeStreamErrorEvent, type RuntimeStreamEvent, type RuntimeStreamEventType, 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, 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.js

@@ -722,13 +722,22 @@ function endpointFor(baseUrl, apiMode) {
 }
 
 // src/openrouter/headers.ts
-function buildHeaders(options) {
+function buildHeaders(options, agentId) {
+  const requestAppName = agentId?.trim();
   return {
     "content-type": "application/json",
     authorization: `Bearer ${options.apiKey}`,
     ...options.appAttribution?.siteUrl ? { "HTTP-Referer": options.appAttribution.siteUrl } : {},
-    ...options.appAttribution?.appName ? { "X-Title": options.appAttribution.appName } : {},
-    ...options.defaultHeaders ?? {}
+    ...appTitleHeaders(options.appAttribution?.appName),
+    ...options.defaultHeaders ?? {},
+    ...requestAppName ? appTitleHeaders(requestAppName) : {}
+  };
+}
+function appTitleHeaders(name) {
+  if (!name) return {};
+  return {
+    "X-Title": name,
+    "X-OpenRouter-Title": name
   };
 }
 
@@ -757,7 +766,7 @@ function cleanParameters(parameters) {
 function enabled(policy) {
   return !!policy && policy.mode !== "disabled";
 }
-function buildOpenRouterServerTools(policy) {
+function buildOpenRouterServerTools(policy, fallbackReasoning) {
   const tools = [];
   const webSearch = buildWebSearchTool(policy?.webSearch);
   if (webSearch) tools.push(webSearch);
@@ -769,10 +778,10 @@ function buildOpenRouterServerTools(policy) {
   if (image) tools.push(image);
   const patch = buildApplyPatchTool(policy?.applyPatch);
   if (patch) tools.push(patch);
-  const fusion = buildFusionTool(policy?.fusion);
+  const fusion = buildFusionTool(policy?.fusion, fallbackReasoning);
   if (fusion) tools.push(fusion);
-  tools.push(...buildAdvisorTools(policy?.advisor));
-  const subagent = buildSubagentTool(policy?.subagent);
+  tools.push(...buildAdvisorTools(policy?.advisor, fallbackReasoning));
+  const subagent = buildSubagentTool(policy?.subagent, fallbackReasoning);
   if (subagent) tools.push(subagent);
   return tools;
 }
@@ -831,7 +840,7 @@ function buildApplyPatchTool(policy) {
   if (!enabled(policy)) return void 0;
   return { type: "openrouter:apply_patch" };
 }
-function buildFusionTool(policy) {
+function buildFusionTool(policy, fallbackReasoning) {
   if (!enabled(policy)) return void 0;
   return {
     type: "openrouter:fusion",
@@ -840,12 +849,12 @@ function buildFusionTool(policy) {
       model: policy?.judgeModel,
       max_tool_calls: policy?.maxToolCalls ?? 8,
       max_completion_tokens: policy?.maxCompletionTokens,
-      reasoning: policy?.reasoning,
+      reasoning: policy?.reasoning ?? fallbackReasoning,
       temperature: policy?.temperature
     })
   };
 }
-function buildAdvisorTools(policy) {
+function buildAdvisorTools(policy, fallbackReasoning) {
   const advisors = Array.isArray(policy) ? policy : policy ? [policy] : [];
   return advisors.filter(enabled).map((advisor) => {
     validateNestedTools(advisor.tools);
@@ -860,13 +869,13 @@ function buildAdvisorTools(policy) {
         stream: advisor.stream,
         max_tool_calls: advisor.maxToolCalls,
         max_completion_tokens: advisor.maxCompletionTokens,
-        reasoning: advisor.reasoning,
+        reasoning: advisor.reasoning ?? fallbackReasoning,
         temperature: advisor.temperature
       })
     };
   });
 }
-function buildSubagentTool(policy) {
+function buildSubagentTool(policy, fallbackReasoning) {
   if (!policy || policy.mode === "disabled") return void 0;
   const subagent = policy;
   validateNestedTools(subagent.tools);
@@ -878,12 +887,86 @@ function buildSubagentTool(policy) {
       tools: subagent.tools,
       max_tool_calls: subagent.maxToolCalls,
       max_completion_tokens: subagent.maxCompletionTokens,
-      reasoning: subagent.reasoning,
+      reasoning: subagent.reasoning ?? fallbackReasoning,
       temperature: subagent.temperature
     })
   };
 }
 
+// src/utils/provider-metadata.ts
+var OPENROUTER_METADATA_LIMITS = {
+  maxPairs: 16,
+  maxKeyLength: 64,
+  maxValueLength: 512
+};
+var PROVIDER_RECORD_CHUNK = 256;
+var PROVIDER_RECORD_MAX_CHUNKS = 16;
+function toProviderMetadata(metadata, agentId, _limits, base) {
+  return encodeProviderRecord(collectProviderStrings(metadata, agentId, base));
+}
+function decodeProviderMetadata(wire) {
+  if (!isRecord2(wire)) return {};
+  const parts = [];
+  for (let index = 0; ; index += 1) {
+    const chunk = wire[`m.${index}`];
+    if (typeof chunk !== "string") break;
+    parts.push(chunk);
+  }
+  if (!parts.length) return {};
+  const parsed = JSON.parse(Buffer.from(parts.join(""), "base64").toString("utf8"));
+  if (!isRecord2(parsed)) return {};
+  const record = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value === "string") record[key] = value;
+  }
+  return record;
+}
+function encodeProviderRecord(map) {
+  const keys = Object.keys(map).sort();
+  if (!keys.length) return void 0;
+  const ordered = {};
+  for (const key of keys) {
+    const value = map[key];
+    if (value !== void 0) ordered[key] = value;
+  }
+  const encoded = Buffer.from(JSON.stringify(ordered), "utf8").toString("base64");
+  const chunks = Math.ceil(encoded.length / PROVIDER_RECORD_CHUNK);
+  if (chunks > PROVIDER_RECORD_MAX_CHUNKS) {
+    throw new Error(
+      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.length} base64 characters; the maximum is ${PROVIDER_RECORD_CHUNK * PROVIDER_RECORD_MAX_CHUNKS}.`
+    );
+  }
+  const wire = {};
+  for (let index = 0; index < chunks; index += 1) {
+    wire[`m.${index}`] = encoded.slice(index * PROVIDER_RECORD_CHUNK, (index + 1) * PROVIDER_RECORD_CHUNK);
+  }
+  return wire;
+}
+function collectProviderStrings(metadata, agentId, base) {
+  const map = {};
+  appendStrings(map, base);
+  appendStrings(map, metadata);
+  const trimmedAgentId = agentId?.trim();
+  if (trimmedAgentId) map.agentId = trimmedAgentId;
+  return map;
+}
+function appendStrings(target, metadata) {
+  if (!metadata) return;
+  for (const [key, value] of Object.entries(metadata)) {
+    const asString = asMetadataString(value);
+    if (asString !== void 0) target[key] = asString;
+  }
+}
+function asMetadataString(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return void 0;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/runtime/runtime.ts
 function compileRuntimeRequest(request, defaults, options = { apiKey: "" }, context = {}) {
   const warnings = [];
@@ -895,7 +978,10 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }, cont
   const apiMode = resolveApiMode(request, defaults.apiMode, serverTools);
   validateRuntimeRequest(request, options, apiMode, normalized.model, serverTools);
   const tools = [
-    ...buildOpenRouterServerTools(serverTools),
+    ...buildOpenRouterServerTools(
+      serverTools,
+      effectiveContext.suppressNestedReasoningFallback ? void 0 : request.reasoning
+    ),
     ...(request.functionTools ?? []).map((tool) => ({
       type: "function",
       function: {
@@ -905,10 +991,12 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }, cont
       }
     }))
   ];
-  const headers = buildHeaders(options);
+  const headers = buildHeaders(options, request.agentId);
   const baseBody = buildBaseBody(request, normalized.model, defaults, tools, serverTools);
-  const body = apiMode === "chat" ? buildChatBody(request, baseBody) : buildResponsesBody(request, baseBody);
+  const assembled = apiMode === "chat" ? buildChatBody(request, baseBody) : buildResponsesBody(request, baseBody);
+  let body = effectiveContext.finalizeBody ? effectiveContext.finalizeBody(assembled) : assembled;
   enforceStreamingPolicyForRun(body, warnings, effectiveContext);
+  body = attachProviderMetadata(body, request);
   return {
     apiMode,
     url: endpointFor(options.baseUrl ?? "https://openrouter.ai/api/v1", apiMode),
@@ -917,6 +1005,15 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }, cont
     warnings
   };
 }
+function attachProviderMetadata(body, request) {
+  const fromBody = isRecord(body.metadata) ? body.metadata : void 0;
+  const metadata = toProviderMetadata(request.metadata, request.agentId, OPENROUTER_METADATA_LIMITS, fromBody);
+  if (metadata) return { ...body, metadata };
+  if (body.metadata === void 0) return body;
+  const rest = { ...body };
+  delete rest.metadata;
+  return rest;
+}
 function enforceStreamingPolicyForRun(body, warnings, context) {
   if (context.streaming) {
     body.stream = true;
@@ -1450,7 +1547,7 @@ function isRetryableStatus2(status) {
 }
 
 // src/runtime/streaming.ts
-async function* executeStreamingChat(request, context) {
+async function* executeStreamingChat(request, context, call = {}) {
   const requestId = request.id ?? "unknown";
   const options = context.options;
   const defaults = context.defaults;
@@ -1465,7 +1562,11 @@ async function* executeStreamingChat(request, context) {
       ...request,
       apiMode: "chat"
     };
-    const compiled = compileRuntimeRequest(streamingRequest, defaults, options, { streaming: true });
+    const compiled = compileRuntimeRequest(streamingRequest, defaults, options, {
+      streaming: true,
+      ...call.finalizeBody ? { finalizeBody: call.finalizeBody } : {},
+      ...call.suppressNestedReasoningFallback ? { suppressNestedReasoningFallback: true } : {}
+    });
     if (compiled.body.stream !== true) {
       throw new RuntimeConfigError(
         "STREAMING_CHAT_MISCONFIGURED",
@@ -1500,6 +1601,10 @@ async function* executeStreamingChat(request, context) {
         if (typeof chunk.model === "string") resolvedModel = chunk.model;
         const choice = Array.isArray(chunk.choices) && isRecord(chunk.choices[0]) ? chunk.choices[0] : void 0;
         const delta = choice && isRecord(choice.delta) ? choice.delta : void 0;
+        if (delta && call.extractStreamReasoning) {
+          const reasoningText = call.extractStreamReasoning(delta);
+          if (reasoningText) yield reasoningDeltaEvent(requestId, reasoningText);
+        }
         if (delta && typeof delta.content === "string" && delta.content.length > 0) {
           text += delta.content;
           yield textDeltaEvent(requestId, delta.content);
@@ -1594,6 +1699,13 @@ function textDeltaEvent(requestId, text) {
     data: { text }
   };
 }
+function reasoningDeltaEvent(requestId, text) {
+  return {
+    type: "stream.reasoning.delta",
+    requestId,
+    data: { text }
+  };
+}
 function toolCallDeltaEvent(requestId, data) {
   return {
     type: "stream.tool_call.delta",
@@ -1663,7 +1775,14 @@ function createOpenRouterRuntime(options) {
   const defaults = resolveDefaults(options);
   const context = { options: resolvedOptions, defaults };
   return {
-    async run(request) {
+    compile(request, call) {
+      return compileRuntimeRequest(request, defaults, resolvedOptions, {
+        streaming: false,
+        ...call?.finalizeBody ? { finalizeBody: call.finalizeBody } : {},
+        ...call?.suppressNestedReasoningFallback ? { suppressNestedReasoningFallback: true } : {}
+      });
+    },
+    async run(request, call) {
       const requestWithId = { ...request, id: request.id ?? createRuntimeId() };
       try {
         resolvedOptions.logger?.info?.("runtime.request.started", {
@@ -1672,7 +1791,11 @@ function createOpenRouterRuntime(options) {
           entrypoint: "run"
         });
         await resolvedOptions.hooks?.beforeCompile?.(requestWithId);
-        const compiled = compileRuntimeRequest(requestWithId, defaults, resolvedOptions, { streaming: false });
+        const compiled = compileRuntimeRequest(requestWithId, defaults, resolvedOptions, {
+          streaming: false,
+          ...call?.finalizeBody ? { finalizeBody: call.finalizeBody } : {},
+          ...call?.suppressNestedReasoningFallback ? { suppressNestedReasoningFallback: true } : {}
+        });
         await resolvedOptions.hooks?.afterCompile?.(compiled);
         resolvedOptions.logger?.debug?.("runtime.request.compiled", {
           requestId: requestWithId.id,
@@ -1694,9 +1817,9 @@ function createOpenRouterRuntime(options) {
         return errorResponse(requestWithId, error);
       }
     },
-    executeStreamingChat(request) {
+    executeStreamingChat(request, call) {
       const requestWithId = { ...request, id: request.id ?? createRuntimeId() };
-      return executeStreamingChat(requestWithId, context);
+      return executeStreamingChat(requestWithId, context, call);
     }
   };
   function errorResponse(request, error) {
@@ -1785,12 +1908,15 @@ function operatorHintFor(code) {
   }
 }
 export {
+  OPENROUTER_METADATA_LIMITS,
   OpenRouterHttpError,
   RuntimeConfigError,
   buildOpenRouterServerTools,
   compileRuntimeRequest,
   createConsoleLogger,
   createOpenRouterRuntime,
-  isRuntimeLoggingEnabled
+  decodeProviderMetadata,
+  isRuntimeLoggingEnabled,
+  toProviderMetadata
 };
 //# sourceMappingURL=index.js.map