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

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

@@ -5,6 +5,13 @@ import {
   type PiApprovalOutcome,
   type PiToolApproval,
 } from "./approval";
+import {
+  cancelPiToolInteraction,
+  respondPiToolInteraction,
+  type PiToolInteraction,
+  type PiToolInteractionCancelReason,
+  type PiToolInteractionOutcome,
+} from "./interaction";
 
 /**
  * 本文件实现 Pi Tool、审批、续跑和终态里程碑的纯恢复状态机。
@@ -52,12 +59,28 @@ export type PiToolRecoveryMilestone =
       type: "approval";
       approval: PiToolApproval;
     })
+  | (RecoveryIdentity & {
+      type: "interaction";
+      interaction: PiToolInteraction;
+    })
   | (RecoveryIdentity & {
       type: "continuation";
       continuationKey: string;
       phase: "pending" | "committed";
       timestamp: number;
     })
+  /**
+   * 一次被承认的装配迁移：这条 Submission 停在人机等待期间换了装配。
+   *
+   * `assemblyRevision` 是迁移前那份（所以它自己通过身份校验），
+   * `nextAssemblyRevision` 是迁移后那份。重放读到它之前按旧 revision 校验
+   * 身份，读到之后按新的。同一条 Submission 允许发生多次。
+   */
+  | (RecoveryIdentity & {
+      type: "assembly-repin";
+      nextAssemblyRevision: string;
+      timestamp: number;
+    })
   | (RecoveryIdentity & {
       type: "terminal";
       phase: "intent" | "committed";
@@ -93,6 +116,7 @@ export interface PiToolRecoveryState {
   assemblyRevision?: string;
   toolCalls: Readonly<Record<string, RecoveredToolCall>>;
   approvals: Readonly<Record<string, PiToolApproval>>;
+  interactions: Readonly<Record<string, PiToolInteraction>>;
   continuations: Readonly<
     Record<string, "pending" | "committed">
   >;
@@ -113,6 +137,11 @@ export type PiToolRecoveryPlan =
       executionId: string;
       chargeRecoveryBudget: false;
     }
+  | {
+      kind: "parked-interaction";
+      interactionId: string;
+      chargeRecoveryBudget: false;
+    }
   | {
       kind: "retry-tool";
       toolCallId: string;
@@ -168,6 +197,19 @@ export interface RecoveredPiApprovalDecision {
   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 里程碑编码与校验
@@ -256,6 +298,28 @@ function isApproval(value: unknown): value is PiToolApproval {
   );
 }
 
+// 校验从持久 JSON 读出的值是否是完整的 Pi Tool interaction 记录。
+// 里程碑解码器处理 interaction 事件时调用它。
+// 状态采用封闭枚举，未知协议值会让本次重放停在可信前缀 —— 与 isApproval 同一口径。
+function isInteraction(value: unknown): value is PiToolInteraction {
+  return (
+    isRecord(value) &&
+    typeof value.interactionId === "string" &&
+    typeof value.requestId === "string" &&
+    typeof value.toolCallId === "string" &&
+    typeof value.toolName === "string" &&
+    typeof value.inputJson === "string" &&
+    typeof value.createdAt === "number" &&
+    (value.respondedAt === undefined ||
+      typeof value.respondedAt === "number") &&
+    (value.responseJson === undefined ||
+      typeof value.responseJson === "string") &&
+    (value.status === "pending" ||
+      value.status === "responded" ||
+      value.status === "cancelled")
+  );
+}
+
 /**
  * 把一个 Pi Tool 恢复里程碑编码成可持久化的 JSON 正文。
  *
@@ -315,6 +379,10 @@ export function decodePiToolRecoveryMilestone(
       return isApproval(value.approval)
         ? (value as PiToolRecoveryMilestone)
         : null;
+    case "interaction":
+      return isInteraction(value.interaction)
+        ? (value as PiToolRecoveryMilestone)
+        : null;
     case "continuation":
       return typeof value.continuationKey === "string" &&
         (value.phase === "pending" ||
@@ -322,6 +390,12 @@ export function decodePiToolRecoveryMilestone(
         typeof value.timestamp === "number"
         ? (value as PiToolRecoveryMilestone)
         : null;
+    case "assembly-repin":
+      return typeof value.nextAssemblyRevision === "string" &&
+        value.nextAssemblyRevision.length > 0 &&
+        typeof value.timestamp === "number"
+        ? (value as PiToolRecoveryMilestone)
+        : null;
     case "terminal":
       return (value.phase === "intent" ||
         value.phase === "committed") &&
@@ -390,6 +464,7 @@ export function replayPiToolRecovery(
 ): PiToolRecoveryState {
   const tools: Record<string, RecoveredToolCall> = {};
   const approvals: Record<string, PiToolApproval> = {};
+  const interactions: Record<string, PiToolInteraction> = {};
   const continuations: Record<
     string,
     "pending" | "committed"
@@ -398,6 +473,7 @@ export function replayPiToolRecovery(
   let state: PiToolRecoveryState = {
     toolCalls: tools,
     approvals,
+    interactions,
     continuations,
     canonicalToolResults: results,
   };
@@ -488,6 +564,27 @@ export function replayPiToolRecovery(
         }
         break;
       }
+      case "interaction": {
+        const previous = interactions[milestone.interaction.interactionId];
+        // 与 approval 同一口径：pending 可以前进到一个结局，但已结局的记录不能被翻转。
+        // 同状态重复记录允许刷新完整持久快照，同时保持结果不变。
+        if (
+          !previous ||
+          previous.status === "pending" ||
+          previous.status === milestone.interaction.status
+        ) {
+          interactions[milestone.interaction.interactionId] =
+            milestone.interaction;
+        }
+        break;
+      }
+      case "assembly-repin":
+        // 身份校验已经按迁移前的 revision 通过；从这里往后的里程碑属于新装配。
+        state = {
+          ...state,
+          assemblyRevision: milestone.nextAssemblyRevision,
+        };
+        break;
       case "continuation":
         // committed 是单调终态，迟到的 pending 记录不能让续跑再次被调度。
         if (
@@ -529,6 +626,7 @@ export function replayPiToolRecovery(
     ...state,
     toolCalls: tools,
     approvals,
+    interactions,
     continuations,
     canonicalToolResults: results,
   };
@@ -574,7 +672,8 @@ function continuationPlan(
  *
  * Runtime 恢复适配器在每次状态变化后调用它，并只执行返回计划对应的一个动作。
  *
- * 优先级固定为终态、已决定审批、待审批、已结算 Tool、未结算 Tool，不能调换到越过终态或用户许可。
+ * 优先级固定为终态、已决定审批、待审批、待响应 interaction、已结算 Tool、未结算 Tool，
+ * 不能调换到越过终态或用户许可。
  */
 export function planPiToolRecovery(
   state: PiToolRecoveryState,
@@ -619,6 +718,18 @@ export function planPiToolRecovery(
       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 只有声明幂等时才自动重试。
   for (const tool of Object.values(state.toolCalls)) {
@@ -724,6 +835,42 @@ export function commitPiRecoveryContinuation(
 
 // #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 恢复审批决定
 
 /**
@@ -790,3 +937,99 @@ export function applyRecoveredPiApprovalDecision(
 }
 
 // #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("Pi 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 Pi 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("Pi 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