@springbrand/agent-runtime 0.1.0

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

@@ -0,0 +1,805 @@
+import {
+  applyRecoveredPiApprovalDecision,
+  commitPiRecoveryContinuation,
+  encodePiToolRecoveryMilestone,
+  planPiToolRecovery,
+  replayPiToolRecovery,
+  stagePiRecoveryContinuation,
+  type PiToolApproval,
+  type PiToolRecoveryMilestone,
+  type PiToolRecoveryPlan,
+  type PiToolRecoveryState,
+} from "../turn";
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import {
+  aiSdkRecoveryCodec,
+  shouldCreditStreamProgress,
+  type StreamProgressCreditThrottle,
+} from "agents/chat";
+import type { PiToolInputRecord } from "./execution";
+import type {
+  RuntimeRecoveryPort,
+  RuntimeRecoveryResult,
+} from "../../kernel/recoverable-chat-agent";
+
+export interface PiRecoveryIdentity {
+  readonly turnId: string;
+  readonly assemblyRevision: string;
+}
+
+export interface PiRecoveredToolSettlement {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly result: {
+    readonly content: ToolResultMessage["content"];
+    readonly details: unknown;
+  };
+  readonly isError: boolean;
+  readonly createdAt: number;
+}
+
+export type PiRecoveryCommand =
+  | { readonly kind: "inspect" }
+  | {
+      readonly kind: "approval-decision";
+      readonly executionId: string;
+      readonly approved: boolean;
+      readonly reason?: string;
+    }
+  | {
+      readonly kind: "record-tool-input";
+      readonly record: PiToolInputRecord;
+    }
+  | {
+      readonly kind: "record-approval";
+      readonly approval: PiToolApproval;
+    }
+  | {
+      readonly kind: "record-tool-result";
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly result: {
+        readonly content: ToolResultMessage["content"];
+        readonly details: unknown;
+      };
+      readonly isError: boolean;
+      readonly timestamp: number;
+      readonly needsContinuation?: boolean;
+    }
+  | {
+      readonly kind: "record-terminal";
+      readonly phase: "intent" | "committed";
+      readonly outcome: "succeeded" | "failed" | "aborted";
+      readonly message?: string;
+    }
+  | {
+      readonly kind: "commit-continuation";
+      readonly continuationKey: string;
+    };
+
+export interface PiRecoveryInput {
+  readonly milestoneBodies: readonly string[];
+  readonly identity?: PiRecoveryIdentity;
+  readonly command: PiRecoveryCommand;
+  readonly now: number;
+}
+
+export interface PiRecoveryDecision {
+  readonly applied: boolean;
+  readonly mutations: readonly PiDurableMutation[];
+  readonly effect: PiRecoveryEffect;
+  readonly recoveredToolSettlements: readonly PiRecoveredToolSettlement[];
+  readonly terminal?: {
+    readonly outcome: "succeeded" | "failed" | "aborted";
+    readonly message?: string;
+    readonly committed: boolean;
+  };
+}
+
+export type PiDurableMutation =
+  | {
+      readonly kind: "append-milestone";
+      readonly key: string;
+      readonly body: string;
+    }
+  | {
+      readonly kind: "decide-approval";
+      readonly executionId: string;
+      readonly status: "approved" | "rejected";
+      readonly decidedAt: number;
+      readonly reason?: string;
+    };
+
+export type PiRecoveryEffect =
+  | {
+      readonly kind: "retry-tool";
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly input: unknown;
+    }
+  | {
+      readonly kind: "schedule-continuation";
+      readonly continuationKey: string;
+      readonly approvalExecutionId: string;
+      readonly idempotencyKey: string;
+    }
+  | {
+      readonly kind: "finish";
+      readonly outcome: "succeeded" | "failed" | "aborted";
+      readonly message?: string;
+    }
+  | {
+      readonly kind: "wait";
+      readonly reason?: "approval" | "uncertain-tool" | "complete";
+    }
+  | { readonly kind: "resume-turn" };
+
+// #region Recovery state and plan helpers
+
+// 把一个恢复里程碑包装成 Runtime 可以持久化的追加操作。
+// decidePiRecovery 在生成工具、审批、续跑和终态记录时统一调用它。
+// 编码集中在这里可保证写入键与恢复重放使用同一种格式。
+function milestoneMutation(
+  key: string,
+  milestone: PiToolRecoveryMilestone,
+): Extract<PiDurableMutation, { kind: "append-milestone" }> {
+  return {
+    kind: "append-milestone",
+    key,
+    body: encodePiToolRecoveryMilestone(milestone),
+  };
+}
+
+// 取出当前 Turn 与装配版本，供新里程碑标明自己属于哪次执行。
+// decidePiRecovery 只在需要追加里程碑的命令路径调用它。
+// 缺少身份时立即失败，避免把无归属的记录混入另一次 Turn 的恢复日志。
+function recoveryIdentity(input: PiRecoveryInput) {
+  if (!input.identity) {
+    throw new Error("Pi recovery command is missing its Turn revision");
+  }
+  return { version: 1 as const, ...input.identity };
+}
+
+// 把重放得到的规范工具结果还原成持久化 settlement 所需的完整形状。
+// decidePiRecovery 每次返回决策时调用它，Runtime 随后补齐可能漏写的 settlement 和 transcript。
+// 输入优先取 tool-input 里程碑；若记录中只有审批，则从其 inputJson 回退，兼容两种已存在的数据来源。
+function recoveredToolSettlements(
+  state: PiToolRecoveryState,
+): PiRecoveredToolSettlement[] {
+  return state.canonicalToolResults.map((toolResult) => {
+    const tool = state.toolCalls[toolResult.toolCallId];
+    const approval = Object.values(state.approvals).find(
+      (item) => item.toolCallId === toolResult.toolCallId,
+    );
+    return {
+      toolCallId: toolResult.toolCallId,
+      toolName: toolResult.toolName,
+      args:
+        tool?.input ??
+        (approval ? JSON.parse(approval.inputJson) : {}),
+      result: {
+        content: toolResult.content,
+        details: toolResult.details,
+      },
+      isError: toolResult.isError,
+      createdAt: toolResult.timestamp,
+    };
+  });
+}
+
+// 从审批续跑键中读出原审批执行编号。
+// fromDispatch 用它判断续跑应交给审批调度器还是直接恢复 Turn。
+// 严格匹配 approve 和 reject 两种既有键形状，普通工具续跑键不会被误当成审批。
+function approvalExecutionId(continuationKey: string): string | null {
+  const match = /^approval:(.+):(approve|reject)$/.exec(
+    continuationKey,
+  );
+  return match?.[1] ?? null;
+}
+
+// 把纯恢复计划翻译成持久化操作和 Runtime 下一步动作。
+// decidePiRecovery 在命令应用并重放最新状态后调用它。
+// pending 续跑必须先形成里程碑并重放，再允许 dispatch，避免外部动作早于可恢复状态落盘。
+function fromPlan(
+  state: PiToolRecoveryState,
+  plan: PiToolRecoveryPlan,
+  now: number,
+  bodies: readonly string[],
+): Pick<PiRecoveryDecision, "mutations" | "effect"> {
+  switch (plan.kind) {
+    case "retry-tool":
+      return {
+        mutations: [],
+        effect: {
+          kind: "retry-tool",
+          toolCallId: plan.toolCallId,
+          toolName: plan.toolName,
+          input: plan.input,
+        },
+      };
+    case "parked-approval":
+      return {
+        mutations: [],
+        effect: { kind: "wait", reason: "approval" },
+      };
+    case "park-uncertain-tool":
+      return {
+        mutations: [],
+        effect: { kind: "wait", reason: "uncertain-tool" },
+      };
+    case "persist-terminal":
+      return {
+        mutations: [],
+        effect: {
+          kind: "finish",
+          outcome: plan.outcome,
+          ...(plan.message === undefined
+            ? {}
+            : { message: plan.message }),
+        },
+      };
+    case "complete":
+      return {
+        mutations: [],
+        effect: { kind: "wait", reason: "complete" },
+      };
+    case "idle":
+      return { mutations: [], effect: { kind: "resume-turn" } };
+    case "persist-continuation": {
+      const staged = stagePiRecoveryContinuation(state, plan, now);
+      if (!staged) {
+        return { mutations: [], effect: { kind: "wait" } };
+      }
+      const pending = milestoneMutation(
+        `continuation:${plan.continuationKey}:pending`,
+        staged,
+      );
+      const nextState = replayPiToolRecovery([
+        ...bodies,
+        pending.body,
+      ]);
+      const dispatch = planPiToolRecovery(nextState);
+      if (dispatch.kind !== "dispatch-continuation") {
+        return { mutations: [pending], effect: { kind: "wait" } };
+      }
+      return fromDispatch(nextState, dispatch, now, [pending]);
+    }
+    case "dispatch-continuation":
+      return fromDispatch(state, plan, now, []);
+  }
+}
+
+// 把已进入 dispatch 阶段的续跑计划交给正确的执行通道。
+// fromPlan 处理新暂存的续跑和已暂存的续跑时都会调用它。
+// 审批续跑保留给幂等调度；普通工具续跑先生成 committed 里程碑再返回 resume-turn，二者不能合并。
+function fromDispatch(
+  state: PiToolRecoveryState,
+  plan: Extract<
+    PiToolRecoveryPlan,
+    { kind: "dispatch-continuation" }
+  >,
+  now: number,
+  mutations: PiDurableMutation[],
+): Pick<PiRecoveryDecision, "mutations" | "effect"> {
+  const executionId = approvalExecutionId(plan.continuationKey);
+  if (executionId) {
+    return {
+      mutations,
+      effect: {
+        kind: "schedule-continuation",
+        continuationKey: plan.continuationKey,
+        approvalExecutionId: executionId,
+        idempotencyKey: plan.idempotencyKey,
+      },
+    };
+  }
+  const committed = commitPiRecoveryContinuation(state, plan, now);
+  return {
+    mutations: committed
+      ? [
+          ...mutations,
+          milestoneMutation(
+            `continuation:${plan.continuationKey}:committed`,
+            committed,
+          ),
+        ]
+      : mutations,
+    effect: { kind: "resume-turn" },
+  };
+}
+
+// #endregion
+
+// #region Recovery decision
+
+/**
+ * 重放持久化里程碑，应用一条恢复命令，并算出下一批写入和后续动作。
+ *
+ * `PiRuntimeAdapter.decideRecovery` 在记录工具、审批、终态、续跑以及启动检查时调用它。
+ *
+ * 这里保持纯计算并只返回 mutations 和 effect；调用方必须先持久化 mutations，再执行 effect，不能把 I/O 搬进来破坏可重放性。
+ */
+export function decidePiRecovery(
+  input: PiRecoveryInput,
+): PiRecoveryDecision {
+  let bodies = [...input.milestoneBodies];
+  let state = replayPiToolRecovery(bodies);
+  const mutations: PiDurableMutation[] = [];
+  let applied = false;
+
+  if (input.command.kind === "approval-decision") {
+    const command = input.command;
+    const decision = applyRecoveredPiApprovalDecision(state, {
+      executionId: command.executionId,
+      decision: command.approved ? "approve" : "reject",
+      decidedAt: input.now,
+      reason: command.reason,
+    });
+    applied = decision.outcome.kind !== "noop";
+    if (applied) {
+      const approval = decision.milestones.find(
+        (milestone) => milestone.type === "approval",
+      );
+      if (!approval || approval.type !== "approval") {
+        throw new Error("Pi approval decision milestone is missing");
+      }
+      mutations.push({
+        kind: "decide-approval",
+        executionId: approval.approval.executionId,
+        status: approval.approval.status as "approved" | "rejected",
+        decidedAt: approval.approval.decidedAt ?? input.now,
+        ...(approval.approval.reason === undefined
+          ? {}
+          : { reason: approval.approval.reason }),
+      });
+      decision.milestones.forEach((milestone, index) => {
+        mutations.push(milestoneMutation(
+          milestone.type === "approval"
+            ? `approval:${command.executionId}:${approval.approval.status}`
+            : `approval-result:${command.executionId}:${index}`,
+          milestone,
+        ));
+      });
+      bodies = [
+        ...bodies,
+        ...decision.milestones.map(encodePiToolRecoveryMilestone),
+      ];
+      state = replayPiToolRecovery(bodies);
+    }
+  }
+  if (input.command.kind === "record-tool-input") {
+    const record = input.command.record;
+    const existing = state.toolCalls[record.toolCallId];
+    if (existing) {
+      if (
+        existing.toolName !== record.toolName ||
+        existing.retry !== record.retry ||
+        JSON.stringify(existing.input) !== JSON.stringify(record.input)
+      ) {
+        throw new Error(
+          `Conflicting Pi Tool input for ${record.toolCallId}`,
+        );
+      }
+    } else {
+      const mutation = milestoneMutation(
+        `tool-input:${record.toolCallId}`,
+        {
+          ...recoveryIdentity(input),
+          type: "tool-input",
+          ...record,
+        },
+      );
+      mutations.push(mutation);
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "record-approval") {
+    const approval = input.command.approval;
+    const existing = state.approvals[approval.executionId];
+    if (existing) {
+      if (
+        existing.requestId !== approval.requestId ||
+        existing.toolCallId !== approval.toolCallId ||
+        existing.toolName !== approval.toolName ||
+        existing.inputJson !== approval.inputJson
+      ) {
+        throw new Error(
+          `Conflicting Pi Tool approval: ${approval.executionId}`,
+        );
+      }
+    } else {
+      const mutation = milestoneMutation(
+        `approval:${approval.executionId}:${approval.status}`,
+        {
+          ...recoveryIdentity(input),
+          type: "approval",
+          approval,
+        },
+      );
+      mutations.push(mutation);
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "record-tool-result") {
+    const command = input.command;
+    const toolResult: ToolResultMessage = {
+      role: "toolResult",
+      toolCallId: command.toolCallId,
+      toolName: command.toolName,
+      content: command.result.content,
+      details: command.result.details,
+      isError: command.isError,
+      timestamp: command.timestamp,
+    };
+    const existing = state.toolCalls[command.toolCallId]?.result;
+    if (existing) {
+      if (JSON.stringify(existing) !== JSON.stringify(toolResult)) {
+        throw new Error(
+          `Conflicting Pi Tool result for ${command.toolCallId}`,
+        );
+      }
+    } else {
+      const mutation = milestoneMutation(
+        `tool-result:${command.toolCallId}`,
+        {
+          ...recoveryIdentity(input),
+          type: "tool-result",
+          toolResult,
+          ...(command.needsContinuation === undefined
+            ? {}
+            : { needsContinuation: command.needsContinuation }),
+        },
+      );
+      mutations.push(mutation);
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "record-terminal") {
+    const command = input.command;
+    const milestone: PiToolRecoveryMilestone = {
+      ...recoveryIdentity(input),
+      type: "terminal",
+      phase: command.phase,
+      outcome: command.outcome,
+      ...(command.message === undefined
+        ? {}
+        : { message: command.message }),
+      timestamp: input.now,
+    };
+    const alreadyRecorded = state.terminal &&
+      state.terminal.outcome === command.outcome &&
+      state.terminal.message === command.message &&
+      (command.phase === "intent" || state.terminal.committed);
+    if (!alreadyRecorded) {
+      const mutation = milestoneMutation(
+        `terminal:${command.phase}`,
+        milestone,
+      );
+      mutations.push(mutation);
+      bodies = [...bodies, mutation.body];
+      state = replayPiToolRecovery(bodies);
+      applied = true;
+    }
+  }
+  if (input.command.kind === "commit-continuation") {
+    const plan = planPiToolRecovery(state);
+    if (
+      plan.kind !== "dispatch-continuation" ||
+      plan.continuationKey !== input.command.continuationKey
+    ) {
+      throw new Error(
+        `Pi continuation is not ready: ${input.command.continuationKey}`,
+      );
+    }
+    const committed = commitPiRecoveryContinuation(
+      state,
+      plan,
+      input.now,
+    );
+    if (!committed) {
+      throw new Error(
+        `Pi continuation could not be committed: ${plan.continuationKey}`,
+      );
+    }
+    const mutation = milestoneMutation(
+      `continuation:${plan.continuationKey}:committed`,
+      committed,
+    );
+    mutations.push(mutation);
+    bodies = [...bodies, mutation.body];
+    state = replayPiToolRecovery(bodies);
+    applied = true;
+  }
+
+  const planned = fromPlan(
+    state,
+    planPiToolRecovery(state),
+    input.now,
+    bodies,
+  );
+  return {
+    applied,
+    mutations: [...mutations, ...planned.mutations],
+    effect: planned.effect,
+    recoveredToolSettlements: recoveredToolSettlements(state),
+    ...(state.terminal ? { terminal: state.terminal } : {}),
+  };
+}
+
+// #endregion
+
+// #region Stream recovery bridges
+
+/**
+ * 把已保存的 Pi 流记录还原成通用聊天恢复内核能读取的部分输出。
+ *
+ * `PiRuntimeRecoveryAdapter.readPartial` 在孤儿流检查、进度恢复和恢复耗尽处理前调用它。
+ *
+ * 解析规则复用 Agents SDK 的 AI SDK codec，避免再维护一套 chunk reducer。
+ */
+export function readPiRecoveryPartial(chunks: readonly string[]) {
+  return aiSdkRecoveryCodec.toRecoveryPartial([...chunks]);
+}
+
+// #endregion
+
+export interface PiChatRecoveryData {
+  readonly submissionId: string;
+  readonly requestId: string;
+}
+
+export interface PiDurableRecoveryState extends PiChatRecoveryData {
+  readonly terminal: boolean;
+  readonly milestoneBodies: readonly string[];
+  readonly settledToolCount: number;
+}
+
+export interface PiRecoveryHost {
+  /**
+   * 读取请求对应的持久恢复状态。
+   *
+   * 恢复适配器在分类请求和合并部分输出时调用它。
+   *
+   * Host 必须返回最新持久化状态，适配器不会缓存副本。
+   */
+  readRecoveryState(requestId: string): PiDurableRecoveryState | null;
+  /**
+   * 重试指定 Submission。
+   *
+   * 通用恢复内核执行 retry 决策时调用它。
+   *
+   * 实际 Submission 生命周期留在 Runtime，恢复适配器只转交结果。
+   */
+  retryTurn(submissionId: string): Promise<RuntimeRecoveryResult>;
+  /**
+   * 把指定 Submission 结束为失败。
+   *
+   * 通用恢复内核无法继续恢复或耗尽预算时调用它。
+   *
+   * 终态写入留在 Runtime，避免恢复适配器复制提交规则。
+   */
+  failTurn(submissionId: string, message: string): Promise<void>;
+  /**
+   * 判断是否仍有待用户处理的审批。
+   *
+   * 恢复内核决定等待还是继续调度时调用它。
+   *
+   * 调用方应直接读取持久审批状态，避免内存缓存跨唤醒后过期。
+   */
+  hasPendingInteraction(): boolean;
+}
+
+// #region Generic recovery port adapter
+
+/**
+ * 把 Pi 的里程碑恢复协议接到通用聊天恢复内核。
+ *
+ * `PiRuntimeAdapter.createRecovery` 在 Runtime 初始化恢复端口时创建它，内核随后通过 `RuntimeRecoveryPort` 调用各方法。
+ *
+ * 适配器只翻译状态和委托 Host 执行 I/O；Pi 决策仍集中在 `decidePiRecovery`，避免内核路径产生第二套恢复规则。
+ */
+export class PiRuntimeRecoveryAdapter
+  implements RuntimeRecoveryPort<PiChatRecoveryData> {
+  /**
+   * 保存 Runtime 提供的恢复 I/O 边界。
+   *
+   * `PiRuntimeAdapter.createRecovery` 每次创建恢复端口时调用这个构造函数。
+   *
+   * Host 以单一依赖注入，便于该类保持为协议适配层而不直接访问 Runtime 数据库。
+   */
+  constructor(private readonly host: PiRecoveryHost) {}
+
+  /**
+   * 判断一个中断请求应该重试、等待、失败还是忽略。
+   *
+   * 通用恢复内核在唤醒恢复任务和检查孤儿流时调用它。
+   *
+   * 分类同时查看 Submission 终态和 Pi 里程碑计划；不能只看流是否结束，否则会越过待审批或不确定的非幂等工具。
+   */
+  async classify(requestId: string) {
+    const durable = this.host.readRecoveryState(requestId);
+    if (!durable) {
+      return {
+        kind: "fail",
+        reason: "Recovered Pi submission is missing",
+      } as const;
+    }
+    if (durable.terminal) {
+      return {
+        kind: "ignore",
+        reason: "Pi submission is already terminal",
+      } as const;
+    }
+    const decision = decidePiRecovery({
+      milestoneBodies: durable.milestoneBodies,
+      command: { kind: "inspect" },
+      now: Date.now(),
+    });
+    if (decision.effect.kind === "wait") {
+      if (decision.effect.reason === "approval") {
+        return {
+          kind: "park",
+          reason: "Pi Turn is waiting for Tool approval",
+        } as const;
+      }
+      if (decision.effect.reason === "uncertain-tool") {
+        return {
+          kind: "park",
+          reason:
+            "Pi Turn is parked on an uncertain non-idempotent Tool",
+          incidentStatus: "failed",
+        } as const;
+      }
+      if (decision.effect.reason === "complete") {
+        return {
+          kind: "fail",
+          reason:
+            "Pi recovery is complete but the Submission is not terminal",
+        } as const;
+      }
+      return {
+        kind: "park",
+        reason: "Pi recovery is waiting for durable input",
+      } as const;
+    }
+    return {
+      kind: "retry",
+      data: {
+        submissionId: durable.submissionId,
+        requestId: durable.requestId,
+      },
+    } as const;
+  }
+
+  /**
+   * 执行 classify 返回的 Pi Turn 重试。
+   *
+   * 通用恢复内核只在决策为 retry 时调用它，并把 classify 返回的数据原样传回。
+   *
+   * 实际恢复留给 Host 的 Submission 生命周期，适配器不复制重试流程。
+   */
+  retry(data: PiChatRecoveryData): Promise<RuntimeRecoveryResult> {
+    return this.host.retryTurn(data.submissionId);
+  }
+
+  /**
+   * 在恢复已无法继续时把对应 Submission 结束为失败。
+   *
+   * 通用恢复内核处理 fail 决策或恢复预算耗尽时调用它。
+   *
+   * 写入前重新读取状态并跳过已终止项，避免重复终态操作覆盖既有结果。
+   */
+  async terminalize(requestId: string, message: string): Promise<void> {
+    const durable = this.host.readRecoveryState(requestId);
+    if (durable && !durable.terminal) {
+      await this.host.failTurn(durable.submissionId, message);
+    }
+  }
+
+  /**
+   * 合并流 chunk 里的部分输出与数据库中已结算的工具结果信号。
+   *
+   * 通用恢复内核检查孤儿流、展示恢复进度和处理恢复耗尽时调用它。
+   *
+   * settlement 不在流 codec 内，因此单独并入 `hasSettledToolResults`，否则无文本但工具已执行的 Turn 会被误判为空。
+   */
+  readPartial(input: {
+    readonly requestId: string;
+    readonly chunks: readonly string[];
+  }) {
+    const partial = readPiRecoveryPartial(input.chunks);
+    const durable = this.host.readRecoveryState(input.requestId);
+    return {
+      ...partial,
+      hasSettledToolResults:
+        partial.hasSettledToolResults ||
+        (durable?.settledToolCount ?? 0) > 0,
+    };
+  }
+
+  /**
+   * 判断一个原始流 chunk 是否应该刷新持久恢复进度。
+   *
+   * `RecoverableChatAgent.appendRecoverableChunk` 保存 chunk 后调用它。
+   *
+   * JSON 解析失败返回 false，让损坏记录留给完整重放检测，而不是让进度计数路径抛错中断写流。
+   */
+  shouldCreditProgress(input: {
+    readonly body: string;
+    readonly throttle: StreamProgressCreditThrottle;
+    readonly now: number;
+  }): boolean {
+    try {
+      const chunk = JSON.parse(input.body) as { type?: unknown };
+      return shouldCreditStreamProgress({
+        codec: aiSdkRecoveryCodec,
+        type: typeof chunk.type === "string" ? chunk.type : undefined,
+        throttle: input.throttle,
+        now: input.now,
+      });
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 从 Pi 消息片段中提取恢复耗尽事件允许暴露的文本和推理内容。
+   *
+   * 通用恢复内核准备 `chat:recovery:exhausted` 事件时调用它。
+   *
+   * 这里显式筛选运行时形状，只转发 text 和 thinking，避免把未知或工具片段错误强制转换成公开事件内容。
+   */
+  toExhaustionParts(parts: readonly unknown[]): Array<{
+    type: "text" | "reasoning";
+    text: string;
+  }> {
+    const output: Array<{
+      type: "text" | "reasoning";
+      text: string;
+    }> = [];
+    for (const part of parts) {
+      if (
+        part !== null &&
+        typeof part === "object" &&
+        "type" in part &&
+        part.type === "text" &&
+        "text" in part &&
+        typeof part.text === "string"
+      ) {
+        output.push({ type: "text", text: part.text });
+        continue;
+      }
+      if (
+        part !== null &&
+        typeof part === "object" &&
+        "type" in part &&
+        part.type === "reasoning" &&
+        "text" in part &&
+        typeof part.text === "string"
+      ) {
+        output.push({ type: "reasoning", text: part.text });
+      }
+    }
+    return output;
+  }
+
+  /**
+   * 判断 Runtime 当前是否在等待用户审批。
+   *
+   * 通用恢复引擎决定是否继续安排恢复工作时调用它。
+   *
+   * 真值由 Host 的持久审批状态提供，适配器不缓存副本，避免恢复调度看到过期交互状态。
+   */
+  isAwaitingInteraction(): boolean {
+    return this.host.hasPendingInteraction();
+  }
+}
+
+// #endregion