@springbrand/agent-runtime 0.2.0-alpha.19 → 0.2.0-alpha.21

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.",
+        ),
       };
     },
   };

package/src/pi/tool/core.ts

@@ -1,16 +1,13 @@
-import { createQuickActionTools } from "@cloudflare/think/tools/browser";
 import type {
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
 import type {
-  RuntimeBrowserPort,
   RuntimeCodeExecutionPort,
 } from "../../kernel/bindings";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiLoadedExtension } from "../assembly/extensions";
-import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
@@ -25,37 +22,146 @@ function result(details: unknown): AgentToolResult<unknown> {
   };
 }
 
-// #region Browser Quick Actions
+const BROWSER_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+const BROWSER_IMAGE_MAX_BASE64_CHARS = Math.ceil(BROWSER_IMAGE_MAX_BYTES / 3) * 4;
+const BROWSER_IMAGE_MIME_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+]);
 
-const BROWSER_TOOL_LABELS: Readonly<Record<string, string>> = {
-  browser_markdown: "Read web page",
-  browser_extract: "Extract web data",
-  browser_links: "List web links",
-  browser_scrape: "Scrape web elements",
-};
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
 
-/**
- * 为 Cloudflare Browser Run 的四个一次性 Quick Action 创建 Pi 工具候选项。
- *
- * Runtime 在宿主提供 Browser port 时调用，模型分别用它读取 Markdown、抽取数据、列出链接或按选择器抓取。
- *
- * Cloudflare 官方将 Quick Actions 定位为只需 browser binding 的无状态单次操作，这里直接复用官方工厂。
- */
-export function browserQuickActionPiToolCandidates(
-  browser: RuntimeBrowserPort,
-): PiToolCandidate[] {
-  return Object.entries(createQuickActionTools({ browser })).map(
-    ([name, tool]) => ({
-      owner: "core:browser",
-      requiredExecutionLevel: "low",
-      tool: aiToolToPi(name, tool, {
-        label: BROWSER_TOOL_LABELS[name] ?? name,
-      }),
-    }),
-  );
+function base64Bytes(value: string): number | undefined {
+  if (
+    value.length === 0 ||
+    value.length % 4 !== 0 ||
+    !/^[A-Za-z0-9+/]+={0,2}$/u.test(value)
+  ) return undefined;
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+  return value.length / 4 * 3 - padding;
 }
 
-// #endregion
+function screenshotMimeType(format: unknown): string {
+  return format === "jpeg"
+    ? "image/jpeg"
+    : format === "webp"
+      ? "image/webp"
+      : "image/png";
+}
+
+function browserImageMetadata(
+  data: unknown,
+  mimeType: unknown,
+): { error: string } | { mimeType: string; bytes: number } {
+  if (typeof mimeType !== "string" || !BROWSER_IMAGE_MIME_TYPES.has(mimeType)) {
+    return { error: "unsupported_mime_type" };
+  }
+  if (typeof data !== "string") return { error: "invalid_base64" };
+  if (data.length > BROWSER_IMAGE_MAX_BASE64_CHARS) {
+    return { error: "image_too_large" };
+  }
+  const bytes = base64Bytes(data);
+  if (bytes === undefined) return { error: "invalid_base64" };
+  if (bytes > BROWSER_IMAGE_MAX_BYTES) return { error: "image_too_large" };
+  return { mimeType, bytes };
+}
+
+/** Project the explicit browser screenshot envelope into Pi's native image content. */
+function browserResult(details: unknown): AgentToolResult<unknown> {
+  const outer = record(details);
+  if (!outer) return result(details);
+  const rawResult = outer.result;
+  let inner = record(rawResult);
+  if (!inner && typeof rawResult === "string") {
+    try {
+      inner = record(JSON.parse(rawResult));
+    } catch {
+      // The screenshot audit below can still recover truncated JSON.
+    }
+  }
+
+  const calls = Array.isArray(outer.calls) ? outer.calls : [];
+  let screenshotCall: Record<string, unknown> | undefined;
+  for (let index = calls.length - 1; index >= 0; index -= 1) {
+    const call = record(calls[index]);
+    const args = record(call?.args);
+    if (
+      call?.connector === "cdp" &&
+      call.method === "send" &&
+      args?.method === "Page.captureScreenshot"
+    ) {
+      screenshotCall = call;
+      break;
+    }
+  }
+
+  const image = record(inner?.image);
+  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;
+  const mimeType = typeof image?.mimeType === "string"
+    ? image.mimeType
+    : screenshotMimeType(format);
+  if (!(inner && "image" in inner) && typeof data !== "string") {
+    return result(details);
+  }
+  const projectedImage = browserImageMetadata(data, mimeType);
+
+  const projectedCalls = Array.isArray(outer.calls)
+    ? outer.calls.map((call) => {
+        const entry = record(call);
+        const args = record(entry?.args);
+        const callResult = record(entry?.result);
+        if (
+          entry?.connector !== "cdp" ||
+          entry.method !== "send" ||
+          args?.method !== "Page.captureScreenshot" ||
+          typeof callResult?.data !== "string"
+        ) return call;
+        const callFormat = record(args.params)?.format;
+        return {
+          ...entry,
+          result: {
+            ...callResult,
+            data: browserImageMetadata(
+              callResult.data,
+              screenshotMimeType(callFormat),
+            ),
+          },
+        };
+      })
+    : outer.calls;
+  const projectedDetails = {
+    ...outer,
+    result: inner
+      ? {
+          ...inner,
+          image: projectedImage,
+        }
+      : {
+          image: projectedImage,
+          note: "Screenshot recovered from the Page.captureScreenshot result.",
+        },
+    ...("calls" in outer ? { calls: projectedCalls } : {}),
+  };
+  return {
+    content: [
+      { type: "text", text: serializeOutput(projectedDetails).text },
+      ...("error" in projectedImage
+        ? []
+        : [{ type: "image" as const, data: data as string, mimeType: projectedImage.mimeType }]),
+    ],
+    details: projectedDetails,
+  };
+}
 
 // #region Extension discovery
 
@@ -107,6 +213,46 @@ const executeParameters = Type.Object({
 });
 const CODEMODE_EXECUTE_TIMEOUT_MS = 60_000;
 
+// 把模型提供的代码交给 Codemode Runtime 执行，并在外层再压一道截止。
+// 两个 Code Mode 类工具（`execute` 与 `browser_execute`）共用同一段时序，
+// 避免两套心智模型；`label` 只用于超时文案，因为模型看到的名字由候选项决定。
+function runCodemode(
+  runtime: RuntimeCodeExecutionPort,
+  label: string,
+  project: (details: unknown) => AgentToolResult<unknown> = result,
+): 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);
+    });
+    try {
+      return project(await Promise.race([
+        runtime.execute(input),
+        deadline,
+      ]));
+    } finally {
+      if (timeout !== undefined) clearTimeout(timeout);
+    }
+  };
+}
+
 /**
  * 把 Cloudflare Codemode Runtime handle 包装为 Pi 代码执行工具候选项。
  *
@@ -123,39 +269,9 @@ export function codeExecutionPiToolCandidate(
     label: "Execute JavaScript",
     description: runtime.description,
     parameters: executeParameters,
-    // 把模型提供的 JavaScript 交给 Codemode Runtime 执行。
     // Pi 工具循环在模型选择 `execute` 时调用，调用前允许 Turn 取消。
     // 必须通过 Runtime handle 而不是直接调用 executor，因为 Cloudflare Codemode 把重放、审批和执行日志放在持久化 Runtime 层。
-    async execute(_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:
-            `Code Mode execute exceeded ${CODEMODE_EXECUTE_TIMEOUT_MS} ms; ` +
-            "use existing results and state the missing evidence.",
-          retryable: false,
-          outcome: "unknown",
-        }), CODEMODE_EXECUTE_TIMEOUT_MS);
-      });
-      try {
-        return result(await Promise.race([
-          runtime.execute(input),
-          deadline,
-        ]));
-      } finally {
-        if (timeout !== undefined) clearTimeout(timeout);
-      }
-    },
+    execute: runCodemode(runtime, "Code Mode execute"),
   };
   return {
     owner: "core:codemode",
@@ -167,4 +283,36 @@ export function codeExecutionPiToolCandidate(
   };
 }
 
+/** 模型可见的浏览器工具名；属外部契约，改名是破坏性变更。 */
+export const BROWSER_EXECUTE_TOOL_NAME = "browser_execute";
+
+/**
+ * 把 Cloudflare Browser Run 的 CDP Code Mode handle 包装为 Pi 浏览器工具候选项。
+ *
+ * Tool Surface 在 Platform 提供浏览器能力时调用，模型通过 `browser_execute`
+ * 对着 `cdp` 连接器驱动一个真实无头浏览器。
+ *
+ * `browser_execute` 是模型可见的外部契约，改名属破坏性变更。
+ * 执行档位取 `low`：它能对任意外部地址发起真实浏览器导航，故不低于 Code Mode 的 `safe`。
+ */
+export function browserExecutionPiToolCandidate(
+  runtime: RuntimeCodeExecutionPort,
+): PiToolCandidate {
+  const tool: AgentTool<typeof executeParameters> = {
+    name: BROWSER_EXECUTE_TOOL_NAME,
+    label: "Drive a browser",
+    description: runtime.description,
+    parameters: executeParameters,
+    execute: runCodemode(runtime, "Browser Code Mode execute", browserResult),
+  };
+  return {
+    owner: "core:browser",
+    requiredExecutionLevel: "low",
+    outputBudget: { kind: "structure" },
+    source: "codemode",
+    summary: "Drive a real headless browser over CDP",
+    tool,
+  };
+}
+
 // #endregion

