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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.17",
+  "version": "0.2.0-alpha.19",
   "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/subagent/runner.ts

@@ -41,6 +41,10 @@ function textOf(message: AssistantMessage): string {
     .trim();
 }
 
+function structuredText(text: string): string {
+  return /^```(?:json)?\s*\n([\s\S]*?)\n```$/i.exec(text)?.[1] ?? text;
+}
+
 function toolErrorText(result: unknown): string {
   if (
     typeof result === "object" &&
@@ -161,7 +165,7 @@ export async function runCloudflareSubAgent(
 
   let output: unknown;
   try {
-    output = JSON.parse(text);
+    output = JSON.parse(structuredText(text));
   } catch {
     throw new Error("SubAgent output is not valid JSON");
   }

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/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/pi/message/projection.ts

@@ -15,6 +15,8 @@ import { USER_STOP_REASON } from "../../kernel/receipts";
 
 const MAX_OUTPUT_BYTES = 256 * 1024;
 const MAX_OUTPUT_PREVIEW = 16 * 1024;
+const PROVIDER_CREDIT_ERROR =
+  "The AI service is temporarily unavailable. Please try again later.";
 
 export interface PiToolApprovalView {
   readonly id: string;
@@ -101,6 +103,16 @@ function errorText(result: unknown): string {
   }
 }
 
+/** Keep provider account details out of browser-facing error messages. */
+export function publicAssistantError(message?: string): string | undefined {
+  if (!message) return undefined;
+  return /"limit_source"\s*:\s*"openrouter_credits"/.test(message) ||
+      (message.includes("Insufficient credits") &&
+        message.includes("openrouter.ai/settings/credits"))
+    ? PROVIDER_CREDIT_ERROR
+    : message;
+}
+
 function toolCallAt(
   update: AssistantMessageEvent,
 ): Partial<ToolCall> | undefined {
@@ -318,7 +330,12 @@ export class PiChunkEncoder {
       case "toolcall_end":
         return this.encodeToolInput(update);
       case "error":
-        return [{ type: "error", errorText: update.error.errorMessage ?? update.reason }];
+        return [{
+          type: "error",
+          errorText: publicAssistantError(
+            update.error.errorMessage ?? update.reason,
+          ) ?? "SpringBrand turn failed",
+        }];
       default:
         return [];
     }
@@ -421,6 +438,7 @@ export class PiChunkEncoder {
       return chunks;
     }
     this.finished = true;
+    const publicError = publicAssistantError(message.errorMessage);
     if (this.startedAt !== undefined) {
       const turnStatus = message.stopReason === "aborted"
         ? "aborted"
@@ -434,10 +452,10 @@ export class PiChunkEncoder {
           completedAt: message.timestamp,
           turnDurationMs: Math.max(0, message.timestamp - this.startedAt),
           turnStatus,
-          ...(message.errorMessage &&
+          ...(publicError &&
               (message.stopReason !== "aborted" ||
                 message.errorMessage !== USER_STOP_REASON)
-            ? { error: message.errorMessage }
+            ? { error: publicError }
             : {}),
         },
       });
@@ -449,7 +467,7 @@ export class PiChunkEncoder {
     if (message.stopReason === "error") {
       chunks.push({
         type: "error",
-        errorText: message.errorMessage ?? "SpringBrand turn failed",
+        errorText: publicError ?? "SpringBrand turn failed",
       });
       return chunks;
     }

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

@@ -53,8 +53,27 @@ import { toolRegistryFromPiCandidates } from "../../tool-registry";
 
 // #region Single-run Pi bridge
 
+// 一片执行最多跑多少个模型回合。这是 CPU 预算边界，不是任务边界：DO 的
+// CPU 上限按 invocation 计，一条长回合跑在一次 invocation 里会把预算吃满并被驱逐，
+// 让步换来的是一次全新 invocation 和全新预算。
 const MAX_MODEL_TURNS_PER_SLICE = 30;
 
+// 一条 Submission 跨所有执行片最多跑多少个模型回合。这是任务边界:
+// 没有它,一个不收敛的工具循环会无限让步、无限唤醒、无限烧 token。
+export const MAX_MODEL_TURNS_PER_SUBMISSION = 300;
+
+// 预算耗尽时注入的收尾指令。跟着它一起把工具表清空,模型只能出文本,
+// 于是这一轮以一条正常的终止助手消息结束 —— 而不是硬判失败或继续让步。
+// 走 user 角色而非 assistant:多个 provider 拒绝以模型回合结尾的请求。
+const WRAP_UP_MESSAGE = "You have reached this run's model-turn budget. Stop " +
+  "calling tools now. Reply with a final message that states what you " +
+  "completed, what you did not finish, and the exact next step you would " +
+  "take. Do not start new work.";
+
+// 收尾开始后最多再放行几个模型回合。工具已经清空，正常一轮就结束了；
+// 留出余量是给 steering 消息，但不能因此把本片的 CPU 上限一起取消。
+const MAX_WRAP_UP_TURNS = 2;
+
 export class RetryableModelError extends Error {}
 
 function normalizePlanToolCalls(message: AgentMessage): void {
@@ -136,6 +155,8 @@ interface PiTurnAdapterOptions {
   // 直接复用 Pi 的回调类型可避免这里维护另一套上下文转换约定。
   readonly transformContext: NonNullable<AgentOptions["transformContext"]>;
   readonly workspace?: SpillWorkspace;
+  // 之前的执行片已经用掉的模型回合数。首次执行传 0。
+  readonly modelTurnsConsumed: number;
 }
 
 function projectToolResultsForModel(
@@ -231,8 +252,13 @@ class PiTurnAdapter {
     signal?.throwIfAborted();
     const canonicalMessages = await this.opts.canonicalMessages();
     const tools = this.compile(opts.tools);
-    let modelTurns = 0;
+    // `modelTurns` 是跨执行片的累计数，`sliceTurns` 只数本片 —— 前者管任务预算，
+    // 后者管 CPU 预算，两个边界互不替代。
+    let modelTurns = this.opts.modelTurnsConsumed;
+    let sliceTurns = 0;
     let reachedModelTurnLimit = false;
+    let wrappingUp = false;
+    let wrapUpTurns = 0;
     const pi = new PiCore({
       convertToLlm,
       streamFn: withProviderRetry(
@@ -253,9 +279,45 @@ class PiTurnAdapter {
         ) as AgentMessage[];
       },
       afterToolCall: this.governance.afterToolCall,
+      // Pi 在每个 turn_end 之后先调 prepareNextTurn、再调 shouldStopAfterTurn，
+      // 所以回合计数记在这里，停止判据只读不写。
+      // 用 `WithContext` 变体：只有它拿得到当前上下文，也就拿得到工具表和消息。
+      prepareNextTurnWithContext: ({ context }) => {
+        modelTurns += 1;
+        sliceTurns += 1;
+        if (wrappingUp) {
+          wrapUpTurns += 1;
+          return undefined;
+        }
+        if (modelTurns < MAX_MODEL_TURNS_PER_SUBMISSION - 1) return undefined;
+        // 预算见底：清空工具表并注入收尾指令，逼出一条真正的终止助手消息。
+        // 直接判失败的话用户拿不到任何交代；继续让步则等于没有预算。
+        // 这条指令不进 newMessages，因此不会写进 transcript —— 它是控制指令，不是历史。
+        wrappingUp = true;
+        return {
+          context: {
+            ...context,
+            tools: [],
+            messages: [
+              ...context.messages,
+              {
+                role: "user" as const,
+                content: [{ type: "text" as const, text: WRAP_UP_MESSAGE }],
+                timestamp: Date.now(),
+              },
+            ],
+          },
+        };
+      },
       shouldStopAfterTurn: () => {
-        reachedModelTurnLimit = ++modelTurns >= MAX_MODEL_TURNS_PER_SLICE;
-        return signal?.aborted === true || reachedModelTurnLimit;
+        if (signal?.aborted === true) return true;
+        // 收尾那一轮必须跑完，否则让步会把唯一的终态机会顶掉。但「必须跑完」
+        // 不等于「不再有上限」：Pi 在这之后还会取 steering 和 follow-up 消息，
+        // 一直有新消息进来就会一直发模型请求，而且全在同一个 invocation 里 ——
+        // 那正是 MAX_MODEL_TURNS_PER_SLICE 要挡的 CPU 驱逐。
+        if (wrappingUp) return wrapUpTurns >= MAX_WRAP_UP_TURNS;
+        reachedModelTurnLimit = sliceTurns >= MAX_MODEL_TURNS_PER_SLICE;
+        return reachedModelTurnLimit;
       },
       initialState: {
         model: this.opts.pi.model,
@@ -286,8 +348,8 @@ class PiTurnAdapter {
       }
       await running;
       return reachedModelTurnLimit
-        ? { kind: "yielded" }
-        : { kind: "terminal" };
+        ? { kind: "yielded", modelTurns }
+        : { kind: "terminal", modelTurns };
     } finally {
       signal?.removeEventListener("abort", abort);
       unsubscribe();
@@ -393,6 +455,8 @@ export interface CreatePreparedPiTurnOptions {
     readonly startedAt: number;
     readonly continuation: boolean;
     readonly assistantOrdinal: number;
+    /** 之前的执行片已用掉的模型回合数；省略按 0 处理。 */
+    readonly modelTurnsConsumed?: number;
   };
   /**
    * 在 Pi 启动前读取最新 canonical transcript。
@@ -474,8 +538,10 @@ export interface PiPreparedTurnRunOptions {
 }
 
 export type PiTurnRunResult =
-  | { readonly kind: "terminal" }
-  | { readonly kind: "yielded" };
+  /** Turn 已产生权威结果，或已经收尾。 */
+  | { readonly kind: "terminal"; readonly modelTurns: number }
+  /** 本片让出执行，Turn 未结束；调用方必须排出续跑。 */
+  | { readonly kind: "yielded"; readonly modelTurns: number };
 
 // #endregion
 
@@ -724,6 +790,7 @@ export class PreparedPiTurnAdapter {
         this.interrupted ? undefined : options.durability.settleTool(call),
       transformContext: options.transformContext,
       workspace: state.snapshot.bindings.workspace,
+      modelTurnsConsumed: options.submission.modelTurnsConsumed ?? 0,
     });
     this.systemPrompt = descriptor.systemPrompt;
     this.options = options;
@@ -835,7 +902,7 @@ export class PreparedPiTurnAdapter {
     );
     if (this.terminalIntent) {
       await this.options.onTerminal(this.terminalIntent);
-      return { kind: "terminal" };
+      return { kind: "terminal", modelTurns: result.modelTurns };
     }
     return result;
   }

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

@@ -17,6 +17,7 @@ import {
   applyPiToolResult,
   captureUIUserSidecar,
   piAssistantToUIMessage,
+  publicAssistantError,
   type PiToolApprovalView,
   type UIUserSidecar,
 } from "../message";
@@ -655,7 +656,9 @@ export class PiRuntimeTranscript {
             completedAt - submission.createdAt,
           ),
           turnStatus: "error",
-          ...(submission.error ? { error: submission.error } : {}),
+          ...(submission.error
+            ? { error: publicAssistantError(submission.error) }
+            : {}),
         },
       });
       seenAssistantSubmissions.add(submissionId);
@@ -761,7 +764,9 @@ export class PiRuntimeTranscript {
                   ),
                 }),
             turnStatus: submission?.status,
-            ...(submission?.error ? { error: submission.error } : {}),
+            ...(submission?.error
+              ? { error: publicAssistantError(submission.error) }
+              : {}),
           },
           approvals: this.approvalViews(entry.submissionId),
         });

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

@@ -22,6 +22,7 @@ import {
   SubmissionLifecycle,
   MAX_PENDING_SUBMISSIONS,
   SubmissionQueueFullError,
+  type SubmissionExecutionMode,
   type SubmissionInput,
   type SubmissionStore,
   type SubmissionHandle,
@@ -128,6 +129,10 @@ import {
 
 const SCHEDULED_STABLE_TIMEOUT_MS = 30_000;
 const TURN_EVENT_RETRY_SECONDS = 10;
+
+// 计划续跑丢失多久后由看门狗接手。必须显著长于一个正常执行片的时长，
+// 否则会在健康的长执行片上误判并派发出重复的一片。
+const CONTINUATION_WATCHDOG_SECONDS = 300;
 // 一次 Host admission 调用最多被视为「在途」多久。停在 pending 的准入行永久保留
 // —— 它固定了同一 identity 重投时必须复用的 runId,不能靠删行来让容量回收 ——
 // 但一次远端失败或崩溃留下的行超过这个窗口后就不再占用 pending 容量,否则
@@ -169,6 +174,10 @@ interface StoredSubmission extends SubmissionReceipt {
   accountId: string | null;
   rateVersion: number | null;
   slotIdentity: string | null;
+  /** 跨执行片累计的模型回合数，全局回合预算据此判断。 */
+  modelTurns: number;
+  /** 当前让步执行片的标识；没有未完成让步时为 null。 */
+  continuationId: string | null;
 }
 
 interface SubmitMessageOptions {
@@ -196,6 +205,35 @@ interface PlannedContinuationData {
   readonly continuationId: string;
 }
 
+/**
+ * 说明一次恢复准备的结局。
+ *
+ * @remarks
+ * `prepareRecoveredTurn` 返回它，`executeNonTerminalSubmission` 据此决定重起 Turn、
+ * 保持停靠还是落终态。
+ *
+ * `parked` 与 `unresumable` 必须分开：前者有人（审批、客户端交互）或有已排的调度会来解开它，
+ * 后者没有任何东西会再唤醒 —— 把两者混成一个「不继续」，非终态记录就会永久停在 running。
+ */
+type RecoveredTurnPreparation =
+  /** Transcript 完好，可以重起 Pi Turn。 */
+  | { readonly kind: "resume" }
+  /** 正在等人或等已排的续跑；保持非终态是正确的。 */
+  | { readonly kind: "parked" }
+  /** 准备过程自己已经写好了终态。 */
+  | { readonly kind: "settled" }
+  /** 续不下去，调用方必须落一条用户看得见的失败终态。 */
+  | { readonly kind: "unresumable"; readonly reason: string };
+
+// 作用：为一个没人会来解开的 `wait` 生成用户能看懂的终态原因。
+// 调用：`prepareRecoveredTurn` 判定 wait 不是 approval/interaction 时调用。
+// 原因：终态文本会直接呈现给用户，必须说明发生了什么以及能不能重试。
+function unresumableWaitMessage(reason: string | undefined): string {
+  return reason === "uncertain-tool"
+    ? "SpringBrand stopped this turn: a non-idempotent Tool was interrupted and its result cannot be confirmed, so it was not retried. Re-send the request if you want to try again."
+    : "SpringBrand could not resume this turn after an interruption.";
+}
+
 // 作用：把任意异常整理成可以持久化或发给客户端的文字。
 // 调用：Turn 执行、恢复和业务投影捕获 `unknown` 异常时调用。
 // 原因：错误边界不能假定抛出值一定是 `Error`。
@@ -494,8 +532,8 @@ export abstract class AgentRuntimeKernel<
     this.submissions = new SubmissionLifecycle({
       store: submissionStore,
       clearTerminal: () => clearChatTerminal(this.ctx.storage),
-      execute: (submissionId, recovery) =>
-        this.executeSubmission(submissionId, recovery),
+      execute: (submissionId, mode) =>
+        this.executeSubmission(submissionId, mode),
       appendAbortIntent: (submission, reason) =>
         this.appendTerminalIntent(submission, "aborted", reason),
       commitTerminal: (submission, outcome, message) =>
@@ -853,6 +891,7 @@ export abstract class AgentRuntimeKernel<
         startedAt,
         continuation: output.continuation ?? false,
         assistantOrdinal: output.assistantOrdinal ?? 0,
+        modelTurnsConsumed: submission.modelTurns,
       },
       canonicalMessages: () => this.transcript.canonicalMessages(),
       durability: {
@@ -2422,21 +2461,26 @@ export abstract class AgentRuntimeKernel<
   // 作用：按持久事实把一个中断 Turn 推进到可继续或已收尾状态。
   // 调用：`executeNonTerminalSubmission` 以 recovery 模式重起 Pi Turn 前调用。
   // 原因：用有界循环执行状态机效果，既允许 Tool 重试产生新事实，也防止错误规则无限自旋。
+  //
+  // 返回值必须区分「在等人」和「续不下去」：以前两者都压成 false，调用方一律原样返回
+  // 非终态记录，于是「续不下去」这一类会让 Submission 永久停在 running。
   private async prepareRecoveredTurn(
     submission: StoredSubmission,
     adapter: PreparedPiTurnAdapter,
-  ): Promise<boolean> {
+  ): Promise<RecoveredTurnPreparation> {
     let decision = await this.materializeRecoveredToolResults(submission);
     for (let step = 0; step < 32; step += 1) {
       const latest = this.readSubmission(submission.submissionId);
-      if (!latest || isTerminalSubmissionStatus(latest.status)) return false;
+      if (!latest || isTerminalSubmissionStatus(latest.status)) {
+        return { kind: "settled" };
+      }
       if (latest.abortReason) {
         await this.submissions.finish(
           latest,
           "aborted",
           latest.abortReason,
         );
-        return false;
+        return { kind: "settled" };
       }
       this.db.transaction(() => {
         this.applyPiRecoveryMutations(
@@ -2446,7 +2490,19 @@ export abstract class AgentRuntimeKernel<
       });
       switch (decision.effect.kind) {
         case "wait":
-          return false;
+          // 这里必须逐个 reason 判，不能按「不是 approval 就算续不下去」一刀切：
+          // - approval / interaction：等人，用户迟早会点。
+          // - complete：终态里程碑已提交，行状态同事务写入，上层的终态检查会收掉。
+          // - undefined：续跑里程碑已暂存待派发，`dispatchPendingContinuations`
+          //   会来接手 —— 判它失败等于杀掉一轮本来有人管的 Turn。
+          // - uncertain-tool：**没有任何人会来解开**。非幂等工具结果不确定，恢复
+          //   拒绝重放，`onStart` 也显式跳过 —— 停在这里就是永久挂死。
+          return decision.effect.reason === "uncertain-tool"
+            ? {
+                kind: "unresumable",
+                reason: unresumableWaitMessage(decision.effect.reason),
+              }
+            : { kind: "parked" };
         case "retry-tool": {
           try {
             if (
@@ -2456,7 +2512,11 @@ export abstract class AgentRuntimeKernel<
                 input: decision.effect.input,
               })
             ) {
-              return false;
+              return {
+                kind: "unresumable",
+                reason:
+                  `SpringBrand could not resume this turn: Tool "${decision.effect.toolName}" is no longer available.`,
+              };
             }
           } catch {
             // The governed Tool persisted its bounded error ToolResult.
@@ -2471,17 +2531,25 @@ export abstract class AgentRuntimeKernel<
             submission,
             decision.effect.approvalExecutionId,
           );
-          return false;
+          return { kind: "parked" };
         case "finish":
           await this.submissions.finish(
             submission,
             decision.effect.outcome,
             decision.effect.message,
           );
-          return false;
+          return { kind: "settled" };
         case "resume-turn": {
           const last = (await this.transcript.canonicalMessages()).at(-1);
-          return last?.role === "user" || last?.role === "toolResult";
+          // Pi 的 agentLoopContinue 拒绝从 assistant 消息继续。悬空的尾部 assistant
+          // 意味着这条 transcript 续不下去了 —— 判断出来就必须收尾,不能默默退场。
+          return last?.role === "user" || last?.role === "toolResult"
+            ? { kind: "resume" }
+            : {
+                kind: "unresumable",
+                reason:
+                  "SpringBrand could not resume this turn: the transcript ends on an assistant message.",
+              };
         }
       }
     }
@@ -2611,7 +2679,7 @@ export abstract class AgentRuntimeKernel<
   // 原因：把失败帧、可续传流和 pre-stream 清理放在最外层，避免内部分支遗留半开传输状态。
   private async executeSubmission(
     submissionId: string,
-    recovery = false,
+    mode: SubmissionExecutionMode = "fresh",
   ): Promise<StoredSubmission> {
     const submission = this.readSubmission(submissionId);
     if (!submission) {
@@ -2627,7 +2695,9 @@ export abstract class AgentRuntimeKernel<
         submission.abortReason,
       );
     }
-    if (recovery) {
+    if (mode === "recovery") {
+      // 只有真中断才记恢复事实。计划让步也走这里的话,每个执行片都会伪造一条
+      // `runtime_restart`,并且抹掉真实的 stall 原因 —— 真崩溃和主动让出在观测上就分不开了。
       this.telemetry.capture("turnRecovering", {
         submissionId,
         reason: submission.recoveryReason ?? "runtime_restart",
@@ -2635,16 +2705,16 @@ export abstract class AgentRuntimeKernel<
       });
       this.db.submissions.clearRecoveryReason(submissionId);
       await this.broadcastApprovals();
-      await this.ensureRuntimeReady();
     }
+    if (mode !== "fresh") await this.ensureRuntimeReady();
     try {
       return await this.executeNonTerminalSubmission(
         submission,
-        recovery,
+        mode,
       );
     } catch (error) {
       if (
-        recovery &&
+        mode === "recovery" &&
         (error instanceof ChatStreamStalledError ||
           error instanceof RetryableModelError)
       ) {
@@ -2665,7 +2735,7 @@ export abstract class AgentRuntimeKernel<
         failed.status === "error"
           ? failed.error ?? "SpringBrand turn failed"
           : undefined,
-        recovery,
+        mode !== "fresh",
       );
       return failed;
     } finally {
@@ -2683,8 +2753,11 @@ export abstract class AgentRuntimeKernel<
   // 原因：恢复补全、状态迁移、fiber、流式记录与终态投影必须保持固定顺序，否则唤醒后会重复执行或丢失回答。
   private async executeNonTerminalSubmission(
     submission: StoredSubmission,
-    recovery: boolean,
+    mode: SubmissionExecutionMode,
   ): Promise<StoredSubmission> {
+    // 续跑和恢复一样要给客户端打 continuation 标记(否则前端会另起一个空累加器,
+    // 把已经渲染出来的半条回答整条换掉),但只有恢复需要重建持久事实。
+    const continuation = mode !== "fresh";
     const submissionId = submission.submissionId;
     if (submission.abortReason) {
       return this.submissions.finish(
@@ -2695,11 +2768,14 @@ export abstract class AgentRuntimeKernel<
     }
     submission = await this.pinSubmissionAssembly(submission);
     await this.assertPinnedSubmission(submission);
-    if (submission.status === "pending" && !recovery) {
+    if (submission.status === "pending" && mode === "fresh") {
       submission = await this.activateQueuedSubmission(submission);
     }
     const recoveryAdapter = this.createSubmissionExecutionAdapter(submission);
-    if (recovery) {
+    // 让步续跑跳过整套里程碑重放:这一片是主动让出的,transcript 完好、没有半路的
+    // Tool 要重建。走恢复通道不只是白跑,重放成本还随让步次数增长 —— 第 N 片要
+    // 重放前 N-1 片积累的全部里程碑。
+    if (mode === "recovery") {
       const deactivatePreparation = this.submissions.activate(submission, {
         submissionId,
         requestId: submission.requestId,
@@ -2708,24 +2784,37 @@ export abstract class AgentRuntimeKernel<
         continuation: true,
         agent: recoveryAdapter,
       });
-      let ready: boolean;
+      let preparation: RecoveredTurnPreparation;
       try {
-        ready = await this.prepareRecoveredTurn(
+        preparation = await this.prepareRecoveredTurn(
           submission,
           recoveryAdapter,
         );
       } finally {
         deactivatePreparation();
       }
-      if (!ready) {
+      if (preparation.kind !== "resume") {
         const latest = this.readSubmission(submissionId)!;
-        return latest.abortReason
-          ? this.submissions.finish(
-              latest,
-              "aborted",
-              latest.abortReason,
-            )
-          : latest;
+        if (latest.abortReason) {
+          return this.submissions.finish(
+            latest,
+            "aborted",
+            latest.abortReason,
+          );
+        }
+        if (isTerminalSubmissionStatus(latest.status)) return latest;
+        // 非终态还想退场,只有「在等人」这一种是合法的。其余一律收成失败终态:
+        // 停在 running 会让 `pump()` 的 `findRunning()` 永远有值,这个 Session
+        // 之后所有消息都排不进去,而且没有任何东西会再唤醒它。
+        if (preparation.kind === "parked") return latest;
+        // `settled` 走到这里说明它没真的写成终态 —— 契约破了也不能放它挂着。
+        return this.submissions.finish(
+          latest,
+          "failed",
+          preparation.kind === "unresumable"
+            ? preparation.reason
+            : unresumableWaitMessage(undefined),
+        );
       }
     } else {
       await this.materializeRecoveredToolResults(submission);
@@ -2767,7 +2856,7 @@ export abstract class AgentRuntimeKernel<
     let turn!: ActiveTurn;
     const adapter = this.createSubmissionExecutionAdapter(submission, {
       startedAt,
-      continuation: recovery,
+      continuation,
       assistantOrdinal,
       onRecord: (record) =>
         this.migratedSubmissions.has(submissionId)
@@ -2796,7 +2885,7 @@ export abstract class AgentRuntimeKernel<
       requestId: submission.requestId,
       messageId: submission.assistantMessageId,
       startedAt,
-      continuation: recovery,
+      continuation,
       agent: adapter,
     };
     let streamId: string | undefined;
@@ -2809,7 +2898,7 @@ export abstract class AgentRuntimeKernel<
         {
           requestId: submission.requestId,
           messageId: submission.assistantMessageId,
-          continuation: recovery,
+          continuation,
           messages: await this.transcript.snapshotMessages(),
           recoveryData: {
             submissionId,
@@ -2844,6 +2933,19 @@ export abstract class AgentRuntimeKernel<
         if (!streamId) {
           throw new Error("Yielded SpringBrand Turn has no recoverable stream");
         }
+        // 回合数和续跑标识必须先落库、再排调度：调度一旦到期就会读这两个值，
+        // 反过来写会让续跑看到上一片的状态。
+        this.db.transaction(() =>
+          this.db.submissions.recordYieldedSlice(
+            submissionId,
+            runResult!.modelTurns,
+            streamId!,
+          )
+        );
+        // 让步必须密封本切片的流，但不能发 done —— 这一轮还没有权威结果。
+        // 不密封的话下一个切片的 start() 会直接顶掉 activeStreamId，旧行永远
+        // 停在 streaming，元数据和 chunk 要等 abandoned 保留期才回收。
+        this.sealRecoverableStreamSlice(streamId);
         await this.schedule(
           0,
           "_piPlannedContinuation",
@@ -2854,8 +2956,21 @@ export abstract class AgentRuntimeKernel<
           },
           { idempotent: true },
         );
+        await this.scheduleContinuationWatchdog(
+          submissionId,
+          submission.requestId,
+          streamId,
+        );
         return latest;
       }
+      if (runResult) {
+        this.db.transaction(() =>
+          this.db.submissions.recordModelTurns(
+            submissionId,
+            runResult!.modelTurns,
+          )
+        );
+      }
       const intent = terminalIntent ?? {
         outcome: "failed" as const,
         message:
@@ -2929,7 +3044,11 @@ export abstract class AgentRuntimeKernel<
             recoveryOutcome !== "disabled" &&
             !this.readSubmission(submissionId)?.abortReason
           ) {
-            if (recovery && recoveryOutcome === "scheduled") throw error;
+            // 只有恢复通道的调用方(`_chatRecoveryRetry`)靠这次重抛判定 "scheduled"。
+            // 让步续跑由 alarm 驱动，重抛只会把那次 alarm 变成一次失败。
+            if (mode === "recovery" && recoveryOutcome === "scheduled") {
+              throw error;
+            }
             return this.readSubmission(submissionId)!;
           }
         } else if (!stoppedDuringRecovery) {
@@ -4024,19 +4143,104 @@ export abstract class AgentRuntimeKernel<
     }
   }
 
-  async _piPlannedContinuation(
-    data?: PlannedContinuationData,
+  // 作用：为一个让步执行片排一次兜底唤醒。
+  // 调用：`executeNonTerminalSubmission` 排出计划续跑之后立即调用。
+  // 原因：计划续跑只有一次机会 —— schedule 抛错、alarm 回调抛错、实例中途被换掉，
+  // 这一轮就再也没人唤醒了。看门狗是唯一能兜住未知丢失路径的东西；
+  // 它按续跑标识判断有没有推进，所以正常情况下醒来即空转返回。
+  private async scheduleContinuationWatchdog(
+    submissionId: string,
+    requestId: string,
+    continuationId: string,
   ): Promise<void> {
-    if (!data?.submissionId || !data.requestId) return;
+    try {
+      await this.schedule(
+        CONTINUATION_WATCHDOG_SECONDS,
+        "_piContinuationWatchdog",
+        { submissionId, requestId, continuationId },
+        { idempotent: true },
+      );
+    } catch (error) {
+      // 看门狗排不上不该反过来杀掉这一轮：计划续跑本身已经排好了。
+      console.warn(
+        "[pi-continuation-watchdog:degraded]",
+        json({ submissionId, error: errorText(error) }),
+      );
+    }
+  }
+
+  // 判断一条让步提交是否仍停在 `continuationId` 这一片上。
+  // 计划续跑和看门狗都用它决定该不该接手，避免和更新的执行片重复派发。
+  //
+  // `allowUnrecorded` 给看门狗用：让步的落库万一没生效（记录已不在
+  // pending/running），`continuationId` 会是 null，此时严格比对会把续跑和看门狗
+  // 一起丢掉 —— 那正是这次要根除的静默挂死。计划续跑不放宽，它的职责就是去重。
+  private stalledOnContinuation(
+    data: PlannedContinuationData,
+    { allowUnrecorded = false }: { allowUnrecorded?: boolean } = {},
+  ): StoredSubmission | null {
     const submission = this.readSubmission(data.submissionId);
     if (
       !submission ||
       submission.requestId !== data.requestId ||
       isTerminalSubmissionStatus(submission.status)
     ) {
-      return;
+      return null;
+    }
+    const onThisSlice = submission.continuationId === data.continuationId ||
+      (allowUnrecorded && submission.continuationId === null);
+    return onThisSlice ? submission : null;
+  }
+
+  async _piPlannedContinuation(
+    data?: PlannedContinuationData,
+  ): Promise<void> {
+    if (!data?.submissionId || !data.requestId || !data.continuationId) return;
+    // 校验续跑标识:两条 alarm 同时到期时，晚到的那条对应的已经是上一片，
+    // 放它进去会白跑一整个执行片。
+    const submission = this.stalledOnContinuation(data);
+    if (!submission) return;
+    await this.submissions.continueAfterCurrent(submission.submissionId);
+  }
+
+  /**
+   * 在计划续跑丢失时接手一条让步提交。
+   *
+   * @remarks
+   * Agents SDK 的调度器在 `scheduleContinuationWatchdog` 排的延时任务到期时按方法名调用。
+   *
+   * 正常情况下这一片早就推进了（`continuationId` 已换或已终态），此时直接返回。
+   *
+   * 走 `recover` 而不是 `continueAfterCurrent`，有两个都不能省的理由：
+   * 一是续跑会丢通常就是实例中途没了，那属于崩溃，必须重放里程碑、补齐半路的
+   * Tool，续跑模式恰恰跳过这些；二是这一轮可能正停在审批或客户端交互上等人
+   * （被驱逐后内存里没有执行器，看起来就像「没人在跑」），只有恢复准备认得出
+   * 这是合法停靠并原样放过 —— 续跑模式会直接在它上面重起一轮。
+   *
+   * `recover` 复用 `executions` 的实例内去重，因此和一片刚进序幕、还没登记执行器的
+   * 竞态也一并合流，不会多跑一片。
+   */
+  async _piContinuationWatchdog(
+    data?: PlannedContinuationData,
+  ): Promise<void> {
+    if (!data?.submissionId || !data.requestId || !data.continuationId) return;
+    const submission = this.stalledOnContinuation(data, {
+      allowUnrecorded: true,
+    });
+    if (!submission) return;
+    try {
+      await this.ensureRuntimeReady();
+      await this.submissions.recover(submission.submissionId);
+    } catch (error) {
+      const latest = this.readSubmission(data.submissionId);
+      if (latest && !isTerminalSubmissionStatus(latest.status)) {
+        await this.submissions.finish(
+          latest,
+          "failed",
+          `SpringBrand could not continue this turn: ${errorText(error)}`,
+        );
+      }
     }
-    await this.submissions.recoverAfterCurrent(submission.submissionId);
   }
 
   // 作用：Agent Tool 子运行开始后重算一次活动投影。