@springbrand/agent-runtime 0.2.0-alpha.30 → 0.2.0-alpha.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.30",
+  "version": "0.2.0-alpha.31",
   "type": "module",
   "files": [
     "src",

package/src/kernel/bindings.ts

@@ -889,7 +889,7 @@ export interface RuntimeBrowserPort {
  */
 export type RuntimeModelProtocol =
   | "openai-chat"
-  | "openrouter-chat"
+  | "openrouter-messages"
   | "anthropic-messages"
   | "google-generative-ai"
   | "openai-codex-responses";

package/src/lib/prompt.ts

@@ -50,6 +50,8 @@ export const TOOLS =
   "or branching or repetition MUST use one execute. Do not make repeated top-level calls for that work. Inside execute, use state.* for " +
   "workspace file operations, tools.* for other host capabilities, a loop for repeated calls, and Promise.all for independent calls. " +
   "Tools available only at the top level must stay Direct. " +
+  "Some Tools may be deferred and absent from the initial list. When Tool Search is available, before saying that a requested capability or named Tool is unavailable, use the available Tool Search once. " +
+  "If the user names a Tool, search that exact name by itself first. Searchable categories may include workspace and files, browser and web, interaction and planning, memory and scheduling, Skills, Extensions, MCP, Plugins, and Host capabilities; discover them only when needed. " +
   "For web tasks, use web_search for web discovery, current facts, cited research, " +
   "and public URL analysis. For web access specifically, use execute Code Mode only for raw or customized network requests, structured " +
   "API calls, or when web_search cannot retrieve the required content; do not use execute for ordinary web " +

package/src/pi/runtime-adapter/assembly.ts

@@ -256,6 +256,7 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
       ...(candidate.alwaysRequiresApproval
         ? { alwaysRequiresApproval: true }
         : {}),
+      ...(candidate.deferLoading ? { deferLoading: true } : {}),
       ...(candidate.source ? { source: candidate.source } : {}),
       retry: piToolRetryPolicy(candidate),
     }))

package/src/pi/runtime-adapter/models.ts

@@ -10,9 +10,7 @@ import {
   type Model,
   type MutableModels,
 } from "@earendil-works/pi-ai";
-import {
-  anthropicMessagesApi,
-} from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
+import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
 import {
   openAICompletionsApi,
 } from "@earendil-works/pi-ai/api/openai-completions.lazy";
@@ -48,10 +46,11 @@ import type {
   RuntimeModelProtocol,
   RuntimeProviderPort,
 } from "../../kernel/bindings";
