@springbrand/agent-runtime 0.3.0-alpha.13 → 0.3.0-alpha.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.13",
+  "version": "0.3.0-alpha.15",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/agent.ts

@@ -156,11 +156,16 @@ export abstract class AgentRuntimeKernel<
   };
 
   protected abstract ensureRuntimeReady(): Promise<void>;
-  /** Runs only before the first pin of a newly activated Submission. */
+  /** Prepare per-Submission Host state before the first assembly pin. */
   protected prepareRuntimeForSubmission(_submissionId: string): Promise<void> {
     return this.ensureRuntimeReady();
   }
 
+  /** Runs before a new Submission records its Runtime key. */
+  protected prepareRuntimeForAdmission(): Promise<void> {
+    return this.ensureRuntimeReady();
+  }
+
   protected ensureRuntimeVersion(_runtimeKey: string): Promise<void> {
     return this.ensureRuntimeReady();
   }
@@ -513,13 +518,12 @@ export abstract class AgentRuntimeKernel<
 
   // #region Submission 准入与配置固定
 
-  /** Pin dynamic Context and execution policy before admission. */
+  /** Pin dynamic Context and execution policy before the first assembly is used. */
   private async admissionPin(fresh: boolean, submissionId: string): Promise<{
     revision: string;
     descriptor: string;
   }> {
     if (fresh) await this.prepareRuntimeForSubmission(submissionId);
-    else await this.ensureRuntimeReady();
     const submission = this.db.submissions.find(submissionId);
     if (!submission) {
       throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
@@ -571,7 +575,7 @@ export abstract class AgentRuntimeKernel<
       submissions: this.db.submissions,
       transaction: (run) => this.db.transaction(run),
       prepareRuntime: async () => {
-        await this.ensureRuntimeReady();
+        await this.prepareRuntimeForAdmission();
         return { runtimeKey: this.activeRuntime!.runtimeKey, admission: this.activeRuntime?.admission };
       },
       findUserMessage: (id) => this.transcript.findUserMessage(id),
@@ -777,7 +781,7 @@ export abstract class AgentRuntimeKernel<
     submission = await this.admission.pin(
       submission,
       () => this.admissionPin(mode === "fresh", submissionId),
-      mode === "fresh" ? undefined : (key) => this.ensureRuntimeVersion(key),
+      (key) => this.ensureRuntimeVersion(key),
     );
     const activeRuntime = this.requireRuntime();
     const harnessInput = this.pi.harnessInputs(

package/src/adapter/cloudflare/define-agent.ts

@@ -17,7 +17,7 @@ import type { RuntimeState } from "../../conversation";
 import type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
-  TemporaryAgentLaunch,
+  TemporaryAgentLaunchSelection,
 } from "../../tools";
 import { TEMPORARY_AGENT_LAUNCH_KEY } from "../../tools";
 import {
@@ -83,7 +83,7 @@ export interface LoadedRuntime<Config> {
 export interface RuntimeConfigUpdate<Change> {
   readonly changed: boolean;
   readonly change: Change;
-  /** Restore any committed config state when the replacement Runtime cannot load. */
+  /** Restore committed state if an immediate replacement fails. */
   readonly rollback?: () => Promise<void>;
 }
 
@@ -96,11 +96,16 @@ interface RuntimeAgentDefinitionBase<
   /** 必须等于 Worker 导出名（Wrangler `class_name`）。 */
   readonly name: string;
 
-  /** Refresh Host-owned inputs before a new Submission is pinned. Never runs on continuation/recovery. */
+  /** Refresh Host-owned inputs before a new Submission records its Runtime key. */
   readonly beforeSubmission?: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
   ) => Promise<boolean>;
 
+  /** Prepare per-Submission Host state after admission and before its first assembly pin. */
+  readonly afterSubmission?: (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+  ) => Promise<void>;
+
   readonly load: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
     requestedRuntimeKey?: string,
@@ -360,9 +365,7 @@ const TERMINAL_AGENT_TOOL_STATUSES = [
 ] as const;
 const AGENT_TOOL_RETENTION_MS = 24 * 60 * 60 * 1_000;
 
-function parseTemporaryAgentLaunch<Config>(
-  input: unknown,
-): TemporaryAgentLaunch<Config> {
+function parseTemporaryAgentLaunch(input: unknown): TemporaryAgentLaunchSelection {
   const record = input != null && typeof input === "object"
     ? input as Record<string, unknown>
     : {};
@@ -380,17 +383,15 @@ function parseTemporaryAgentLaunch<Config>(
   ) {
     throw new Error("invalid temporary agent executionLevel");
   }
-  if (!("config" in record)) {
-    throw new Error("invalid temporary agent config");
-  }
-  return {
+  const selection: TemporaryAgentLaunchSelection = {
     subagentName: read("subagentName", 128),
     instructions: read("instructions", 65_536),
     task: read("task", 65_536),
     runtimeKey: read("runtimeKey", 512),
-    config: record.config as Config,
     executionLevel: executionLevel as ExecutionLevel,
   };
+  if ("config" in record) throw new Error("unexpected temporary agent config");
+  return selection;
 }
 
 /**
@@ -428,7 +429,7 @@ export function defineRuntimeAgent<
       private loading?: Promise<void>;
       private telemetryResolved = false;
       private resolvedTelemetry?: AgentTelemetryBinding;
-      private temporaryLaunch?: TemporaryAgentLaunch<Config>;
+      private temporaryLaunch?: TemporaryAgentLaunchSelection;
       private temporaryDispose?: () => Promise<void>;
       private temporaryCleanup?: Promise<void>;
 
@@ -449,10 +450,10 @@ export function defineRuntimeAgent<
         return this.ensureConfig(runtimeKey);
       }
 
-      protected async prepareRuntimeForSubmission(submissionId: string): Promise<void> {
+      protected async prepareRuntimeForAdmission(): Promise<void> {
         const beforeSubmission = definition.beforeSubmission as RuntimeAgentDefinitionBase<Env, Config, Command, Change>["beforeSubmission"];
         try {
-          const changed = await beforeSubmission?.(this.createDefinitionContext(undefined, submissionId));
+          const changed = await beforeSubmission?.(this.createDefinitionContext());
           await this.ensureConfig(undefined, changed === true);
         } catch (error) {
           this.hasLoadedRuntime = false;
@@ -460,6 +461,17 @@ export function defineRuntimeAgent<
         }
       }
 
+      protected async prepareRuntimeForSubmission(submissionId: string): Promise<void> {
+        const afterSubmission = definition.afterSubmission as RuntimeAgentDefinitionBase<Env, Config, Command, Change>["afterSubmission"];
+        try {
+          await this.ensureRuntimeReady();
+          await afterSubmission?.(this.createDefinitionContext(undefined, submissionId));
+        } catch (error) {
+          this.hasLoadedRuntime = false;
+          throw error;
+        }
+      }
+
       // 作用：加载默认 Runtime，或切换到调用方指定的 key。
       // 调用：RPC 控制面在业务配置需要刷新时调用。
       // 原因：复用 `ensureConfig`，让手动重载遵守和首次启动相同的原子规则。
@@ -551,7 +563,7 @@ export function defineRuntimeAgent<
         if (this.role !== "temporary") {
           throw new Error("Agent Tool runs require a temporary child facet");
         }
-        const launch = parseTemporaryAgentLaunch<Config>(input);
+        const launch = parseTemporaryAgentLaunch(input);
         this.temporaryLaunch = launch;
         await this.ctx.storage.put(TEMPORARY_AGENT_LAUNCH_KEY, launch);
         await this.reloadRuntime(launch.runtimeKey, { force: true });
@@ -624,6 +636,11 @@ export function defineRuntimeAgent<
             if (!resolvedRuntimeKey) {
               throw new Error("Resolved Runtime key must not be empty");
             }
+            if (requestedRuntimeKey && resolvedRuntimeKey !== requestedRuntimeKey) {
+              throw new Error(
+                `Requested Runtime key ${requestedRuntimeKey} resolved to ${resolvedRuntimeKey}`,
+              );
+            }
             const context = this.createDefinitionContext({
               value: loaded.config,
             });
@@ -723,7 +740,7 @@ export function defineRuntimeAgent<
         resources: ResolvedResources,
       ): Promise<ResolvedResources> {
         const launch = this.temporaryLaunch ??
-          await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
+          await this.ctx.storage.get<TemporaryAgentLaunchSelection>(
             TEMPORARY_AGENT_LAUNCH_KEY,
           );
         if (!launch) throw new Error("Temporary Agent is not initialized");
@@ -754,7 +771,7 @@ export function defineRuntimeAgent<
       }
 
       private async requestParentTemporaryApproval(
-        launch: TemporaryAgentLaunch<Config>,
+        launch: TemporaryAgentLaunchSelection,
         request: {
           toolCallId: string;
           toolName: string;
@@ -820,7 +837,7 @@ export function defineRuntimeAgent<
         this.temporaryCleanup = (async () => {
           if (!this.temporaryDispose) {
             const launch = this.temporaryLaunch ??
-              await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
+              await this.ctx.storage.get<TemporaryAgentLaunchSelection>(
                 TEMPORARY_AGENT_LAUNCH_KEY,
               );
             if (launch) await this.ensureConfig(launch.runtimeKey);
@@ -890,7 +907,6 @@ export function defineRuntimeAgent<
                     input: {
                       ...normalized,
                       runtimeKey: agent.loadedRuntimeKey,
-                      config: runtimeConfig.value,
                       executionLevel: agent.executionLevel(),
                     },
                     runId: `temporary-agent:${runContext.toolCallId}`,

package/src/config/assembler.ts

@@ -583,6 +583,9 @@ class RuntimeBuilder {
             ? { headers: Object.freeze({ ...endpoint.headers }) }
             : {}),
           models: Object.freeze([...endpoint.models]),
+          ...(endpoint.openRouterProviderPins
+            ? { openRouterProviderPins: Object.freeze({ ...endpoint.openRouterProviderPins }) }
+            : {}),
           ...(endpoint.modelInputModalities
             ? {
                 modelInputModalities: Object.freeze(Object.fromEntries(
@@ -592,6 +595,22 @@ class RuntimeBuilder {
                 )),
               }
             : {}),
+          ...(endpoint.modelMetadata
+            ? {
+                modelMetadata: Object.freeze(Object.fromEntries(
+                  Object.entries(endpoint.modelMetadata).map(([modelId, metadata]) => [
+                    modelId,
+                    Object.freeze({
+                      ...metadata,
+                      cost: Object.freeze({ ...metadata.cost }),
+                      ...(metadata.thinkingLevelMap
+                        ? { thinkingLevelMap: Object.freeze({ ...metadata.thinkingLevelMap }) }
+                        : {}),
+                    }),
+                  ]),
+                )),
+              }
+            : {}),
         }),
       )),
     });

package/src/config/pinning.ts

@@ -283,10 +283,25 @@ function describeRuntime(
   candidates: readonly PiToolCandidate[],
   loadedExtensions: readonly PiLoadedExtension[],
 ): string {
+  const model = snapshot.pi.model;
+  const openRouterRouting = model.compat && "openRouterRouting" in model.compat
+    ? model.compat.openRouterRouting
+    : undefined;
   return JSON.stringify({
     version: 1,
-    model: snapshot.pi.model.id,
-    provider: snapshot.pi.model.provider,
+    model: model.id,
+    provider: model.provider,
+    modelConfig: {
+      api: model.api,
+      name: model.name,
+      reasoning: model.reasoning,
+      input: model.input,
+      contextWindow: model.contextWindow,
+      maxTokens: model.maxTokens,
+      cost: model.cost,
+      ...(model.thinkingLevelMap ? { thinkingLevelMap: model.thinkingLevelMap } : {}),
+      ...(openRouterRouting ? { openRouterRouting } : {}),
+    },
     thinking: snapshot.pi.thinkingLevel,
     systemPrompt: snapshot.pi.systemPrompt,
     executionLevel: snapshot.profile.executionLevel,

package/src/config/ports.ts

@@ -950,6 +950,8 @@ export interface RuntimeBrowserPort {
 export type RuntimeModelProtocol =
   | "openai-chat"
   | "openrouter-messages"
+  | "openrouter-chat"
+  | "openrouter-responses"
   | "anthropic-messages"
   | "google-generative-ai"
   | "openai-codex-responses";
@@ -963,6 +965,31 @@ export type RuntimeModelProtocol =
  *
  * 凭据只留在 Port 对象，不进入 `RuntimeProfile` 或持久状态；术语见 `../index.ts`。
  */
+export type RuntimeModelThinkingLevel =
+  | "off"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max";
+
+export interface RuntimeModelMetadata {
+  readonly name: string;
+  readonly reasoning: boolean;
+  readonly contextWindow: number;
+  readonly maxTokens: number;
+  readonly cost: Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  }>;
+  readonly thinkingLevelMap?: Readonly<
+    Partial<Record<RuntimeModelThinkingLevel, string | null>>
+  >;
+}
+
 export interface RuntimeModelEndpoint {
   protocol: RuntimeModelProtocol;
   /** Resolved credential; never enters RuntimeProfile or persisted state. */
@@ -977,6 +1004,7 @@ export interface RuntimeModelEndpoint {
   >;
   /** OpenRouter upstream provider pins keyed by model ID; pinned requests never fall back. */
   openRouterProviderPins?: Readonly<Record<string, string>>;
+  modelMetadata?: Readonly<Record<string, RuntimeModelMetadata>>;
 }
 
 /**

package/src/conversation/message/projection.ts

@@ -373,6 +373,23 @@ export class PiChunkEncoder {
         const chunks = this.toolInputs.has(event.toolCallId)
           ? []
           : this.toolInput(event.toolCallId, event.toolName, event.args);
+        const partialResult = isRecord(event.partialResult)
+          ? event.partialResult
+          : undefined;
+        const details = isRecord(partialResult?.details)
+          ? partialResult.details
+          : undefined;
+        const actionToolMeta = isRecord(details?.actionToolMeta)
+          ? details.actionToolMeta
+          : undefined;
+        if (actionToolMeta) {
+          chunks.push({
+            type: "data-action-tool-meta",
+            id: event.toolCallId,
+            data: { toolCallId: event.toolCallId, ...actionToolMeta },
+          });
+          return chunks;
+        }
         chunks.push({
           type: "tool-output-available",
           toolCallId: event.toolCallId,

package/src/index.ts

@@ -127,7 +127,7 @@ export {
 export type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
-  TemporaryAgentLaunch,
+  TemporaryAgentLaunchSelection,
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
 } from "./tools/subagent/temporary/core";
@@ -144,3 +144,12 @@ export {
   modelRequestUrl,
   resolvePiModel,
 } from "./models";
+export {
+  openRouterRequestUrl,
+  requestOpenRouter,
+} from "./model-protocol/openrouter";
+export type { OpenRouterRequestOptions } from "./model-protocol/openrouter";
+export type {
+  ModelProtocolResponse,
+  OpenRouterProtocol,
+} from "./models/openrouter/protocol-response";

package/src/model-protocol/openrouter.ts

@@ -0,0 +1,41 @@
+import type { RuntimeModelEndpoint } from "../config/ports";
+
+export interface OpenRouterRequestOptions {
+  readonly headers?: HeadersInit;
+  readonly signal?: AbortSignal;
+  readonly fetch?: typeof fetch;
+}
+
+export function openRouterRequestUrl(
+  endpoint: Pick<RuntimeModelEndpoint, "protocol" | "baseURL">,
+): string {
+  const baseURL = endpoint.baseURL.replace(/\/+$/, "");
+  switch (endpoint.protocol) {
+    case "openrouter-messages":
+      return `${baseURL}/v1/messages`;
+    case "openrouter-chat":
+      return `${baseURL}/chat/completions`;
+    case "openrouter-responses":
+      return `${baseURL}/responses`;
+    default:
+      throw new Error(`Not an OpenRouter protocol: ${endpoint.protocol}`);
+  }
+}
+
+export function requestOpenRouter(
+  endpoint: RuntimeModelEndpoint,
+  body: Readonly<Record<string, unknown>>,
+  options: OpenRouterRequestOptions = {},
+): Promise<Response> {
+  const url = openRouterRequestUrl(endpoint);
+  const headers = new Headers(endpoint.headers);
+  new Headers(options.headers).forEach((value, name) => headers.set(name, value));
+  headers.set("content-type", "application/json");
+  headers.set("authorization", `Bearer ${endpoint.apiKey}`);
+  return (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    ...(options.signal ? { signal: options.signal } : {}),
+  });
+}

package/src/models/index.ts

@@ -48,12 +48,15 @@ import {
 } from "agents/chat";
 import type {
   RuntimeModelEndpoint,
+  RuntimeModelMetadata,
   RuntimeModelInputModality,
   RuntimeModelProtocol,
   RuntimeProviderPort,
 } from "../config/ports";
 import { modelInputMessages } from "../conversation/message/model-input";
 import { openRouterMessagesApi } from "./openrouter/messages";
+import { openRouterChatApi, openRouterResponsesApi } from "./openrouter/openai";
+import { withModelProtocolResponse } from "./openrouter/protocol-response";
 import {
   overlayProviderStreams,
   remapProviderStreamModels,
@@ -62,6 +65,8 @@ import {
 const CATALOGS = {
   "openai-chat": openaiProvider().getModels(),
   "openrouter-messages": openrouterProvider().getModels(),
+  "openrouter-chat": openrouterProvider().getModels(),
+  "openrouter-responses": openrouterProvider().getModels(),
   "anthropic-messages": anthropicProvider().getModels(),
   "google-generative-ai": googleProvider().getModels(),
   "openai-codex-responses": openaiCodexProvider().getModels(),
@@ -73,7 +78,7 @@ const NO_HOSTED_INPUT_MODALITIES: readonly RuntimeModelInputModality[] = [];
 function adapterHostedInputModalities(
   protocol: RuntimeModelProtocol,
 ): readonly RuntimeModelInputModality[] {
-  return protocol === "openrouter-messages" || protocol === "anthropic-messages"
+  return protocol.startsWith("openrouter-") || protocol === "anthropic-messages"
     ? MESSAGES_HOSTED_INPUT_MODALITIES
     : NO_HOSTED_INPUT_MODALITIES;
 }
@@ -148,10 +153,13 @@ export function structuredOutputStream(
   model: Model<Api>,
   schema: Record<string, unknown>,
 ): StreamFn | undefined {
-  if (
-    model.api !== "anthropic-messages" ||
-    !model.provider.startsWith("model-api-openrouter-messages-")
-  ) return undefined;
+  const messages = model.api === "anthropic-messages" &&
+    model.provider.startsWith("model-api-openrouter-messages-");
+  const chat = model.api === "openai-completions" &&
+    model.provider.startsWith("model-api-openrouter-chat-");
+  const responses = model.api === "openai-responses" &&
+    model.provider.startsWith("model-api-openrouter-responses-");
+  if (!messages && !chat && !responses) return undefined;
 
   return (activeModel, context, options) =>
     streamFn(activeModel, context, {
@@ -161,14 +169,36 @@ export function structuredOutputStream(
         if (!value || typeof value !== "object" || Array.isArray(value)) {
           throw new Error("Structured model payload must be an object");
         }
-        const current = (value as Record<string, unknown>).output_config;
+        const body = value as Record<string, unknown>;
+        if (messages) {
+          const current = body.output_config;
+          return {
+            ...body,
+            output_config: {
+              ...(current && typeof current === "object" && !Array.isArray(current)
+                ? current
+                : {}),
+              format: { type: "json_schema", schema },
+            },
+          };
+        }
+        if (chat) {
+          return {
+            ...body,
+            response_format: {
+              type: "json_schema",
+              json_schema: { name: "agent_output", strict: true, schema },
+            },
+          };
+        }
+        const current = body.text;
         return {
-          ...value,
-          output_config: {
+          ...body,
+          text: {
             ...(current && typeof current === "object" && !Array.isArray(current)
               ? current
               : {}),
-            format: { type: "json_schema", schema },
+            format: { type: "json_schema", name: "agent_output", strict: true, schema },
           },
         };
       },
@@ -264,7 +294,8 @@ function pdfPayload(payload: unknown, api: Api): unknown {
       };
     }
   }
-  if (api === "openai-codex-responses" && value.type === "input_image") {
+  if ((api === "openai-codex-responses" || api === "openai-responses") &&
+    value.type === "input_image") {
     if (
       typeof value.image_url === "string" &&
       value.image_url.startsWith("data:application/pdf;base64,")
@@ -483,6 +514,8 @@ export function modelRequestUrl(model: Model<Api>): string {
       return `${base}/v1/messages`;
     case "google-generative-ai":
       return `${base}/models/${model.id}:streamGenerateContent`;
+    case "openai-responses":
+      return `${base}/responses`;
     case "openai-codex-responses":
       return base.endsWith("/codex/responses") || base.endsWith("/responses")
         ? base
@@ -697,7 +730,10 @@ function providerId(endpoint: RuntimeModelEndpoint, index: number): string {
 function apiFor(protocol: RuntimeModelProtocol): Api {
   switch (protocol) {
     case "openai-chat":
+    case "openrouter-chat":
       return "openai-completions";
+    case "openrouter-responses":
+      return "openai-responses";
     case "openrouter-messages":
     case "anthropic-messages":
       return "anthropic-messages";
@@ -710,12 +746,16 @@ function apiFor(protocol: RuntimeModelProtocol): Api {
 
 function piApiFor(endpoint: RuntimeModelEndpoint): ProviderStreams {
   const protocol = endpoint.protocol;
-  const api = (() => {
+  const implementation = (() => {
     switch (protocol) {
       case "openai-chat":
         return openAICompletionsApi();
       case "openrouter-messages":
         return openRouterMessagesApi();
+      case "openrouter-chat":
+        return openRouterChatApi();
+      case "openrouter-responses":
+        return openRouterResponsesApi();
       case "anthropic-messages":
         return anthropicMessagesApi();
       case "google-generative-ai":
@@ -724,6 +764,9 @@ function piApiFor(endpoint: RuntimeModelEndpoint): ProviderStreams {
         return openAICodexResponsesApi();
     }
   })();
+  const api = protocol.startsWith("openrouter-")
+    ? withModelProtocolResponse(implementation, protocol as "openrouter-messages" | "openrouter-chat" | "openrouter-responses")
+    : implementation;
   const contextFor = (
     model: Model<Api>,
     context: TranscriptContext,
@@ -760,6 +803,28 @@ function anthropicMessagesModelForOpenRouter(
 // 把部署声明的模型改造成可由对应自定义端点执行的 Pi 模型。
 // resolvePiModel 为单个运行快照调用它，configurePiModels 则在注册端点时为端点中的每个 modelId 调用它。
 // Pi 的内置 OpenAI、Anthropic provider 提供上下文窗口、费用和推理能力等元数据；这里保留这些元数据，但以部署协议、provider 标识和 baseURL 覆盖内置路由，未知模型会在初始化阶段直接报错，而不是拖到请求阶段。
+function assertModelMetadata(
+  metadata: RuntimeModelMetadata,
+  modelId: string,
+): void {
+  if (
+    typeof metadata.name !== "string" || !metadata.name.trim() ||
+    typeof metadata.reasoning !== "boolean" ||
+    !Number.isSafeInteger(metadata.contextWindow) || metadata.contextWindow <= 0 ||
+    !Number.isSafeInteger(metadata.maxTokens) || metadata.maxTokens <= 0 ||
+    metadata.maxTokens > metadata.contextWindow ||
+    !metadata.cost ||
+    [metadata.cost.input, metadata.cost.output, metadata.cost.cacheRead, metadata.cost.cacheWrite]
+      .some((rate) => !Number.isFinite(rate) || rate < 0) ||
+    Object.entries(metadata.thinkingLevelMap ?? {}).some(([level, value]) =>
+      !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(level) ||
+      (value !== null && (typeof value !== "string" || !value.trim()))
+    )
+  ) {
+    throw new Error(`Invalid deployment model metadata: ${modelId}`);
+  }
+}
+
 function configuredModel(
   endpoint: RuntimeModelEndpoint,
   index: number,
@@ -768,11 +833,28 @@ function configuredModel(
   const catalogModel = CATALOGS[endpoint.protocol].find(
     (model) => model.id === modelId,
   );
-  if (!catalogModel) {
+  const explicitMetadata = endpoint.modelMetadata?.[modelId];
+  if (!catalogModel && !explicitMetadata) {
     throw new Error(
-      `Model is not in SpringBrand's built-in catalog for ${endpoint.protocol}: ${modelId}`,
+      `Model is not in SpringBrand's built-in catalog and has no deployment metadata for ${endpoint.protocol}: ${modelId}`,
     );
   }
+  if (explicitMetadata) assertModelMetadata(explicitMetadata, modelId);
+  if (!catalogModel && !endpoint.modelInputModalities?.[modelId]?.includes("text")) {
+    throw new Error(`Deployment model requires explicit text input capability: ${modelId}`);
+  }
+  const sourceModel: Model<Api> = catalogModel ?? {
+    id: modelId,
+    name: explicitMetadata!.name,
+    api: apiFor(endpoint.protocol),
+    provider: "openrouter",
+    baseUrl: endpoint.baseURL,
+    reasoning: explicitMetadata!.reasoning,
+    input: ["text"],
+    cost: explicitMetadata!.cost,
+    contextWindow: explicitMetadata!.contextWindow,
+    maxTokens: explicitMetadata!.maxTokens,
+  };
   const {
     api: catalogApi,
     provider: _provider,
@@ -781,7 +863,7 @@ function configuredModel(
     headers: catalogHeaders,
     input: catalogInput,
     ...metadata
-  } = catalogModel;
+  } = sourceModel;
   const headers = {
     ...catalogHeaders,
     ...endpoint.headers,
@@ -794,27 +876,70 @@ function configuredModel(
     (modality): modality is "text" | "image" =>
       modality === "text" || modality === "image",
   );
-  // OpenRouter uses dotted versions and optional transport suffixes while the
-  // Anthropic catalog uses dashed base model ids.
+  const isOpenRouter = endpoint.protocol.startsWith("openrouter-");
   const anthropicMessagesCompat = endpoint.protocol === "openrouter-messages"
     ? anthropicMessagesModelForOpenRouter(modelId)?.compat
     : undefined;
+  const openAIResponsesCompat = endpoint.protocol === "openrouter-responses" &&
+      modelId.startsWith("openai/")
+    ? CATALOGS["openai-chat"].find((model) =>
+      model.id === modelId.slice("openai/".length) && model.api === "openai-responses"
+    )?.compat
+    : undefined;
   return {
     ...metadata,
+    ...(explicitMetadata
+      ? {
+          name: explicitMetadata.name,
+          reasoning: explicitMetadata.reasoning,
+          contextWindow: explicitMetadata.contextWindow,
+          maxTokens: explicitMetadata.maxTokens,
+          cost: { ...explicitMetadata.cost },
+          ...(explicitMetadata.thinkingLevelMap
+            ? { thinkingLevelMap: { ...explicitMetadata.thinkingLevelMap } }
+            : {}),
+        }
+      : {}),
     input,
     api: configuredApi,
     provider: providerId(endpoint, index),
     baseUrl: endpoint.baseURL,
-    ...(endpoint.protocol === "openrouter-messages"
+    ...(isOpenRouter
       ? {
           compat: {
-            ...anthropicMessagesCompat,
-            // OpenRouter rejects Anthropic's mid-conversation effort messages and block binding.
-            supportsMidConvoEffort: false,
-            supportsEagerToolInputStreaming: false,
-            supportsStrictTools:
-              anthropicMessagesCompat?.supportsStrictTools ?? false,
-            supportsToolReferences: true,
+            ...(endpoint.protocol === "openrouter-messages"
+              ? {
+                  ...anthropicMessagesCompat,
+                  supportsMidConvoEffort: false,
+                  supportsEagerToolInputStreaming: false,
+                  supportsStrictTools:
+                    anthropicMessagesCompat?.supportsStrictTools ?? false,
+                  supportsToolReferences: true,
+                  ...(modelId === "anthropic/claude-sonnet-5.5" ||
+                      modelId === "anthropic/claude-opus-5.5"
+                    ? { forceAdaptiveThinking: true }
+                    : {}),
+                }
+              : endpoint.protocol === "openrouter-chat"
+                ? {
+                    ...catalogCompat,
+                    thinkingFormat: "openrouter" as const,
+                    maxTokensField: "max_tokens" as const,
+                    supportsStore: false,
+                    sessionAffinityFormat: "openrouter" as const,
+                    sendSessionAffinityHeaders: true,
+                    ...(modelId.startsWith("anthropic/")
+                      ? { cacheControlFormat: "anthropic" as const }
+                      : {}),
+                  }
+                : {
+                    sessionAffinityFormat: "openrouter" as const,
+                    supportsDeveloperRole: modelId.startsWith("openai/") ||
+                      modelId.startsWith("anthropic/"),
+                    supportsStrictMode: openAIResponsesCompat?.supportsStrictMode ?? false,
+                    supportsOpenAIGrammarTools:
+                      openAIResponsesCompat?.supportsOpenAIGrammarTools ?? false,
+                  }),
             openRouterRouting: {
               require_parameters: true,
               ...(openRouterProviderPin
@@ -868,6 +993,13 @@ export function configurePiModels(
   models: MutableModels,
   provider: RuntimeProviderPort,
 ): MutableModels {
+  for (const endpoint of provider.endpoints) {
+    for (const modelId of Object.keys(endpoint.modelMetadata ?? {})) {
+      if (!endpoint.models.includes(modelId)) {
+        throw new Error(`Deployment metadata is not configured for this endpoint: ${modelId}`);
+      }
+    }
+  }
   const configuredProviders = provider.endpoints.map((endpoint, index) =>
     createProvider({
       id: providerId(endpoint, index),

package/src/models/openrouter/openai.ts

@@ -0,0 +1,200 @@
+import type {
+  Context,
+  Model,
+  ProviderStreams,
+  StreamOptions,
+  TranscriptContext,
+} from "@earendil-works/pi-ai";
+import { getCurrentTools } from "@earendil-works/pi-ai";
+import {
+  openAICompletionsApi,
+} from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import {
+  openAIResponsesApi,
+} from "@earendil-works/pi-ai/api/openai-responses.lazy";
+import { overlayProviderStreams } from "../provider-streams";
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function openRouterOptions(
+  model: Model<"openai-completions" | "openai-responses">,
+  context: TranscriptContext,
+  options?: StreamOptions,
+): StreamOptions {
+  return {
+    ...options,
+    onPayload: async (payload, activeModel) => {
+      const callerPayload = await options?.onPayload?.(payload, activeModel) ?? payload;
+      const body = record(callerPayload);
+      if (!body) throw new Error("OpenRouter payload must be an object");
+      const replayed = model.api === "openai-responses"
+        ? responsesToolSearch(replayResponsesMessages(body, model, context), context)
+        : body;
+      if (model.api === "openai-responses") {
+        if (replayed.store !== false || replayed.previous_response_id != null) {
+          throw new Error("OpenRouter Responses requires store: false and full input history");
+        }
+        if (replayed.background === true) {
+          throw new Error("Background Responses cannot run in a streaming Agent turn");
+        }
+      }
+      const compat = model.compat as {
+        openRouterRouting?: Readonly<Record<string, unknown>>;
+      } | undefined;
+      const reasoning = record(replayed.reasoning);
+      const include = Array.isArray(replayed.include) ? replayed.include : [];
+      return {
+        ...replayed,
+        ...(model.api === "openai-responses" && reasoning?.effort !== undefined &&
+          reasoning.effort !== null && reasoning.effort !== "none" &&
+          !include.includes("reasoning.encrypted_content")
+          ? { include: [...include, "reasoning.encrypted_content"] }
+          : {}),
+        ...(options?.sessionId ? { session_id: options.sessionId } : {}),
+        provider: {
+          ...record(replayed.provider),
+          ...compat?.openRouterRouting,
+          require_parameters: true,
+        },
+      };
+    },
+  };
+}
+
+function responsesToolSearch(
+  body: Record<string, unknown>,
+  context: TranscriptContext,
+): Record<string, unknown> {
+  const deferredNames = new Set(
+    getCurrentTools(context.messages)
+      .filter((tool) => tool.deferLoading).map((tool) => tool.name),
+  );
+  if (deferredNames.size === 0) return body;
+  const tools = Array.isArray(body.tools) ? body.tools : [];
+  const toolName = (tool: unknown) => {
+    const name = record(tool)?.name;
+    return typeof name === "string" ? name : "";
+  };
+  const deferred = tools.filter((tool) => deferredNames.has(toolName(tool)));
+  if (deferred.length !== deferredNames.size) {
+    throw new Error("Deferred Runtime tools are missing from the Responses payload");
+  }
+  const choice = record(body.tool_choice);
+  if (body.tool_choice !== undefined && body.tool_choice !== "auto" &&
+    choice?.type !== "allowed_tools") {
+    throw new Error("tool_choice conflicts with openrouter:tool_search");
+  }
+  const hasSearch = tools.some((tool) =>
+    ["openrouter:tool_search", "tool_search"].includes(record(tool)?.type as string)
+  );
+  return {
+    ...body,
+    tools: [
+      ...(hasSearch ? [] : [{ type: "openrouter:tool_search", parameters: { max_results: 5 } }]),
+      ...tools.map((tool) => deferredNames.has(toolName(tool))
+        ? { ...record(tool), defer_loading: true }
+        : tool),
+    ],
+  };
+}
+
+function responsesOutput(message: Context["messages"][number]): Record<string, unknown>[] {
+  if (message.role !== "assistant") return [];
+  if (!message.protocolResponse?.output) return [];
+  return message.protocolResponse.output.map((item) => ({ ...item }));
+}
+
+function sameResponseItem(
+  generated: Record<string, unknown> | undefined,
+  original: Record<string, unknown>,
+): boolean {
+  if (!generated || generated.type !== original.type ||
+    generated.id !== original.id) return false;
+  if (original.type === "message") {
+    const text = (content: unknown) => Array.isArray(content)
+      ? content.map((block) => {
+          const part = record(block);
+          return part?.type === "output_text" ? part.text : part?.refusal;
+        }).join("")
+      : content;
+    return text(generated.content) === text(original.content);
+  }
+  if (original.type === "function_call" || original.type === "custom_tool_call") {
+    return generated.call_id === original.call_id &&
+      generated.name === original.name;
+  }
+  return original.type === "reasoning";
+}
+
+function replayResponsesMessages(
+  body: Record<string, unknown>,
+  model: Model<"openai-completions" | "openai-responses">,
+  context: TranscriptContext,
+): Record<string, unknown> {
+  if (!Array.isArray(body.input)) return body;
+  const input = [...body.input];
+  for (const message of context.messages) {
+    if (
+      message.role !== "assistant" ||
+      message.provider !== model.provider ||
+      message.model !== model.id ||
+      message.api !== "openai-responses" ||
+      !message.protocolResponse?.output
+    ) continue;
+    const output = responsesOutput(message);
+    const anchors = output.filter((item) => [
+      "message", "reasoning", "function_call", "custom_tool_call",
+    ].includes(item.type as string));
+    if (anchors.length === 0) continue;
+    const start = input.findIndex((item) =>
+      sameResponseItem(record(item), anchors[0]!)
+    );
+    if (start < 0 || !anchors.every((item, index) =>
+      sameResponseItem(record(input[start + index]), item)
+    )) {
+      for (const item of output) {
+        if (item.type !== "message") continue;
+        const index = input.findIndex((value) => sameResponseItem(record(value), item));
+        if (index >= 0) input[index] = item;
+      }
+      continue;
+    }
+    input.splice(start, anchors.length, ...output.map((item) => {
+      if (item.type !== "reasoning" || item.encrypted_content) return item;
+      const original = record(input[start + anchors.indexOf(item)]);
+      return original?.encrypted_content
+        ? { ...item, encrypted_content: original.encrypted_content }
+        : item;
+    }));
+  }
+  return { ...body, input };
+}
+
+function routedApi(api: ProviderStreams): ProviderStreams {
+  return overlayProviderStreams(api, {
+    stream: (model, context, options) =>
+      api.stream(model, context, openRouterOptions(
+        model as Model<"openai-completions" | "openai-responses">,
+        context,
+        options,
+      )),
+    streamSimple: (model, context, options) =>
+      api.streamSimple(model, context, openRouterOptions(
+        model as Model<"openai-completions" | "openai-responses">,
+        context,
+        options,
+      )),
+  });
+}
+
+export function openRouterChatApi(): ProviderStreams {
+  return routedApi(openAICompletionsApi());
+}
+
+export function openRouterResponsesApi(): ProviderStreams {
+  return routedApi(openAIResponsesApi());
+}

package/src/models/openrouter/protocol-response.ts

@@ -0,0 +1,161 @@
+import {
+  createAssistantMessageEventStream,
+  fauxAssistantMessage,
+  type Api,
+  type AssistantMessage,
+  type AssistantMessageEventStream,
+  type Model,
+  type ProviderStreams,
+  type StreamOptions,
+} from "@earendil-works/pi-ai";
+import type { RuntimeModelProtocol } from "../../config/ports";
+import { overlayProviderStreams } from "../provider-streams";
+
+export type OpenRouterProtocol = Extract<RuntimeModelProtocol, `openrouter-${string}`>;
+
+/** Minimal native output retained for the next OpenRouter Responses request. */
+export interface ModelProtocolResponse {
+  readonly output: readonly Readonly<Record<string, unknown>>[];
+}
+
+interface ProtocolEvent {
+  readonly data: unknown;
+}
+
+declare module "@earendil-works/pi-ai" {
+  interface AssistantMessage {
+    protocolResponse?: ModelProtocolResponse;
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function parseProtocolEvents(body: string): ProtocolEvent[] {
+  return body.split(/\r?\n\r?\n/).flatMap((frame) => {
+    const lines = frame.split(/\r?\n/);
+    const dataLines = lines.filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).replace(/^ /, ""));
+    if (dataLines.length === 0) return [];
+    const dataText = dataLines.join("\n");
+    let data: unknown = dataText;
+    try {
+      data = JSON.parse(dataText);
+    } catch {
+      data = dataText;
+    }
+    return [{ data }];
+  });
+}
+
+function compactResponsesBody(body: string): ModelProtocolResponse | undefined {
+  const completedItems = new Map<number, Record<string, unknown>>();
+  let terminalItems: Record<string, unknown>[] | undefined;
+  let terminal = false;
+  for (const frame of parseProtocolEvents(body)) {
+    const event = record(frame.data);
+    if (
+      event?.type === "response.output_item.done" &&
+      typeof event.output_index === "number"
+    ) {
+      const item = record(event.item);
+      if (item) completedItems.set(event.output_index, item);
+    }
+    if (event?.type === "response.completed" || event?.type === "response.incomplete") {
+      terminal = true;
+      const response = record(event.response);
+      if (Array.isArray(response?.output)) {
+        terminalItems = response.output.flatMap((value) => {
+          const output = record(value);
+          return output ? [output] : [];
+        });
+      }
+    }
+  }
+  if (!terminal) return undefined;
+  const output = terminalItems?.length
+    ? terminalItems.map((item, index) => ({ ...completedItems.get(index), ...item }))
+    : [...completedItems.entries()]
+      .sort(([left], [right]) => left - right)
+      .map(([, item]) => item);
+  return output.length > 0 ? { output } : undefined;
+}
+
+function streamWithProtocolResponse<T extends StreamOptions>(
+  model: Model<Api>,
+  options: T | undefined,
+  start: (options: T) => AssistantMessageEventStream,
+): AssistantMessageEventStream {
+  const output = createAssistantMessageEventStream();
+  const fetcher = options?.fetch ?? globalThis.fetch;
+  let responseOutput: Promise<ModelProtocolResponse | undefined> | undefined;
+  let terminal = false;
+  const requestOptions = {
+    ...options,
+    fetch: (async (...args: Parameters<typeof fetch>) => {
+      const response = await fetcher(...args);
+      responseOutput = response.clone().text()
+        .then((body) => compactResponsesBody(body))
+        .catch(() => undefined);
+      return response;
+    }) satisfies typeof fetch,
+  } as T;
+
+  void (async () => {
+    const source = start(requestOptions);
+    for await (const event of source) {
+      if (event.type === "done" || event.type === "error") {
+        terminal = true;
+        if (responseOutput) {
+          const message = event.type === "done" ? event.message : event.error;
+          const compact = await responseOutput;
+          if (compact) message.protocolResponse = compact;
+        }
+      }
+      output.push(event);
+    }
+    if (!terminal) throw new Error("Provider stream ended without a terminal event");
+    output.end();
+  })().catch(async (error: unknown) => {
+    if (terminal) {
+      output.end();
+      return;
+    }
+    const reason = options?.signal?.aborted ? "aborted" : "error";
+    const failure = fauxAssistantMessage("", {
+      stopReason: reason,
+      errorMessage: error instanceof Error ? error.message : String(error),
+    });
+    if (responseOutput) {
+      const compact = await responseOutput;
+      if (compact) failure.protocolResponse = compact;
+    }
+    output.push({
+      type: "error",
+      reason,
+      error: { ...failure, api: model.api, provider: model.provider, model: model.id },
+    });
+    output.end();
+  });
+  return output;
+}
+
+export function withModelProtocolResponse(
+  api: ProviderStreams,
+  protocol: OpenRouterProtocol,
+): ProviderStreams {
+  if (protocol !== "openrouter-responses") return api;
+  return overlayProviderStreams(api, {
+    stream: (model, context, options) =>
+      streamWithProtocolResponse(model, options, (requestOptions) =>
+        api.stream(model, context, requestOptions)
+      ),
+    streamSimple: (model, context, options) =>
+      streamWithProtocolResponse(model, options, (requestOptions) =>
+        api.streamSimple(model, context, requestOptions)
+      ),
+  });
+}

package/src/tools/subagent/temporary/core.ts

@@ -9,10 +9,9 @@ export interface TemporaryAgentRequest {
   task: string;
 }
 
-export interface TemporaryAgentLaunch<Config = unknown>
+export interface TemporaryAgentLaunchSelection
   extends TemporaryAgentRequest {
   runtimeKey: string;
-  config: Config;
   executionLevel: ExecutionLevel;
 }
 

package/src/tools/web/search/api.ts

@@ -1128,6 +1128,8 @@ export interface WebSearchOptions {
 function apiFor(endpoint: RuntimeModelEndpoint): NativeApi {
   switch (endpoint.protocol) {
     case "openrouter-messages":
+    case "openrouter-chat":
+    case "openrouter-responses":
       return "openrouter-responses";
     case "google-generative-ai":
       return "google-generative-ai";