@springbrand/agent-runtime 0.1.0

package/src/pi/turn/tool-recovery.ts

@@ -0,0 +1,792 @@
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import { EXECUTION_LEVELS } from "../../lib/execution-level";
+import {
+  decidePiToolApproval,
+  type PiApprovalOutcome,
+  type PiToolApproval,
+} from "./approval";
+
+/**
+ * 本文件实现 Pi Tool、审批、续跑和终态里程碑的纯恢复状态机。
+ *
+ * @remarks
+ * 核心术语见本目录入口 `index.ts`；这里负责校验、重放和规划，不直接执行持久化或调度。
+ */
+
+// #region 持久恢复契约
+
+type RecoveryIdentity = {
+  version: 1;
+  turnId: string;
+  assemblyRevision: string;
+};
+
+/**
+ * 描述一个 Pi Turn 在恢复时可以重放的持久事件。
+ *
+ * Runtime 在 Tool 输入、结算、审批、续跑和终态边界写入对应变体。
+ *
+ * 每条记录都携带 Turn 与装配 revision，恢复时不能把不同配置下产生的事件拼在一起。
+ */
+export type PiToolRecoveryMilestone =
+  | (RecoveryIdentity & {
+      type: "tool-input";
+      toolCallId: string;
+      toolName: string;
+      input: unknown;
+      retry: "idempotent" | "non-idempotent";
+    })
+  | (RecoveryIdentity & {
+      type: "tool-result";
+      toolResult: ToolResultMessage;
+      needsContinuation?: boolean;
+    })
+  | (RecoveryIdentity & {
+      type: "tool-error";
+      toolCallId: string;
+      toolName: string;
+      error: string;
+      timestamp: number;
+    })
+  | (RecoveryIdentity & {
+      type: "approval";
+      approval: PiToolApproval;
+    })
+  | (RecoveryIdentity & {
+      type: "continuation";
+      continuationKey: string;
+      phase: "pending" | "committed";
+      timestamp: number;
+    })
+  | (RecoveryIdentity & {
+      type: "terminal";
+      phase: "intent" | "committed";
+      outcome: "succeeded" | "failed" | "aborted";
+      message?: string;
+      timestamp: number;
+    });
+
+interface RecoveredToolCall {
+  toolCallId: string;
+  toolName: string;
+  input?: unknown;
+  retry?: "idempotent" | "non-idempotent";
+  result?: ToolResultMessage;
+  needsContinuation: boolean;
+}
+
+interface RecoveredTerminal {
+  outcome: "succeeded" | "failed" | "aborted";
+  message?: string;
+  committed: boolean;
+}
+
+/**
+ * 表示按顺序重放里程碑后得到的 Pi Tool 恢复状态。
+ *
+ * Runtime 恢复适配器把它交给 `planPiToolRecovery`，也用权威 ToolResult 重建持久结算和 transcript。
+ *
+ * 这些集合是里程碑的派生视图，不应由调用方绕过重放器自行修改。
+ */
+export interface PiToolRecoveryState {
+  turnId?: string;
+  assemblyRevision?: string;
+  toolCalls: Readonly<Record<string, RecoveredToolCall>>;
+  approvals: Readonly<Record<string, PiToolApproval>>;
+  continuations: Readonly<
+    Record<string, "pending" | "committed">
+  >;
+  canonicalToolResults: readonly ToolResultMessage[];
+  terminal?: RecoveredTerminal;
+}
+
+/**
+ * 描述恢复状态机建议 Runtime 执行的唯一下一步。
+ *
+ * 恢复适配器每次重放后消费一个计划，完成持久化或外部动作后再重放并重新规划。
+ *
+ * `chargeRecoveryBudget` 明确区分真正的 Tool 重试和等待、提交等可重复维护动作。
+ */
+export type PiToolRecoveryPlan =
+  | {
+      kind: "parked-approval";
+      executionId: string;
+      chargeRecoveryBudget: false;
+    }
+  | {
+      kind: "retry-tool";
+      toolCallId: string;
+      toolName: string;
+      input: unknown;
+      chargeRecoveryBudget: true;
+    }
+  | {
+      kind: "park-uncertain-tool";
+      toolCallId: string;
+      toolName: string;
+      chargeRecoveryBudget: true;
+    }
+  | {
+      kind: "persist-continuation";
+      turnId: string;
+      assemblyRevision: string;
+      continuationKey: string;
+      chargeRecoveryBudget: false;
+    }
+  | {
+      kind: "dispatch-continuation";
+      turnId: string;
+      assemblyRevision: string;
+      continuationKey: string;
+      idempotencyKey: string;
+      chargeRecoveryBudget: false;
+    }
+  | {
+      kind: "persist-terminal";
+      turnId: string;
+      assemblyRevision: string;
+      outcome: RecoveredTerminal["outcome"];
+      message: string | undefined;
+      chargeRecoveryBudget: false;
+    }
+  | {
+      kind: "complete";
+      outcome: RecoveredTerminal["outcome"];
+      chargeRecoveryBudget: false;
+    }
+  | { kind: "idle"; chargeRecoveryBudget: false };
+
+/**
+ * 表示恢复路径应用审批决定后需要追加的里程碑和审批动作。
+ *
+ * Runtime 收到 approve 或 reject 命令时同时持久化 `milestones` 并处理 `outcome`。
+ *
+ * 把两者绑定返回可防止审批状态与 ToolResult 或续跑动作只完成一半。
+ */
+export interface RecoveredPiApprovalDecision {
+  milestones: PiToolRecoveryMilestone[];
+  outcome: PiApprovalOutcome;
+}
+
+// #endregion
+
+// #region 里程碑编码与校验
+
+// 判断未知值是不是可按字段读取的普通 JSON 对象。
+// 所有里程碑校验器在读取属性前先调用它。
+// 排除 null 和数组，可避免后续字段判断接受错误的 JSON 容器。
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value)
+  );
+}
+
+// 校验里程碑共同携带的版本和 Turn revision 身份。
+// 顶层解码器在检查具体事件字段前调用它。
+// 版本门和非空身份让未知格式失败关闭，也为跨 revision 检查提供可靠键值。
+function isIdentity(
+  value: Record<string, unknown>,
+): value is Record<string, unknown> & RecoveryIdentity {
+  return (
+    value.version === 1 &&
+    typeof value.turnId === "string" &&
+    value.turnId.length > 0 &&
+    typeof value.assemblyRevision === "string" &&
+    value.assemblyRevision.length > 0
+  );
+}
+
+// 判断未知值是不是当前 Pi ToolResult 支持的文本或图片内容块。
+// ToolResult 校验器会对 content 数组中的每一项调用它。
+// 内容类型与已安装的 pi-ai 契约保持一致；依赖新增内容类型时这里也必须显式升级。
+function isContentBlock(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    ((value.type === "text" && typeof value.text === "string") ||
+      (value.type === "image" &&
+        typeof value.data === "string" &&
+        typeof value.mimeType === "string"))
+  );
+}
+
+// 校验从持久 JSON 读出的值是否满足 Pi ToolResult 的恢复字段。
+// `decodePiToolRecoveryMilestone` 处理 tool-result 事件时调用它。
+// 在断言类型前逐字段检查，避免损坏记录进入 canonical ToolResult 集合。
+function isToolResultMessage(
+  value: unknown,
+): value is ToolResultMessage {
+  return (
+    isRecord(value) &&
+    value.role === "toolResult" &&
+    typeof value.toolCallId === "string" &&
+    typeof value.toolName === "string" &&
+    Array.isArray(value.content) &&
+    value.content.every(isContentBlock) &&
+    typeof value.isError === "boolean" &&
+    typeof value.timestamp === "number"
+  );
+}
+
+// 校验从持久 JSON 读出的值是否是完整的 Pi Tool 审批记录。
+// 里程碑解码器处理 approval 事件时调用它。
+// 状态、执行档位和来源采用封闭枚举，未知协议值会让本次重放停在可信前缀。
+function isApproval(value: unknown): value is PiToolApproval {
+  return (
+    isRecord(value) &&
+    typeof value.executionId === "string" &&
+    typeof value.requestId === "string" &&
+    (value.source === "action" || value.source === "codemode") &&
+    typeof value.toolCallId === "string" &&
+    typeof value.toolName === "string" &&
+    typeof value.summary === "string" &&
+    typeof value.inputJson === "string" &&
+    typeof value.createdAt === "number" &&
+    EXECUTION_LEVELS.some((level) => level === value.executionLevel) &&
+    EXECUTION_LEVELS.some((level) =>
+      level === value.requiredExecutionLevel
+    ) &&
+    (value.decidedAt === undefined ||
+      typeof value.decidedAt === "number") &&
+    (value.reason === undefined || typeof value.reason === "string") &&
+    (value.status === "pending" ||
+      value.status === "approved" ||
+      value.status === "rejected")
+  );
+}
+
+/**
+ * 把一个 Pi Tool 恢复里程碑编码成可持久化的 JSON 正文。
+ *
+ * Runtime 恢复适配器在生成 `append-milestone` 变更时调用它。
+ *
+ * 编码保持为无包装的版本化 JSON；解码器在信任字段前会重新校验完整协议。
+ */
+export function encodePiToolRecoveryMilestone(
+  milestone: PiToolRecoveryMilestone,
+): string {
+  return JSON.stringify(milestone);
+}
+
+/**
+ * 把一条持久正文解码为经过校验的 Pi Tool 恢复里程碑。
+ *
+ * 重放器按存储顺序逐条调用它；无效或未知版本返回 null，由重放器保留此前的可信前缀。
+ *
+ * 每个联合类型分支单独验证所需字段，不能用直接类型断言跳过持久数据边界。
+ */
+export function decodePiToolRecoveryMilestone(
+  body: string,
+): PiToolRecoveryMilestone | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(body);
+  } catch {
+    // JSON 损坏属于可识别的 torn 尾部，不应在这里升级为 Runtime 异常。
+    // replay 会在 null 处停止，并保留已经成功重放的记录。
+    return null;
+  }
+  if (!isRecord(value) || !isIdentity(value)) return null;
+
+  switch (value.type) {
+    case "tool-input":
+      return typeof value.toolCallId === "string" &&
+        typeof value.toolName === "string" &&
+        Object.hasOwn(value, "input") &&
+        (value.retry === "idempotent" ||
+          value.retry === "non-idempotent")
+        ? (value as PiToolRecoveryMilestone)
+        : null;
+    case "tool-result":
+      return isToolResultMessage(value.toolResult) &&
+        (value.needsContinuation === undefined ||
+          typeof value.needsContinuation === "boolean")
+        ? (value as PiToolRecoveryMilestone)
+        : null;
+    case "tool-error":
+      return typeof value.toolCallId === "string" &&
+        typeof value.toolName === "string" &&
+        typeof value.error === "string" &&
+        typeof value.timestamp === "number"
+        ? (value as PiToolRecoveryMilestone)
+        : null;
+    case "approval":
+      return isApproval(value.approval)
+        ? (value as PiToolRecoveryMilestone)
+        : null;
+    case "continuation":
+      return typeof value.continuationKey === "string" &&
+        (value.phase === "pending" ||
+          value.phase === "committed") &&
+        typeof value.timestamp === "number"
+        ? (value as PiToolRecoveryMilestone)
+        : null;
+    case "terminal":
+      return (value.phase === "intent" ||
+        value.phase === "committed") &&
+        (value.outcome === "succeeded" ||
+          value.outcome === "failed" ||
+          value.outcome === "aborted") &&
+        (value.message === undefined ||
+          typeof value.message === "string") &&
+        typeof value.timestamp === "number"
+        ? (value as PiToolRecoveryMilestone)
+        : null;
+    default:
+      return null;
+  }
+}
+
+// #endregion
+
+// #region 里程碑重放与冲突保护
+
+// 确认一条里程碑属于当前正在重放的 Turn revision。
+// replay 在接受首条记录后的每一步调用它。
+// 身份冲突直接失败关闭，避免配置或 Tool surface 已变化时拼出一个不存在的历史 Turn。
+function assertIdentity(
+  state: PiToolRecoveryState,
+  milestone: PiToolRecoveryMilestone,
+): void {
+  if (
+    (state.turnId && state.turnId !== milestone.turnId) ||
+    (state.assemblyRevision &&
+      state.assemblyRevision !== milestone.assemblyRevision)
+  ) {
+    throw new Error(
+      "Pi recovery milestone does not belong to the active Turn revision",
+    );
+  }
+}
+
+// 判断重复的 tool-input 里程碑是否描述完全相同的调用。
+// replay 在同一 toolCallId 再次出现时调用它，兼容幂等追加但拒绝冲突内容。
+// Tool 名称、重试策略和输入都属于恢复安全边界，任何一项变化都不能静默覆盖。
+function sameToolInput(
+  previous: RecoveredToolCall,
+  milestone: Extract<
+    PiToolRecoveryMilestone,
+    { type: "tool-input" }
+  >,
+): boolean {
+  // 待确认：JSON.stringify 对对象键顺序敏感；当前写入链会保留输入顺序，重建输入的调用方可能产生语义相同但顺序不同的对象。
+  return (
+    previous.toolName === milestone.toolName &&
+    previous.retry === milestone.retry &&
+    JSON.stringify(previous.input) === JSON.stringify(milestone.input)
+  );
+}
+
+/**
+ * 按持久顺序重放 Pi Tool 恢复里程碑并还原当前状态。
+ *
+ * Runtime 在检查、写入命令后和每轮恢复规划前调用它；传入顺序必须与持久存储一致。
+ *
+ * 重放采用单调规则：首个 ToolResult 成为权威结果，已提交续跑不回退，审批和终态不能翻转。
+ */
+export function replayPiToolRecovery(
+  bodies: readonly string[],
+): PiToolRecoveryState {
+  const tools: Record<string, RecoveredToolCall> = {};
+  const approvals: Record<string, PiToolApproval> = {};
+  const continuations: Record<
+    string,
+    "pending" | "committed"
+  > = {};
+  const results: ToolResultMessage[] = [];
+  let state: PiToolRecoveryState = {
+    toolCalls: tools,
+    approvals,
+    continuations,
+    canonicalToolResults: results,
+  };
+
+  for (const body of bodies) {
+    const milestone = decodePiToolRecoveryMilestone(body);
+    // 无法解码的记录截断剩余日志，避免越过损坏位置组合不连续状态。
+    // 已经重放出的前缀仍可供恢复诊断和安全规划使用。
+    if (!milestone) break;
+    assertIdentity(state, milestone);
+    state = {
+      ...state,
+      turnId: state.turnId ?? milestone.turnId,
+      assemblyRevision:
+        state.assemblyRevision ?? milestone.assemblyRevision,
+    };
+
+    switch (milestone.type) {
+      case "tool-input": {
+        const previous = tools[milestone.toolCallId];
+        if (previous && !sameToolInput(previous, milestone)) {
+          throw new Error(
+            `Conflicting Pi Tool input for ${milestone.toolCallId}`,
+          );
+        }
+        tools[milestone.toolCallId] = previous ?? {
+          toolCallId: milestone.toolCallId,
+          toolName: milestone.toolName,
+          input: milestone.input,
+          retry: milestone.retry,
+          needsContinuation: true,
+        };
+        break;
+      }
+      case "tool-result": {
+        const result = milestone.toolResult;
+        const previous = tools[result.toolCallId];
+        // 重复结算只复用第一次持久结果，绝不让后来的记录改写已完成副作用。
+        // canonicalToolResults 同样只追加一次，供 transcript 恢复使用。
+        if (!previous?.result) results.push(result);
+        tools[result.toolCallId] = {
+          toolCallId: result.toolCallId,
+          toolName: result.toolName,
+          input: previous?.input,
+          retry: previous?.retry,
+          result: previous?.result ?? result,
+          needsContinuation:
+            previous?.result !== undefined
+              ? previous.needsContinuation
+              : milestone.needsContinuation ?? true,
+        };
+        break;
+      }
+      case "tool-error": {
+        const previous = tools[milestone.toolCallId];
+        const result: ToolResultMessage = {
+          role: "toolResult",
+          toolCallId: milestone.toolCallId,
+          toolName: milestone.toolName,
+          content: [{ type: "text", text: milestone.error }],
+          details: { code: "tool_error" },
+          isError: true,
+          timestamp: milestone.timestamp,
+        };
+        // Tool 错误也是已经结算的结果；重复记录仍保留第一次看到的版本。
+        if (!previous?.result) results.push(result);
+        tools[milestone.toolCallId] = {
+          toolCallId: milestone.toolCallId,
+          toolName: milestone.toolName,
+          input: previous?.input,
+          retry: previous?.retry,
+          result: previous?.result ?? result,
+          needsContinuation: previous?.needsContinuation ?? true,
+        };
+        break;
+      }
+      case "approval": {
+        const previous = approvals[milestone.approval.executionId];
+        // pending 可以前进到一个决定，但已决定状态不能被相反决定覆盖。
+        // 同状态重复记录允许刷新完整持久快照，同时保持结果不翻转。
+        if (
+          !previous ||
+          previous.status === "pending" ||
+          previous.status === milestone.approval.status
+        ) {
+          approvals[milestone.approval.executionId] =
+            milestone.approval;
+        }
+        break;
+      }
+      case "continuation":
+        // committed 是单调终态，迟到的 pending 记录不能让续跑再次被调度。
+        if (
+          continuations[milestone.continuationKey] !== "committed" ||
+          milestone.phase === "committed"
+        ) {
+          continuations[milestone.continuationKey] =
+            milestone.phase;
+        }
+        break;
+      case "terminal": {
+        const terminal = state.terminal;
+        // 第一个终态意图决定 outcome，之后只允许同一 outcome 从 intent 前进到 committed。
+        // 重复 wake 因此不能制造第二个或相反的 Submission 终态。
+        if (!terminal) {
+          state = {
+            ...state,
+            terminal: {
+              outcome: milestone.outcome,
+              message: milestone.message,
+              committed: milestone.phase === "committed",
+            },
+          };
+        } else if (
+          terminal.outcome === milestone.outcome &&
+          milestone.phase === "committed"
+        ) {
+          state = {
+            ...state,
+            terminal: { ...terminal, committed: true },
+          };
+        }
+        break;
+      }
+    }
+  }
+
+  return {
+    ...state,
+    toolCalls: tools,
+    approvals,
+    continuations,
+    canonicalToolResults: results,
+  };
+}
+
+// #endregion
+
+// #region 恢复动作规划
+
+// 把一个续跑键的持久阶段转换成下一步恢复计划。
+// 主规划器在审批已决定或 ToolResult 需要继续原 Turn 时调用它。
+// 未记录时先要求持久化 pending，已有 pending 才允许派发，committed 则不再产生动作。
+function continuationPlan(
+  state: PiToolRecoveryState,
+  continuationKey: string,
+): PiToolRecoveryPlan | null {
+  if (!state.turnId || !state.assemblyRevision) {
+    return null;
+  }
+  const phase = state.continuations[continuationKey];
+  if (phase === "committed") return null;
+  if (phase === "pending") {
+    return {
+      kind: "dispatch-continuation",
+      turnId: state.turnId,
+      assemblyRevision: state.assemblyRevision,
+      continuationKey,
+      idempotencyKey: `${state.turnId}:${continuationKey}`,
+      chargeRecoveryBudget: false,
+    };
+  }
+  return {
+    kind: "persist-continuation",
+    turnId: state.turnId,
+    assemblyRevision: state.assemblyRevision,
+    continuationKey,
+    chargeRecoveryBudget: false,
+  };
+}
+
+/**
+ * 根据已重放状态选择 Pi Tool 恢复的唯一下一步。
+ *
+ * Runtime 恢复适配器在每次状态变化后调用它，并只执行返回计划对应的一个动作。
+ *
+ * 优先级固定为终态、已决定审批、待审批、已结算 Tool、未结算 Tool，不能调换到越过终态或用户许可。
+ */
+export function planPiToolRecovery(
+  state: PiToolRecoveryState,
+): PiToolRecoveryPlan {
+  // 终态优先于任何 Tool 或审批动作，避免已经结束的 Turn 被再次续跑。
+  if (state.terminal) {
+    if (state.terminal.committed) {
+      return {
+        kind: "complete",
+        outcome: state.terminal.outcome,
+        chargeRecoveryBudget: false,
+      };
+    }
+    if (!state.turnId || !state.assemblyRevision) {
+      return { kind: "idle", chargeRecoveryBudget: false };
+    }
+    return {
+      kind: "persist-terminal",
+      turnId: state.turnId,
+      assemblyRevision: state.assemblyRevision,
+      outcome: state.terminal.outcome,
+      message: state.terminal.message,
+      chargeRecoveryBudget: false,
+    };
+  }
+
+  // 已决定审批先完成其续跑 outbox，确保决定持久化后只调度一次原 Turn。
+  for (const approval of Object.values(state.approvals)) {
+    if (approval.status === "pending") continue;
+    const key = `approval:${approval.executionId}:${
+      approval.status === "approved" ? "approve" : "reject"
+    }`;
+    const plan = continuationPlan(state, key);
+    if (plan) return plan;
+  }
+  // 仍待用户决定的审批保持 parked，不消耗普通恢复预算，也不执行其 Tool。
+  for (const approval of Object.values(state.approvals)) {
+    if (approval.status !== "pending") continue;
+    return {
+      kind: "parked-approval",
+      executionId: approval.executionId,
+      chargeRecoveryBudget: false,
+    };
+  }
+
+  // 已结算 Tool 先补齐续跑；未结算 Tool 只有声明幂等时才自动重试。
+  for (const tool of Object.values(state.toolCalls)) {
+    if (tool.result) {
+      const key = `tool:${tool.toolCallId}:settled`;
+      const plan = tool.needsContinuation
+        ? continuationPlan(state, key)
+        : null;
+      if (plan) return plan;
+      continue;
+    }
+    if (tool.retry === "idempotent") {
+      return {
+        kind: "retry-tool",
+        toolCallId: tool.toolCallId,
+        toolName: tool.toolName,
+        input: tool.input,
+        chargeRecoveryBudget: true,
+      };
+    }
+    if (tool.retry === "non-idempotent") {
+      return {
+        kind: "park-uncertain-tool",
+        toolCallId: tool.toolCallId,
+        toolName: tool.toolName,
+        chargeRecoveryBudget: true,
+      };
+    }
+  }
+
+  return { kind: "idle", chargeRecoveryBudget: false };
+}
+
+// #endregion
+
+// #region 续跑两阶段提交
+
+/**
+ * 为一次尚未登记的续跑创建 `pending` 里程碑。
+ *
+ * Runtime 处理 `persist-continuation` 计划时先调用它，持久化成功后才能重新规划为派发动作。
+ *
+ * 状态和 Turn revision 必须仍与计划一致；过期或重复计划返回 null，避免写出第二份 outbox 意图。
+ */
+export function stagePiRecoveryContinuation(
+  state: PiToolRecoveryState,
+  plan: Extract<
+    PiToolRecoveryPlan,
+    { kind: "persist-continuation" }
+  >,
+  timestamp: number,
+): PiToolRecoveryMilestone | null {
+  if (
+    state.continuations[plan.continuationKey] !== undefined ||
+    state.turnId !== plan.turnId ||
+    state.assemblyRevision !== plan.assemblyRevision
+  ) {
+    return null;
+  }
+  return {
+    version: 1,
+    type: "continuation",
+    turnId: plan.turnId,
+    assemblyRevision: plan.assemblyRevision,
+    continuationKey: plan.continuationKey,
+    phase: "pending",
+    timestamp,
+  };
+}
+
+/**
+ * 为一次已经登记的续跑创建 `committed` 里程碑。
+ *
+ * Runtime 确认 `dispatch-continuation` 计划仍有效时调用它，随后把提交记录与对应恢复动作按宿主顺序处理。
+ *
+ * 只允许 `pending` 且 revision 匹配的计划提交，使重复 wake 或重复调度不会重新打开同一续跑。
+ */
+export function commitPiRecoveryContinuation(
+  state: PiToolRecoveryState,
+  plan: Extract<
+    PiToolRecoveryPlan,
+    { kind: "dispatch-continuation" }
+  >,
+  timestamp: number,
+): PiToolRecoveryMilestone | null {
+  if (
+    state.continuations[plan.continuationKey] !== "pending" ||
+    state.turnId !== plan.turnId ||
+    state.assemblyRevision !== plan.assemblyRevision
+  ) {
+    return null;
+  }
+  return {
+    version: 1,
+    type: "continuation",
+    turnId: plan.turnId,
+    assemblyRevision: plan.assemblyRevision,
+    continuationKey: plan.continuationKey,
+    phase: "committed",
+    timestamp,
+  };
+}
+
+// #endregion
+
+// #region 恢复审批决定
+
+/**
+ * 在恢复状态上应用一个用户审批决定，并生成需要持久化的里程碑。
+ *
+ * Runtime 收到冷重建后的 approve 或 reject 命令时调用它，再按返回结果更新审批表和恢复日志。
+ *
+ * approve 只记录决定并安排续跑；reject 额外写入稳定 ToolResult，且重复决定返回空里程碑。
+ */
+export function applyRecoveredPiApprovalDecision(
+  state: PiToolRecoveryState,
+  input: {
+    executionId: string;
+    decision: "approve" | "reject";
+    decidedAt: number;
+    reason?: string;
+  },
+): RecoveredPiApprovalDecision {
+  const approval = state.approvals[input.executionId];
+  if (!approval) {
+    throw new Error(`Unknown Pi Tool approval ${input.executionId}`);
+  }
+  const transition = decidePiToolApproval(
+    approval,
+    input.decision === "approve"
+      ? { decision: "allow_once", decidedAt: input.decidedAt }
+      : {
+          decision: "deny",
+          decidedAt: input.decidedAt,
+          reason: input.reason,
+        },
+  );
+  // decidePiToolApproval 已处理的审批只返回 noop；这里不应再追加任何持久记录。
+  if (transition.outcome.kind === "noop") {
+    return { milestones: [], outcome: transition.outcome };
+  }
+  if (!state.turnId || !state.assemblyRevision) {
+    throw new Error("Pi Tool approval is missing its Turn revision");
+  }
+
+  const identity: RecoveryIdentity = {
+    version: 1,
+    turnId: state.turnId,
+    assemblyRevision: state.assemblyRevision,
+  };
+  const milestones: PiToolRecoveryMilestone[] = [
+    {
+      ...identity,
+      type: "approval",
+      approval: transition.approval,
+    },
+  ];
+  if (transition.outcome.kind === "denied") {
+    // 拒绝直接结算成 ToolResult，且不再安排 Tool settled continuation。
+    // 审批决定本身仍有独立 continuation，保持 approve/reject 的恢复调度一致。
+    milestones.push({
+      ...identity,
+      type: "tool-result",
+      toolResult: transition.outcome.toolResult,
+      needsContinuation: false,
+    });
+  }
+  return { milestones, outcome: transition.outcome };
+}
+
+// #endregion