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

package/package.json

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

package/src/adapter/cloudflare/sandbox/adapter.ts

@@ -412,6 +412,20 @@ function timedOut(error: unknown): boolean {
   return message.includes("timeout") || message.includes("timed out");
 }
 
+function processAlreadyStopped(error: unknown): boolean {
+  if (
+    typeof error !== "object" ||
+    error === null ||
+    !("code" in error)
+  ) {
+    return false;
+  }
+  return (
+    error.code === "COMMAND_NOT_FOUND" ||
+    error.code === "PROCESS_NOT_FOUND"
+  );
+}
+
 function mappedError(error: unknown): SandboxPortError {
   if (error instanceof SandboxPortError) return error;
   const message = errorMessage(error).toLowerCase();
@@ -664,11 +678,11 @@ export class CloudflareSandboxAdapter implements RuntimeSandboxPort {
           id,
           PROCESS_SESSION_ID,
         );
-        if (!process) {
-          throw new SandboxPortError(
-            "not_found",
-            "background process was not found",
-          );
+        if (
+          !process ||
+          (process.status !== "starting" && process.status !== "running")
+        ) {
+          return { stopped: false };
         }
         if (this.processExpired(id)) {
           await this.client
@@ -683,6 +697,7 @@ export class CloudflareSandboxAdapter implements RuntimeSandboxPort {
         this.emit("sandbox.process.stopped", { success: true });
         return { stopped: true };
       } catch (error) {
+        if (processAlreadyStopped(error)) return { stopped: false };
         throw mappedError(error);
       }
     });

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

@@ -46,6 +46,16 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
   if (!submissionColumns.has("admission_retryable")) {
     sql`ALTER TABLE pi_submissions ADD COLUMN admission_retryable INTEGER`;
   }
+  // 跨执行片累计的模型回合数。让步把一个 Turn 切成多片后，每片的回合计数都从 0 开始，
+  // 只有把总数落到持久层，全局预算才拦得住「一直让步、永不收敛」的工具循环。
+  if (!submissionColumns.has("model_turns")) {
+    sql`ALTER TABLE pi_submissions
+        ADD COLUMN model_turns INTEGER NOT NULL DEFAULT 0`;
+  }
+  // 当前让步片的标识。用来丢弃重复到期的续跑 alarm，并让看门狗判断这一轮有没有推进。
+  if (!submissionColumns.has("continuation_id")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN continuation_id TEXT`;
+  }
   sql`CREATE UNIQUE INDEX IF NOT EXISTS pi_submissions_run_id
       ON pi_submissions(run_id) WHERE run_id IS NOT NULL`;
   if (!submissionColumns.has("queued_input_json")) {

package/src/db/submission.repo.ts

@@ -53,6 +53,10 @@ export interface StoredSubmission {
   rateVersion: number | null;
   slotIdentity: string | null;
   retryable?: boolean;
+  /** 跨执行片累计的模型回合数，全局回合预算的唯一事实来源。 */
+  modelTurns: number;
+  /** 当前让步执行片的标识；没有未完成让步时为 null。 */
+  continuationId: string | null;
 }
 
 export interface NewSubmission {
@@ -97,6 +101,8 @@ type SubmissionRow = {
   rate_version: number | null;
   slot_identity: string | null;
   admission_retryable: number | null;
+  model_turns: number;
+  continuation_id: string | null;
 };
 
 // #endregion
@@ -131,6 +137,8 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     retryable: row.admission_retryable === null
       ? undefined
       : row.admission_retryable === 1,
+    modelTurns: row.model_turns ?? 0,
+    continuationId: row.continuation_id,
   };
 }
 
@@ -153,7 +161,8 @@ export class SubmissionRepository {
              queued_input_json, queued_ui_message_json, user_message_id,
              regenerate_message_id, recovery_error_count, recovery_reason,
              run_id, account_id, rate_version, slot_identity,
-             admission_retryable
+             admission_retryable,
+             model_turns, continuation_id
       FROM pi_submissions
       WHERE submission_id = ${id}
     `[0];
@@ -413,6 +422,40 @@ export class SubmissionRepository {
     `[0]?.recovery_error_count ?? 0;
   }
 
+  /**
+   * 记录一个让步执行片的累计模型回合数和续跑标识。
+   *
+   * @remarks
+   * Runtime 在一片主动让出后、排出续跑调度之前调用。
+   *
+   * 两个值必须一起写：全局回合预算靠 `model_turns` 拦住不收敛的工具循环，
+   * 续跑去重和看门狗靠 `continuation_id` 判断这一轮到底有没有推进。
+   * 只写非终态记录，避免一次迟到的写入复活已经结束的 Submission。
+   */
+  recordYieldedSlice(
+    id: string,
+    modelTurns: number,
+    continuationId: string,
+  ): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET model_turns = ${modelTurns},
+          continuation_id = ${continuationId}
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+    `;
+  }
+
+  /** 记录累计模型回合数，不改动续跑标识。终态提交前的最后一次结算用它。 */
+  recordModelTurns(id: string, modelTurns: number): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET model_turns = ${modelTurns}
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+    `;
+  }
+
   clearRecoveryReason(id: string): void {
     this.sql`
       UPDATE pi_submissions

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/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/recoverable-chat-agent.ts

@@ -353,10 +353,41 @@ export abstract class RecoverableChatAgent<
    * 清理延后执行，为断线重连的客户端保留终态流片段。
    */
   protected completeRecoverableStream(streamId: string): void {
-    const completedRequestId = this.resumableStream.activeRequestId;
-    this.resumableStream.complete(streamId);
+    this.closeRecoverableStream(streamId, (id) =>
+      this.resumableStream.complete(id),
+    );
+  }
+
+  /**
+   * 密封一个只跑完当前执行切片的可续传流，把这一轮交给下一个切片继续。
+   *
+   * @remarks
+   * 子类在一次计划让步（Turn 未结束、但本次执行已让出）后调用；调用方随后必须
+   * 排出续跑，且**不能**同时发 `done` 终态帧 —— 这一轮还没有权威结果。
+   *
+   * 与 `completeRecoverableStream` 的差别只在语义：那个断言「业务终态已提交」，
+   * 这个断言「本切片不再产出，另一个切片接手」。底层动作相同是有意的 ——
+   * 让步不密封的话，`ResumableStream.start()` 会直接覆盖 `activeStreamId`，
+   * 旧行永远停在 `streaming`，缓冲区要等 abandoned 保留期才回收。
+   */
+  protected sealRecoverableStreamSlice(streamId: string): void {
+    this.closeRecoverableStream(streamId, (id) =>
+      this.resumableStream.complete(id),
+    );
+  }
+
+  // 作用：收口一条可续传流的终止写入与内存续传状态。
+  // 调用：完成、失败和切片密封三条路径共用。
+  // 原因：清理顺序（先读 activeRequestId、再写状态、最后比对续传归属）三处必须一致，
+  // 分开维护过一次就会漏掉 pendingResumeConnections 或 continuation 归属其中之一。
+  private closeRecoverableStream(
+    streamId: string,
+    close: (streamId: string) => void,
+  ): void {
+    const closedRequestId = this.resumableStream.activeRequestId;
+    close(streamId);
     this.pendingResumeConnections.clear();
-    if (completedRequestId === this.continuation.activeRequestId) {
+    if (closedRequestId === this.continuation.activeRequestId) {
       this.continuation.activeRequestId = null;
       this.continuation.activeConnectionId = null;
     }
@@ -372,14 +403,9 @@ export abstract class RecoverableChatAgent<
    * 流错误标志与业务失败分开，因为续传协议和提交生命周期的责任不同。
    */
   protected failRecoverableStream(streamId: string): void {
-    const erroredRequestId = this.resumableStream.activeRequestId;
-    this.resumableStream.markError(streamId);
-    this.pendingResumeConnections.clear();
-    if (erroredRequestId === this.continuation.activeRequestId) {
-      this.continuation.activeRequestId = null;
-      this.continuation.activeConnectionId = null;
-    }
-    void this.ensureStreamCleanupScheduled();
+    this.closeRecoverableStream(streamId, (id) =>
+      this.resumableStream.markError(id),
+    );
   }
 
   /**

package/src/kernel/submission-lifecycle.ts

@@ -131,6 +131,25 @@ export class SubmissionQueueFullError extends Error {
  */
 export type SubmissionOutcome = "succeeded" | "failed" | "aborted";
 
+/**
+ * 说明一次执行是怎么被启动的。
+ *
+ * @remarks
+ * `SubmissionLifecycle` 把它交给 `execute`，Runtime 据此选择执行前置动作。
+ *
+ * `recovery` 和 `continuation` 必须分开：前者的内存状态已经丢了、transcript 可能停在半路，
+ * 要走完整的里程碑重放；后者是本轮主动让出执行片，transcript 完好、什么都不用重建。
+ * 合成一个布尔量意味着最常跑的那条路径每次都去趟最脆弱的恢复代码，
+ * 而且重放成本会随让步次数增长。
+ */
+export type SubmissionExecutionMode =
+  /** 首次执行一条新接收的提交。 */
+  | "fresh"
+  /** 中断后按持久事实重建并继续。 */
+  | "recovery"
+  /** 上一执行片主动让出后，接着跑同一条提交。 */
+  | "continuation";
+
 /**
  * 描述接收一次提交所需的标识和延迟创建步骤。
  *
@@ -183,10 +202,13 @@ interface SubmissionLifecycleOptions<
   // 调用：`admit` 只在新提交成功写入后调用。
   // 原因：重复提交只加入旧工作，不应清除现有终态。
   clearTerminal(): Promise<void>;
-  // 作用：执行或恢复一条已持久化的提交。
+  // 作用：执行、恢复或续跑一条已持久化的提交。
   // 调用：`start` 在 `TurnQueue` 轮到该提交时调用。
-  // 原因：生命周期只管调度，具体 Pi Turn 执行仍由 Runtime 负责。
-  execute(submissionId: string, recovery: boolean): Promise<TSubmission>;
+  // 原因：生命周期只管调度，具体 Pi Turn 执行仍由 Runtime 负责；模式决定 Runtime 的前置动作。
+  execute(
+    submissionId: string,
+    mode: SubmissionExecutionMode,
+  ): Promise<TSubmission>;
   // 作用：记录可恢复的取消意图。
   // 调用：`cancel` 在同一存储事务内与取消原因一起写入。
   // 原因：持久化里程碑可以让恢复路径看到已经发生的取消。
@@ -300,22 +322,30 @@ export class SubmissionLifecycle<
    * 它复用 `start` 的实例内去重和串行队列，避免重复唤醒产生两个执行器。
    */
   recover(submissionId: string): Promise<TSubmission> {
-    return this.start(submissionId, true);
+    return this.start(submissionId, "recovery");
   }
 
-  /** 等当前切片退出后恢复同一条非终态 Submission，避免 planned wake 被实例内去重吞掉。 */
-  async recoverAfterCurrent(submissionId: string): Promise<TSubmission> {
+  /**
+   * 等当前执行片退出后，接着跑同一条非终态 Submission。
+   *
+   * @remarks
+   * `_piPlannedContinuation` 在计划让步的唤醒里调用。先 await 当前执行片，
+   * 是为了避开 `executions` 的实例内去重 —— 否则这次唤醒会被合流到正在退场的那一片上。
+   *
+   * 走 `continuation` 而不是 `recovery`：这一轮什么都没丢，不需要重放里程碑。
+   */
+  async continueAfterCurrent(submissionId: string): Promise<TSubmission> {
     const current = this.executions.get(submissionId);
     if (current) {
       const outcome = await current;
       if (isTerminalSubmissionStatus(outcome.status)) return outcome;
     }
-    return this.start(submissionId, true);
+    return this.start(submissionId, "continuation");
   }
 
   recoverHead(): Promise<TSubmission | null> {
     const running = this.options.store.findRunning();
-    if (running) return this.start(running.submissionId, true);
+    if (running) return this.start(running.submissionId, "recovery");
     const pending = this.options.store.findNextPending();
     return pending
       ? this.start(pending.submissionId)
@@ -410,14 +440,14 @@ export class SubmissionLifecycle<
   // 原因：`TurnQueue` 防止不同 Pi Turn 重叠，`executions` 则防止同一标识重复入队。
   private start(
     submissionId: string,
-    recovery = false,
+    mode: SubmissionExecutionMode = "fresh",
   ): Promise<TSubmission> {
     const existing = this.executions.get(submissionId);
     if (existing) return existing;
     let shouldPump = false;
     const started = this.queue
       .enqueue(submissionId, () =>
-        this.options.execute(submissionId, recovery),
+        this.options.execute(submissionId, mode),
       )
       .then((outcome) => {
         // TODO(待确认): 当前类没有调用 `queue.reset()`，按现有调用链不会产生 `stale` 结果。
@@ -583,6 +613,19 @@ export class SubmissionLifecycle<
     await this.executions.get(submissionId)?.catch(() => undefined);
   }
 
+  /**
+   * 判断某条提交此刻是否有执行器在跑。
+   *
+   * @remarks
+   * 续跑看门狗在决定要不要接手前调用。
+   *
+   * 只反映本实例的内存状态 —— 这正是它要问的：跨实例的丢失由持久事实兜底，
+   * 而「有执行器在跑」只有本实例知道，误判会派发出重复的执行片。
+   */
+  isActive(submissionId: string): boolean {
+    return this.activeBySubmission.has(submissionId);
+  }
+
   /**
    * 返回当前唯一活动的执行器。
    *

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 {