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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.30",
+  "version": "0.2.0-alpha.32",
   "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

@@ -18,8 +18,7 @@ export const PERSONA =
 export const RUNTIME =
   "Runtime: this agent runs on Cloudflare Workers. When execute is present, its Code Mode Dynamic Worker is your " +
   "instrument — code there runs with outbound network access (fetch), your " +
-  "workspace filesystem (state.*), and your other tools (tools.* when that connector is available). Put repeated or multi-step work " +
-  "in one execute instead of making consecutive top-level Tool calls. Use it for raw or customized HTTP " +
+  "workspace filesystem (state.*), and the tools.* methods listed in its own description. Use it for raw or customized HTTP " +
   "requests, parsing a payload, hitting several known endpoints, or computing over a file. Write plain " +
   "JavaScript — the sandbox evaluates " +
   "it directly, so TypeScript type annotations (`: number`, `as Type`) are a syntax error, and there " +
@@ -33,7 +32,9 @@ export const BEHAVIOR =
   "When uncertain, investigate before answering rather than guess or confirm a belief. Match response " +
   "length to the task — a short question gets a short answer; skip filler preamble and don't restate " +
   "what you just did. Be proactive when asked to *do* something (take the needed follow-up actions too), " +
-  "but when the user only asks *how* to approach something, answer first and don't jump into changes.";
+  "but when the user only asks *how* to approach something, answer first and don't jump into changes. " +
+  "A failed Tool call produced no requested result. Never infer completion or fabricate URLs, files, identifiers, or business results " +
+  "from a failed call's arguments or identifiers; correct the Tool route or report the failure.";
 
 // The main Agent alone owns user-visible planning.
 export const PLANNING =
@@ -43,13 +44,18 @@ export const PLANNING =
   "one step in_progress at a time and don't batch completions. Do not make a plan for a single trivial " +
   "step or a purely conversational reply — just do it.";
 
+const TOOL_ROUTING =
+  "Tools: execute can call only the tools.* methods explicitly listed in its description; that list is exhaustive. Never guess a tools.* method. " +
+  "If a required top-level Tool is not visible, do not use execute. Call top-level Tool Search with that exact name, then call the discovered Tool directly. " +
+  "codemode.search searches only methods already installed inside execute; it cannot discover deferred top-level Tools.";
+
 // Tool-selection guidance mirrors the actual approval and network boundaries.
 export const TOOLS =
-  "Tools: When execute is present, call a top-level Tool directly only for a single standalone Tool call or when that Tool is unavailable " +
-  "inside execute. Any operation that needs the same Tool more than once, two or more related file, Skill, Extension, MCP, or Host Tool calls, " +
-  "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. " +
+  TOOL_ROUTING +
+  " Relatedness, repetition, or multiple calls never overrides this availability rule. " +
+  "When every required Tool is available inside execute, use one execute for repeated or related calls, branching, or repetition. Inside execute, " +
+  "use state.* for workspace file operations, tools.* for other host capabilities, a loop for repeated calls, and Promise.all for independent calls. " +
+  "Top-level-only Tools remain Direct even when called repeatedly. " +
   "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 " +
@@ -63,7 +69,7 @@ export const TOOLS =
   "When execute is present, make related file changes in one execute with state.*; when execute is absent, use one write or bash operation instead of serial edits. " +
   "Do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
   "prioritize verification, saving durable results, and the final response. " +
-  "When related Tool calls can run independently and execute is present, run them inside that execute rather than as parallel top-level calls; " +
+  "When related Tool calls can run independently, all are available inside execute, and execute is present, run them inside that execute rather than as parallel top-level calls; " +
   "only independent top-level-only Direct Tools should be issued together in one turn. When you reference " +
   "code, cite it as file_path:line_number.";
 
@@ -164,5 +170,5 @@ export function assembleSystemPrompt(base?: string | null): string {
  * Agent、Runtime 和 Memory 的术语见 `src/index.ts`。
  */
 export function assembleSubagentPrompt(persona: string): string {
-  return [persona, RUNTIME, BEHAVIOR].join("\n\n");
+  return [persona, RUNTIME, BEHAVIOR, TOOL_ROUTING].join("\n\n");
 }

package/src/pi/message/contract.ts

@@ -4,7 +4,7 @@ export type UIChatTrigger = "submit-message" | "regenerate-message";
 
 /** A user-selected Runtime capability persisted with the visible UIMessage. */
 export interface RequestedCapability {
-  readonly kind: "skill" | "plan";
+  readonly kind: "skill" | "tool" | "plan";
   readonly name: string;
   readonly label: string;
 }

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/index.ts

@@ -18,6 +18,7 @@ export {
 import {
   pinPiRuntime,
   preparePiRuntime,
+  readPreparedPiRuntime,
   type PinPiRuntimeOptions,
   type PinnedPiRuntime,
   type PreparePiRuntimeOptions,
@@ -143,6 +144,12 @@ export class PiRuntimeAdapter {
     return preparePiRuntime(options, this.owner);
   }
 
+  hasTool(prepared: PreparedPiRuntime, name: string): boolean {
+    return readPreparedPiRuntime(prepared, this.owner).candidates.some(
+      (candidate) => candidate.tool.name === name,
+    );
+  }
+
   /**
    * 用已经通过加载检查的快照启用当前部署声明的模型目录。
    *

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/core-host.ts

@@ -18,6 +18,10 @@ import type {
 // 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
 
 const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
+const CODEMODE_TOOL_SURFACE_GUIDANCE =
+  "The `tools.*` Available list below is exhaustive, not examples. Inside execute, call only methods in that list; " +
+  "never guess or construct a `tools.*` method name. If a required Tool is absent, leave execute and call it at the top level, " +
+  "using top-level Tool Search first when it is deferred. `codemode.search` cannot add methods to `tools.*`.";
 
 /**
  * 宿主的 Browser Rendering 绑定，只取本仓真正用到的那一面。
@@ -183,10 +187,10 @@ export function createWorkspaceCodeExecutionFactory(options: {
       const port = toCodeExecutionPort(tool, "execute");
       return {
         ...port,
-        description: port.description.replace(
+        description: `${CODEMODE_TOOL_SURFACE_GUIDANCE}\n\n${port.description.replace(
           "- Do not use `fetch` — use connector SDKs.",
           "- Raw `fetch` is available inside `codemode.step(...)`; prefer connector SDKs when one owns the target.",
-        ),
+        )}`,
       };
     },
   };

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 }
@@ -360,7 +360,7 @@ function requestedCapabilitiesOf(metadata: unknown): RequestedCapability[] {
     }
     const capability = value as Record<string, unknown>;
     if (
-      (capability.kind !== "skill" && capability.kind !== "plan") ||
+      (capability.kind !== "skill" && capability.kind !== "tool" && capability.kind !== "plan") ||
       typeof capability.name !== "string" ||
       !capability.name.trim() ||
       typeof capability.label !== "string" ||
@@ -1352,6 +1352,16 @@ export abstract class AgentRuntimeKernel<
         );
         continue;
       }
+      if (capability.kind === "tool") {
+        if (!this.pi.hasTool(this.preparedPi(), capability.name)) {
+          throw new Error(`Requested Tool is not installed: ${capability.name}`);
+        }
+        context.push(
+          `requested capability: tool/${capability.name}`,
+          `required action: call tool "${capability.name}" when handling the task`,
+        );
+        continue;
+      }
       if (capability.name !== "plan") {
         throw new Error(`Unknown plan capability: ${capability.name}`);
       }

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 {