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

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

@@ -96,7 +96,7 @@ function candidate<T extends TSchema>(
   options: Partial<
     Pick<
       PiToolCandidate,
-      "alwaysRequiresApproval" | "owner" | "requiredExecutionLevel" | "summary"
+      "alwaysRequiresApproval" | "direct" | "owner" | "requiredExecutionLevel" | "summary"
     >
   > = {},
 ): PiToolCandidate {
@@ -108,6 +108,7 @@ function candidate<T extends TSchema>(
     ...(options.alwaysRequiresApproval
       ? { alwaysRequiresApproval: true }
       : {}),
+    ...(options.direct ? { direct: true } : {}),
     ...(options.summary ? { summary: options.summary } : {}),
   };
 }
@@ -137,6 +138,7 @@ export function schedulePiToolCandidates(
       },
       {
         alwaysRequiresApproval: true,
+        direct: true,
         summary: "Create a scheduled task",
       },
     ),

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

package/src/pi/tool/workspace-sandbox.ts

@@ -64,14 +64,137 @@ const workspaceReadParameters = Type.Object({
     maxLength: 4_096,
     description: "Absolute Workspace path",
   }),
-  offset: Type.Optional(Type.Integer({ minimum: 1 })),
-  limit: Type.Optional(Type.Integer({ minimum: 1 })),
+  offset: Type.Optional(Type.Integer({
+    minimum: 1,
+    description: "1-indexed line to start from; pass the nextOffset of the previous page",
+  })),
+  limit: Type.Optional(Type.Integer({
+    minimum: 1,
+    description: "Maximum lines to return; a page is capped by size regardless",
+  })),
 });
 const workspaceEditParameters = Type.Object({
   path: Type.String({ minLength: 1, maxLength: 4_096 }),
   old_string: Type.String(),
   new_string: Type.String(),
 });
