@springbrand/agent-runtime 0.1.0

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

@@ -0,0 +1,899 @@
+import {
+  Agent,
+  type Connection,
+  type FiberContext,
+  type FiberRecoveryContext,
+} from "agents";
+import {
+  ChatRecoveryEngine,
+  ContinuationState,
+  MessageType,
+  PreStreamTurns,
+  ResumableStream,
+  ResumeHandshake,
+  STREAM_CLEANUP_DELAY_SECONDS,
+  StreamProgressCreditThrottle,
+  buildChatRecoveringFrame,
+  bumpChatRecoveryProgress,
+  cleanupStreamBuffers,
+  createChatFiberSnapshot,
+  pendingChatTerminal,
+  readChatRecoveryProgress,
+  resolveChatRecoveryConfig,
+  runChatRecoveryExhaustion,
+  sendIfOpen,
+  setChatRecovering,
+  sweepStaleChatRecoveryIncidents,
+  unwrapChatFiberSnapshot,
+  wrapChatFiberSnapshot,
+  type ChatFiberWakeHooks,
+  type ChatRecoveryAdapter,
+  type ChatRecoveryConfig,
+  type ChatRecoveryIncident,
+  type ChatRecoveryIncidentEvent,
+  type ChatRecoveryScheduleCallback,
+  type ChatRecoveryScheduleReason,
+  type DispatchRecoveredTurnInput,
+  type RecoveryPartial,
+  type ResolvedRecoveryStream,
+} from "agents/chat";
+
+const RECOVERY_MESSAGE_TYPE = MessageType.CF_AGENT_CHAT_RECOVERING;
+
+// #region 本地工具与恢复协议类型
+
+// 把未知异常转成可持久化的简短文本；恢复回调记录失败原因时调用，且保留 Error.message 而不持久化不稳定的对象结构。
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// 把协议帧编码为 WebSocket 文本；发送和广播路径在输出前调用，以保持本文件只有一种编码方式。
+function json(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+/**
+ * 说明 Runtime 遇到一次中断对话时要采取的下一步。
+ *
+ * @remarks
+ * 恢复端口的 `classify` 在 Fiber 唤醒或孤立流重连时返回此类型。
+ *
+ * 调用方应仅在 `retry` 分支提供可重放的业务数据；其余分支只描述如何结束或记录本次恢复。
+ *
+ * 该联合类型让恢复策略留在具体 Runtime，而通用引擎只处理调度、事故状态和终态化。`Runtime` 与 `Port` 沿用 `../index.ts` 的统一术语。
+ */
+export type RuntimeRecoveryDecision<Data> =
+  | { readonly kind: "retry"; readonly data: Data }
+  | {
+      readonly kind: "park";
+      readonly reason: string;
+      readonly incidentStatus?: "skipped" | "failed";
+    }
+  | { readonly kind: "fail"; readonly reason: string }
+  | { readonly kind: "ignore"; readonly reason: string };
+
+/**
+ * 记录一次已执行恢复的最终结果。
+ *
+ * @remarks
+ * `_chatRecoveryRetry` 在调用端口的 `retry` 后读取该结果，并用它关闭对应的恢复事故。
+ *
+ * 只有失败时才需要 `error`；结果不承载流内容，避免在调度数据与流缓冲区之间复制状态。
+ */
+export interface RuntimeRecoveryResult {
+  readonly status: "completed" | "failed";
+  readonly error?: string;
+}
+
+/**
+ * 让通用对话恢复层调用具体 Runtime 的最小业务能力。
+ *
+ * @remarks
+ * 子类在 `createRecoveryPort` 中提供实现，本类在分类、重试、部分内容读取和耗尽处理时调用它。
+ *
+ * 实现应使 `requestId` 稳定地指向同一业务提交，并保持 `retry` 可被持久调度回调调用。这是 `../index.ts` 所述 `Port` 边界，不应把通用流恢复状态携回子类。
+ */
+export interface RuntimeRecoveryPort<Data> {
+  /**
+   * 判断一次中断对话应重试、停放、失败还是忽略。
+   *
+   * @remarks Fiber 恢复和孤立流处理会调用它；实现应只读取当前持久状态，把后续副作用交给返回分支的执行路径。
+   */
+  classify(requestId: string): Promise<RuntimeRecoveryDecision<Data>>;
+  /**
+   * 使用已分类的业务数据重放一次对话。
+   *
+   * @remarks 持久调度回调会调用它；实现应返回权威终态，而不是仅表示重试已启动。
+   */
+  retry(data: Data): Promise<RuntimeRecoveryResult>;
+  /**
+   * 把无法继续的对话写成用户可见的失败终态。
+   *
+   * @remarks 分类为 `fail` 或恢复次数耗尽时调用；实现必须更新业务持久状态，不能只发送临时消息。
+   */
+  terminalize(requestId: string, message: string): Promise<void>;
+  /**
+   * 从已持久的流块还原可保留的部分回答。
+   *
+   * @remarks 孤立流恢复和耗尽处理在读取缓冲区后调用；实现需要容忍不完整的最后一块。
+   */
+  readPartial(input: {
+    readonly requestId: string;
+    readonly chunks: readonly string[];
+  }): RecoveryPartial;
+  /**
+   * 判断新流块是否足以证明恢复进度向前推进。
+   *
+   * @remarks 每次追加流块时调用；实现应通过传入的 throttle 限制持久化频率，避免每个 token 都写 Durable Object 存储。
+   */
+  shouldCreditProgress(input: {
+    readonly body: string;
+    readonly throttle: StreamProgressCreditThrottle;
+    readonly now: number;
+  }): boolean;
+  /**
+   * 把运行时特有的部分段落收敛为耗尽处理能保存的文本段落。
+   *
+   * @remarks 恢复引擎准备失败终态时调用；返回值只允许 text 与 reasoning，防止未结算的工具状态越过边界。
+   */
+  toExhaustionParts(parts: readonly unknown[]): Array<{
+    readonly type: "text" | "reasoning";
+    readonly text: string;
+  }>;
+  /**
+   * 判断 Runtime 是否正在等待必须由用户完成的交互。
+   *
+   * @remarks 恢复引擎决定是否继续自动恢复时调用；实现应只反映权威业务状态，避免将等待审批误当成停滞。
+   */
+  isAwaitingInteraction(): boolean;
+}
+
+interface RecoverableChatAgentOptions {
+  readonly fiberPrefix: string;
+  readonly snapshotKey: string;
+  readonly snapshotKind: string;
+}
+
+interface RecoverableFiberInput<Data> {
+  readonly requestId: string;
+  readonly messageId?: string;
+  readonly continuation: boolean;
+  readonly messages: ReadonlyArray<{ id?: string; role: string }>;
+  readonly recoveryData: Data;
+}
+
+type RecoveryScheduleData<Data> = Data & {
+  readonly incidentId?: string;
+};
+
+// #endregion
+
+// #region 装配与子类契约
+
+/**
+ * 为具体 Runtime 提供与 Pi 无关的对话传输与恢复底座。
+ *
+ * @remarks
+ * `AgentRuntimeKernel` 在 Durable Object 实例构造时继承本类，并通过 `createRecoveryPort` 连接具体业务状态。
+ *
+ * 子类应通过受保护方法启动 Fiber、写入流和处理客户端续传，不应绕过这些入口自行维护并行恢复状态。
+ *
+ * 实现将流缓冲、续传握手、恢复事故、Fiber 快照、重试调度与清理收口到一处，防止具体 Runtime 各自保存一套会分叉的状态。`Runtime` 和 `Port` 的含义以 `../index.ts` 为准。
+ *
+ * @see https://developers.cloudflare.com/agents/runtime/execution/durable-execution/
+ * @see https://developers.cloudflare.com/agents/runtime/execution/schedule-tasks/
+ */
+export abstract class RecoverableChatAgent<
+  Env extends Cloudflare.Env,
+  State,
+  RecoveryData extends { requestId: string },
+> extends Agent<Env, State> {
+  /**
+   * 控制对话中断后是否启用自动恢复以及使用哪些限制。
+   *
+   * @remarks
+   * 恢复引擎在处理孤立 Fiber 和事故时读取该值；子类可在实例启动前覆盖它。
+   *
+   * 保留 Agents SDK 的 `boolean | config` 形状，避免本层创建第二套配置语义。
+   */
+  chatRecovery: ChatRecoveryConfig = true;
+
+  private readonly recoveryOptions: RecoverableChatAgentOptions;
+  private readonly resumableStream: ResumableStream;
+  private readonly progressThrottles = new Map<
+    string,
+    StreamProgressCreditThrottle
+  >();
+  private readonly continuation = new ContinuationState<Connection>();
+  private readonly preStream = new PreStreamTurns<Connection>();
+  private readonly pendingResumeConnections = new Set<string>();
+  private readonly resumeHandshake: ResumeHandshake;
+  private activeRecoveryRootRequestId: string | undefined;
+  private recoveryEngine?: ChatRecoveryEngine;
+  private runtimeRecoveryPort?: RuntimeRecoveryPort<RecoveryData>;
+
+  /**
+   * 为一个 Cloudflare Agent 实例建立可续传流与恢复握手状态。
+   *
+   * @remarks
+   * 只由具体 Runtime 构造器通过 `super` 调用；`options` 中的前缀、快照键和种类必须在该 Runtime 的所有版本中保持可识别。
+   *
+   * 构造期只连接 Agent 提供的 SQL、存储和连接查询，不执行恢复副作用；这保证对象唤醒时由正式回调驱动后续工作。
+   */
+  constructor(
+    ctx: DurableObjectState,
+    env: Env,
+    options: RecoverableChatAgentOptions,
+  ) {
+    super(ctx, env);
+    this.recoveryOptions = options;
+    this.resumableStream = new ResumableStream(this.sql.bind(this));
+    this.resumeHandshake = new ResumeHandshake({
+      responseMessageType: MessageType.CF_AGENT_USE_CHAT_RESPONSE,
+      resumableStream: this.resumableStream,
+      continuation: this.continuation,
+      preStream: this.preStream,
+      pendingResumeConnections: this.pendingResumeConnections,
+      pendingChatTerminal: () => pendingChatTerminal(this.ctx.storage),
+      persistOrphanedStream: (streamId) =>
+        this.recoverOrphanedStream(streamId),
+      isConnectionPresent: (connectionId) =>
+        this.getConnection(connectionId) !== undefined,
+    });
+  }
+
+  /**
+   * 创建连接通用恢复机制与具体 Runtime 状态的端口。
+   *
+   * @remarks
+   * 本类首次需要分类、重试或解析部分流时惰性调用；子类只需返回一个稳定实现。
+   *
+   * 实现由 `recoveryPort` 缓存，因此不能依赖每次调用都重新构建的短命状态。
+   */
+  protected abstract createRecoveryPort(): RuntimeRecoveryPort<RecoveryData>;
+
+  // 作用：惰性取得并缓存子类提供的恢复端口。
+  // 调用：Fiber、续传和调度恢复路径在访问恢复 I/O 时调用。
+  // 原因：同一 Agent 必须复用单例，避免策略状态分叉。
+  private recoveryPort(): RuntimeRecoveryPort<RecoveryData> {
+    return (this.runtimeRecoveryPort ??= this.createRecoveryPort());
+  }
+
+  // #endregion
+
+  // #region 可恢复轮次与流生命周期
+
+  /**
+   * 在可持久恢复的 Fiber 和可续传流中执行一次对话。
+   *
+   * @remarks
+   * 子类在业务提交进入模型或工具循环前调用，并在 `run` 中使用传入的 `streamId` 写入增量记录。
+   *
+   * 该方法先固定快照和恢复根请求，再启动流；这个顺序使 Agent 被中断后能把 Fiber、流和业务提交重新关联。不要在子类中另外创建同一轮次的恢复快照。
+   *
+   * @see https://developers.cloudflare.com/agents/runtime/execution/durable-execution/
+   */
+  protected async runRecoverableChatFiber(
+    input: RecoverableFiberInput<RecoveryData>,
+    run: (fiber: FiberContext, streamId: string) => Promise<void>,
+  ): Promise<void> {
+    const snapshot = createChatFiberSnapshot({
+      kind: this.recoveryOptions.snapshotKind,
+      requestId: input.requestId,
+      recoveryRootRequestId:
+        this.activeRecoveryRootRequestId ?? input.requestId,
+      continuation: input.continuation,
+      messages: input.messages,
+    });
+    await this._runFiberWithStashWrapper(
+      this.recoveryOptions.fiberPrefix + input.requestId,
+      async (fiber) => {
+        const streamId = this.startRecoverableStream(input.requestId, {
+          ...(input.messageId === undefined
+            ? {}
+            : { messageId: input.messageId }),
+          continuation: input.continuation,
+        });
+        try {
+          await run(fiber, streamId);
+        } finally {
+          this.progressThrottles.delete(streamId);
+        }
+      },
+      {
+        initialSnapshot: wrapChatFiberSnapshot(
+          this.recoveryOptions.snapshotKey,
+          snapshot,
+          input.recoveryData,
+        ),
+        wrapStash: (data) =>
+          wrapChatFiberSnapshot(
+            this.recoveryOptions.snapshotKey,
+            snapshot,
+            data,
+          ),
+      },
+    );
+  }
+
+  /**
+   * 把一块对话输出追加到可续传流，并在值得时记录恢复进度。
+   *
+   * @remarks
+   * 子类在向客户端广播每个已结构化的流记录前调用；`streamId` 必须来自 `runRecoverableChatFiber` 的当前回调。
+   *
+   * 流块每次都先进缓冲区，但持久化进度由端口节流；这避免逐 token 写存储，同时让停滞检测看到有意义的前进。
+   */
+  protected async appendRecoverableChunk(
+    streamId: string,
+    body: string,
+  ): Promise<void> {
+    this.resumableStream.storeChunk(streamId, body);
+    let throttle = this.progressThrottles.get(streamId);
+    if (!throttle) {
+      throttle = new StreamProgressCreditThrottle();
+      this.progressThrottles.set(streamId, throttle);
+    }
+    if (this.recoveryPort().shouldCreditProgress({
+      body,
+      throttle,
+      now: Date.now(),
+    })) {
+      this.resumableStream.flushBuffer();
+      await bumpChatRecoveryProgress(this.ctx.storage);
+    }
+  }
+
+  /**
+   * 把可续传流标记为成功完成并安排延后清理。
+   *
+   * @remarks
+   * 子类只在对应业务提交已提交权威成功终态后调用；不要用它表示“暂无更多块”。
+   *
+   * 清理延后执行，为断线重连的客户端保留终态流片段。
+   */
+  protected completeRecoverableStream(streamId: string): void {
+    this.resumableStream.complete(streamId);
+    void this.ensureStreamCleanupScheduled();
+  }
+
+  /**
+   * 把可续传流标记为失败并安排延后清理。
+   *
+   * @remarks
+   * 子类在轮次失败、取消或未形成权威助手终态时调用；调用后仍应由业务层写入失败终态。
+   *
+   * 流错误标志与业务失败分开，因为续传协议和提交生命周期的责任不同。
+   */
+  protected failRecoverableStream(streamId: string): void {
+    this.resumableStream.markError(streamId);
+    void this.ensureStreamCleanupScheduled();
+  }
+
+  /**
+   * 结算一个尚未建立流的对话请求。
+   *
+   * @remarks
+   * 子类在提交执行结束的 `finally` 路径调用，以便无论流是否真正开始都能释放等待续传的连接。
+   *
+   * 只在没有活动流时批量释放等待者，避免把尚可续传的轮次误判为结束。
+   */
+  protected settlePreStream(requestId: string): void {
+    if (
+      this.preStream.settle(requestId) &&
+      !this.resumableStream.hasActiveStream()
+    ) {
+      this.preStream.releaseAwaiting();
+    }
+  }
+
+  /**
+   * 记录一个已接收但尚未建立可续传流的请求。
+   *
+   * @remarks
+   * 子类在接受客户端提交后立即调用，且必须使用与后续 Fiber 相同的 `requestId`。
+   *
+   * 单独记录这个窗口，是为了让刚提交就断线的客户端也能等到流启动，而不是过早放弃续传。
+   */
+  protected beginPreStream(requestId: string): void {
+    this.preStream.begin(requestId);
+  }
+
+  /**
+   * 删除当前 Agent 保存的所有可续传流数据。
+   *
+   * @remarks
+   * 子类只在用户明确清空且业务数据同处一事务边界时调用；不应将它用作单个轮次的常规清理。
+   *
+   * 使用 `ResumableStream.clearAll` 与业务清空收口，防止聊天记录已删除但旧流仍可重放。
+   */
+  protected clearRecoverableStreamStorage(): void {
+    this.resumableStream.clearAll();
+  }
+
+  /**
+   * 重置当前内存中的续传连接、继续状态和流前请求。
+   *
+   * @remarks
+   * 子类在持久聊天数据已成功清空后调用；它不删除流表，因此通常与 `clearRecoverableStreamStorage` 成对使用。
+   *
+   * 独立清理内存状态能避免已失效连接在清空后继续收到旧轮次的续传信号。
+   */
+  protected clearRecoverableChatState(): void {
+    this.pendingResumeConnections.clear();
+    this.continuation.clearAll();
+    this.preStream.reset();
+  }
+
+  // #endregion
+
+  // #region 客户端连接与续传协议
+
+  /**
+   * 处理客户端发起的流续传探测。
+   *
+   * @remarks
+   * 子类在收到 `stream-resume-request` 协议消息时调用，并原样传入当前连接与可选 probe id。
+   *
+   * 所有握手状态由 `ResumeHandshake` 集中管理，避免子类自行判断流、流前请求和终态之间的优先级。
+   */
+  protected handleResumeRequest(
+    connection: Connection,
+    probeId?: string,
+  ): Promise<void> {
+    return this.resumeHandshake.handleResumeRequest(connection, probeId);
+  }
+
+  /**
+   * 处理客户端对某次续传的确认。
+   *
+   * @remarks
+   * 子类在收到 `stream-resume-ack` 协议消息时调用，并使用该消息的请求 id 结算握手。
+   *
+   * 确认由 `ResumeHandshake` 统一释放暂存的连接状态，不能与普通聊天响应的 `done` 信号混用。
+   */
+  protected handleResumeAck(
+    connection: Connection,
+    requestId: string,
+  ): Promise<void> {
+    return this.resumeHandshake.handleResumeAck(connection, requestId);
+  }
+
+  /**
+   * 向当前可用的聊天连接广播一帧轮次响应。
+   *
+   * @remarks
+   * 子类在发送增量记录、成功终态或失败终态时调用；`done` 表示轮次终态，`error` 只在终态失败时设置。
+   *
+   * 广播显式排除正在续传握手的连接，避免它们在历史流重放完成前同时收到实时帧。
+   */
+  protected sendChatResponse(
+    requestId: string,
+    body: string,
+    done: boolean,
+    error = false,
+  ): void {
+    this.broadcast(
+      json({
+        type: MessageType.CF_AGENT_USE_CHAT_RESPONSE,
+        id: requestId,
+        body,
+        done,
+        ...(error ? { error: true } : {}),
+      }),
+      [...this.pendingResumeConnections],
+    );
+  }
+
+  /**
+   * 在新连接建立时同步当前恢复状态并启动续传通知。
+   *
+   * @remarks
+   * Agents SDK 在 WebSocket 连接建立后调用；子类覆盖时应调用 `super.onConnect`，否则新客户端无法得知已在进行的恢复。
+   *
+   * 先发送持久化的 recovering 帧，再通知流重放，使客户端先建立正确的界面状态。
+   */
+  async onConnect(connection: Connection): Promise<void> {
+    const recovering = await buildChatRecoveringFrame(
+      this.ctx.storage,
+      RECOVERY_MESSAGE_TYPE,
+      Date.now(),
+    );
+    if (recovering) sendIfOpen(connection, json(recovering));
+    this.resumeHandshake.notifyStreamResuming(connection);
+  }
+
+  /**
+   * 在连接关闭时释放该连接持有的续传和流前等待状态。
+   *
+   * @remarks
+   * Agents SDK 在 WebSocket 断开时调用；子类覆盖时应调用 `super.onClose`。
+   *
+   * 此处只清理按 connection id 索引的内存状态，不删除持久流，因为断线正是续传需要保留数据的场景。
+   */
+  onClose(
+    connection: Connection,
+    _code: number,
+    _reason: string,
+    _wasClean: boolean,
+  ): void {
+    this.pendingResumeConnections.delete(connection.id);
+    this.continuation.releaseConnection(connection.id);
+    this.preStream.release(connection.id);
+  }
+
+  // #endregion
+
+  // #region Fiber 恢复分类与重试调度
+
+  /**
+   * 执行一次已持久调度的对话重试，并结算对应恢复事故。
+   *
+   * @remarks
+   * Agents SDK 的调度器在 `dispatchRecoveredTurn` 创建的延时任务到期时按方法名调用；它是框架回调，不是供子类直接触发的重试入口。
+   *
+   * 执行期间暂存恢复根请求，使重试内新建的 Fiber 仍归属原始事故；`finally` 必须恢复旧值，否则后续正常轮次会被错误关联。
+   *
+   * @see https://developers.cloudflare.com/agents/runtime/execution/schedule-tasks/
+   */
+  async _chatRecoveryRetry(
+    data?: RecoveryScheduleData<RecoveryData>,
+  ): Promise<void> {
+    if (!data) return;
+    const previous = this.activeRecoveryRootRequestId;
+    this.activeRecoveryRootRequestId = data.requestId;
+    try {
+      const result = await this.recoveryPort().retry(data);
+      await this.engine().updateIncident(
+        data.incidentId,
+        result.status === "completed" ? "completed" : "failed",
+        result.status === "completed"
+          ? undefined
+          : result.error ?? "Chat recovery failed",
+      );
+    } catch (error) {
+      await this.engine().updateIncident(
+        data.incidentId,
+        "failed",
+        errorText(error),
+      );
+      throw error;
+    } finally {
+      this.activeRecoveryRootRequestId = previous;
+    }
+  }
+
+  /**
+   * 把 Agents SDK 发现的孤立 Fiber 交给聊天恢复引擎。
+   *
+   * @remarks
+   * Agent 在 Durable Object 重新激活并扫描到未完成 Fiber 时调用；返回值表示该 Fiber 是否由聊天恢复路径接管。
+   *
+   * 所有快照解包、分类与重试派发都经过同一引擎，避免 SDK 唤醒与客户端续传各用一套恢复规则。
+   *
+   * @see https://developers.cloudflare.com/agents/runtime/execution/durable-execution/
+   */
+  protected override async _handleInternalFiberRecovery(
+    context: FiberRecoveryContext,
+  ): Promise<boolean> {
+    return this.engine().handleChatFiberRecovery<
+      RuntimeRecoveryDecision<RecoveryData>
+    >(context, this.wakeHooks());
+  }
+
+  // 作用：组装 Fiber 唤醒需要的回调。
+  // 调用：内部恢复入口每次处理恢复上下文时调用。
+  // 原因：单一适配器可以统一快照解包、分类和派发边界。
+  private wakeHooks(): ChatFiberWakeHooks<
+    RuntimeRecoveryDecision<RecoveryData>
+  > {
+    return {
+      chatFiberPrefix: () => this.recoveryOptions.fiberPrefix,
+      unwrapRecoverySnapshot: (context) => {
+        const { snapshot, user } = unwrapChatFiberSnapshot(
+          this.recoveryOptions.snapshotKey,
+          context.snapshot,
+          this.recoveryOptions.snapshotKind,
+        );
+        return { snapshot, recoveryData: user };
+      },
+      classifyRecoveredTurn: async (input) => ({
+        recoveryKind: "retry",
+        detail: await this.recoveryPort().classify(
+          input.snapshot?.requestId ?? input.requestId,
+        ),
+      }),
+      shouldPersistOrphanedPartial: (input) => input.streamStillActive,
+      persistOrphanedStream: async () => {},
+      completeRecoveredStream: (streamId) => {
+        this.completeRecoverableStream(streamId);
+      },
+      dispatchRecoveredTurn: (input) =>
+        this.dispatchRecoveredTurn(input),
+    };
+  }
+
+  // 作用：把已分类的恢复决策落到事故终态或持久调度。
+  // 调用：唤醒回调在恢复分类完成后调用。
+  // 原因：单一分支点可以防止各入口对 retry、park、fail 和 ignore 的解释分叉。
+  private async dispatchRecoveredTurn(
+    input: DispatchRecoveredTurnInput<
+      RuntimeRecoveryDecision<RecoveryData>
+    >,
+  ): Promise<void> {
+    const decision = input.detail;
+    if (decision.kind === "park") {
+      await this.engine().updateIncident(
+        input.incident.incidentId,
+        decision.incidentStatus ?? "skipped",
+        decision.reason,
+      );
+      return;
+    }
+    if (decision.kind === "ignore") {
+      await this.engine().updateIncident(
+        input.incident.incidentId,
+        "completed",
+        decision.reason,
+      );
+      return;
+    }
+    if (decision.kind === "fail") {
+      await this.recoveryPort().terminalize(
+        input.recoveryRootRequestId,
+        decision.reason,
+      );
+      await this.engine().updateIncident(
+        input.incident.incidentId,
+        "failed",
+        decision.reason,
+      );
+      return;
+    }
+    await this.engine().scheduleRecovery({
+      incident: input.incident,
+      recoveryKind: "retry",
+      callback: "_chatRecoveryRetry",
+      data: {
+        ...decision.data,
+        incidentId: input.incident.incidentId,
+      },
+    });
+  }
+
+  // #endregion
+
+  // #region 恢复引擎适配与事故记账
+
+  // 作用：惰性取得并缓存聊天恢复引擎。
+  // 调用：Fiber、续传和调度路径在处理恢复事故时调用。
+  // 原因：共用单例可以保持事故处理只有一个统一入口。
+  private engine(): ChatRecoveryEngine {
+    return (this.recoveryEngine ??= new ChatRecoveryEngine(
+      this.recoveryAdapter(),
+    ));
+  }
+
+  // 作用：把 Agent 的存储、调度、事件与流能力映射给恢复引擎。
+  // 调用：恢复引擎在首次惰性初始化时调用。
+  // 原因：适配边界可以避免恢复策略直接依赖具体 Durable Object 类。
+  private recoveryAdapter(): ChatRecoveryAdapter {
+    return {
+      resolveConfig: () => resolveChatRecoveryConfig(this.chatRecovery),
+      now: () => Date.now(),
+      sweepStaleIncidents: (now) =>
+        sweepStaleChatRecoveryIncidents(this.ctx.storage, now),
+      getIncident: (key) =>
+        this.ctx.storage
+          .get<ChatRecoveryIncident>(key)
+          .then((value) => value ?? null),
+      readProgress: () => readChatRecoveryProgress(this.ctx.storage),
+      isAwaitingClientInteraction: () =>
+        this.recoveryPort().isAwaitingInteraction(),
+      putIncident: (key, incident) =>
+        this.ctx.storage.put(key, incident),
+      deleteIncident: (key) =>
+        this.ctx.storage.delete(key).then(() => {}),
+      emitRecoveryEvent: (event: ChatRecoveryIncidentEvent) =>
+        this._emit(event.type, { ...event }),
+      scheduleRecovery: async (
+        callback: ChatRecoveryScheduleCallback,
+        data: Record<string, unknown>,
+        reason: ChatRecoveryScheduleReason,
+        delaySeconds: number,
+      ) => {
+        await this.schedule(
+          delaySeconds,
+          callback as keyof this,
+          data,
+          { idempotent: reason === "initial" },
+        );
+      },
+      setRecovering: (active, requestId) =>
+        this.setRecovering(active, requestId),
+      onShouldKeepRecoveringError: (error) =>
+        console.error("[chat-recovery] shouldKeepRecovering threw", error),
+      exhaustChatRecovery: (
+        incident,
+        config,
+        partial,
+        streamId,
+        createdAt,
+      ) =>
+        runChatRecoveryExhaustion(
+          {
+            incident,
+            config,
+            partialText: partial.text,
+            partialParts: this.recoveryPort().toExhaustionParts(
+              partial.parts,
+            ),
+            streamId,
+            createdAt,
+          },
+          {
+            emit: (context) =>
+              this._emit("chat:recovery:exhausted", { ...context }),
+            onError: (error) =>
+              console.error("[chat-recovery] onExhausted threw", error),
+            terminalize: async (context) => {
+              await this.recoveryPort().terminalize(
+                context.recoveryRootRequestId ?? context.requestId,
+                context.terminalMessage,
+              );
+              await this.setRecovering(false, context.requestId);
+            },
+          },
+        ),
+      resolveRecoveryStream: (requestId): ResolvedRecoveryStream => {
+        const streamId = this.resolveStreamId(requestId);
+        return {
+          streamId,
+          streamStillActive:
+            streamId !== "" &&
+            streamId === this.resumableStream.activeStreamId,
+        };
+      },
+      getPartialStreamText: (streamId): RecoveryPartial => {
+        const metadata = this.resumableStream.getStreamMetadata(streamId);
+        return this.recoveryPort().readPartial({
+          requestId: metadata?.request_id ?? "",
+          chunks: this.resumableStream
+            .getStreamChunks(streamId)
+            .map((chunk) => chunk.body),
+        });
+      },
+      activeChatRecoveryRootRequestId: () =>
+        this.activeRecoveryRootRequestId,
+      onGiveUpBookkeepingError: (phase, error) =>
+        console.error(`[chat-recovery] give-up ${phase} error`, error),
+    };
+  }
+
+  // 作用：查找请求当前或最新的可恢复流。
+  // 调用：恢复适配器在关联事故与流时调用。
+  // 原因：先取内存活动流、再回退到持久元数据，才能覆盖 Durable Object 重启。
+  private resolveStreamId(requestId: string): string {
+    if (
+      this.resumableStream.activeRequestId === requestId &&
+      this.resumableStream.activeStreamId
+    ) {
+      return this.resumableStream.activeStreamId;
+    }
+    const metadata = this.resumableStream
+      .getAllStreamMetadata()
+      .filter((row) => row.request_id === requestId)
+      .sort((left, right) => right.created_at - left.created_at)[0];
+    return metadata?.id ?? "";
+  }
+
+  // 作用：持久化恢复标志并通知所有客户端。
+  // 调用：恢复引擎与孤立流处理在状态切换时调用。
+  // 原因：共享方法能保证持久状态和客户端协议帧同步变化。
+  private setRecovering(
+    active: boolean,
+    requestId?: string,
+  ): Promise<void> {
+    return setChatRecovering(active, requestId, {
+      storage: this.ctx.storage,
+      messageType: RECOVERY_MESSAGE_TYPE,
+      broadcast: (frame) => this.broadcast(json(frame)),
+      now: Date.now(),
+    });
+  }
+
+  // 作用：恢复已有部分输出、但没有活动执行者的孤立流。
+  // 调用：续传握手层在发现孤立流时调用。
+  // 原因：只对可重试的非空部分流开启后台重放，避免无进度请求被误恢复。
+  private async recoverOrphanedStream(streamId: string): Promise<void> {
+    const metadata = this.resumableStream.getStreamMetadata(streamId);
+    if (!metadata) return;
+    const partial = this.recoveryPort().readPartial({
+      requestId: metadata.request_id,
+      chunks: this.resumableStream
+        .getStreamChunks(streamId)
+        .map((chunk) => chunk.body),
+    });
+    if (
+      partial.text.length === 0 &&
+      partial.parts.length === 0 &&
+      !partial.hasSettledToolResults
+    ) {
+      return;
+    }
+    const decision = await this.recoveryPort().classify(
+      metadata.request_id,
+    );
+    if (decision.kind === "fail") {
+      await this.recoveryPort().terminalize(
+        metadata.request_id,
+        decision.reason,
+      );
+      return;
+    }
+    if (decision.kind !== "retry") return;
+    await this.setRecovering(true, metadata.request_id);
+    // TODO(待确认): Cloudflare 文档说 DurableObjectState.waitUntil 不延长对象生命期；需确认此处是否只为保持调用形式一致。
+    this.ctx.waitUntil(
+      this.recoveryPort()
+        .retry(decision.data)
+        .finally(() => this.setRecovering(false, metadata.request_id)),
+    );
+  }
+
+  // #endregion
+
+  // #region 流启动与延后清理
+
+  // 作用：为请求建立可续传流并释放流前等待者。
+  // 调用：可恢复 Fiber 真正开始执行时调用。
+  // 原因：握手切换和清理调度必须从同一入口启动。
+  private startRecoverableStream(
+    requestId: string,
+    options: {
+      readonly messageId?: string;
+      readonly continuation?: boolean;
+    } = {},
+  ): string {
+    const streamId = this.resumableStream.start(requestId, options);
+    this.preStream.settle(requestId);
+    this.preStream.flushOnStreamStart((connection) =>
+      this.resumeHandshake.notifyStreamResuming(connection),
+    );
+    void this.ensureStreamCleanupScheduled();
+    return streamId;
+  }
+
+  // 作用：确保存在一个未来执行的流缓冲清理任务。
+  // 调用：流开始、完成、失败或清理回调需要续排时调用。
+  // 原因：首次幂等去重可防止重复调度，而回调续排必须明确创建下一个任务。
+  private async ensureStreamCleanupScheduled(
+    { idempotent = true }: { idempotent?: boolean } = {},
+  ): Promise<void> {
+    await this.schedule(
+      STREAM_CLEANUP_DELAY_SECONDS,
+      "_cleanupStreamBuffers",
+      undefined,
+      { idempotent },
+    );
+  }
+
+  /**
+   * 删除已过期的流缓冲区，并在仍有数据需保留时续排下一次清理。
+   *
+   * @remarks
+   * Agents SDK 的调度器在 `ensureStreamCleanupScheduled` 创建的延时任务到期时按方法名调用；它是公开的框架回调，不是业务层手动清空入口。
+   *
+   * 实际保留策略由 `cleanupStreamBuffers` 和 SDK 常量决定；本层只负责把持久调度回接到清理算法，不应另外引入第二个保留时钟。
+   *
+   * @see https://developers.cloudflare.com/agents/runtime/execution/schedule-tasks/
+   */
+  async _cleanupStreamBuffers(): Promise<void> {
+    await cleanupStreamBuffers(
+      this.resumableStream,
+      () => this.ensureStreamCleanupScheduled({ idempotent: false }),
+    );
+  }
+
+  // #endregion
+}