@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.3

package/package.json

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

package/src/db/schema.ts

@@ -21,7 +21,9 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
     assembly_revision TEXT NOT NULL,
     assembly_descriptor TEXT NOT NULL,
     assistant_message_id TEXT NOT NULL,
-    abort_reason TEXT
+    abort_reason TEXT,
+    recovery_error_count INTEGER NOT NULL DEFAULT 0,
+    recovery_reason TEXT
   )`;
   const submissionColumns = new Set(
     sql<{ name: string }>`PRAGMA table_info(pi_submissions)`
@@ -39,6 +41,13 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
   if (!submissionColumns.has("regenerate_message_id")) {
     sql`ALTER TABLE pi_submissions ADD COLUMN regenerate_message_id TEXT`;
   }
+  if (!submissionColumns.has("recovery_error_count")) {
+    sql`ALTER TABLE pi_submissions
+        ADD COLUMN recovery_error_count INTEGER NOT NULL DEFAULT 0`;
+  }
+  if (!submissionColumns.has("recovery_reason")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN recovery_reason TEXT`;
+  }
   sql`CREATE UNIQUE INDEX IF NOT EXISTS pi_submissions_one_running
       ON pi_submissions(status)
       WHERE status = 'running'`;

package/src/db/submission.repo.ts

@@ -9,6 +9,9 @@ export type SubmissionStatus =
   | "aborted"
   | "skipped"
   | "error";
+export type SubmissionRecoveryReason =
+  | "no_meaningful_model_progress"
+  | "transient_model_error";
 
 const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
   "completed",
@@ -43,6 +46,8 @@ export interface StoredSubmission {
   queuedUiMessageJson: string | null;
   userMessageId: string | null;
   regenerateMessageId: string | null;
+  recoveryErrorCount: number;
+  recoveryReason: SubmissionRecoveryReason | null;
 }
 
 export interface NewSubmission {
@@ -76,6 +81,8 @@ type SubmissionRow = {
   queued_ui_message_json: string | null;
   user_message_id: string | null;
   regenerate_message_id: string | null;
+  recovery_error_count: number;
+  recovery_reason: string | null;
 };
 
 // #endregion
@@ -101,6 +108,8 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     queuedUiMessageJson: row.queued_ui_message_json,
     userMessageId: row.user_message_id,
     regenerateMessageId: row.regenerate_message_id,
+    recoveryErrorCount: row.recovery_error_count,
+    recoveryReason: row.recovery_reason as SubmissionRecoveryReason | null,
   };
 }
 
@@ -121,7 +130,7 @@ export class SubmissionRepository {
              error, created_at, completed_at, assembly_revision,
              assembly_descriptor, assistant_message_id, abort_reason,
              queued_input_json, queued_ui_message_json, user_message_id,
-             regenerate_message_id
+             regenerate_message_id, recovery_error_count, recovery_reason
       FROM pi_submissions
       WHERE submission_id = ${id}
     `[0];
@@ -309,6 +318,30 @@ export class SubmissionRepository {
     `;
   }
 
