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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.25",
+  "version": "0.3.0-alpha.26",
   "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.2"
   },
   "peerDependencies": {
     "agents": ">=0.28.1 <0.29.0",

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/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;
 }
 
@@ -19,6 +22,11 @@ export function piCandidatesToAiTools(
       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 +37,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);
+  }
+}

package/src/tools/codemode/executor.ts

@@ -0,0 +1,173 @@
+/// <reference lib="esnext.disposable" />
+import {
+  DynamicWorkerExecutor,
+  type ConnectorBinding,
+  type DynamicWorkerExecutorOptions,
+  type ExecuteResult,
+  type Executor,
+  type ResolvedProvider,
+} from "@cloudflare/codemode";
+import { RpcTarget } from "cloudflare:workers";
+
+const CONTROL = "__springbrand_execution_control";
+const SETUP = "__springbrand_execution_setup";
+const CANCELLED = "Code execution cancelled";
+
+interface AbortHandle {
+  abort(): Promise<void>;
+  dup(): AbortHandle;
+  [Symbol.dispose](): void;
+}
+
+function isAbortHandle(value: unknown): value is AbortHandle {
+  return (typeof value === "object" && value !== null || typeof value === "function") &&
+    typeof Reflect.get(value, "abort") === "function" &&
+    typeof Reflect.get(value, "dup") === "function" &&
+    typeof Reflect.get(value, Symbol.dispose) === "function";
+}
+
+class ExecutionControl extends RpcTarget {
+  #handle?: AbortHandle;
+  #registered = false;
+  #requested = false;
+  #aborting?: Promise<void>;
+  failure?: unknown;
+
+  constructor(readonly abortMessage: string) {
+    super();
+  }
+
+  async callTool(method: string, value: unknown): Promise<void> {
+    if (method !== "register" || this.#registered || !isAbortHandle(value)) {
+      throw new Error("Invalid Code Mode cancellation registration");
+    }
+    this.#registered = true;
+    this.#handle = value.dup();
+    if (this.#requested) {
+      this.abort();
+      await this.#aborting;
+    }
+  }
+
+  abort(): void {
+    this.#requested = true;
+    const handle = this.#handle;
+    if (!handle || this.#aborting) return;
+    this.#aborting = Promise.resolve().then(() => handle.abort()).then(
+      () => undefined,
+      (error: unknown) => {
+        if (!(error instanceof Error && error.message === this.abortMessage)) {
+          this.failure = error;
+        }
+      },
+    );
+  }
+
+  async close(): Promise<void> {
+    this.abort();
+    await this.#aborting;
+    try {
+      this.#handle?.[Symbol.dispose]();
+    } catch (error) {
+      this.failure = error;
+    } finally {
+      this.#handle = undefined;
+    }
+  }
+}
+
+class GuardedConnector extends RpcTarget {
+  constructor(
+    readonly binding: ConnectorBinding["binding"],
+    readonly check: () => void,
+  ) {
+    super();
+  }
+
+  async callTool(method: string, args: unknown): Promise<unknown> {
+    this.check();
+    return await this.binding.callTool(method, args);
+  }
+}
+
+function setup(abortMessage: string): string {
+  return `await (async () => {
+    const { RpcTarget } = await import("cloudflare:workers");
+    const context = this.ctx;
+    if (typeof context.abort !== "function") throw new Error("Native Code Mode cancellation is unavailable");
+    const abort = context.abort.bind(context);
+    const reason = new Error(${JSON.stringify(abortMessage)});
+    class Cancellation extends RpcTarget {
+      abort() { abort(reason); }
+    }
+    await ${CONTROL}.register(new Cancellation());
+  })();`;
+}
+
+/** Cancels a native sandbox pass, not its Host effects or the loaded Worker isolate. */
+export function createCodeExecutionExecutor(
+  options: DynamicWorkerExecutorOptions,
+  signal?: AbortSignal,
+): Executor {
+  const executor = new DynamicWorkerExecutor(options);
+  return {
+    async execute(code, providersOrFns, executeOptions): Promise<ExecuteResult> {
+      if (signal?.aborted) return { result: undefined, error: CANCELLED };
+      const providers: ResolvedProvider[] = Array.isArray(providersOrFns)
+        ? providersOrFns
+        : [{ name: "codemode", fns: providersOrFns }];
+      const connectors = executeOptions?.connectors ?? [];
+      if ([...providers, ...connectors].some(({ name }) => name === CONTROL || name === SETUP)) {
+        return { result: undefined, error: "Code execution uses a reserved namespace" };
+      }
+      const control = new ExecutionControl(`Code Mode pass aborted (${crypto.randomUUID()})`);
+      let ended = false;
+      const check = () => {
+        if (signal?.aborted || ended) throw new Error(CANCELLED);
+      };
+      const onAbort = () => control.abort();
+      signal?.addEventListener("abort", onAbort, { once: true });
+      let result: ExecuteResult;
+      try {
+        if (signal?.aborted) return { result: undefined, error: CANCELLED };
+        result = await executor.execute(code, [{
+          name: SETUP,
+          fns: {},
+          prelude: setup(control.abortMessage),
+        }, ...providers.map((provider) => ({
+          ...provider,
+          fns: Object.fromEntries(Object.entries(provider.fns).map(([name, fn]) => [
+            name,
+            async (...args: unknown[]) => {
+              check();
+              return await fn(...args);
+            },
+          ])),
+        }))], {
+          ...executeOptions,
+          connectors: [{
+            name: CONTROL,
+            binding: control,
+          }, ...connectors.map((connector) => ({
+            ...connector,
+            binding: new GuardedConnector(connector.binding, check),
+          }))],
+        });
+      } catch (error) {
+        result = {
+          result: undefined,
+          error: error instanceof Error && error.message === control.abortMessage
+            ? CANCELLED
+            : error instanceof Error ? error.message : String(error),
+        };
+      } finally {
+        ended = true;
+        signal?.removeEventListener("abort", onAbort);
+        // A returned SDK timeout is only a soft race; stop the native pass too.
+        await control.close();
+      }
+      if (control.failure) return { result: undefined, error: "Failed to stop the Code Mode pass" };
+      return signal?.aborted ? { result: undefined, error: CANCELLED } : result;
+    },
+  };
+}

