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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.19",
+  "version": "0.2.0-alpha.21",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/universal-agent/preparation.ts

@@ -4,7 +4,6 @@ import type {
   RunAgentToolOptions,
 } from "agents";
 import type {
-  RuntimeBrowserPort,
   RuntimeMemoryPort,
   RuntimePlatformPort,
   RuntimeSubagentPort,
@@ -15,7 +14,11 @@ import type { RuntimeDegradation } from "../../../kernel/degradation";
 import type { RuntimeMemoryProfile } from "../../../kernel/profile";
 import { AGENT_TYPES } from "../../../layers/orchestration/subagents/agent-types/registry";
 import type { RuntimeAgentConfigContext } from "../../../runtime-agent-context";
-import { createWorkspaceCodeExecutionFactory } from "../../../pi/tool/core-host";
+import {
+  createBrowserExecutionFactory,
+  createWorkspaceCodeExecutionFactory,
+  type RuntimeBrowserBinding,
+} from "../../../pi/tool/core-host";
 import {
   createCloudflareSandboxAdapter,
   type SandboxAdmission,
@@ -33,7 +36,8 @@ export type PlatformLoader = () => Promise<RuntimePlatformPort>;
 
 export interface CloudflarePlatformBindings {
   LOADER: WorkerLoader;
-  BROWSER?: RuntimeBrowserPort;
+  /** Browser Rendering 绑定（可选）：CDP Code Mode 的 `browser_execute` 由它开出浏览器会话。 */
+  BROWSER?: RuntimeBrowserBinding;
 }
 
 export interface WorkspaceRequirement {
@@ -97,7 +101,18 @@ export function createWorkspaceLoader(
 
 export function createPlatformLoader<
   Env extends Cloudflare.Env & CloudflarePlatformBindings,
->(context: RuntimeAgentConfigContext<Env>): PlatformLoader {
+>(
+  context: RuntimeAgentConfigContext<Env>,
+  options: {
+    /**
+     * 本 Session 的 Workspace preview URL（可以带短期签名 query）。
+     *
+     * 只有 Host 知道公开 origin、这个 Session 的身份和签名方式，所以只能由 Host 传进来。
+     * 调用方拿不到就别传 —— 浏览器工具会因此不声称自己能打开产物。
+     */
+    previewBaseUrl?: string;
+  } = {},
+): PlatformLoader {
   let cached: ReturnType<PlatformLoader> | undefined;
   return () => cached ??= Promise.resolve().then(() => {
     const exports = (context.ctx as unknown as {
@@ -107,7 +122,19 @@ export function createPlatformLoader<
     }).exports;
     return {
       loader: context.env.LOADER,
-      ...(context.env.BROWSER ? { browser: context.env.BROWSER } : {}),
+      // 绑定缺失时整条浏览器能力不进 Platform Port，Tool Surface 因此注册空集。
+      ...(context.env.BROWSER
+        ? {
+            browser: createBrowserExecutionFactory({
+              ctx: context.ctx,
+              loader: context.env.LOADER,
+              browser: context.env.BROWSER,
+              ...(options.previewBaseUrl
+                ? { previewBaseUrl: options.previewBaseUrl }
+                : {}),
+            }),
+          }
+        : {}),
       outbound: () => exports.HttpGateway({}),
     };
   });

package/src/db/approval.repo.ts

@@ -39,6 +39,7 @@ export interface NewApproval {
 
 export interface PendingApprovalSummary {
   executionId: string;
+  toolCallId: string;
   source: string;
   toolName: string;
   summary: string;
@@ -189,6 +190,7 @@ export class ApprovalRepository {
   listPendingActive(): PendingApprovalSummary[] {
     return this.sql<{
       execution_id: string;
+      tool_call_id: string;
       source: string;
       tool_name: string;
       summary: string;
@@ -197,7 +199,7 @@ export class ApprovalRepository {
       input_json: string;
       request_id: string;
     }>`
-      SELECT approval.execution_id, approval.source,
+      SELECT approval.execution_id, approval.tool_call_id, approval.source,
              approval.tool_name, approval.summary,
              approval.execution_level, approval.required_level,
              approval.input_json, approval.request_id
@@ -209,6 +211,7 @@ export class ApprovalRepository {
       ORDER BY approval.created_at ASC
     `.map((row) => ({
       executionId: row.execution_id,
+      toolCallId: row.tool_call_id,
       source: row.source,
       toolName: row.tool_name,
       summary: row.summary,

package/src/index.ts

@@ -135,10 +135,12 @@ export {
 export { skillPiToolCandidates } from "./pi/tool";
 export type { PiSkillBinding } from "./pi/tool";
 export {
-  browserQuickActionPiToolCandidates,
+  BROWSER_EXECUTE_TOOL_NAME,
+  browserExecutionPiToolCandidate,
   codeExecutionPiToolCandidate,
 } from "./pi/tool";
 export {
+  createBrowserExecutionFactory,
   createWorkspaceCodeExecutionFactory,
 } from "./pi/tool";
 export {

package/src/kernel/approval-lifecycle.ts

@@ -158,6 +158,7 @@ export class ApprovalLifecycle<
   list(): ApprovalReceipt[] {
     return this.options.db.approvals.listPendingActive().map((row) => ({
       executionId: row.executionId,
+      toolCallId: row.toolCallId,
       source: row.source as ApprovalReceipt["source"],
       action: row.toolName,
       summary: row.summary,

package/src/kernel/bindings.ts

@@ -2,7 +2,7 @@ import type { SkillSource } from "agents/skills";
 import type { ScheduleSpec } from "./receipts";
 import type { RuntimeActivityProjection } from "./state";
 import type { ExecutionLevel } from "../lib/execution-level";
-import type { RuntimeCodeExecutionFactory } from "../tool-registry";
+import type { ToolRegistry } from "./tool-surface";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -856,26 +856,23 @@ export interface RuntimeTurnEventsPort {
 }
 
 /**
- * 向 Runtime 浏览器工具提供 Browser Run Quick Action 调用。
+ * 向 Runtime 提供一个真实无头浏览器的 CDP Code Mode 执行能力。
  *
  * @remarks
- * Platform Plugin 在 Browser 绑定存在时生成快捷操作工具，工具在读取、提取或抓取页面时调用。
+ * Platform Plugin 在 Browser 绑定存在时准备它，Tool Surface 决定注册 `browser_execute` 时才调用 `create()`。
  *
- * 该 Port 保留 Browser Run 的通用 `action + options` 协议，具体工具仍由 `agents/browser` 辅助函数组装。
+ * 该 Port 只承载「能不能开出一个浏览器执行端口」，浏览器会话生命周期与 CDP 协议细节都留在 `agents/browser`，
+ * 避免本仓复制一份会随上游漂移的协议。旧的 Quick Action `action + options` 单方法协议已于 2026-08-13 退役：
+ * 复测确认本地绑定至今不实现 `quickAction()`，该面在本仓从未执行过。
  */
 export interface RuntimeBrowserPort {
   /**
-   * 执行一个 Browser Run Quick Action 并返回原始响应。
+   * 创建本次装配的浏览器代码执行端口。
    *
    * @remarks
-   * `agents/browser` 的快捷操作辅助函数在对应 Pi 工具执行期调用。
-   *
-   * Runtime 不复制 Browser Run 的选项联合类型，避免两份协议随上游漂移。
+   * Tool Surface 在浏览器工具确实可见时调用一次，延迟到此刻是为了让被 deny 的装配不白建连接器。
    */
-  quickAction(
-    action: string,
-    options: unknown,
-  ): Promise<Response>;
+  create(): RuntimeCodeExecutionPort;
 }
 
 // #endregion
@@ -942,7 +939,7 @@ export interface RuntimeProviderPort {
 export interface RuntimePlatformPort {
   /** Workspace Codemode 在创建 Dynamic Worker 执行器时使用的 Worker Loader。 */
   loader: WorkerLoader;
-  /** Platform Plugin 存在 Browser Run 绑定时用它生成浏览器工具。 */
+  /** Platform Plugin 存在 Browser Run 绑定时用它生成 `browser_execute`；缺失即整条浏览器 Tool 面不注册。 */
   browser?: RuntimeBrowserPort;
   /**
    * 为一次 Dynamic Worker 组装取得已限定的网络出口。
@@ -1021,6 +1018,18 @@ export interface RuntimeSkillSourceBinding {
  *
  * 它不携带业务 ID、Repository、数据库 Key、任意能力注册表或凭据配置；术语见 `../index.ts`。
  */
+/**
+ * 延迟到最终 Tool Surface 完成后再创建 Code Mode 执行能力。
+ *
+ * @remarks
+ * 定义在这里而不是 `tool-registry.ts`：它的返回类型是本文件的
+ * `RuntimeCodeExecutionPort`，而 `RuntimeBindings` 又要引用这个工厂 —— 放在
+ * tool-registry 会让两个模块互相 import。`tool-registry.ts` 继续对外导出它。
+ */
+export interface RuntimeCodeExecutionFactory {
+  create(tools: ToolRegistry): RuntimeCodeExecutionPort;
+}
+
 export interface RuntimeBindings {
   provider: RuntimeProviderPort;
   platform: RuntimePlatformPort;

package/src/kernel/receipts.ts

@@ -24,6 +24,8 @@ export const APPROVAL_DECISIONS = [
  */
 export interface ApprovalReceipt {
   executionId: string;
+  /** Tool call that owns this approval; absent for non-tool approval sources. */
+  toolCallId?: string;
   source: "action" | "codemode" | "temporary-agent";
   action: string;
   summary: string;

package/src/kernel/tool-surface.ts

@@ -0,0 +1,41 @@
+import type { ExecutionLevel } from "../lib/execution-level";
+import type { PiToolCandidate } from "../pi/tool/compiler";
+
+/**
+ * Tool Surface 的形状类型。
+ *
+ * @remarks
+ * `kernel/bindings.ts` 和 `tool-registry.ts` 都要用它们，所以它们不能住在其中任何
+ * 一边：`RuntimeBindings.codeExecution` 的工厂签名需要 `ToolRegistry`，而
+ * `tool-registry.ts` 又需要 bindings 里的各个 Port —— 两边互相 import 就形成了
+ * depcruise 的 no-circular 违规（`bindings → tool-registry → bindings`）。
+ *
+ * 这里只放形状，不放行为：注册表的合并、筛选和构造仍然留在 `tool-registry.ts`。
+ *
+ * 术语见 `../index.ts`。
+ */
+
+/** 模型调用 Tool 时传给 `execute` 的上下文。 */
+export interface ToolContext {
+  readonly toolCallId: string;
+  readonly signal: AbortSignal;
+}
+
+/** Definition 作者声明的一个 Tool。 */
+export interface ToolSpec extends Partial<
+  Omit<PiToolCandidate, "tool" | "requiredExecutionLevel">
+> {
+  readonly label: string;
+  readonly description: string;
+  readonly parameters: unknown;
+  readonly requiredExecutionLevel: ExecutionLevel;
+  /** Require a fresh human decision for every call, regardless of execution level. */
+  readonly alwaysRequiresApproval?: boolean;
+  readonly execute: (
+    input: unknown,
+    ctx: ToolContext,
+  ) => Promise<unknown>;
+}
+
+/** 一次装配声明的全部 Tool，键即模型可见的工具名。 */
+export type ToolRegistry = Record<string, ToolSpec>;

package/src/layers/context/budget/gate.ts

@@ -15,14 +15,48 @@ import {
  * must be given an explicit protected path here.
  */
 
-/** Maximum string leaf retained in durable tool output. */
-const STORAGE_LEAF_MAX_CHARS = 32 * 1024;
+/**
+ * 预算常量的排序不变量（改任何一个都必须同时复核其余三个）：
+ *
+ *     MODEL_LEAF_MAX_CHARS < MODEL_REPLAY_THRESHOLD < SPILL_THRESHOLD
+ *                                                        ≤ STORAGE_LEAF_MAX_CHARS
+ *            4 KB                   16 KB                32 KB      64 KB
+ *
+ * 这四个数回答四个不同问题。曾经其中两个共用一个常量，结果“放宽外置”和“收紧
+ * 历史”这两个互相冲突的诉求被绑在同一个旋钮上，只能二选一。
+ */
 
-/** Serialized outputs above this threshold get a narrower model view. */
-const MODEL_VIEW_THRESHOLD = 8 * 1024;
+/**
+ * 持久化单个字符串叶子的上限。
+ *
+ * MUST ≥ 单页 read 的上限（见 `workspace-sandbox.ts` 的 `READ_PAGE_MAX_CHARS`），
+ * 否则持久记录会比模型当轮看到的内容还少，会话恢复后出现凭空缺页。
+ */
+export const STORAGE_LEAF_MAX_CHARS = 64 * 1024;
 
-/** Maximum string leaf exposed in a structure-preserving model view. */
-const MODEL_LEAF_MAX_CHARS = 500;
+/**
+ * 一次新的 Tool 结果多大才值得外置成 Workspace 文件。
+ *
+ * 只影响当轮新产生的结果，不影响历史重放。
+ */
+export const SPILL_THRESHOLD = 32 * 1024;
+
+/**
+ * 历史里一条旧 Tool 结果重放多少。
+ *
+ * 这条最紧，因为它对每个 Turn 的**全部**历史消息生效（见
+ * `pi/runtime-adapter/execution.ts` 的 `projectToolResultsForModel`）：
+ * 放宽 1 KB 就是 N 条历史 × 1 KB。
+ */
+export const MODEL_REPLAY_THRESHOLD = 16 * 1024;
+
+/**
+ * 重放时单个字符串叶子的上限。
+ *
+ * 曾经是 500，小到让 Code Mode 这类返回长字符串的结果在**第二轮**就塌成碎片，
+ * 模型只能反复换姿势（`Object.values()`、`slice()`）去捞已经不存在的内容。
+ */
+export const MODEL_LEAF_MAX_CHARS = 4 * 1024;
 
 const ELISION_RESERVE = 40;
 const PREVIEW_CHARS = 600;
@@ -118,7 +152,7 @@ export async function spillDurableToolOutput(
   },
 ): Promise<ArtifactRef | null> {
   const { text, ext } = serializeOutput(value);
-  if (text.length <= MODEL_VIEW_THRESHOLD || !options.workspace) return null;
+  if (text.length <= SPILL_THRESHOLD || !options.workspace) return null;
   try {
     const hash = await sha256Hex(text);
     const path = `${DEFAULT_SPILL_DIR}/${hash.slice(0, 24)}.${ext}`;
@@ -133,9 +167,19 @@ export async function spillDurableToolOutput(
       bytes: new TextEncoder().encode(text).byteLength,
       hash: hash.slice(0, 16),
       preview: text.slice(0, PREVIEW_CHARS),
+      // 出口指令必须是可执行的：只说“去 read 这个路径”会诱导模型整读，而整读一个
+      // 刚刚因为过大被外置的文件毫无意义。这里明确要求分页，并告知 read 会返回
+      // nextOffset / eof 以便继续。
+      // 出口指令必须是可执行的，而且必须只承诺模型真的拿得到的东西：Provider 只把
+      // Tool 结果的 content 发给模型，所以这里不能引用只存在于 details 的字段。
+      // 溢出产物是 JSON，一个大字符串叶子会整块挤在一行上，而按行分页追不回被行宽
+      // 截断的内容 —— 那种情况要走 grep / bash，不能让模型以为 read 一定够用。
       note:
         "Output was large and has been saved to the Workspace file above. " +
-        "Use the read tool with that path to retrieve the full content when needed.",
+        "Read it in pages with read(path, offset, limit) — do not read it whole; " +
+        "each page ends with a footer telling you the line range and the next offset. " +
+        "This file is JSON, so a single large value can sit on one very long line: " +
+        "if a page reports that lines were cut short, use grep or bash on the path instead.",
     };
   } catch {
     return null;
@@ -145,7 +189,9 @@ export async function spillDurableToolOutput(
 // Bounds leaves first, then removes oldest array entries until the view fits.
 function structureView(output: unknown): unknown {
   const capped = truncateStringLeaves(output, MODEL_LEAF_MAX_CHARS);
-  if (serializeOutput(capped).text.length <= MODEL_VIEW_THRESHOLD) return capped;
+  if (serializeOutput(capped).text.length <= MODEL_REPLAY_THRESHOLD) {
+    return capped;
+  }
   if (typeof capped !== "object" || capped === null) return capped;
 
   const record = { ...(capped as Record<string, unknown>) };
@@ -159,7 +205,7 @@ function structureView(output: unknown): unknown {
   while (
     items.length > 1 &&
     serializeOutput({ ...record, [arrayKey]: items }).text.length >
-      MODEL_VIEW_THRESHOLD
+      MODEL_REPLAY_THRESHOLD
   ) {
     items.shift();
     dropped += 1;
@@ -178,7 +224,7 @@ function structureView(output: unknown): unknown {
 /** Creates a non-destructive, smaller Tool-result projection for the model. */
 export function projectToolOutputForModel(output: unknown): unknown {
   try {
-    return serializeOutput(output).text.length <= MODEL_VIEW_THRESHOLD
+    return serializeOutput(output).text.length <= MODEL_REPLAY_THRESHOLD
       ? output
       : structureView(output);
   } catch {

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

@@ -21,19 +21,7 @@ function attachmentText(
   part: Extract<UIMessage["parts"][number], { type: "file" }>,
 ): string {
   const name = part.filename?.trim() || "attachment";
-  let ref: string | null = null;
-  try {
-    const path = part.url.startsWith("/")
-      ? new URL(part.url, "https://attachment.invalid").pathname
-      : new URL(part.url).pathname;
-    const leaf = path.split("/").filter(Boolean).at(-1);
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(leaf ?? "")) {
-      ref = leaf!;
-    }
-  } catch {
-    // Preserve the existing canonical form for non-platform file URLs.
-  }
-  return `[Attachment: ${name} (${part.mediaType}) ${ref ? `ref=${ref}` : part.url}]`;
+  return `[Attachment: ${name} (${part.mediaType}) path=${part.url}]`;
 }
 
 function userContent(

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

@@ -70,6 +70,10 @@ const WRAP_UP_MESSAGE = "You have reached this run's model-turn budget. Stop " +
   "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;
@@ -159,12 +163,37 @@ interface PiTurnAdapterOptions {
   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,
@@ -252,6 +281,7 @@ class PiTurnAdapter {
     signal?.throwIfAborted();
     const canonicalMessages = await this.opts.canonicalMessages();
     const tools = this.compile(opts.tools);
+    const selfBounded = selfBoundedToolNames(opts.tools);
     // `modelTurns` 是跨执行片的累计数，`sliceTurns` 只数本片 —— 前者管任务预算，
     // 后者管 CPU 预算，两个边界互不替代。
     let modelTurns = this.opts.modelTurnsConsumed;
@@ -274,7 +304,7 @@ 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[];
       },
@@ -289,9 +319,13 @@ class PiTurnAdapter {
           wrapUpTurns += 1;
           return undefined;
         }
-        if (modelTurns < MAX_MODEL_TURNS_PER_SUBMISSION - 1) return undefined;
-        // 预算见底：清空工具表并注入收尾指令，逼出一条真正的终止助手消息。
-        // 直接判失败的话用户拿不到任何交代；继续让步则等于没有预算。
+        const toolFailureLimitReached = this.governance.wrapUpRequested();
+        if (
+          !toolFailureLimitReached &&
+          modelTurns < MAX_MODEL_TURNS_PER_SUBMISSION - 1
+        ) return undefined;
+        // 预算见底或工具熔断：清空工具表并注入收尾指令，逼出一条真正的
+        // 终止助手消息。直接判失败的话用户拿不到任何交代。
         // 这条指令不进 newMessages，因此不会写进 transcript —— 它是控制指令，不是历史。
         wrappingUp = true;
         return {
@@ -302,7 +336,12 @@ class PiTurnAdapter {
               ...context.messages,
               {
                 role: "user" as const,
-                content: [{ type: "text" as const, text: WRAP_UP_MESSAGE }],
+                content: [{
+                  type: "text" as const,
+                  text: toolFailureLimitReached
+                    ? TOOL_FAILURE_WRAP_UP_MESSAGE
+                    : WRAP_UP_MESSAGE,
+                }],
                 timestamp: Date.now(),
               },
             ],

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