@springbrand/agent-runtime 0.3.0-alpha.25 → 0.3.0-alpha.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.25",
+  "version": "0.3.0-alpha.27",
   "type": "module",
   "files": [
     "src",
@@ -36,7 +36,7 @@
     "zod": "^4.4.3",
     "@earendil-works/pi-durable": "1.1.0",
     "@earendil-works/chord": "1.1.0",
-    "@springbrand/model-client": "0.1.0-alpha.1"
+    "@springbrand/model-client": "0.1.0-alpha.3"
   },
   "peerDependencies": {
     "agents": ">=0.28.1 <0.29.0",

package/src/adapter/cloudflare/agent.ts

@@ -73,6 +73,8 @@ import type {
 } from "@earendil-works/pi-ai";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { openCloudflareSession } from "../../session";
+import type { ToolPrerequisiteResponse } from "../../tools/runtime/prerequisite-contracts";
+import { matchesPrerequisite, parsePrerequisiteResponse, projectPrerequisites } from "../../tools/runtime/prerequisites";
 import { ModelRecovery, openSessionHarness, prepareSubmissionOperation } from "../../harness";
 import type { SessionHarness } from "../../harness";
 import {
@@ -158,6 +160,7 @@ export abstract class AgentRuntimeKernel<
 
   initialState: RuntimeState = {
     runtimeLoad: { status: "idle", available: false },
+    prerequisites: [],
   };
 
   protected abstract ensureRuntimeReady(): Promise<void>;
@@ -826,6 +829,10 @@ export abstract class AgentRuntimeKernel<
       interactions: this.db.interactions,
       transaction: (run) => this.db.transaction(run),
       release: (reason) => runtime.requestHumanRelease(reason),
+      isSubmissionActive: () => {
+        const current = this.db.submissions.find(submissionId);
+        return Boolean(current && current.status === "running" && !current.abortReason && !current.unattendedFailure);
+      },
       onChanged: async (kind, id) => {
         await this.broadcastApprovals();
         if (kind === "approval") {
@@ -1513,11 +1520,12 @@ export abstract class AgentRuntimeKernel<
     };
   }
 
-  /** Validate a client-provided Tool result and resume its durable Submission. */
+  /** Answers settle a Tool result; full prerequisite decisions control pre-effect waits. */
   async respondToolInteraction(
-    toolCallId: string,
-    response: unknown,
+    toolCallId: string | ToolPrerequisiteResponse,
+    response?: unknown,
   ): Promise<{ ok: boolean }> {
+    if (typeof toolCallId !== "string") return this.respondPrerequisite(toolCallId);
     const pending = this.db.interactions.findPendingByToolCallId(toolCallId);
     if (!pending) return { ok: false };
     const submission = this.db.submissions.find(pending.submissionId);
@@ -1552,6 +1560,29 @@ export abstract class AgentRuntimeKernel<
     return { ok: true };
   }
 
+  private async respondPrerequisite(response: ToolPrerequisiteResponse): Promise<{ ok: boolean }> {
+    const identity = parsePrerequisiteResponse(response);
+    if (!identity) return { ok: false };
+    const pending = this.db.interactions.find(identity.id);
+    if (!matchesPrerequisite(pending, identity) || pending.status !== "pending") return { ok: false };
+    const submission = this.db.submissions.findRunning();
+    if (!submission || submission.submissionId !== pending.submissionId || submission.abortReason) return { ok: false };
+    const active = this.submissions.currentActive();
+    if (active && active.submissionId !== submission.submissionId) return { ok: false };
+    // Decline is Config-independent, like an ordinary ask_user answer. It can win
+    // while OAuth verification or the previous slice's parallel effects drain.
+    if (identity.decision === "recheck" && !active) await this.ensureRuntimeVersion(submission.runtimeKey, true);
+    const spec = identity.decision === "recheck"
+      ? this.pi.prerequisite(this.requireRuntime().pi, pending.toolName) : undefined;
+    const result = await this.humanDecisions.respondPrerequisite(pending, spec, identity);
+    if (!result.ok) return { ok: false };
+    await this.broadcastApprovals();
+    if (result.resume) this.ctx.waitUntil(
+      this.submissions.continueAfterCurrent(submission.submissionId).then(() => undefined),
+    );
+    return { ok: true };
+  }
+
   /** Apply one decision; the Host must persist allow_level before resuming. */
   async decideApproval(
     executionId: string,
@@ -1619,6 +1650,7 @@ export abstract class AgentRuntimeKernel<
     try {
       const { state, changed } = projectRuntimeState({
         approvals: this.db.approvals.listPendingActive(),
+        prerequisites: projectPrerequisites(this.db.interactions.listPendingActive()),
         temporaryApprovals: this.temporaryAgentApprovals.list(),
         running: this.db.submissions.findRunning(),
         pending: this.db.submissions.listPending(),

package/src/adapter/cloudflare/database.ts

@@ -21,8 +21,8 @@ import {
 // 数据库术语以这里为准。
 // Submission 是一次可持久化的用户提交，从排队到终态都用同一个 submissionId 跟踪。
 // Approval 是某次工具调用的持久化审批记录，executionId 是对外决策时的主键。
-// Tool Interaction 是「结果由客户端提供」的工具调用的 park 记录，interactionId 是主键；
-// 它保存人的回答，Harness Session 保存工具执行位置和最终 ToolResult。
+// Tool Interaction 保存客户端答案或原工具的前置条件等待，interactionId 是主键；
+// 它保存人的决定和有界核验事实，Pi 保存工具执行位置和最终 ToolResult。
 // Extension Context 是扩展按 label 保存的文本，不随清空聊天记录删除。
 // Message UI 是会话消息的用户界面补充数据，它由 Transcript 而不是 Turn 生命周期管理。
 // Agent Tool Run 是 Agents SDK 派发的子运行，唯一一张不归 Runtime 所有的表：SDK 建它、写它、清它，

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

@@ -20,6 +20,7 @@ import type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
   TemporaryAgentLaunchSelection,
+  ToolPrerequisiteResponse,
 } from "../../tools";
 import { TEMPORARY_AGENT_LAUNCH_KEY } from "../../tools";
 import {
@@ -215,14 +216,15 @@ export interface RuntimeAgentControls {
     decision: ApprovalDecision,
   ): Promise<{ ok: boolean }>;
   /**
-   * 把客户端投递的响应作为某次 Tool 调用的结果并续跑原 Turn。
+   * Settle an answer Tool, or control a prerequisite using its full wait identity.
    *
    * @remarks
-   * 前端经 WS RPC 调用，只带 `toolCallId`。查无、已结算或响应体不过校验都返回 `{ ok: false }`。
+   * Legacy answers use (toolCallId, answer). Prerequisites use one response object;
+   * only the backend verifies readiness. Missing/stale/invalid decisions return false.
    */
   respondToolInteraction(
-    toolCallId: string,
-    response: unknown,
+    toolCallId: string | ToolPrerequisiteResponse,
+    response?: unknown,
   ): Promise<{ ok: boolean }>;
   /**
    * 登记一条受管临时 Agent 发起的审批请求。
@@ -327,6 +329,8 @@ export interface RuntimeAgentConfigControls<Command, Change> {
 
 /** Type-only Host extension seam implemented by AgentRuntimeKernel. */
 declare class RuntimeAgentHostSeam {
+  protected runConfigControl<T>(run: () => Promise<T>): Promise<T>;
+  protected ensureRuntimeVersion(runtimeKey: string, force?: boolean): Promise<void>;
   protected prepareToolInteractionResponse(
     input: import("./agent").ToolInteractionResponsePreparation,
   ): Promise<unknown | null>;
@@ -626,8 +630,8 @@ export function defineRuntimeAgent<
       }
 
       respondToolInteraction(
-        toolCallId: string,
-        response: unknown,
+        toolCallId: string | ToolPrerequisiteResponse,
+        response?: unknown,
       ): Promise<{ ok: boolean }> {
         return super.respondToolInteraction(toolCallId, response);
       }

package/src/adapter/cloudflare/schema.ts

@@ -209,6 +209,28 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
     responded_at INTEGER,
     UNIQUE (submission_id, tool_call_id)
   )`;
+  const interactionColumns = new Set(
+    sql<{ name: string }>`PRAGMA table_info(pi_tool_interactions)`.map((column) => column.name),
+  );
+  // Old client-settled answers keep their original meaning on a rolling upgrade.
+  if (!interactionColumns.has("purpose")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN purpose TEXT NOT NULL DEFAULT 'answer'`;
+  }
+  if (!interactionColumns.has("scope_key")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN scope_key TEXT`;
+  }
+  if (!interactionColumns.has("version")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN version INTEGER NOT NULL DEFAULT 1`;
+  }
+  if (!interactionColumns.has("presentation_json")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN presentation_json TEXT`;
+  }
+  if (!interactionColumns.has("verified_until")) {
+    sql`ALTER TABLE pi_tool_interactions ADD COLUMN verified_until INTEGER`;
+  }
+  sql`CREATE INDEX IF NOT EXISTS pi_tool_interactions_scope
+      ON pi_tool_interactions(submission_id, scope_key, status)
+      WHERE purpose = 'prerequisite'`;
   sql`CREATE TABLE IF NOT EXISTS pi_extension_context (
     label TEXT PRIMARY KEY,
     content TEXT NOT NULL,

package/src/config/assembler.ts

@@ -256,6 +256,9 @@ async function createToolSurface(
           if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
             throw new Error(`SpringBrand Tool ${name} execution level is invalid`);
           }
+          if (candidate.prerequisite && (candidate.interaction || exposureOf(candidate) === "codemode")) {
+            throw new Error(`SpringBrand Tool ${name} prerequisites require a direct, non-answer Tool`);
+          }
           if (candidate.unattendedExecution) {
             requiredName(
               candidate.unattendedExecution.capability,
@@ -293,6 +296,7 @@ async function createToolSurface(
           (candidate) =>
             exposureOf(candidate) !== "direct" &&
             !candidate.interaction &&
+            !candidate.prerequisite &&
             typeof candidate.tool.execute === "function",
         );
         const codeExecutionCandidates = Object.freeze([...mergeable]);

package/src/config/harness-runtime.ts

@@ -88,6 +88,12 @@ export class HarnessRuntimeConfig {
     )?.interaction;
   }
 
+  prerequisite(prepared: PreparedPiRuntime, name: string) {
+    return readPreparedPiRuntime(prepared, this.owner).candidates.find(
+      (candidate) => candidate.tool.name === name,
+    )?.prerequisite;
+  }
+
   /** Read all executable inputs from the current Prepared Runtime. */
   async harnessInputs(
     prepared: PreparedPiRuntime,

package/src/config/ports.ts

@@ -264,7 +264,16 @@ export interface WorkspaceStreamWriteOptions {
  */
 export interface RuntimeCodeExecutionPort {
   readonly description: string;
-  execute(input: { code: string }): Promise<AgentToolResult<unknown>>;
+  /**
+   * Honour a provided signal before dispatch and throughout execution.
+   * On abort, stop suspended sandbox continuations and further Host dispatches,
+   * await execution finalization, and reject rather than accepting a late result.
+   * Already-started Host effects are not rolled back; CPU preemption is not guaranteed.
+   */
+  execute(
+    input: { code: string },
+    options?: { signal?: AbortSignal },
+  ): Promise<AgentToolResult<unknown>>;
 }
 
 /**

package/src/config/prepared-runtime.ts

@@ -197,6 +197,7 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
       parameters: candidate.tool.parameters,
       requiredExecutionLevel: candidate.requiredExecutionLevel,
       ...(candidate.confirmation ? { confirmation: true } : {}),
+      ...(candidate.prerequisite ? { prerequisite: true } : {}),
       ...(candidate.alwaysRequiresApproval
         ? { alwaysRequiresApproval: true }
         : {}),

package/src/config/public-contracts.ts

@@ -18,6 +18,13 @@ export * from "../conversation/canonical-context";
 export * from "../submission/contracts";
 export * from "../conversation/state";
 export * from "../lib/execution-level";
+export type {
+  ToolPrerequisiteDecision,
+  ToolPrerequisiteIdentity,
+  ToolPrerequisitePresentation,
+  ToolPrerequisiteRequest,
+  ToolPrerequisiteResponse,
+} from "../tools/runtime/prerequisite-contracts";
 export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace/versioning";
 export type {
   RuntimeEventConfirmation,

package/src/conversation/state.ts

@@ -2,6 +2,7 @@ import type { ApprovalReceipt } from "../submission/contracts";
 import type { StoredSubmission } from "../submission/repository";
 import type { PendingApprovalSummary } from "../tools/runtime/approval/repository";
 import type { PiCanonicalUserInput } from "./message/contract";
+import type { ToolPrerequisiteRequest } from "../tools/runtime/prerequisite-contracts";
 
 export type RuntimeLoadPhase = "config" | "assembly" | "mcp" | "pi";
 
@@ -95,6 +96,8 @@ export interface RuntimeState {
   /** 供 Host 列表持久化的粗粒度活动状态；Submission 与 Approval 仍是执行真相。 */
   activity?: RuntimeActivityProjection;
   approvals?: ApprovalReceipt[];
+  /** Durable pre-effect waits, separate from canonical messages and answer tools. */
+  prerequisites?: ToolPrerequisiteRequest[];
   turn?: RuntimeTurnState;
   /** 有值时普通输入被锁定,直到锁定的 Submission 进入终态。 */
   inputLock?: RuntimeInputLock;
@@ -109,6 +112,7 @@ type SubmissionProjection = Pick<
 /** Rebuild client-visible activity from current facts without retaining lifecycle state. */
 export function projectRuntimeState(input: {
   readonly approvals: readonly PendingApprovalSummary[];
+  readonly prerequisites?: readonly ToolPrerequisiteRequest[];
   readonly temporaryApprovals: readonly ApprovalReceipt[];
   readonly running: SubmissionProjection | null | undefined;
   readonly pending: readonly SubmissionProjection[];
@@ -134,6 +138,9 @@ export function projectRuntimeState(input: {
     ...input.temporaryApprovals,
   ];
   const current = input.running ?? input.pending[0];
+  const prerequisites = (input.prerequisites ?? []).filter(
+    (request) => request.submissionId === current?.submissionId,
+  );
   const queued = (input.running ? input.pending : input.pending.slice(1)).map(
     (submission, index): RuntimeQueuedSubmission => {
       let preview = "Queued message";
@@ -166,7 +173,7 @@ export function projectRuntimeState(input: {
     hasPendingSteer: Boolean(current && input.hasPendingSteer(current.submissionId)),
     queued,
   };
-  const activity: RuntimeActivity = approvals.length > 0 ||
+  const activity: RuntimeActivity = approvals.length > 0 || prerequisites.length > 0 ||
       (current && input.hasPendingInteraction(current.submissionId))
     ? "needs-input"
     : current || queued.length > 0 ? "working" : "idle";
@@ -183,13 +190,15 @@ export function projectRuntimeState(input: {
     ? { reason: "scheduled-run" }
     : undefined;
   const changed = input.previousState.approvals === undefined ||
+    input.previousState.prerequisites === undefined ||
     JSON.stringify(input.previousState.approvals) !== JSON.stringify(approvals) ||
+    JSON.stringify(input.previousState.prerequisites) !== JSON.stringify(prerequisites) ||
     JSON.stringify(input.previousState.turn) !== JSON.stringify(turn) ||
     JSON.stringify(input.previousState.inputLock) !== JSON.stringify(inputLock) ||
     nextActivity !== previousActivity;
   return {
     state: changed
-      ? { ...input.previousState, activity: nextActivity, approvals, turn, inputLock }
+      ? { ...input.previousState, activity: nextActivity, approvals, prerequisites, turn, inputLock }
       : input.previousState,
     changed,
   };

package/src/index.ts

@@ -91,6 +91,14 @@ export type {
 } from "./tools/subagent/types/contract";
 export type {
   PiToolCandidate,
+  PiToolPrerequisiteCheck,
+  PiToolPrerequisiteContext,
+  PiToolPrerequisiteSpec,
+  ToolPrerequisiteDecision,
+  ToolPrerequisiteIdentity,
+  ToolPrerequisitePresentation,
+  ToolPrerequisiteRequest,
+  ToolPrerequisiteResponse,
   ToolExposureMode,
 } from "./tools";
 export { basePiToolCandidates } from "./tools";

package/src/tools/README.md

@@ -34,6 +34,30 @@ codemode/adapter.ts              Cloudflare 执行器组装、描述与结果适
 
 `pi-to-ai.ts` 也被 Skill 脚本执行使用，因此放在共用 `adapters/` 中。工具声明仍以 Pi 为唯一事实源。
 
+### Cancellation And Settlement
+
+`RuntimeCodeExecutionPort.execute(input, { signal })` carries cancellation
+through the adapter to the invocation's native sandbox. Parent cancellation
+and the Tool deadline share this path. The Port awaits sandbox finalization
+and connector cleanup before rejecting; it does not abandon a running Promise.
+
+`codemode/executor.ts` composes the public Cloudflare executor with a retained,
+per-invocation RPC cancellation handle. It aborts the sandbox invocation, never
+the parent Host context or a sibling invocation. This does not guarantee CPU
+preemption, Worker destruction, quota release or rollback of Host effects.
+
+Already-started Host work can finish after sandbox cancellation. Its returned
+facts must still reach the completion callback and the official connector's
+durable result history. That does not permit model continuation or accept a
+cancelled Tool's termination control. Producer-owned usage events remain
+authoritative; an aborted outer Tool must not be interpreted as zero usage.
+
+Browser invocations each own an `InvocationBrowserConnector`. At pass end it
+rejects new dispatches and drains its already-started browser calls before the
+public SDK closes the socket and one-shot session. An allocation can complete
+after sandbox abort; the Port waits for that late allocation and its cleanup
+rather than reporting terminal cleanup early. Other Host tools are not drained.
+
 ## 修改位置
 
 - 修改某个工具：进入对应功能目录，测试与实现放在一起。

package/src/tools/adapters/pi-to-ai.ts

@@ -4,7 +4,10 @@ import { tool as aiTool, jsonSchema, type ToolSet } from "ai";
 import type { PiToolCandidate } from "../runtime/contracts";
 
 interface NestedToolOptions {
+  /** Bound by the execution when the upstream connector omits AI SDK call options. */
+  readonly signal?: AbortSignal;
   readonly fallbackToolCallId?: (name: string) => string;
+  /** Settled Host facts, even after cancellation; not permission for model control. */
   readonly onResult?: (result: AgentToolResult<unknown>) => void;
 }
 
@@ -13,12 +16,19 @@ export function piCandidatesToAiTools(
   candidates: readonly PiToolCandidate[],
   options: NestedToolOptions,
 ): ToolSet {
-  return Object.fromEntries(candidates.map((candidate) => [
+  // Nested sandboxes have no pre-intent durable human wait. Never bypass a
+  // prerequisite by exposing its raw execute closure in Code Mode or Skill scripts.
+  return Object.fromEntries(candidates.filter((candidate) => !candidate.prerequisite).map((candidate) => [
     candidate.tool.name,
     aiTool({
       description: candidate.tool.description,
       inputSchema: jsonSchema(candidate.tool.parameters as never),
       execute: async (input, call) => {
+        const callSignal = call?.abortSignal;
+        const signal = options.signal && callSignal && options.signal !== callSignal
+          ? AbortSignal.any([options.signal, callSignal])
+          : options.signal ?? callSignal ?? new AbortController().signal;
+        signal.throwIfAborted();
         const toolCallId = call?.toolCallId ??
           options.fallbackToolCallId?.(candidate.tool.name) ??
           candidate.tool.name;
@@ -29,11 +39,15 @@ export function piCandidatesToAiTools(
           name: candidate.tool.name,
           arguments: prepared as JsonObject,
         });
+        signal.throwIfAborted();
         const result = await candidate.tool.execute(
           toolCallId,
           args,
-          call?.abortSignal ?? new AbortController().signal,
+          signal,
         );
+        // A resolved Host operation is a fact even if cancellation happened
+        // while it ran. Let settlement and the connector's durable recordResult
+        // finish; the outer Code Mode boundary rejects model continuation.
         options.onResult?.(result);
         if (result.details !== undefined) return result.details;
         const [only] = result.content;

package/src/tools/codemode/adapter.ts

@@ -1,4 +1,4 @@
-import { truncateResponse, truncateResult, type ProxyToolOutput } from "@cloudflare/codemode";
+import { createCodemodeRuntime, truncateResponse, truncateResult, type ProxyToolOutput } from "@cloudflare/codemode";
 import { generateTypes } from "@cloudflare/codemode/ai";
 import {
   STATE_TYPES,
@@ -6,10 +6,10 @@ import {
   type StateBackend,
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
-import { createBrowserTools } from "@cloudflare/think/tools/browser";
 import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Usage } from "@earendil-works/pi-ai";
+import { DurableBrowserSessionStore } from "agents/browser";
 import type { ToolSet } from "ai";
 import type {
   RuntimeBrowserPort,
@@ -19,6 +19,8 @@ import type {
 } from "../../config/ports";
 import { serializeOutput } from "../../lib/artifacts";
 import { piCandidatesToAiTools } from "../adapters/pi-to-ai";
+import { InvocationBrowserConnector } from "./browser-connector";
+import { createCodeExecutionExecutor } from "./executor";
 import {
   WORKSPACE_PAGING_INSTRUCTIONS,
   WORKSPACE_STATE_TYPES,
@@ -226,11 +228,23 @@ function toCodeExecutionPort(
   }
   return {
     description,
-    execute: async (input) => project(await execute(input, {
-      toolCallId: name,
-      messages: [],
-      context: undefined,
-    })),
+    execute: async (input, options) => {
+      const signal = options?.signal;
+      signal?.throwIfAborted();
+      try {
+        const output = await execute(input, {
+          toolCallId: name,
+          messages: [],
+          context: undefined,
+          abortSignal: signal,
+        });
+        signal?.throwIfAborted();
+        return project(output);
+      } catch (error) {
+        signal?.throwIfAborted();
+        throw error;
+      }
+    },
   };
 }
 
@@ -292,30 +306,38 @@ export function createBrowserExecutionFactory(options: {
 }): 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");
-      const description = `${port.description}\n\n${browserToolDescription()}`;
-      if (!options.previewBaseUrl) return { ...port, description };
-      // 前置而不是追加：上游的 codemode 描述很长，缀在末尾的一句会被读丢 ——
-      // 2026-08-13 手动冒烟里模型就没看见它，转而去猜 `file://` 和 `https://workspace.local/`。
+      // Compose public seams with per-invocation ownership. No Quick Actions.
+      const createPort = (signal?: AbortSignal) => {
+        const connector = new InvocationBrowserConnector(options.ctx, {
+          browser: options.browser,
+          store: new DurableBrowserSessionStore(options.ctx.storage),
+          timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
+          // Keep the public connector's default one-shot lifecycle.
+        });
+        const runtime = createCodemodeRuntime({
+          ctx: options.ctx,
+          executor: createCodeExecutionExecutor({
+            loader: options.loader,
+            timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
+          }, signal),
+          connectors: [connector],
+          name: "browser",
+          // Keep raw screenshots intact for browserResult's Pi image projection.
+        });
+        return toCodeExecutionPort(runtime.tool({
+          connectorHints: {
+            cdp: "Browser CDP. Return screenshots as { type: 'browser_screenshot', mediaType: 'image/png', data: screenshot.data }; the UI keeps the image while the model receives a compact summary.",
+          },
+        }), "browser_execute");
+      };
+      const description = `${createPort().description}\n\n${browserToolDescription()}`;
       return {
-        ...port,
-        description: `${previewNote(options.previewBaseUrl)}\n\n${description}`,
+        // Keep the Session's exact preview URL ahead of the long generated guidance.
+        description: options.previewBaseUrl
+          ? `${previewNote(options.previewBaseUrl)}\n\n${description}`
+          : description,
+        execute: (input, executionOptions) =>
+          createPort(executionOptions?.signal).execute(input, executionOptions),
       };
     },
   };
@@ -343,9 +365,11 @@ export function createWorkspaceCodeExecutionFactory(options: {
         : undefined;
       const createPort = (
         innerResults: AgentToolResult<unknown>[],
+        signal?: AbortSignal,
       ) => {
         let nestedCallOrdinal = 0;
         const tools = piCandidatesToAiTools(candidates, {
+          signal,
           fallbackToolCallId: (name) =>
             `codemode:${++nestedCallOrdinal}:${name}`,
           onResult: (value) => innerResults.push(value),
@@ -354,6 +378,11 @@ export function createWorkspaceCodeExecutionFactory(options: {
           ctx: options.ctx,
           loader: options.loader,
           globalOutbound: options.outbound,
+          executor: createCodeExecutionExecutor({
+            loader: options.loader,
+            globalOutbound: options.outbound,
+            timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
+          }, signal),
           tools,
           timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
           connectors: workspaceState ? [workspaceState] : [],
@@ -392,7 +421,8 @@ export function createWorkspaceCodeExecutionFactory(options: {
           ...(state && options.workspace.readFilePage ? [WORKSPACE_PAGING_INSTRUCTIONS] : []),
           SPRINGBRAND_CODE_MODE_POLICY,
         ].join("\n\n"),
-        execute: (input) => createPort([]).execute(input),
+        execute: (input, executionOptions) =>
+          createPort([], executionOptions?.signal).execute(input, executionOptions),
       };
     },
   };

package/src/tools/codemode/browser-connector.ts

@@ -0,0 +1,28 @@
+import { BrowserConnector } from "agents/browser";
+
+/** Drains one invocation's browser calls before the upstream pass lifecycle ends. */
+export class InvocationBrowserConnector extends BrowserConnector {
+  readonly #pending = new Set<Promise<unknown>>();
+  #ending = false;
+
+  override async executeTool(
+    ...args: Parameters<BrowserConnector["executeTool"]>
+  ): Promise<unknown> {
+    if (this.#ending) throw new Error("Browser execution has ended");
+    const pending = super.executeTool(...args);
+    this.#pending.add(pending);
+    try {
+      return await pending;
+    } finally {
+      this.#pending.delete(pending);
+    }
+  }
+
+  override async onPassEnd(
+    ...args: Parameters<BrowserConnector["onPassEnd"]>
+  ): Promise<void> {
+    this.#ending = true;
+    await Promise.allSettled(this.#pending);
+    await super.onPassEnd(...args);
+  }
+}