+  // chatRecovery 遇到 partial 会重置 attempt；Submission 计数保证同一 Turn 的可恢复模型错误仍绝对封顶。
+  incrementRecoveryErrorCount(
+    id: string,
+    reason: SubmissionRecoveryReason,
+  ): number {
+    return this.sql<{ recovery_error_count: number }>`
+      UPDATE pi_submissions
+      SET recovery_error_count = recovery_error_count + 1,
+          recovery_reason = ${reason}
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+      RETURNING recovery_error_count
+    `[0]?.recovery_error_count ?? 0;
+  }
+
+  clearRecoveryReason(id: string): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET recovery_reason = NULL
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+    `;
+  }
+
   // 返回所有标准会话消息到 Submission 的关联映射。
   // Transcript.storedMessages 读取 Pi Session 分支时调用，它用 Map 为每条消息补回 submissionId。
   // 关联表由 Pi Session 存储拥有，本方法只读不写；不能在 RuntimeDatabase.clearAll 中单独删它而破坏 Transcript 的所有权。

package/src/index.ts

@@ -126,6 +126,7 @@ export {
 } from "./layers/orchestration/temporary-agent/workspace";
 export {
   createPiModels,
+  modelRequestUrl,
   resolvePiApiKey,
   resolvePiModel,
 } from "./pi/runtime-adapter/models";

package/src/kernel/bindings.ts

@@ -294,9 +294,7 @@ export interface RuntimeMemoryPort {
    * 按标签覆盖一块热记忆。
    *
    * @remarks
-   * Host 实现提供该能力，但当前 `packages/agent-runtime/src` 没有调用点。
-   *
-   * TODO(待确认): 确认后续写入方是否仍需通过这个公开 Port 提交热记忆。
+   * `set_context` 在校验标签和 token 预算后调用，Host 负责按当前 Agent 与会话持久化。
    */
   set(label: string, content: string): Promise<void>;
 }

package/src/kernel/recoverable-chat-agent.ts

@@ -73,15 +73,15 @@ export type RuntimeRecoveryDecision<Data> =
   | { readonly kind: "ignore"; readonly reason: string };
 
 /**
- * 记录一次已执行恢复的最终结果。
+ * 记录一次已执行恢复的结果，或表明该恢复已接力给下一次持久调度。
  *
  * @remarks
- * `_chatRecoveryRetry` 在调用端口的 `retry` 后读取该结果，并用它关闭对应的恢复事故。
+ * `_chatRecoveryRetry` 在调用端口的 `retry` 后读取该结果；终态关闭事故，`scheduled` 保持事故活跃。
  *
  * 只有失败时才需要 `error`；结果不承载流内容，避免在调度数据与流缓冲区之间复制状态。
  */
 export interface RuntimeRecoveryResult {
-  readonly status: "completed" | "failed";
+  readonly status: "completed" | "scheduled" | "failed";
   readonly error?: string;
 }
 
@@ -103,7 +103,7 @@ export interface RuntimeRecoveryPort<Data> {
   /**
    * 使用已分类的业务数据重放一次对话。
    *
-   * @remarks 持久调度回调会调用它；实现应返回权威终态，而不是仅表示重试已启动。
+   * @remarks 持久调度回调会调用它；实现应返回权威终态，或明确说明下一次恢复已经持久调度。
    */
   retry(data: Data): Promise<RuntimeRecoveryResult>;
   /**
@@ -544,6 +544,7 @@ export abstract class RecoverableChatAgent<
     this.activeRecoveryRootRequestId = data.requestId;
     try {
       const result = await this.recoveryPort().retry(data);
+      if (result.status === "scheduled") return;
       await this.engine().updateIncident(
         data.incidentId,
         result.status === "completed" ? "completed" : "failed",
@@ -563,6 +564,83 @@ export abstract class RecoverableChatAgent<
     }
   }
 
+  /**
+   * 把活跃进程内检测到的模型流停滞交给同一套持久恢复预算。
+   *
+   * @remarks
+   * 子类在确认当前 Turn 可以从 durable checkpoint 重放后调用；`beforeSchedule`
+   * 必须先结束旧流并恢复权威消息快照，随后引擎才广播 recovering 状态。
+   */
+  protected async scheduleChatRecoveryRetry(
+    data: RecoveryData,
+    beforeSchedule: () => void | Promise<void>,
+  ): Promise<"disabled" | "scheduled" | "exhausted"> {
+    if (!resolveChatRecoveryConfig(this.chatRecovery).enabled) {
+      return "disabled";
+    }
+    const recoveryRootRequestId =
+      this.activeRecoveryRootRequestId ?? data.requestId;
+    const { incident, exhausted } = await this.engine().beginIncident({
+      requestId: data.requestId,
+      recoveryRootRequestId,
+      recoveryKind: "retry",
+    });
+    await beforeSchedule();
+    if (exhausted) {
+      await this.engine().exhaustRecoveryGiveUp({
+        callback: "_chatRecoveryRetry",
+        data: {
+          incidentId: incident.incidentId,
+          originalRequestId: recoveryRootRequestId,
+        },
+        reason: incident.reason ?? "max_attempts_exceeded",
+      });
+      return "exhausted";
+    }
+    await this.engine().scheduleRecovery({
+      incident,
+      recoveryKind: "retry",
+      callback: "_chatRecoveryRetry",
+      data: {
+        ...data,
+        incidentId: incident.incidentId,
+      },
+      reason: this.activeRecoveryRootRequestId
+        ? "stable_timeout_retry"
+        : "initial",
+    });
+    return "scheduled";
+  }
+
+  /** 终态化一个 Turn 时取消同请求的恢复调度，并关闭恢复事故与客户端状态。 */
+  protected async settleChatRecovery(
+    requestId: string,
+    status: "completed" | "skipped" | "failed",
+    reason?: string,
+  ): Promise<void> {
+    const incidentIds = new Set<string>();
+    try {
+      for (const schedule of await this.listSchedules()) {
+        if (schedule.callback !== "_chatRecoveryRetry") continue;
+        const payload = schedule.payload;
+        if (!payload || typeof payload !== "object") continue;
+        const recovery = payload as Partial<
+          RecoveryScheduleData<RecoveryData>
+        >;
+        if (recovery.requestId !== requestId) continue;
+        if (typeof recovery.incidentId === "string") {
+          incidentIds.add(recovery.incidentId);
+        }
+        await this.cancelSchedule(schedule.id);
+      }
+      for (const incidentId of incidentIds) {
+        await this.engine().updateIncident(incidentId, status, reason);
+      }
+    } finally {
+      await this.setRecovering(false, requestId);
+    }
+  }
+
   /**
    * 把 Agents SDK 发现的孤立 Fiber 交给聊天恢复引擎。
    *

package/src/kernel/state.ts

@@ -51,6 +51,10 @@ export interface RuntimeQueuedSubmission {
 
 export interface RuntimeTurnState {
   activeSubmissionId?: string;
+  activeRequestId?: string;
+  recoveryAttempt?: number;
+  recoveryMax?: number;
+  recoveryReason?: "no_meaningful_model_progress" | "transient_model_error";
   steerable: boolean;
   hasPendingSteer: boolean;
   queued: RuntimeQueuedSubmission[];

package/src/kernel/submission-lifecycle.ts

@@ -587,13 +587,14 @@ export class SubmissionLifecycle<
           return submission ? [submission.submissionId] : [];
         })()
       : (() => {
-          const submission = this.options.store.findRunning();
+          const submission = this.options.store.findRunning() ??
+            this.options.store.findNextPending();
           return submission ? [submission.submissionId] : [];
         })();
     for (const submissionId of submissionIds) {
       await this.cancel(submissionId, reason);
     }
-    return { ok: true };
+    return { ok: submissionIds.length > 0 };
   }
 
   // #endregion

package/src/lib/prompt.ts

@@ -46,7 +46,7 @@ export const BEHAVIOR =
 export const PLANNING =
   "Planning: For work with 3 or more distinct steps, or any non-trivial / multi-file change, call " +
   "update_plan with the complete plan (it fully replaces the previous one) so the user sees live " +
-  "progress. Mark a step in_progress before starting it and completed the moment it's done; keep only " +
+  "progress. Mark a step in_progress before starting it and done the moment it's done; keep only " +
   "one step in_progress at a time and don't batch completions. Do not make a plan for a single trivial " +
   "step or a purely conversational reply — just do it.";
 

package/src/lib/telemetry-dev.ts

@@ -1,9 +1,12 @@
 /**
- * dev-only 观测降级:把 observability 事件打到 console,让 `wrangler dev` /
- * `wrangler tail` 里能实时看到埋点(否则 publish 到零订阅 channel = 静默 no-op)。
+ * 观测降级:把 observability 事件打到 console,让 `wrangler dev` / `wrangler tail` 里能实时看到埋点,
+ * 并且(生产上开了 `observability.logs` 时)进 Workers Logs 供事后查询。
+ * 不装它,事件就 publish 到零订阅 channel = 静默 no-op。
  *
- * 仅在 env `TELEMETRY_CONSOLE==="1"` 时由 onStart 装载(`.dev.vars` 里开,prod 不设 → 自动关)。
- * 生产不靠它:prod 所有 channel 事件自动转发 Tail Worker。
+ * 由 onStart 在 env `TELEMETRY_CONSOLE==="1"` 时装载 —— `.dev.vars` 和 `wrangler.jsonc` 的 vars 里都开着。
+ * 注意:上游注释宣称"生产上所有 channel 事件自动转发 Tail Worker",那条路径需要 `tail_consumers`,
+ * 本仓没有配,所以生产**不能**指望它;这个 console sink 就是生产的唯一消费面(2026-08-06 实测:
+ * 未开启前 Observability API 查 universal-agent 24h 事件 count=0)。
  *
  * 用 `agents/observability` 的类型化 `subscribe`(按 channel key 订阅),避免引 `node:diagnostics_channel`
  * 与 `@types/node`(tsconfig 只带 workers-types)。

package/src/pi/assembly/snapshot.ts

@@ -3,6 +3,7 @@ import type {
   ThinkingLevel,
 } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
+import { clampReasoning } from "@earendil-works/pi-ai/api/simple-options";
 import type {
   RuntimeMcpServer,
   RuntimeProfile,
@@ -79,11 +80,13 @@ function freezeModel(model: Model<Api>): Model<Api> {
 
 // 作用：把 Runtime 的思考强度名称转成 Pi Agent Core 接受的名称。
 // 调用：创建 Runtime 装配快照时对 profile 中的 `thinking` 调用。
-// 原因：只有 `none` 与 Pi 的 `off` 命名不同，其他级别应保持原值。
+// 原因：`none` 映射成 `off`；xhigh/max 用 clampReasoning 夹到 API 真正支持的最高档，
+// 避免超出范围的等级在 provider 侧静默失败。
 function toPiThinkingLevel(
   thinking: ThinkingEffort,
 ): ThinkingLevel {
-  return thinking === "none" ? "off" : thinking;
+  if (thinking === "none") return "off";
+  return clampReasoning(thinking) ?? "off";
 }
 
 // 作用：复制并冻结一个 Extension 配置的 manifest 和权限集合。

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

@@ -160,7 +160,7 @@ export interface PinnedPiRuntime {
  * @remarks
  * `PreparedPiTurnAdapter` 在重建 Turn 前读取这个 JSON 结构。
  *
- * 版本号和基础版本校验用于阻止恢复落到不兼容的 Runtime 状态。
+ * 基础版本作为准入时元数据保留，创建 Turn 时不与当前 Runtime 比较。
  */
 export interface PinnedPiRuntimeDescriptor {
   readonly version: 1;
@@ -200,6 +200,8 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "browser_markdown",
   "browser_scrape",
   "bind_resource",
+  "delete",
+  "edit",
   "find",
   "get_time",
   "grep",
@@ -211,6 +213,7 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "read_skill_resource",
   "sandbox_process_logs",
   "web_search",
+  "write",
   "unbind_resource",
 ]);
 
@@ -251,7 +254,7 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
 
 // 把本模块认定会影响版本的准备结果序列化出来。
 // preparePiRuntime 创建一次，Runtime 接受快照前再对结果求哈希。
-// 集合排序保证等价输入稳定；增删字段会改变版本哈希和恢复兼容性。
+// 集合排序保证等价输入稳定；增删字段会改变版本哈希。
 function describeRuntime(
   snapshot: RuntimeSnapshot,
   candidates: readonly PiToolCandidate[],
@@ -334,18 +337,17 @@ export function readPreparedPiRuntime(
 }
 
 /**
- * 校验已存的固定描述是否仍与当前准备好的 Runtime 兼容。
+ * 读取已存的固定描述。
  *
  * @remarks
  * `PreparedPiTurnAdapter` 在新建或恢复 Pi Turn 前调用它。
  *
- * 只有固定阶段写入的提示词允许不同，其余准备字段及基础版本必须匹配。
+ * Prepared Runtime 提供当前执行能力，descriptor 仅保留 Submission 固定的 Turn 字段。
  */
 export function readPinnedPiRuntime(
   prepared: PreparedPiRuntime,
   owner: object,
   descriptorBody: string,
-  baseRevision: string,
 ): {
   readonly state: PreparedPiRuntimeState;
   readonly descriptor: PinnedPiRuntimeDescriptor;
@@ -361,24 +363,11 @@ export function readPinnedPiRuntime(
     throw new Error("Pinned Runtime assembly descriptor is invalid");
   }
   const descriptor = value as PinnedPiRuntimeDescriptor;
-  const expected = JSON.parse(prepared.revisionDescriptor) as Record<
-    string,
-    unknown
-  >;
-  const actual = descriptor as unknown as Record<string, unknown>;
-  const incompatible = Object.keys(expected).some((key) =>
-    key !== "systemPrompt" &&
-    JSON.stringify(actual[key]) !== JSON.stringify(expected[key])
-  );
   if (
     descriptor.version !== 1 ||
-    descriptor.baseRevision !== baseRevision ||
-    typeof descriptor.systemPrompt !== "string" ||
-    incompatible
+    typeof descriptor.systemPrompt !== "string"
   ) {
-    throw new Error(
-      "Pinned Runtime revision is unavailable for Pi recovery",
-    );
+    throw new Error("Pinned Runtime assembly descriptor is invalid");
   }
   return { state, descriptor };
 }

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

@@ -9,17 +9,21 @@ import {
 import type {
   Api,
   AssistantMessage,
+  Message,
   Model,
   Models,
   ToolResultMessage,
   UserMessage,
 } from "@earendil-works/pi-ai";
+import { transformMessages } from "@earendil-works/pi-ai/api/transform-messages";
 import { requiresPiToolApproval, parkPiToolApproval } from "../turn";
 import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
+import { ChatStreamStalledError } from "agents/chat";
 import {
   compilePiTools,
   createPiToolGovernance,
+  normalizeUpdatePlanArguments,
   type PiToolCandidate,
   type PiToolGovernance,
   type PiToolTelemetry,
@@ -30,12 +34,28 @@ import {
   readPinnedPiRuntime,
   type PreparedPiRuntime,
 } from "./assembly";
-import { resolvePiApiKey, withProviderRetry } from "./models";
+import {
+  isRecoverableAssistantError,
+  isModelStreamStallMessage,
+  resolvePiApiKey,
+  withProviderRetry,
+} from "./models";
 
 // #region Single-run Pi bridge
 
 const MAX_MODEL_TURNS = 30;
 
+export class RetryableModelError extends Error {}
+
+function normalizePlanToolCalls(message: AgentMessage): void {
+  if (message.role !== "assistant") return;
+  for (const part of message.content) {
+    if (part.type === "toolCall" && part.name === "update_plan") {
+      part.arguments = normalizeUpdatePlanArguments(part.arguments);
+    }
+  }
+}
+
 /**
  * 把 Pi 的终止原因翻译成本仓的回合结局。
  *
@@ -72,6 +92,16 @@ function classifyPiStopReason(stopReason: string | undefined): {
   }
 }
 
+function visibleAssistantContent(message: AssistantMessage) {
+  return message.content.filter((part) =>
+    part.type === "text"
+      ? part.text.trim()
+      : part.type === "thinking"
+        ? part.thinking.trim()
+        : false
+  );
+}
+
 interface PiTurnAdapterOptions {
   readonly pi: {
     readonly model: Model<Api>;
@@ -79,6 +109,7 @@ interface PiTurnAdapterOptions {
   };
   readonly models: Models;
   readonly apiKey: string;
+  readonly modelSessionId: string;
   // 读取这次执行真正要交给 Pi 的 canonical transcript。
   // PiTurnAdapter.run 在创建 PiCore 前调用它，宿主应返回当时最新的 transcript。
   // 这里保留为延迟读取，是为了避免适配器创建后新增的恢复消息被旧快照漏掉。
@@ -129,10 +160,12 @@ class PiTurnAdapter {
     candidate: PiToolCandidate,
     toolCallId: string,
     input: unknown,
+    signal?: AbortSignal,
   ): Promise<boolean> {
     const [tool] = this.compile([candidate]);
     if (!tool) return false;
-    await tool.execute(toolCallId, input);
+    signal?.throwIfAborted();
+    await tool.execute(toolCallId, input, signal);
     return true;
   }
 
@@ -173,9 +206,17 @@ class PiTurnAdapter {
       convertToLlm,
       streamFn: withProviderRetry(
         this.opts.models.streamSimple.bind(this.opts.models),
+        0,
+        this.opts.modelSessionId,
       ),
       getApiKey: () => this.opts.apiKey,
-      transformContext: this.opts.transformContext,
+      // transformMessages 在宿主上下文变换之后运行，确保跨 provider 的 tool call ID 格式兼容。
+      // OpenAI Responses API 生成含 `|` 的 450+ 字符 ID，Anthropic 只接受 ^[a-zA-Z0-9_-]+$(64 字符上限)；
+      // 切换 provider 或消息跨 provider 回放时若不规范化，provider 会静默拒绝。
+      transformContext: async (messages, signal) => {
+        const ctx = await this.opts.transformContext(messages, signal);
+        return transformMessages(ctx as Message[], this.opts.pi.model) as AgentMessage[];
+      },
       afterToolCall: this.governance.afterToolCall,
       shouldStopAfterTurn: () => {
         reachedModelTurnLimit = ++modelTurns >= MAX_MODEL_TURNS;
@@ -295,7 +336,6 @@ export interface PiTurnDurability {
  */
 export interface CreatePreparedPiTurnOptions {
   readonly prepared: PreparedPiRuntime;
-  readonly baseRevision: string;
   readonly pinnedDescriptor: string;
   readonly submission: {
     readonly id: string;
@@ -398,6 +438,7 @@ export interface PiPreparedTurnRunOptions {
  */
 export class PreparedPiTurnAdapter {
   private readonly turn: PiTurnAdapter;
+  private readonly abortController = new AbortController();
   private readonly candidates: readonly PiToolCandidate[];
   private assistantOrdinal: number;
   private readonly encoder: PiChunkEncoder;
@@ -422,7 +463,6 @@ export class PreparedPiTurnAdapter {
       options.prepared,
       dependencies.owner,
       options.pinnedDescriptor,
-      options.baseRevision,
     );
     this.assistantOrdinal = options.submission.assistantOrdinal;
     this.encoder = new PiChunkEncoder({
@@ -530,6 +570,7 @@ export class PreparedPiTurnAdapter {
         state.snapshot.bindings.provider,
         state.snapshot.pi.model.id,
       ),
+      modelSessionId: options.submission.requestId,
       canonicalMessages: options.canonicalMessages,
       settle: options.durability.settleTool,
       onToolTelemetry: options.onToolTelemetry,
@@ -550,6 +591,7 @@ export class PreparedPiTurnAdapter {
    * 转交给 PiTurnAdapter 可保留启动前取消标记；run() 之前还没有可直接调用的 PiCore。
    */
   abort(): void {
+    this.abortController.abort();
     this.turn.abort();
   }
 
@@ -588,6 +630,7 @@ export class PreparedPiTurnAdapter {
           candidate,
           request.toolCallId,
           request.input,
+          this.abortController.signal,
         )
       : false;
   }
@@ -626,9 +669,49 @@ export class PreparedPiTurnAdapter {
   // PiTurnAdapter 会对每个 AgentEvent 调用它，PiCore 会等待该 Promise 后再越过订阅事件屏障。
   // canonical message 先于流投影提交，恢复才不会依赖仅供浏览器消费的记录；调整顺序必须复核 recovery effect。
   private async handleEvent(event: AgentEvent): Promise<void> {
+    if (
+      event.type === "message_start" ||
+      event.type === "message_update" ||
+      event.type === "message_end"
+    ) {
+      normalizePlanToolCalls(event.message);
+    }
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "error" &&
+      (isModelStreamStallMessage(
+        event.assistantMessageEvent.error.errorMessage,
+      ) ||
+        isRecoverableAssistantError(event.assistantMessageEvent.error))
+    ) {
+      return;
+    }
     let projectedEvent = event;
     if (event.type === "message_end") {
       const message = event.message;
+      if (message.role === "assistant") {
+        const stalled = message.stopReason === "error" &&
+          isModelStreamStallMessage(message.errorMessage);
+        const retryable = isRecoverableAssistantError(message);
+        if (stalled || retryable) {
+          const content = visibleAssistantContent(message);
+          if (content.length > 0) {
+            this.assistantOrdinal += 1;
+            await this.options.onCanonicalMessage({
+              kind: "commit-turn",
+              ordinal: this.assistantOrdinal,
+              message: {
+                ...message,
+                content,
+              },
+            });
+          }
+          if (stalled) {
+            throw new ChatStreamStalledError(message.errorMessage!);
+          }
+          throw new RetryableModelError(message.errorMessage);
+        }
+      }
       if (message.role === "user") {
         await this.options.onCanonicalMessage({
           kind: "append-user",
@@ -646,7 +729,7 @@ export class PreparedPiTurnAdapter {
           abortReason
             ? {
                 ...message,
-                content: [],
+                content: visibleAssistantContent(message),
                 stopReason: "aborted" as const,
                 errorMessage: abortReason,
               }

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

@@ -2,13 +2,19 @@ import {
   PreparedPiTurnAdapter,
   type CreatePreparedPiTurnOptions,
 } from "./execution";
+export { RetryableModelError } from "./execution";
 import {
   uiUserMessageToPi,
 } from "../message";
 import type { UIMessage } from "ai";
 import { createModels, type MutableModels } from "@earendil-works/pi-ai";
 import { configurePiModels, resolvePiApiKey } from "./models";
-export { withProviderRetry } from "./models";
+export {
+  MODEL_STREAM_STALL_TIMEOUT_MS,
+  modelRequestUrl,
+  readModelStreamStallDetails,
+  withProviderRetry,
+} from "./models";
 import {
   pinPiRuntime,
   preparePiRuntime,
@@ -148,7 +154,7 @@ export class PiRuntimeAdapter {
    * @remarks
    * 调用方：Runtime 的准入流程为每个新 Submission 调用，并把 descriptor 与其哈希一起持久化。
    *
-   * 实现理由：memory、workspace 和 Extension context 可能随时间变化，恢复必须使用准入时的描述符检查兼容性。
+   * 实现理由：memory、workspace 和 Extension context 可能随时间变化，所以把准入时的 Turn 字段保存在 descriptor 中。
    * 不要把 pin 推迟到 Turn 启动后，否则已持久化的 Submission 将失去可验证的执行基线。
    */
   pin(options: PinPiRuntimeOptions): Promise<PinnedPiRuntime> {
@@ -187,7 +193,7 @@ export class PiRuntimeAdapter {
    * @remarks
    * 调用方：Runtime 在首次执行和恢复继续时各创建一个新 Turn，并提供 canonical messages、durable Tool 回调和流事件回调。
    *
-   * 实现理由：构造时会校验 Prepared Runtime 的 owner、pinned descriptor 和 base revision，再建立本 Turn 独享的 Tool governance 与执行状态。
+   * 实现理由：构造时会校验 Prepared Runtime 的 owner 和 pinned descriptor 格式，再建立本 Turn 独享的 Tool governance 与执行状态。
    * 不要跨 Turn 复用返回对象；abort、steer、assistant ordinal 和 Tool governance 都是单次执行状态。
    */
   createTurn(