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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.29",
+  "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 " +
@@ -67,28 +69,29 @@ export const TOOLS =
   "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.";
 
-// The browser tool is the only way to observe what a page actually does; its
-// failure mode is returning nothing and looking clean, so the shape is fixed here.
+// A real browser is the only way to observe what a page actually does, and the
+// shared failure mode is a browser tool that returns nothing and looks clean.
+//
+// This section names no browser tool and no protocol. A Host may expose the
+// kernel's own `browser_execute`, its own narrower browser tools, or none at
+// all — a section that spelled out one tool's mechanics would be teaching a
+// tool that is not there for every Host but the first. How to drive a specific
+// browser tool belongs to that tool's own description, which the model sees if
+// and only if the tool is registered.
 export const BROWSER =
-  "Browser: When browser_execute is present, it is for one thing execute cannot do — what a page actually " +
-  "does in a real browser: rendered result, console output, runtime exceptions, failed resource loads, CSP " +
-  "blocks, and state after an interaction. Everything else stays with execute: computation, files, and " +
-  "ordinary HTTP requests (fetching HTML is execute's job, not the browser's). " +
-  "After you write or change a web page in the workspace, open it once with browser_execute before you call " +
-  "the work done, and say in your reply what you checked and what you saw. " +
-  "The cdp connector is request/response only: it delivers no CDP events. Enabling Runtime/Log/Network and " +
-  "then reading cdp.getDebugLog() returns method names with no payload — a page full of errors reads as clean. " +
-  "So the fixed shape is: create a target and attach for a sessionId; BEFORE Page.navigate, install a page-side " +
-  "collector via Page.addScriptToEvaluateOnNewDocument that buffers console.*, a capture-phase window 'error' " +
-  "listener (it catches both uncaught exceptions and failed <script>/<img>/<link> loads), 'unhandledrejection' " +
-  "and 'securitypolicyviolation' into one page global; then navigate, poll Runtime.evaluate for " +
-  "document.readyState === 'complete' (you cannot await an event), then Runtime.evaluate that global back with " +
-  "returnByValue. When visual appearance matters, call Page.captureScreenshot and return " +
-  "`{ image: { mimeType: 'image/png', data: screenshot.data }, observations }`; the Runtime projects that image " +
-  "back to you, so evaluate the visible hierarchy, spacing, clipping and overlap against the request as well as " +
-  "the textual diagnostics. Issue CDP calls sequentially — never Promise.all — because call order is recorded for replay. " +
+  "Browser: a real browser is for the one thing execute cannot do — observe what a page actually does: " +
+  "rendered result, console output, runtime exceptions, failed resource loads, CSP blocks, and state after an " +
+  "interaction. Everything else stays with execute: computation, files, and ordinary HTTP requests (fetching " +
+  "HTML is execute's job, not the browser's). " +
+  "After you write or change a web page in the workspace, open it once with the browser tools you have before " +
+  "you call the work done, and say in your reply what you checked and what you saw. " +
+  "Drive each browser tool the way its own description tells you to; the failure mode they share is coming back " +
+  "empty and looking clean, so read every result for what it does not contain and never report a page as " +
+  "verified on the strength of a result that observed nothing. When visual appearance matters, capture the page " +
+  "and judge the visible hierarchy, spacing, clipping and overlap against the request alongside the textual " +
+  "diagnostics. " +
   "Fix what you find and re-check; when the page comes back clean, stop — do not re-verify a page that is " +
-  "already clean. If browser_execute is absent, say plainly that you could not verify the page in a browser " +
+  "already clean. If you have no browser tool, say plainly that you could not verify the page in a browser " +
   "instead of implying you did.";
 
 // Uploaded-file routing prevents lossy markdown conversions from becoming data sources.
@@ -103,7 +106,7 @@ export const FILES =
 
 // User-interaction actions are called only when their UI semantics are useful.
 export const INTERACTION =
-  "Interaction: When progress requires user decisions, put all 1-4 necessary questions in one ask_user call " +
+  "Interaction: When progress requires user decisions, put all 1-10 necessary questions in one ask_user call " +
   "instead of asking each question separately or writing 'please choose A/B/C' as text. Use 2-6 options for " +
   "a bounded choice; for required free text, omit the options field entirely — never pass an empty or single-item options array; " +
   "continue the same turn when its result arrives. " +

package/src/pi/message/projection.ts