package/src/pi/tool/skill.ts

@@ -50,6 +50,80 @@ function scriptTools(
   })) as ToolSet;
 }
 
+/**
+ * `run_skill_script` 一次挂载的 Skill 资源总量上限。
+ *
+ * 上游 SkillRegistry 在启动脚本前会把 Skill 的**全部**资源读进内存
+ * （`readSkillResources`），运行器随后还要再复制几份：files map、base64 解码后的
+ * 字节、以及内联进生成源码的那份 JSON。同一个资源包因此会在 Worker isolate 里
+ * 同时存在三到四份，按四倍放大倒推 128 MB 的 DO 内存上限，安全线落在 8 MB。
+ *
+ * 这道闸只认体积不认 Skill 名字：以后再上一个大包不需要改代码。
+ */
+const SKILL_RESOURCE_BUDGET_BYTES = 8 * 1024 * 1024;
+
+type LoadedSkill = NonNullable<Awaited<ReturnType<SkillSource["load"]>>>;
+
+/**
+ * 按体积裁掉超预算的 Skill 资源，并把裁掉的事实写回 Skill 正文。
+ *
+ * @remarks
+ * `catalogSkillSource` 在每次 `load` 后调用，必须在这一层拦截：上游拿到 descriptor
+ * 后会立刻把它们全读进内存，等运行器收到请求时资源已经在堆上，再判断就晚了。
+ *
+ * 裁掉的资源必须**说出来**。它们同时会从 `activate_skill` 的资源清单里消失，若不
+ * 在正文里点名，模型只会看到一个凭空少了文件的 Skill，然后去猜。
+ *
+ * 已知缺口：没有 `size` 的 descriptor 不计入预算。R2 来源的 size 来自对象列表因而
+ * 总是存在；manifest 来源可能没有，此时这道闸对那些资源不生效。宁可放过也不误杀，
+ * 因为误杀会让本来能跑的 Skill 直接坏掉。
+ */
+function budgetSkillResources(skill: LoadedSkill): LoadedSkill {
+  const resources = skill.resources ?? [];
+  const kept: typeof resources = [];
+  const dropped: { path: string; size: number }[] = [];
+  let used = 0;
+
+  for (const resource of resources) {
+    if (typeof resource.size !== "number") {
+      kept.push(resource);
+      continue;
+    }
+    if (used + resource.size > SKILL_RESOURCE_BUDGET_BYTES) {
+      dropped.push({ path: resource.path, size: resource.size });
+      continue;
+    }
+    used += resource.size;
+    kept.push(resource);
+  }
+
+  if (dropped.length === 0) return skill;
+  const budgetMb = Math.round(SKILL_RESOURCE_BUDGET_BYTES / (1024 * 1024));
+  // materialize_skill_resource 也要把整份资源读进内存(base64 字符串 → atob 副本 →
+  // Uint8Array),放大倍数和挂载路径同量级。把一个单独就超预算的文件推荐给它,只是把
+  // OOM 从脚本挪到复制那一步 —— 那种资源这一轮就是拿不到,必须直说。
+  const portable = dropped.filter((entry) => entry.size <= SKILL_RESOURCE_BUDGET_BYTES);
+  const oversized = dropped.filter((entry) => entry.size > SKILL_RESOURCE_BUDGET_BYTES);
+  const lines = [
+    `> ${dropped.length} bundled resource(s) exceed the ${budgetMb} MB ` +
+    "script-mount budget and are NOT available to run_skill_script.",
+  ];
+  if (portable.length > 0) {
+    lines.push(
+      `> If any of these resources are needed, copy all required ones into the Workspace ` +
+      `in one execute with materialize_skill_resource: ` +
+      `${portable.map((entry) => entry.path).join(", ")}.`,
+    );
+  }
+  if (oversized.length > 0) {
+    lines.push(
+      `> These are individually larger than ${budgetMb} MB and cannot be loaded at ` +
+      `all in this session — do not try: ${oversized.map((entry) => entry.path).join(", ")}.`,
+    );
+  }
+  return { ...skill, resources: kept, body: `${skill.body}\n\n${lines.join("\n")}` };
+}
+
 function catalogSkillSource(binding: PiSkillBinding): SkillSource {
   const source = binding.source;
   return {
@@ -63,7 +137,10 @@ function catalogSkillSource(binding: PiSkillBinding): SkillSource {
       description: binding.description,
       sourceId: source.id,
     }],
-    load: (name) => source.load(name),
+    load: async (name) => {
+      const skill = await source.load(name);
+      return skill && budgetSkillResources(skill);
+    },
     ...(source.readResource
       ? { readResource: (name: string, path: string) =>
         source.readResource!(name, path) }
@@ -134,6 +211,7 @@ function materializeSkillResourceTool(
     description:
       "Copy a complete bundled Skill resource directly into the Workspace without returning its contents to the model. " +
       "Use this instead of read_skill_resource when a template, script, image, font, or other asset must become a Workspace file. " +
+      "When multiple resources are needed, copy them in one execute with a loop or Promise.all; never start one execute per resource. " +
       "The destination is created or overwritten, including parent directories.",
     inputSchema: z.object({
       name: z.enum(names).describe("Activated Skill name"),
@@ -230,6 +308,15 @@ export async function skillPiToolCandidates(
         name === "run_skill_script" || name === "materialize_skill_resource"
           ? "high"
           : "safe",
+      // activate_skill 返回的是 Skill 指令本身,是模型接下来所有动作的依据。把它外置
+      // 成文件,模型手里就只剩一个路径,必须再取一次才能知道该做什么 —— 而典型
+      // SKILL.md 正好落在会触发外置的区间。指令必须当场到手。
+      ...(name === "activate_skill"
+        ? { outputBudget: { kind: "structure" as const } }
+        : {}),
+      ...(name === "materialize_skill_resource"
+        ? { codeExecutionOnly: true as const }
+        : {}),
       tool: adapted,
     };
   });