@springbrand/agent-runtime 0.2.0-alpha.18 → 0.2.0-alpha.20

package/src/lib/prompt.ts

@@ -1,10 +1,9 @@
 /**
  * Stable system-prompt sections shared by every Runtime profile.
  *
- * Only `PERSONA` is replaceable by `RuntimeProfile.systemPrompt`. The global
- * `SYSTEM_PROMPT`, environment, tool and safety facts remain because a custom
- * Agent persona must not redefine capabilities that the running kernel does
- * not actually provide.
+ * Only `PERSONA` is replaceable by `RuntimeProfile.systemPrompt`. Environment,
+ * tool and safety facts remain because a custom Agent persona must not redefine
+ * capabilities that the running kernel does not actually provide.
  * Dynamic skills, memory and context blocks are injected by their own modules
  * so this static prefix remains cacheable.
  */
@@ -15,13 +14,6 @@ export const PERSONA =
   "You can recall user-managed cold memory across sessions and keep working memory within the current Session, " +
   "manage files in your workspace, and use execute Code Mode for network requests and tool composition.";
 
-// Base constraint injected alongside every Agent-specific persona.
-export const SYSTEM_PROMPT =
-  "Web development: when writing a website or web page, use browser-ready mode: emit browser-ready static files " +
-  "that run directly in Workspace preview. Use ./ or ../ for every Workspace asset, never a root-relative path; " +
-  "load CSS from HTML instead of importing it from JavaScript. Resolve third-party ESM with a full pinned HTTPS URL " +
-  "or import map to a pinned CORS-enabled CDN. Do not require Vite, Node.js, bundling, or Sandbox at preview time.";
-
 // Explains how to reach capabilities instead of listing unsupported substitutes.
 export const RUNTIME =
   "Runtime: this agent runs on Cloudflare Workers. When execute is present, its Code Mode Dynamic Worker is your " +
@@ -56,7 +48,8 @@ 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 non-CDP calls. " +
+  "workspace file operations, tools.* for other host capabilities, a loop for repeated calls, and Promise.all for independent calls. " +
+  "For materialize_skill_resource, materialize every known set of Skill resources in one execute; never start one execute per resource. " +
   "Tools available only at the top level must stay Direct. " +
   "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 " +
@@ -75,6 +68,30 @@ 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.
+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. " +
+  "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 " +
+  "instead of implying you did.";
+
 // Uploaded-file routing prevents lossy markdown conversions from becoming data sources.
 export const FILES =
   "Uploaded files live under /uploads/ in your workspace; convertible formats have a companion " +
@@ -112,7 +129,7 @@ export const MEMORY =
  * @remarks
  * Pi 快照装配在生成每次 Runtime Snapshot 时调用；调用方只替换角色文本，不要重复拼接其他段落。
  *
- * 全局 SYSTEM_PROMPT 固定前置；Runtime、行为、规划、Tool、文件、交互和 Memory 按固定顺序追加，
+ * Runtime、行为、规划、Tool、浏览器、文件、交互和 Memory 按固定顺序追加，
  * 因为自定义角色不应重新定义实际 Kernel 没有的能力。
  *
  * 各段保持静态，动态 Skill、Context 和 Memory 由各自模块注入，避免这个可缓存前缀每回合改变。