package/src/tools/codemode/index.ts

@@ -1,3 +1,4 @@
+import { truncateResult } from "@cloudflare/codemode";
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
 import type { RuntimeCodeExecutionPort } from "../../config/ports";
@@ -86,17 +87,18 @@ function browserResult(details: unknown): AgentToolResult<unknown> {
   }
 
   const image = record(inner?.image);
+  const nativeImage = inner?.type === "browser_screenshot" ? inner : undefined;
   const screenshotArgs = record(screenshotCall?.args);
   const screenshotResult = record(screenshotCall?.result);
   const format = record(screenshotArgs?.params)?.format;
   const data = typeof image?.data === "string"
     ? image.data
-    : screenshotResult?.data;
+    : nativeImage ? nativeImage.data : screenshotResult?.data;
   const mimeType = typeof image?.mimeType === "string"
     ? image.mimeType
-    : screenshotMimeType(format);
-  if (!(inner && "image" in inner) && typeof data !== "string") {
-    return result(details);
+    : nativeImage ? nativeImage.mediaType : screenshotMimeType(format);
+  if (!(inner && "image" in inner) && !nativeImage && typeof data !== "string") {
+    return result("result" in outer ? { ...outer, result: truncateResult(rawResult) } : details);
   }
   const projectedImage = browserImageMetadata(data, mimeType);
 
@@ -127,10 +129,9 @@ function browserResult(details: unknown): AgentToolResult<unknown> {
   const projectedDetails = {
     ...outer,
     result: inner
-      ? {
-        ...inner,
-        image: projectedImage,
-      }
+      ? nativeImage
+        ? { ...inner, data: projectedImage }
+        : { ...inner, image: projectedImage }
       : {
         image: projectedImage,
         note: "Screenshot recovered from the Page.captureScreenshot result.",
@@ -172,30 +173,18 @@ function runCodemode(
 ): AgentTool<typeof executeParameters>["execute"] {
   return async (_toolCallId, input, signal) => {
     signal?.throwIfAborted();
-    // ponytail: 外层截止只保证 Agent 继续；Codemode 支持 AbortSignal 或宿主 dispose 后再终止底层执行。
-    let timeout: ReturnType<typeof setTimeout> | undefined;
-    const deadline = new Promise<{
-      status: "error";
-      code: "timeout";
-      error: string;
-      retryable: false;
-      outcome: "unknown";
-    }>((resolve) => {
-      timeout = setTimeout(() => resolve({
-        status: "error",
-        code: "timeout",
-        error:
-          `${label} exceeded ${CODEMODE_EXECUTE_TIMEOUT_MS} ms; ` +
-          "use existing results and state the missing evidence.",
-        retryable: false,
-        outcome: "unknown",
-      }), CODEMODE_EXECUTE_TIMEOUT_MS);
-    });
+    const execution = new AbortController();
+    const cancel = () => execution.abort(signal?.reason);
+    signal?.addEventListener("abort", cancel, { once: true });
+    // The first abort reason distinguishes a parent cancellation from our deadline.
+    const timeout = setTimeout(() => execution.abort(new Error(
+      `${label} exceeded ${CODEMODE_EXECUTE_TIMEOUT_MS} ms; ` +
+      "use existing results and state the missing evidence.",
+    )), CODEMODE_EXECUTE_TIMEOUT_MS);
     try {
-      const output = await Promise.race([
-        runtime.execute(input),
-        deadline.then(result),
-      ]);
+      // The Port settles only after the executor and connector cleanup finish.
+      const output = await runtime.execute(input, { signal: execution.signal });
+      execution.signal.throwIfAborted();
       const details = output.details as { status?: unknown; error?: unknown } | null;
       if (details?.status === "error") {
         throw new Error(typeof details.error === "string"
@@ -203,8 +192,12 @@ function runCodemode(
           : `${label} failed`);
       }
       return project(output);
+    } catch (error) {
+      execution.signal.throwIfAborted();
+      throw error;
     } finally {
-      if (timeout !== undefined) clearTimeout(timeout);
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", cancel);
     }
   };
 }