@@ -148,6 +148,7 @@ interface StreamingToolInput extends PendingToolInput {
 export class PiChunkEncoder {
   private readonly messageId: string;
   private readonly startedAt?: number;
+  private readonly turnId?: string;
   private started = false;
   private finished = false;
   private firstTurnStarted = false;
@@ -162,9 +163,14 @@ export class PiChunkEncoder {
     { toolName: string; input: Record<string, unknown> }
   >();
 
-  constructor(options: { messageId: string; startedAt?: number }) {
+  constructor(options: {
+    messageId: string;
+    startedAt?: number;
+    turnId?: string;
+  }) {
     this.messageId = options.messageId;
     this.startedAt = options.startedAt;
+    this.turnId = options.turnId;
   }
 
   start(): UIMessageChunk[] {
@@ -181,6 +187,7 @@ export class PiChunkEncoder {
               messageMetadata: {
                 createdAt: this.startedAt,
                 turnStatus: "running",
+                ...(this.turnId ? { turnId: this.turnId } : {}),
               },
             }),
       },
@@ -452,6 +459,7 @@ export class PiChunkEncoder {
           completedAt: message.timestamp,
           turnDurationMs: Math.max(0, message.timestamp - this.startedAt),
           turnStatus,
+          ...(this.turnId ? { turnId: this.turnId } : {}),
           ...(publicError &&
               (message.stopReason !== "aborted" ||
                 message.errorMessage !== USER_STOP_REASON)

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

@@ -663,6 +663,7 @@ export class PreparedPiTurnAdapter {
     this.encoder = new PiChunkEncoder({
       messageId: options.submission.messageId,
       startedAt: options.submission.startedAt,
+      turnId: options.submission.id,
     });
     const bindCandidate = (
       candidate: PiToolCandidate,

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/runtime-adapter/transcript.ts

@@ -649,6 +649,7 @@ export class PiRuntimeTranscript {
         role: "assistant",
         parts: [],
         metadata: {
+          turnId: submissionId,
           createdAt: submission.createdAt,
           completedAt,
           turnDurationMs: Math.max(
@@ -706,6 +707,7 @@ export class PiRuntimeTranscript {
         const createdAt = submission?.createdAt ?? entry.createdAt;
         const completedAt = submission?.completedAt ?? entry.createdAt;
         const metadata = {
+          turnId: entry.submissionId,
           createdAt,
           completedAt,
           turnDurationMs: Math.max(
@@ -753,6 +755,7 @@ export class PiRuntimeTranscript {
             ? entry.id
             : submission?.assistantMessageId ?? entry.id,
           metadata: {
+            turnId: entry.submissionId,
             createdAt: submission?.createdAt ?? entry.createdAt,
             completedAt,
             ...(completedAt === undefined

package/src/pi/tool/base.ts

@@ -40,7 +40,7 @@ const askUserQuestion = Type.Object({
 const askUserParameters = Type.Object({
   questions: Type.Array(askUserQuestion, {
     minItems: 1,
-    maxItems: 4,
+    maxItems: 10,
     description:
       "All user decisions needed to continue. Ask them together in one call.",
   }),
@@ -70,7 +70,7 @@ function recordOf(value: unknown): Record<string, unknown> | null {
 
 function questionsOf(value: unknown): AskUserInput["questions"] | null {
   const questions = recordOf(value)?.questions;
-  if (!Array.isArray(questions) || questions.length < 1 || questions.length > 4) {
+  if (!Array.isArray(questions) || questions.length < 1 || questions.length > 10) {
     return null;
   }
   for (const value of questions) {
@@ -238,7 +238,7 @@ export function basePiToolCandidates(
         name: "ask_user",
         label: "Ask user",
         description:
-          "Ask all 1-4 user questions needed to continue in one call. For a bounded choice, provide 2-6 distinct options. For required free text, omit the options field entirely; never pass an empty, single-item, or more-than-6-item options array. Do not make one call per question or write plain text like 'please pick A / B / C'. The answers return as this tool's result, so continue the same turn after calling it.",
+          "Ask all 1-10 user questions needed to continue in one call. For a bounded choice, provide 2-6 distinct options. For required free text, omit the options field entirely; never pass an empty, single-item, or more-than-6-item options array. Do not make one call per question or write plain text like 'please pick A / B / C'. The answers return as this tool's result, so continue the same turn after calling it.",
         parameters: askUserParameters,
         // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
         // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。

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

@@ -73,9 +73,7 @@ function toCodeExecutionPort(
   };
 }
 
-// 只有这一条挂在 Tool description 上：preview URL 是 per-Session 的，
-// 放进静态 system prompt 前缀会让它每轮都变，破坏 prompt cache。
-// 怎么用 CDP 才不会静默读空，是与 Session 无关的固定动作，住在静态提示词里。
+// preview URL 是 per-Session 的：放进静态 system prompt 前缀会让它每轮都变，破坏 prompt cache。
 function previewNote(base: string): string {
   return "Open the current Workspace app with this exact preview URL, unchanged: " +
     `${base} Keep its path and query string intact; do not append a workspace file path. ` +
@@ -83,6 +81,9 @@ function previewNote(base: string): string {
     "file:// cannot reach the workspace, and there is no other preview host — do not guess one.";
 }
 
+// 怎么用 CDP 才不会静默读空，住在这里而不是静态提示词里：它只对 `browser_execute` 成立。
+// 一个 Host 可以 deny 它、换成自己的浏览器工具，那时静态提示词里的这套配方就是在教一个
+// 不存在的工具；工具描述只在工具真被注册时才出现，所以这份知识跟着工具走。
 function browserToolDescription(): string {
   return "Run JavaScript against a live browser over the Chrome DevTools Protocol through the `cdp` connector. " +
     "Use the bare lexical identifiers `cdp` and `codemode`. They are not properties of `globalThis` and are not importable modules. " +
@@ -92,7 +93,20 @@ function browserToolDescription(): string {
     "Create targets, attach, navigate, interact, inspect diagnostics, and capture screenshots within the same call. " +
     "Use `cdp.spec()` to discover commands, `cdp.send({ method, params })` for target-scoped commands, " +
     "and `cdp.attachToTarget({ targetId })` before page-scoped commands. " +
-    "Issue browser calls sequentially so the inspection can be replayed reliably.";
+    "Issue browser calls sequentially — never Promise.all — because call order is recorded for replay. " +
+    "The `cdp` connector is request/response only: it delivers no CDP events. Enabling Runtime/Log/Network and " +
+    "then reading `cdp.getDebugLog()` returns method names with no payload — a page full of errors reads as clean. " +
+    "So the fixed shape for collecting diagnostics is: create a target and attach for a sessionId; BEFORE " +
+    "Page.navigate, install a page-side collector via Page.addScriptToEvaluateOnNewDocument that buffers " +
+    "console.*, a capture-phase window 'error' listener (it catches both uncaught exceptions and failed " +
+    "<script>/<img>/<link> loads), 'unhandledrejection' and 'securitypolicyviolation' into one page global; then " +
+    "navigate, poll Runtime.evaluate for document.readyState === 'complete' (you cannot await an event), then " +
+    "Runtime.evaluate that global back with returnByValue. " +
+    "When visual appearance matters, call Page.captureScreenshot and return " +
+    "`{ image: { mimeType: 'image/png', data: screenshot.data }, observations }`; this tool projects that image " +
+    "back to you. Every call's result is recorded whole for replay, and one full-page PNG can exceed that " +
+    "record's size limit and fail the entire call — capture the viewport rather than the full page, and return " +
+    "one screenshot per call, not several.";
 }
 
 /**

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-agent-context.ts

@@ -60,6 +60,8 @@ export interface RuntimeAgentConfigContext<
   readonly parentPath: readonly RuntimeAgentPathStep[];
   /** Runtime 根据 Agent facet 父子关系自动判定，不是外部配置项。 */
   readonly role: RuntimeAgentRole;
+  /** 向当前 Agent facet 的已连接客户端发送实时消息。 */
+  broadcast(message: string): void;
   /**
    * 通过当前 Agent 调用一个受 SDK 管理的子 Agent Tool。
    *

package/src/runtime-agent.ts

@@ -87,6 +87,8 @@ 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. */
+  readonly rollback?: () => Promise<void>;
 }
 
 interface RuntimeAgentDefinitionBase<
@@ -482,7 +484,17 @@ export function defineRuntimeAgent<
         try {
           await this.ensureConfig(undefined, true);
           return { change: result.change, runtime: "reloaded" };
-        } catch {
+        } catch (reloadError) {
+          if (result.rollback) {
+            try {
+              await result.rollback();
+            } catch (rollbackError) {
+              throw new AggregateError(
+                [reloadError, rollbackError],
+                "Runtime Config rollback failed",
+              );
+            }
+          }
           return { change: result.change, runtime: "reload-failed" };
         }
       }
@@ -824,6 +836,7 @@ export function defineRuntimeAgent<
           get role() {
             return agent.role;
           },
+          broadcast: (message) => agent.broadcast(message),
           ...(agent.role === "primary"
             ? {
                 updateConfig: (command: Command) =>

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/skills/springbrand-worker-website/index.ts

@@ -68,6 +68,6 @@ export const SPRINGBRAND_WORKER_WEBSITE_SKILL = {
     "2. Create or update the complete project rather than only an entry HTML file.",
     "3. Build when the project requires a build step.",
     "4. Preview the Website through the available Workspace or Space capability.",
-    "5. When `browser_execute` is available, check runtime errors, failed resources, CSP violations, responsive layout, clipping, overlap, and visual hierarchy. Capture a screenshot when visual appearance matters, fix discovered problems, and verify once more.",
+    "5. Open the previewed Website with the browser tools you have and check runtime errors, failed resources, CSP violations, responsive layout, clipping, overlap, and visual hierarchy. Capture a screenshot when visual appearance matters, fix discovered problems, and verify once more.",
   ].join("\n"),
 };

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 {