+
+/**
+ * 单页 read 返回的字符上限。
+ *
+ * 上游 think 的 read 只卡行数（2000）和行宽（2000 字符），二者相乘意味着单次调用
+ * 理论上能返回 4 MB。这里补上缺失的总量闸，让一页的大小可预测。
+ *
+ * MUST ≤ `budget/gate.ts` 的 `STORAGE_LEAF_MAX_CHARS`，否则持久记录会比模型当轮
+ * 看到的内容还少；`gate.test.ts` 有断言守着这条关系。
+ */
+export const READ_PAGE_MAX_CHARS = 64 * 1024;
+
+/** think 给每一行加的 `${lineNo}\t` 前缀。 */
+const NUMBERED_LINE = /^(\d+)\t/;
+
+/** 页脚占用的字符预留量；页脚和正文同属一个字符串叶子，必须一起受预算约束。 */
+const MARKER_RESERVE_CHARS = 256;
+
+interface ReadPage {
+  readonly content?: unknown;
+  readonly totalLines?: unknown;
+  readonly fromLine?: unknown;
+}
+
+/**
+ * 把一次 read 收敛成一页，并明确给出下一页的位置。
+ *
+ * @remarks
+ * read 的包装层在拿到上游结果后调用；图片、PDF 和二进制结果原样透传，因为它们
+ * 没有行的概念。
+ *
+ * 行号从内容里回读而不是复用上游的 `toLine`：上游那个字段是按**请求区间**算的，
+ * 一旦它自己触发 2000 行截断就会偏大，照抄会让 `nextOffset` 跳过没读到的行。
+ *
+ * 返回值同时重建模型可见文本和 details，二者必须来自同一份分页结果，否则模型读到
+ * 的内容会比 details 记录的多。
+ */
+function pageReadResult(
+  output: AgentToolResult<unknown>,
+): AgentToolResult<unknown> {
+  const details = output.details;
+  if (details === null || typeof details !== "object") return output;
+  const page = details as ReadPage;
+  if (typeof page.content !== "string") return output;
+
+  const totalLines = typeof page.totalLines === "number"
+    ? page.totalLines
+    : undefined;
+  const rows = page.content.split("\n").filter((row) => NUMBERED_LINE.test(row));
+  if (rows.length === 0) {
+    // offset 越过文件末尾时上游返回空内容。空白结果没有任何可操作信息，而模型现在
+    // 是被要求自己推进 offset 的，不说清楚它只会换个数再试一次。
+    const text = `[no lines at that offset` +
+      `${totalLines === undefined ? "" : `; the file has ${totalLines} lines`}]`;
+    return {
+      ...output,
+      content: [{ type: "text", text }],
+      details: { ...details, eof: true, ...(totalLines === undefined ? {} : { totalLines }) },
+    };
+  }
+
+  // 页脚也要算进预算：它和正文一起构成模型看到的那个字符串叶子，漏算就会正好顶穿
+  // STORAGE_LEAF_MAX_CHARS，让持久化再从中间挖掉几十个字符。
+  const budget = READ_PAGE_MAX_CHARS - MARKER_RESERVE_CHARS;
+  let used = 0;
+  let kept = 0;
+  for (const row of rows) {
+    const next = used + row.length + (kept === 0 ? 0 : 1);
+    // 至少留一行,否则单行超限的文件会返回空页,模型无从推进。
+    if (kept > 0 && next > budget) break;
+    used = next;
+    kept += 1;
+  }
+
+  const lastRow = rows[kept - 1] as string;
+  const toLine = Number(NUMBERED_LINE.exec(lastRow)?.[1]);
+  const eof = totalLines === undefined
+    ? kept === rows.length
+    : toLine >= totalLines;
+  // 上游按 2000 字符截断超长行并就地打标。JSON 溢出产物这类“整块内容挤在一行”的
+  // 文件会命中它，此时按行分页永远追不回被砍掉的部分 —— 必须说出来，否则模型会
+  // 拿着一个 eof 以为自己读全了。
+  const lossy = rows.slice(0, kept).some((row) => row.endsWith("... (truncated)"));
+
+  const content = rows.slice(0, kept).join("\n");
+  const fromLine = typeof page.fromLine === "number"
+    ? page.fromLine
+    : Number(NUMBERED_LINE.exec(rows[0] as string)?.[1]);
+
+  // 分页信息 MUST 进 content，不能只放 details：Provider 把 Tool 结果转成 tool_result
+  // 时只带 content，details 是给应用和 UI 的（见 pi-ai 的 `convertToolResult`）。
+  // 放错地方，模型就看不见下一页在哪，只能把半个文件当成整个文件用。
+  const span = `lines ${fromLine}-${toLine} of ${totalLines ?? toLine}`;
+  const lossyNote = lossy
+    ? " Some lines were longer than 2000 chars and are cut short; " +
+      "paging cannot recover them — use grep or bash on this path instead."
+    : "";
+  const marker = fromLine === 1 && eof && !lossy
+    ? ""
+    : eof
+      ? `\n\n[${span} — end of file.${lossyNote}]`
+      : `\n\n[${span} — more remains. ` +
+        `Continue with read(path, offset: ${toLine + 1}).${lossyNote}]`;
+
+  return {
+    ...output,
+    content: [{ type: "text", text: `${content}${marker}` }],
+    details: {
+      ...details,
+      content,
+      fromLine,
+      toLine,
+      eof,
+      ...(eof ? {} : { nextOffset: toLine + 1 }),
+    },
+  };
+}
 /**
  * 把模型给的路径收敛成稳定的闸键。
  *
@@ -174,7 +297,7 @@ export function workspacePiToolCandidates(
       );
       const error = (output.details as { error?: unknown })?.error;
       if (typeof error === "string") throw new Error(error);
-      return output;
+      return pageReadResult(output);
     },
   };
 
@@ -286,7 +409,16 @@ export function workspacePiToolCandidates(
   );
 
   return [
-    ...[read, write, edit, list, find, grep, remove].map((tool) => ({
+    {
+      owner: "workspace",
+      requiredExecutionLevel: "safe" as const,
+      // read 是大输出外置协议的**出口**：溢出结果的提示语指向它。出口自己再外置，
+      // 就会变成 read → 新 artifact → read 的死循环，模型只能靠猜逃出去。
+      // 分页上限由 `pageReadResult` 自己保证，不需要外置也不会撑爆一轮。
+      outputBudget: { kind: "structure" } as const,
+      tool: read,
+    },
+    ...[write, edit, list, find, grep, remove].map((tool) => ({
       owner: "workspace",
       requiredExecutionLevel: "safe" as const,
       tool,