@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/{pi/turn/tool-recovery.ts → session/cloudflare/legacy-tool-recovery.ts}

@@ -1,28 +1,45 @@
+import type { ApprovalReceipt } from "../../submission/contracts";
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
 import { isEqual } from "lodash-es";
 import { EXECUTION_LEVELS } from "../../lib/execution-level";
-import {
-  decidePiToolApproval,
-  type PiApprovalOutcome,
-  type PiToolApproval,
-} from "./approval";
-import {
-  cancelPiToolInteraction,
-  respondPiToolInteraction,
-  type PiToolInteraction,
-  type PiToolInteractionCancelReason,
-  type PiToolInteractionOutcome,
-} from "./interaction";
-
 /**
- * 本文件实现 Pi Tool、审批、续跑和终态里程碑的纯恢复状态机。
+ * 本文件只解码和重放旧 Pi Tool 恢复里程碑，供一次性 Session 迁移使用。
  *
  * @remarks
- * 核心术语见本目录入口 `index.ts`；这里负责校验、重放和规划，不直接执行持久化或调度。
+ * 正常 AgentHarness 执行路径不导入本文件。
  */
 
 // #region 持久恢复契约
 
+interface PiToolApproval {
+  executionId: string;
+  requestId: string;
+  source: ApprovalReceipt["source"];
+  toolCallId: string;
+  toolName: string;
+  summary: string;
+  executionLevel: ApprovalReceipt["executionLevel"];
+  requiredExecutionLevel: ApprovalReceipt["requiredExecutionLevel"];
+  inputJson: string;
+  createdAt: number;
+  status: "pending" | "approved" | "rejected";
+  decidedAt?: number;
+  reason?: string;
+}
+
+interface PiToolInteraction {
+  interactionId: string;
+  requestId: string;
+  toolCallId: string;
+  toolName: string;
+  inputJson: string;
+  createdAt: number;
+  status: "pending" | "responded" | "cancelled";
+  respondedAt?: number;
+  responseJson?: string;
+}
+
+
 type RecoveryIdentity = {
   version: 1;
   turnId: string;
@@ -108,7 +125,7 @@ interface RecoveredTerminal {
 /**
  * 表示按顺序重放里程碑后得到的 Pi Tool 恢复状态。
  *
- * Runtime 恢复适配器把它交给 `planPiToolRecovery`，也用权威 ToolResult 重建持久结算和 transcript。
+ * Session 迁移用权威 ToolResult 重建持久结算和 transcript。
  *
  * 这些集合是里程碑的派生视图，不应由调用方绕过重放器自行修改。
  */
@@ -125,92 +142,6 @@ export interface PiToolRecoveryState {
   terminal?: RecoveredTerminal;
 }
 
-/**
- * 描述恢复状态机建议 Runtime 执行的唯一下一步。
- *
- * 恢复适配器每次重放后消费一个计划，完成持久化或外部动作后再重放并重新规划。
- *
- * `chargeRecoveryBudget` 明确区分真正的 Tool 重试和等待、提交等可重复维护动作。
- */
-export type PiToolRecoveryPlan =
-  | {
-      kind: "parked-approval";
-      executionId: string;
-      chargeRecoveryBudget: false;
-    }
-  | {
-      kind: "parked-interaction";
-      interactionId: 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;
-}
-
-/**
- * 表示恢复路径应用一次 interaction 响应或取消后需要追加的里程碑和动作。
- *
- * Runtime 收到 respond 或 cancel 命令时同时持久化 `milestones` 并处理 `outcome`。
- *
- * 与审批不同的是，settle 分支的 `tool-result` 里程碑带 `needsContinuation: true`：
- * interaction 没有自己的续跑键，续跑完全依赖既有的 `tool:<id>:settled` 路径。
- */
-export interface RecoveredPiToolInteractionSettlement {
-  milestones: PiToolRecoveryMilestone[];
-  outcome: PiToolInteractionOutcome;
-}
-
 // #endregion
 
 // #region 里程碑编码与校验
@@ -321,19 +252,6 @@ function isInteraction(value: unknown): value is PiToolInteraction {
   );
 }
 
-/**
- * 把一个 Pi Tool 恢复里程碑编码成可持久化的 JSON 正文。
- *
- * Runtime 恢复适配器在生成 `append-milestone` 变更时调用它。
- *
- * 编码保持为无包装的版本化 JSON；解码器在信任字段前会重新校验完整协议。
- */
-export function encodePiToolRecoveryMilestone(
-  milestone: PiToolRecoveryMilestone,
-): string {
-  return JSON.stringify(milestone);
-}
-
 /**
  * 把一条持久正文解码为经过校验的 Pi Tool 恢复里程碑。
  *
@@ -633,413 +551,3 @@ export function replayPiToolRecovery(
 }
 
 // #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 恢复适配器在每次状态变化后调用它，并只执行返回计划对应的一个动作。
- *
- * 优先级固定为终态、已决定审批、待审批、待响应 interaction、已结算 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,
-    };
-  }
-  // 仍等客户端投递结果的 interaction 同样保持 parked。
-  // 已响应或已取消的 interaction 不在这里出现：它们在写入本记录的同一批里程碑中
-  // 一并写了 tool-result，因此直接落到下面「已结算 Tool 补齐续跑」那条既有路径，
-  // 不需要 interaction 专属的续跑键。
-  for (const interaction of Object.values(state.interactions)) {
-    if (interaction.status !== "pending") continue;
-    return {
-      kind: "parked-interaction",
-      interactionId: interaction.interactionId,
-      chargeRecoveryBudget: false,
-    };
-  }
-
-  // 已结算 Tool 先补齐续跑；未结算 Tool 只有声明幂等时才自动重试。
-  const tools = Object.values(state.toolCalls);
-  const codeModeParents = tools
-    .filter((tool) => tool.toolName === "execute")
-    .map((tool) => `${tool.toolCallId}:`);
-  for (const tool of tools) {
-    // 旧版把 Code Mode 内层调用写成独立 Pi attempt，但只有父
-    // execute 会产生 settlement。这些带父调用前缀的记录不是可
-    // 独立恢复的 Tool；父 execute 才是唯一恢复边界。
-    if (codeModeParents.some((prefix) => tool.toolCallId.startsWith(prefix))) {
-      continue;
-    }
-    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 装配迁移
-
-/**
- * 为一次停在人机等待期间发生的装配迁移创建里程碑。
- *
- * 宿主换完装配、准备把 Submission 重新 pin 到新装配上时调用它；返回的里程碑
- * 必须与 `pinAssembly` 的写入落在同一个事务里，否则重启后里程碑与 Submission
- * 会各自指向一半的迁移。
- *
- * 已经处在目标 revision（重复调用）或还没有任何里程碑（没有身份要迁移）时返回
- * null：这两种情况下重放本来就得到正确的身份，多写一条只会造出假历史。
- */
-export function stagePiAssemblyRepin(
-  state: PiToolRecoveryState,
-  nextAssemblyRevision: string,
-  timestamp: number,
-): PiToolRecoveryMilestone | null {
-  if (
-    !state.turnId ||
-    !state.assemblyRevision ||
-    state.assemblyRevision === nextAssemblyRevision
-  ) {
-    return null;
-  }
-  return {
-    version: 1,
-    turnId: state.turnId,
-    assemblyRevision: state.assemblyRevision,
-    type: "assembly-repin",
-    nextAssemblyRevision,
-    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 SpringBrand 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("SpringBrand 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
-
-// #region 恢复 interaction 结算
-
-/**
- * 在恢复状态上记录一条新 park 的 interaction。
- *
- * 执行链进入 park 前调用，返回的里程碑让重启后的重放知道这次 Tool 调用在等客户端，
- * 从而规划成 `parked-interaction` 而不是去重试 Tool。
- */
-export function recordRecoveredPiToolInteraction(
-  state: PiToolRecoveryState,
-  interaction: PiToolInteraction,
-): PiToolRecoveryMilestone[] {
-  if (!state.turnId || !state.assemblyRevision) {
-    throw new Error("SpringBrand Tool interaction is missing its Turn revision");
-  }
-  return [{
-    version: 1,
-    turnId: state.turnId,
-    assemblyRevision: state.assemblyRevision,
-    type: "interaction",
-    interaction,
-  }];
-}
-
-/**
- * 在恢复状态上应用一次客户端响应或取消，并生成需要持久化的里程碑。
- *
- * Runtime 收到 `respondToolInteraction` 或判定取消时调用它，再按返回结果更新表和恢复日志。
- *
- * 两种结局形状相同 —— 都写 interaction 记录 + 一条权威 `tool-result`。重复投递返回空里程碑。
- */
-export function applyRecoveredPiToolInteractionSettlement(
-  state: PiToolRecoveryState,
-  input:
-    | {
-        interactionId: string;
-        kind: "respond";
-        response: unknown;
-        toolResult: ToolResultMessage;
-        settledAt: number;
-      }
-    | {
-        interactionId: string;
-        kind: "cancel";
-        reason: PiToolInteractionCancelReason;
-        settledAt: number;
-        toolResult?: ToolResultMessage;
-      },
-): RecoveredPiToolInteractionSettlement {
-  const interaction = state.interactions[input.interactionId];
-  if (!interaction) {
-    throw new Error(`Unknown SpringBrand Tool interaction ${input.interactionId}`);
-  }
-  const transition = input.kind === "respond"
-    ? respondPiToolInteraction(interaction, {
-        response: input.response,
-        toolResult: input.toolResult,
-        respondedAt: input.settledAt,
-      })
-    : cancelPiToolInteraction(interaction, {
-        reason: input.reason,
-        cancelledAt: input.settledAt,
-        ...(input.toolResult ? { toolResult: input.toolResult } : {}),
-      });
-  const outcome = transition.outcome;
-  // 已结束的 interaction 只返回 noop；这里不应再追加任何持久记录。
-  if (outcome.kind !== "settle") {
-    return { milestones: [], outcome };
-  }
-  if (!state.turnId || !state.assemblyRevision) {
-    throw new Error("SpringBrand Tool interaction is missing its Turn revision");
-  }
-
-  const identity: RecoveryIdentity = {
-    version: 1,
-    turnId: state.turnId,
-    assemblyRevision: state.assemblyRevision,
-  };
-  return {
-    milestones: [
-      { ...identity, type: "interaction", interaction: transition.interaction },
-      // needsContinuation 必须为 true：interaction 没有自己的续跑键，
-      // 唤醒原 Turn 全靠 planPiToolRecovery 里 `tool:<id>:settled` 那条既有分支。
-      {
-        ...identity,
-        type: "tool-result",
-        toolResult: outcome.toolResult,
-        needsContinuation: true,
-      },
-    ],
-    outcome,
-  };
-}
-
-// #endregion