@@ -121,12 +138,12 @@ export const MEMORY =
  */
 export function assembleSystemPrompt(base?: string | null): string {
   return [
-    SYSTEM_PROMPT,
     base ?? PERSONA,
     RUNTIME,
     BEHAVIOR,
     PLANNING,
     TOOLS,
+    BROWSER,
     FILES,
     INTERACTION,
     MEMORY,
@@ -139,7 +156,7 @@ export function assembleSystemPrompt(base?: string | null): string {
  * @remarks
  * Pi SubAgent 在启动有界子任务前调用；调用方应传入该子代理类型自己的 persona。
  *
- * 子代理共享真实执行环境和基本行为，但不获得主 Agent 专属的规划、Memory 和用户交互指令，因为这些责任留在主循环。
+ * 子代理共享真实执行环境和基本行为，但不获得主 Agent 专属的 Skill、规划、Memory 和用户交互指令，因为这些责任留在主循环。
  *
  * 不要直接改成复用 `assembleSystemPrompt`，否则子代理会收到它没有的 Session 记忆和对话交互责任。
  *

package/src/pi/message/projection.ts

@@ -15,6 +15,8 @@ import { USER_STOP_REASON } from "../../kernel/receipts";
 
 const MAX_OUTPUT_BYTES = 256 * 1024;
 const MAX_OUTPUT_PREVIEW = 16 * 1024;
+const PROVIDER_CREDIT_ERROR =
+  "The AI service is temporarily unavailable. Please try again later.";
 
 export interface PiToolApprovalView {
   readonly id: string;
@@ -101,6 +103,16 @@ function errorText(result: unknown): string {
   }
 }
 
+/** Keep provider account details out of browser-facing error messages. */
+export function publicAssistantError(message?: string): string | undefined {
+  if (!message) return undefined;
+  return /"limit_source"\s*:\s*"openrouter_credits"/.test(message) ||
+      (message.includes("Insufficient credits") &&
+        message.includes("openrouter.ai/settings/credits"))
+    ? PROVIDER_CREDIT_ERROR
+    : message;
+}
+
 function toolCallAt(
   update: AssistantMessageEvent,
 ): Partial<ToolCall> | undefined {
@@ -318,7 +330,12 @@ export class PiChunkEncoder {
       case "toolcall_end":
         return this.encodeToolInput(update);
       case "error":
-        return [{ type: "error", errorText: update.error.errorMessage ?? update.reason }];
+        return [{
+          type: "error",
+          errorText: publicAssistantError(
+            update.error.errorMessage ?? update.reason,
+          ) ?? "SpringBrand turn failed",
+        }];
       default:
         return [];
     }
@@ -421,6 +438,7 @@ export class PiChunkEncoder {
       return chunks;
     }
     this.finished = true;
+    const publicError = publicAssistantError(message.errorMessage);
     if (this.startedAt !== undefined) {
       const turnStatus = message.stopReason === "aborted"
         ? "aborted"
@@ -434,10 +452,10 @@ export class PiChunkEncoder {
           completedAt: message.timestamp,
           turnDurationMs: Math.max(0, message.timestamp - this.startedAt),
           turnStatus,
-          ...(message.errorMessage &&
+          ...(publicError &&
               (message.stopReason !== "aborted" ||
                 message.errorMessage !== USER_STOP_REASON)
-            ? { error: message.errorMessage }
+            ? { error: publicError }
             : {}),
         },
       });
@@ -449,7 +467,7 @@ export class PiChunkEncoder {
     if (message.stopReason === "error") {
       chunks.push({
         type: "error",
-        errorText: message.errorMessage ?? "SpringBrand turn failed",
+        errorText: publicError ?? "SpringBrand turn failed",
       });
       return chunks;
     }

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

@@ -53,8 +53,31 @@ import { toolRegistryFromPiCandidates } from "../../tool-registry";
 
 // #region Single-run Pi bridge
 
+// 一片执行最多跑多少个模型回合。这是 CPU 预算边界，不是任务边界：DO 的
+// CPU 上限按 invocation 计，一条长回合跑在一次 invocation 里会把预算吃满并被驱逐，
+// 让步换来的是一次全新 invocation 和全新预算。
 const MAX_MODEL_TURNS_PER_SLICE = 30;
 
+// 一条 Submission 跨所有执行片最多跑多少个模型回合。这是任务边界:
+// 没有它,一个不收敛的工具循环会无限让步、无限唤醒、无限烧 token。
+export const MAX_MODEL_TURNS_PER_SUBMISSION = 300;
+
+// 预算耗尽时注入的收尾指令。跟着它一起把工具表清空,模型只能出文本,
+// 于是这一轮以一条正常的终止助手消息结束 —— 而不是硬判失败或继续让步。
+// 走 user 角色而非 assistant:多个 provider 拒绝以模型回合结尾的请求。
+const WRAP_UP_MESSAGE = "You have reached this run's model-turn budget. Stop " +
+  "calling tools now. Reply with a final message that states what you " +
+  "completed, what you did not finish, and the exact next step you would " +
+  "take. Do not start new work.";
+
+const TOOL_FAILURE_WRAP_UP_MESSAGE = "This turn reached its tool failure limit. " +
+  "Stop calling tools now. Reply with a final message that explains what " +
+  "failed and the exact next step the user should take. Do not start new work.";
+
+// 收尾开始后最多再放行几个模型回合。工具已经清空，正常一轮就结束了；
+// 留出余量是给 steering 消息，但不能因此把本片的 CPU 上限一起取消。
+const MAX_WRAP_UP_TURNS = 2;
+
 export class RetryableModelError extends Error {}
 
 function normalizePlanToolCalls(message: AgentMessage): void {
@@ -136,14 +159,41 @@ interface PiTurnAdapterOptions {
   // 直接复用 Pi 的回调类型可避免这里维护另一套上下文转换约定。
   readonly transformContext: NonNullable<AgentOptions["transformContext"]>;
   readonly workspace?: SpillWorkspace;
+  // 之前的执行片已经用掉的模型回合数。首次执行传 0。
+  readonly modelTurnsConsumed: number;
+}
+
+/**
+ * 收集那些结果已经由工具自己收口的 Tool 名字。
+ *
+ * @remarks
+ * `run` 在建 PiCore 前调用，把结果交给 `projectToolResultsForModel`。
+ *
+ * `outputBudget: "structure"` 的语义就是“这个结果不需要 Runtime 再替它省”：read
+ * 按页返回并在页脚写明覆盖的行号，activate_skill 返回的是模型接下来要照做的指令，
+ * Code Mode 的结果由它自己收口。对这些再套一次叶子上限，模型看到的正文会和结果里
+ * 写明的范围对不上 —— 页脚说 `lines 1-307`，正文却被从中间挖空。
+ *
+ * 其余工具仍然照常压缩：这道闸按分类放行，不是整体放宽。
+ */
+function selfBoundedToolNames(
+  candidates: readonly PiToolCandidate[],
+): ReadonlySet<string> {
+  return new Set(
+    candidates
+      .filter((candidate) => candidate.outputBudget?.kind === "structure")
+      .map((candidate) => candidate.tool.name),
+  );
 }
 
 function projectToolResultsForModel(
   messages: readonly AgentMessage[],
+  selfBounded: ReadonlySet<string>,
 ): AgentMessage[] {
   let changed = false;
   const projected = messages.map((message) => {
     if (message.role !== "toolResult") return message;
+    if (selfBounded.has(message.toolName)) return message;
     const payload = {
       content: message.content,
       details: message.details,
@@ -231,8 +281,14 @@ class PiTurnAdapter {
     signal?.throwIfAborted();
     const canonicalMessages = await this.opts.canonicalMessages();
     const tools = this.compile(opts.tools);
-    let modelTurns = 0;
+    const selfBounded = selfBoundedToolNames(opts.tools);
+    // `modelTurns` 是跨执行片的累计数，`sliceTurns` 只数本片 —— 前者管任务预算，
+    // 后者管 CPU 预算，两个边界互不替代。
+    let modelTurns = this.opts.modelTurnsConsumed;
+    let sliceTurns = 0;
     let reachedModelTurnLimit = false;
+    let wrappingUp = false;
+    let wrapUpTurns = 0;
     const pi = new PiCore({
       convertToLlm,
       streamFn: withProviderRetry(
@@ -248,14 +304,59 @@ class PiTurnAdapter {
       transformContext: async (messages, signal) => {
         const ctx = await this.opts.transformContext(messages, signal);
         return transformMessages(
-          projectToolResultsForModel(ctx) as Message[],
+          projectToolResultsForModel(ctx, selfBounded) as Message[],
           this.opts.pi.model,
         ) as AgentMessage[];
       },
       afterToolCall: this.governance.afterToolCall,
+      // Pi 在每个 turn_end 之后先调 prepareNextTurn、再调 shouldStopAfterTurn，
+      // 所以回合计数记在这里，停止判据只读不写。
+      // 用 `WithContext` 变体：只有它拿得到当前上下文，也就拿得到工具表和消息。
+      prepareNextTurnWithContext: ({ context }) => {
+        modelTurns += 1;
+        sliceTurns += 1;
+        if (wrappingUp) {
+          wrapUpTurns += 1;
+          return undefined;
+        }
+        const toolFailureLimitReached = this.governance.wrapUpRequested();
+        if (
+          !toolFailureLimitReached &&
+          modelTurns < MAX_MODEL_TURNS_PER_SUBMISSION - 1
+        ) return undefined;
+        // 预算见底或工具熔断：清空工具表并注入收尾指令，逼出一条真正的
+        // 终止助手消息。直接判失败的话用户拿不到任何交代。
+        // 这条指令不进 newMessages，因此不会写进 transcript —— 它是控制指令，不是历史。
+        wrappingUp = true;
+        return {
+          context: {
+            ...context,
+            tools: [],
+            messages: [
+              ...context.messages,
+              {
+                role: "user" as const,
+                content: [{
+                  type: "text" as const,
+                  text: toolFailureLimitReached
+                    ? TOOL_FAILURE_WRAP_UP_MESSAGE
+                    : WRAP_UP_MESSAGE,
+                }],
+                timestamp: Date.now(),
+              },
+            ],
+          },
+        };
+      },
       shouldStopAfterTurn: () => {
-        reachedModelTurnLimit = ++modelTurns >= MAX_MODEL_TURNS_PER_SLICE;
-        return signal?.aborted === true || reachedModelTurnLimit;
+        if (signal?.aborted === true) return true;
+        // 收尾那一轮必须跑完，否则让步会把唯一的终态机会顶掉。但「必须跑完」
+        // 不等于「不再有上限」：Pi 在这之后还会取 steering 和 follow-up 消息，
+        // 一直有新消息进来就会一直发模型请求，而且全在同一个 invocation 里 ——
+        // 那正是 MAX_MODEL_TURNS_PER_SLICE 要挡的 CPU 驱逐。
+        if (wrappingUp) return wrapUpTurns >= MAX_WRAP_UP_TURNS;
+        reachedModelTurnLimit = sliceTurns >= MAX_MODEL_TURNS_PER_SLICE;
+        return reachedModelTurnLimit;
       },
       initialState: {
         model: this.opts.pi.model,
@@ -286,8 +387,8 @@ class PiTurnAdapter {
       }
       await running;
       return reachedModelTurnLimit
-        ? { kind: "yielded" }
-        : { kind: "terminal" };
+        ? { kind: "yielded", modelTurns }
+        : { kind: "terminal", modelTurns };
     } finally {
       signal?.removeEventListener("abort", abort);
       unsubscribe();
@@ -393,6 +494,8 @@ export interface CreatePreparedPiTurnOptions {
     readonly startedAt: number;
     readonly continuation: boolean;
     readonly assistantOrdinal: number;
+    /** 之前的执行片已用掉的模型回合数；省略按 0 处理。 */
+    readonly modelTurnsConsumed?: number;
   };
   /**
    * 在 Pi 启动前读取最新 canonical transcript。
@@ -474,8 +577,10 @@ export interface PiPreparedTurnRunOptions {
 }
 
 export type PiTurnRunResult =
-  | { readonly kind: "terminal" }
-  | { readonly kind: "yielded" };
+  /** Turn 已产生权威结果，或已经收尾。 */
+  | { readonly kind: "terminal"; readonly modelTurns: number }
+  /** 本片让出执行，Turn 未结束；调用方必须排出续跑。 */
+  | { readonly kind: "yielded"; readonly modelTurns: number };
 
 // #endregion
 
@@ -724,6 +829,7 @@ export class PreparedPiTurnAdapter {
         this.interrupted ? undefined : options.durability.settleTool(call),
       transformContext: options.transformContext,
       workspace: state.snapshot.bindings.workspace,
+      modelTurnsConsumed: options.submission.modelTurnsConsumed ?? 0,
     });
     this.systemPrompt = descriptor.systemPrompt;
     this.options = options;
@@ -835,7 +941,7 @@ export class PreparedPiTurnAdapter {
     );
     if (this.terminalIntent) {
       await this.options.onTerminal(this.terminalIntent);
-      return { kind: "terminal" };
+      return { kind: "terminal", modelTurns: result.modelTurns };
     }
     return result;
   }

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

@@ -17,6 +17,7 @@ import {
   applyPiToolResult,
   captureUIUserSidecar,
   piAssistantToUIMessage,
+  publicAssistantError,
   type PiToolApprovalView,
   type UIUserSidecar,
 } from "../message";
@@ -655,7 +656,9 @@ export class PiRuntimeTranscript {
             completedAt - submission.createdAt,
           ),
           turnStatus: "error",
-          ...(submission.error ? { error: submission.error } : {}),
+          ...(submission.error
+            ? { error: publicAssistantError(submission.error) }
+            : {}),
         },
       });
       seenAssistantSubmissions.add(submissionId);
@@ -761,7 +764,9 @@ export class PiRuntimeTranscript {
                   ),
                 }),
             turnStatus: submission?.status,
-            ...(submission?.error ? { error: submission.error } : {}),
+            ...(submission?.error
+              ? { error: publicAssistantError(submission.error) }
+              : {}),
           },
           approvals: this.approvalViews(entry.submissionId),
         });

package/src/pi/tool/compiler.ts

@@ -48,6 +48,8 @@ export interface PiToolCandidate {
   readonly tool: AgentTool<any, any>;
   /** 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. */
+  readonly codeExecutionOnly?: true;
   /** @internal Tools also callable through this Code Mode candidate. */
   readonly codeExecutionTools?: readonly PiToolCandidate[];
   /** Conservative maximum used in the stable Runtime descriptor. */
@@ -85,6 +87,7 @@ const governanceState = Symbol("PiToolGovernanceState");
 /** 向 Pi Agent 提供工具后置钩子，并为编译器保留同一 Turn 的治理状态。 */
 export interface PiToolGovernance {
   readonly afterToolCall: NonNullable<AgentOptions["afterToolCall"]>;
+  readonly wrapUpRequested: () => boolean;
   readonly [governanceState]: PiToolGovernanceState;
 }
 
@@ -222,7 +225,7 @@ function recordFailure(
 
 // 在执行前判断这次工具调用是否已超过重试或 Turn 上限。
 // 受治理 execute 方法对每个调用首先调用它。
-// 被阻断的 call id 必须记入 terminalCalls，才能让 Pi 的 afterToolCall 在返回错误后终止 Turn。
+// 被阻断的 call id 必须记入 terminalCalls，才能让 Pi 在返回错误后进入无工具收尾回合。
 function blockReason(
   state: PiToolGovernanceState | undefined,
   toolCallId: string,
@@ -263,15 +266,16 @@ export function createPiToolGovernance(): PiToolGovernance {
   };
   const governance: PiToolGovernance = {
     [governanceState]: state,
-    // 在必须终止的工具调用后告诉 Pi 停止当前 Turn。
-    // Pi Agent 在每次工具执行结束后调用，并传入实际 toolCall id。
-    // 只消费 terminalCalls 中的 id，可避免一次失败误终止后续无关工具调用。
+    // Pi Agent 在每次工具执行结束后调用，并传入实际 toolCall id。只消费
+    // terminalCalls 中的 id，可避免一次失败误触发收尾；不能在这里直接
+    // terminate，否则模型没有机会产出权威 assistant 消息。
     async afterToolCall(context) {
       if (!state.terminalCalls.delete(context.toolCall.id)) {
         return;
       }
-      return { terminate: true };
+      state.aborted = true;
     },
+    wrapUpRequested: () => state.aborted,
   };
   return governance;
 }

package/src/pi/tool/core-host.ts

@@ -2,9 +2,12 @@ import {
   createWorkspaceStateBackend,
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
+import { createBrowserTools } from "@cloudflare/think/tools/browser";
 import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
 import { jsonSchema, tool as aiTool, type ToolSet } from "ai";
 import type {
+  RuntimeBrowserPort,
+  RuntimeCodeExecutionPort,
   WorkspacePort,
 } from "../../kernel/bindings";
 import type {
@@ -16,6 +19,16 @@ import type {
 
 const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
 
+/**
+ * 宿主的 Browser Rendering 绑定，只取本仓真正用到的那一面。
+ *
+ * 结构化声明而不是 `Fetcher`：`wrangler types` 现在为这个绑定生成 `BrowserRun` 而不是 `Fetcher`，
+ * 两种声明都得能传进来（上游 `BrowserBinding` 出于同样理由也是结构化的）。
+ */
+export interface RuntimeBrowserBinding {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+
 /**
  * 把宿主的 Worker Loader、出站网络和 Workspace 组装成代码执行 Port。
  *
@@ -37,6 +50,89 @@ function codeExecutionTools(tools: ToolRegistry): ToolSet {
   ]));
 }
 
+// 上游把 Code Mode 类工具交付为 AI SDK tool；本仓只取 description 和 execute 两件，
+// 并在这里就地校验，使装配期缺件立刻失败，而不是等模型调用时才炸。
+function toCodeExecutionPort(
+  tool: ToolSet[string],
+  name: string,
+): RuntimeCodeExecutionPort {
+  const { description, execute } = tool;
+  if (typeof description !== "string" || description.length === 0) {
+    throw new Error(`Upstream ${name} runtime returned a tool without a description`);
+  }
+  if (typeof execute !== "function") {
+    throw new Error(`Upstream ${name} runtime returned a non-executable tool`);
+  }
+  return {
+    description,
+    execute: (input) => Promise.resolve(execute(input, {
+      toolCallId: name,
+      messages: [],
+      context: undefined,
+    })),
+  };
+}
+
+// 只有这一条挂在 Tool description 上：preview URL 是 per-Session 的，
+// 放进静态 system prompt 前缀会让它每轮都变，破坏 prompt cache。
+// 怎么用 CDP 才不会静默读空，是与 Session 无关的固定动作，住在静态提示词里。
+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. ` +
+    "It is the exact URL and Content-Security-Policy (sandbox allow-scripts) the user sees. " +
+    "file:// cannot reach the workspace, and there is no other preview host — do not guess one.";
+}
+
+/**
+ * 把宿主的 Durable Object state、Worker Loader 和 Browser Run 绑定组装成浏览器执行 Port。
+ *
+ * Worker 宿主在具备 DO state 与 Browser 绑定时调用，返回值经 Platform Port 交给 Runtime 工具组装。
+ *
+ * 形状与 `createWorkspaceCodeExecutionFactory` 同构：宿主提供 DO state 与平台绑定，Runtime 只拿到一个可选装配输入。
+ * `create()` 延迟到 Tool Surface 真的要注册时才调，被 deny 的装配不会白建连接器。
+ */
+export function createBrowserExecutionFactory(options: {
+  readonly ctx: DurableObjectState;
+  readonly loader: WorkerLoader;
+  readonly browser: RuntimeBrowserBinding;
+  /**
+   * 本 Session 的 Workspace preview URL（可以带短期签名 query）。
+   *
+   * 宿主能确定公开 origin 并签发当前 Session 地址时提供；只有它能给出浏览器真的打得开的地址。
+   * 拿不到就不提供 —— 宁可让模型知道自己没有这条信息，也不要给一个猜的、会 404 的地址。
+   */
+  readonly previewBaseUrl?: string;
+}): RuntimeBrowserPort {
+  return {
+    create() {
+      const tools = createBrowserTools({
+        ctx: options.ctx,
+        loader: options.loader,
+        browser: options.browser,
+        // 沙箱超时沿用 Code Mode 的同一个常量，先于 60s 外层截止结束。
+        timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
+        // 会话用上游默认的 one-shot：每次执行一个全新浏览器，两次自检互不污染。
+        // Quick Action 显式关闭：2026-08-13 复测本地绑定仍不实现 quickAction()，
+        // 让上游默认值把那四个工具带回来只会注册出本地必然失败的 Tool（knowledge F22）。
+        quickActions: false,
+        name: "browser",
+      });
+      const tool = tools.browser_execute;
+      if (!tool) {
+        throw new Error("Upstream createBrowserTools did not return browser_execute");
+      }
+      const port = toCodeExecutionPort(tool, "browser_execute");
+      if (!options.previewBaseUrl) return port;
+      // 前置而不是追加：上游的 codemode 描述很长，缀在末尾的一句会被读丢 ——
+      // 2026-08-13 手动冒烟里模型就没看见它，转而去猜 `file://` 和 `https://workspace.local/`。
+      return {
+        ...port,
+        description: `${previewNote(options.previewBaseUrl)}\n\n${port.description}`,
+      };
+    },
+  };
+}
+
 export function createWorkspaceCodeExecutionFactory(options: {
   readonly ctx: DurableObjectState;
   readonly loader: WorkerLoader;
@@ -57,20 +153,13 @@ export function createWorkspaceCodeExecutionFactory(options: {
         ),
         name: "execute",
       });
-      const { description, execute } = tool;
-      if (typeof description !== "string" || description.length === 0) {
-        throw new Error("Think createExecuteRuntime returned a tool without a description");
-      }
-      if (typeof execute !== "function") {
-        throw new Error("Think createExecuteRuntime returned a non-executable tool");
-      }
+      const port = toCodeExecutionPort(tool, "execute");
       return {
-        description,
-        execute: (input) => Promise.resolve(execute(input, {
-          toolCallId: "execute",
-          messages: [],
-          context: undefined,
-        })),
+        ...port,
+        description: 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.",
+        ),
       };
     },
   };