+import { openRouterMessagesApi } from "./openrouter-messages";
 
 const CATALOGS = {
   "openai-chat": openaiProvider().getModels(),
-  "openrouter-chat": openrouterProvider().getModels(),
+  "openrouter-messages": openrouterProvider().getModels(),
   "anthropic-messages": anthropicProvider().getModels(),
   "google-generative-ai": googleProvider().getModels(),
   "openai-codex-responses": openaiCodexProvider().getModels(),
@@ -560,8 +559,8 @@ 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-messages":
     case "anthropic-messages":
       return "anthropic-messages";
     case "google-generative-ai":
@@ -574,8 +573,9 @@ function apiFor(protocol: RuntimeModelProtocol): Api {
 function piApiFor(protocol: RuntimeModelProtocol) {
   switch (protocol) {
     case "openai-chat":
-    case "openrouter-chat":
       return openAICompletionsApi();
+    case "openrouter-messages":
+      return openRouterMessagesApi();
     case "anthropic-messages":
       return anthropicMessagesApi();
     case "google-generative-ai":
@@ -619,12 +619,11 @@ function configuredModel(
     api: apiFor(endpoint.protocol),
     provider: providerId(endpoint, index),
     baseUrl: endpoint.baseURL,
-    ...(endpoint.protocol === "openrouter-chat"
+    ...(endpoint.protocol === "openrouter-messages"
       ? {
           compat: {
-            ...compat,
-            sendSessionAffinityHeaders: true,
-            sessionAffinityFormat: "openrouter" as const,
+            supportsEagerToolInputStreaming: false,
+            supportsToolReferences: true,
             ...(openRouterProviderPin
               ? {
                   openRouterRouting: {

package/src/pi/runtime-adapter/openrouter-messages.ts

@@ -0,0 +1,127 @@
+import type {
+  Context,
+  Model,
+  ProviderStreams,
+  StreamOptions,
+} from "@earendil-works/pi-ai";
+import {
+  anthropicMessagesApi,
+} from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
+
+type Payload = Record<string, unknown>;
+
+function record(value: unknown): Payload | undefined {
+  return value !== null && typeof value === "object"
+    ? value as Payload
+    : undefined;
+}
+
+function decoratePayload(
+  payload: unknown,
+  model: Model<"anthropic-messages">,
+  context: Context,
+  sessionId?: string,
+): unknown {
+  const body = record(payload);
+  if (!body) throw new Error("OpenRouter Messages payload must be an object");
+
+  const deferredNames = new Set(
+    context.tools?.filter((tool) => tool.deferLoading).map((tool) => tool.name),
+  );
+  const tools = Array.isArray(body.tools) ? body.tools : [];
+  const immediate: unknown[] = [];
+  const deferred: unknown[] = [];
+  for (const tool of tools) {
+    const definition = record(tool);
+    if (definition && typeof definition.name === "string" && deferredNames.has(definition.name)) {
+      deferred.push({ ...definition, defer_loading: true });
+    } else {
+      immediate.push(tool);
+    }
+  }
+
+  if (deferred.length > 0) {
+    const choice = record(body.tool_choice);
+    if (
+      body.tool_choice !== undefined &&
+      body.tool_choice !== "auto" &&
+      choice?.type !== "auto"
+    ) {
+      throw new Error(
+        "tool_choice conflicts with openrouter:tool_search; omit it or use auto",
+      );
+    }
+  }
+
+  return {
+    ...body,
+    ...(sessionId ? { session_id: sessionId } : {}),
+    ...(model.compat?.openRouterRouting
+      ? { provider: model.compat.openRouterRouting }
+      : {}),
+    ...(deferred.length > 0
+      ? {
+          tools: [
+            {
+              type: "openrouter:tool_search",
+              parameters: { max_results: 5 },
+            },
+            ...immediate,
+            ...deferred,
+          ],
+        }
+      : {}),
+  };
+}
+
+function openRouterOptions(
+  model: Model<"anthropic-messages">,
+  context: Context,
+  options: StreamOptions | undefined,
+): StreamOptions {
+  const apiKey = options?.apiKey;
+  const headers = Object.fromEntries(
+    Object.entries(options?.headers ?? {}).filter(([name]) =>
+      !["authorization", "x-api-key"].includes(name.toLowerCase())
+    ),
+  );
+  return {
+    ...options,
+    apiKey: undefined,
+    headers: {
+      ...headers,
+      ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+      "x-api-key": null,
+    },
+    onPayload: async (payload, activeModel) => {
+      const callerPayload = await options?.onPayload?.(payload, activeModel) ?? payload;
+      return decoratePayload(callerPayload, model, context, options?.sessionId);
+    },
+  };
+}
+
+export function openRouterMessagesApi(): ProviderStreams {
+  const anthropic = anthropicMessagesApi();
+  return {
+    stream: (model, context, options) =>
+      anthropic.stream(
+        model,
+        context,
+        openRouterOptions(
+          model as Model<"anthropic-messages">,
+          context,
+          options,
+        ),
+      ),
+    streamSimple: (model, context, options) =>
+      anthropic.streamSimple(
+        model,
+        context,
+        openRouterOptions(
+          model as Model<"anthropic-messages">,
+          context,
+          options,
+        ),
+      ),
+  };
+}

package/src/pi/runtime-adapter/test-fixtures/openrouter-tool-search.sse

@@ -0,0 +1,45 @@
+event: message_start
+data: {"type":"message_start","message":{"id":"msg_tool_search","type":"message","role":"assistant","model":"anthropic/claude-sonnet-5","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":0}}}
+
+event: content_block_start
+data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"I need the hidden status tool."}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"signed-thinking"}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":0}
+
+event: content_block_start
+data: {"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_search_1","name":"tool_search_tool_regex","input":{}}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"pattern\":\"status\"}"}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":1}
+
+event: content_block_start
+data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_search_tool_result","tool_use_id":"srvtoolu_search_1","content":{"type":"tool_search_tool_search_result","tool_references":[{"type":"tool_reference","tool_name":"deferred_status"}]}}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":2}
+
+event: content_block_start
+data: {"type":"content_block_start","index":3,"content_block":{"type":"tool_use","id":"toolu_status_1","name":"deferred_status","input":{}}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":3,"delta":{"type":"input_json_delta","partial_json":"{\"scope\":\"runtime\"}"}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":3}
+
+event: message_delta
+data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":24}}
+
+event: message_stop
+data: {"type":"message_stop"}
+

package/src/pi/tool/compiler.ts

@@ -46,6 +46,8 @@ export interface PiToolInteractionSpec {
 export interface PiToolCandidate {
   readonly owner: string;
   readonly tool: AgentTool<any, any>;
+  /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
+  readonly deferLoading?: true;
   /** Keep this Tool Direct-only instead of also offering it through Code Mode. */
   readonly direct?: true;
   /** Offer this Tool only through Code Mode, never as a top-level Tool. */
@@ -314,6 +316,7 @@ function governedTool(
 
   return {
     ...candidate.tool,
+    ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
     // 执行一次完整的受治理 Pi 工具调用。
     // Pi 工具循环选中编译后的工具时调用，调用方应传入稳定 toolCall id 供结算去重。
     // 输出限额必须发生在 settle 之前，否则 Durable Object 会持久化一份与模型最终所见不同的过大结果。

package/src/pi/tool/web-search/api.ts

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

package/src/runtime-assembler.ts

@@ -191,9 +191,17 @@ async function createToolSurface(
   const deny = new Set(input.policy?.denyPolicy?.deny ?? []);
   const allowsTool = input.policy?.allowsTool;
   const allowsExtension = input.policy?.allowsExtension;
+  const defersTool = input.policy?.defersTool;
   const visible = (candidate: PiToolCandidate) =>
     !deny.has(candidate.tool.name) &&
     allowsTool?.(candidate.tool.name) !== false;
+  const classify = (candidate: PiToolCandidate): PiToolCandidate =>
+    Object.freeze({
+      ...candidate,
+      ...(defersTool?.(candidate.tool.name) === true
+        ? { deferLoading: true as const }
+        : { deferLoading: undefined }),
+    });
   // 平台没有浏览器能力时注册空集：宁可没有这个 Tool，也不注册一个必然失败的 Tool 误导模型。
   // `create()` 推迟到确认这个名字真的可见之后，被 deny 的装配不白建一个浏览器连接器。
   // `direct` 使它只走 Direct 调用，不再被并进 `execute` 的工具集——两个 Code Mode 类工具互相嵌套
@@ -259,7 +267,7 @@ async function createToolSurface(
           deny.has("execute") ||
           allowsTool?.("execute") === false
         ) {
-          return Object.freeze(directVisible);
+          return Object.freeze(directVisible.map(classify));
         }
         const mergeable = finalized.filter(
           (candidate) =>
@@ -280,7 +288,7 @@ async function createToolSurface(
             "Use a loop or Promise.all when copying multiple resources.\n\n"
           : "";
         return Object.freeze([
-          Object.freeze({
+          classify({
             ...codeExecutionPiToolCandidate(
               {
                 ...codeExecution,
@@ -289,7 +297,7 @@ async function createToolSurface(
             ),
             codeExecutionTools,
           }),
-          ...directVisible,
+          ...directVisible.map(classify),
         ]);
       },
     }),
@@ -831,12 +839,18 @@ export async function assembleRuntimeSnapshot<
           ...(settings.toolPolicy?.allowsExtension
             ? { allowsExtension: settings.toolPolicy.allowsExtension }
             : {}),
+          ...(settings.toolPolicy?.defersTool
+            ? { defersTool: settings.toolPolicy.defersTool }
+            : {}),
           ...(toolAssembly.surfacePolicy?.allowsTool
             ? { allowsTool: toolAssembly.surfacePolicy.allowsTool }
             : {}),
           ...(toolAssembly.surfacePolicy?.allowsExtension
             ? { allowsExtension: toolAssembly.surfacePolicy.allowsExtension }
             : {}),
+          ...(toolAssembly.surfacePolicy?.defersTool
+            ? { defersTool: toolAssembly.surfacePolicy.defersTool }
+            : {}),
         }
       : undefined;
 

package/src/runtime-definition.ts

@@ -28,6 +28,7 @@ import type {
   RuntimeAgentPlanningContext,
 } from "./runtime-agent-context";
 import type { AgentTelemetryBinding } from "./telemetry/contract";
+import type { ToolSurfaceSelectionPolicy } from "./tool-registry";
 
 export interface RuntimeProfileContribution {
   readonly model: string;
@@ -48,10 +49,8 @@ export interface RuntimeExtensionContribution {
   readonly extension: RuntimeExtensionConfig;
 }
 
-export interface RuntimeToolSurfacePolicy {
+export interface RuntimeToolSurfacePolicy extends ToolSurfaceSelectionPolicy {
   readonly denyPolicy?: RuntimeDenyPolicy;
-  readonly allowsTool?: (name: string) => boolean;
-  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
 }
 
 export type { RuntimeAgentContext, RuntimeAssemblyContext } from "./runtime-agent-context";

package/src/runtime.ts

@@ -147,7 +147,7 @@ export const CHAT_RECOVERY_MAX_ATTEMPTS = 5;
 // 那种情况下 5 次 × 240s ≈ 20 分钟的空转纯属折磨用户。3 次约 12 分钟封顶。
 export const CHAT_STALL_MAX_ATTEMPTS = 3;
 const CHAT_RECOVERY_TERMINAL_MESSAGE =
-  "多次恢复仍未成功，本次生成已停止，当前进度已保留。请发送新消息继续。";
+  "Recovery failed after multiple attempts. This generation has stopped and your progress has been saved. Send a new message to continue.";
 
 type RuntimeEventOutboxPayload =
   | { readonly type: "model-usage"; readonly event: RuntimeModelUsageEvent }

package/src/tool-registry.ts

@@ -27,6 +27,7 @@ export type {
 export interface ToolSurfaceSelectionPolicy {
   readonly allowsTool?: (name: string) => boolean;
   readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
+  readonly defersTool?: (name: string) => boolean;
 }
 
 export function emptyToolRegistry(): ToolRegistry {