@springbrand/agent-runtime 0.1.0

package/src/pi/turn/approval.ts

@@ -0,0 +1,181 @@
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type {
+  ApprovalDecision,
+  ApprovalReceipt,
+} from "../../kernel/receipts";
+import { requiresExecutionApproval } from "../../lib/execution-level";
+
+/**
+ * 表示一个 Pi Tool 在执行前等待用户处理的持久审批。
+ *
+ * Runtime 在 Tool handler 运行前保存它，恢复路径按 `executionId` 读取并应用一次决定。
+ *
+ * Tool 输入和执行身份随审批一起保存，才能在 Durable Object 重建后恢复原请求，而不是重新推断它。
+ */
+export 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;
+}
+
+/**
+ * 描述一次审批转换要求调用方采取的动作。
+ *
+ * Runtime 根据 `park`、`resume`、`denied` 或 `noop` 决定等待、续跑、写入拒绝结果或忽略重复决定。
+ *
+ * 状态转换与 I/O 分开，使同一套幂等规则同时服务在线执行和崩溃恢复。
+ */
+export type PiApprovalOutcome =
+  | {
+      kind: "park";
+      executionId: string;
+      requestId: string;
+    }
+  | {
+      kind: "resume";
+      executionId: string;
+      requestId: string;
+      toolCallId: string;
+    }
+  | {
+      kind: "denied";
+      executionId: string;
+      requestId: string;
+      toolResult: ToolResultMessage;
+    }
+  | {
+      kind: "noop";
+      executionId: string;
+    };
+
+/**
+ * 把审批的新状态和对应动作绑定为一个不可拆分的决策结果。
+ *
+ * 在线执行与恢复调用方应同时消费 `approval` 和 `outcome`，不要只持久化其中一半。
+ *
+ * 两者由同一纯函数生成，可避免审批状态已经改变但续跑动作仍按旧状态计算。
+ */
+export interface PiApprovalTransition {
+  approval: PiToolApproval;
+  outcome: PiApprovalOutcome;
+}
+
+/**
+ * 判断当前 Pi Tool 是否必须先等待用户审批。
+ *
+ * 执行适配器会在调用 Tool handler 前传入 Agent 已授予档位和 Tool 所需档位。
+ *
+ * 最终矩阵委托给共享的 `requiresExecutionApproval`，避免 Pi 路径复制后偏离 Runtime 规则。
+ */
+export function requiresPiToolApproval(input: {
+  executionLevel: ApprovalReceipt["executionLevel"];
+  requiredExecutionLevel: ApprovalReceipt["requiredExecutionLevel"];
+}): boolean {
+  return requiresExecutionApproval(
+    input.executionLevel,
+    input.requiredExecutionLevel,
+  );
+}
+
+/**
+ * 创建一个待处理审批，并告诉调用方暂停当前 Turn。
+ *
+ * 执行适配器确认需要审批后调用它，再把返回的 `approval` 持久化并等待用户决定。
+ *
+ * 此处不填写决定时间或理由，保证新记录只有一个明确的 `pending` 起点。
+ */
+export function parkPiToolApproval(
+  input: Omit<
+    PiToolApproval,
+    "status" | "decidedAt" | "reason"
+  >,
+): PiApprovalTransition {
+  return {
+    approval: { ...input, status: "pending" },
+    outcome: {
+      kind: "park",
+      executionId: input.executionId,
+      requestId: input.requestId,
+    },
+  };
+}
+
+/**
+ * 把用户的首次审批决定应用到待处理记录。
+ *
+ * 在线审批和恢复路径在读到持久审批后调用它；已经决定过的记录会返回 `noop`，调用方不得再次执行 Tool。
+ *
+ * 拒绝仍生成 `isError: false` 的稳定 ToolResult，这是现有客户端识别 rejection envelope 的协议，不能改成普通异常。
+ */
+export function decidePiToolApproval(
+  approval: PiToolApproval,
+  input: ApprovalDecision & { decidedAt: number },
+): PiApprovalTransition {
+  // 已结束的审批保持原状态，重复或并发决定只能得到 noop。
+  // 恢复路径依赖这一点避免重复续跑或产生相反终态。
+  if (approval.status !== "pending") {
+    return {
+      approval,
+      outcome: {
+        kind: "noop",
+        executionId: approval.executionId,
+      },
+    };
+  }
+
+  if (input.decision !== "deny") {
+    return {
+      approval: {
+        ...approval,
+        status: "approved",
+        decidedAt: input.decidedAt,
+      },
+      outcome: {
+        kind: "resume",
+        executionId: approval.executionId,
+        requestId: approval.requestId,
+        toolCallId: approval.toolCallId,
+      },
+    };
+  }
+
+  const reason = input.reason?.trim() || "Tool execution denied by user";
+  // 拒绝是一个已处理的 Tool 结果，不是 Tool handler 失败。
+  // 保留 rejection details 和 isError:false，客户端才能继续显示既有拒绝语义。
+  return {
+    approval: {
+      ...approval,
+      status: "rejected",
+      decidedAt: input.decidedAt,
+      reason,
+    },
+    outcome: {
+      kind: "denied",
+      executionId: approval.executionId,
+      requestId: approval.requestId,
+      toolResult: {
+        role: "toolResult",
+        toolCallId: approval.toolCallId,
+        toolName: approval.toolName,
+        content: [{ type: "text", text: reason }],
+        details: {
+          status: "rejected",
+          executionId: approval.executionId,
+          reason,
+        },
+        isError: false,
+        timestamp: input.decidedAt,
+      },
+    },
+  };
+}

package/src/pi/turn/index.ts

@@ -0,0 +1,62 @@
+/**
+ * 集中导出 Pi Turn 的审批和崩溃恢复规则。
+ *
+ * @remarks
+ * Runtime 适配器通过本入口判断审批、重放持久记录并选择恢复动作。
+ *
+ * 本目录统一使用以下术语：
+ *
+ * - **审批（approval）**：Tool handler 运行前持久化的用户许可；`pending` 状态会暂停 Turn。
+ * - **里程碑（milestone）**：属于同一个 `turnId` 和 `assemblyRevision` 的持久 JSON 记录。
+ * - **结算结果（settled ToolResult）**：已持久化且恢复时必须复用、不能再次执行副作用的 Tool 结果。
+ * - **续跑（continuation）**：审批或 Tool 结算后恢复原 Turn 的动作；先记 `pending`，再记 `committed`。
+ * - **权威结果（canonical ToolResult）**：同一 `toolCallId` 第一次成功重放出的结算结果。
+ *
+ * 这些定义对应 Runtime 的持久记录和恢复状态机；其他文件应引用本入口，不要另写一套含义。
+ *
+ * @packageDocumentation
+ */
+
+import {
+  parkPiToolApproval,
+  requiresPiToolApproval,
+} from "./approval";
+import {
+  applyRecoveredPiApprovalDecision,
+  commitPiRecoveryContinuation,
+  encodePiToolRecoveryMilestone,
+  planPiToolRecovery,
+  replayPiToolRecovery,
+  stagePiRecoveryContinuation,
+} from "./tool-recovery";
+
+/**
+ * 提供 Pi Tool 审批的两个入口操作。
+ *
+ * Runtime 执行适配器在调用 Tool handler 前先判断 `requires`，需要等待时再用 `park` 生成待审批状态。
+ *
+ * 冻结该门面可防止调用方在运行期间替换审批规则；完整类型和决策函数仍由本模块单独导出。
+ */
+export const piApproval = Object.freeze({
+  park: parkPiToolApproval,
+  requires: requiresPiToolApproval,
+});
+
+/**
+ * 提供 Pi Turn 恢复状态机的稳定入口。
+ *
+ * Runtime 恢复适配器先用 `replay` 还原状态，再用 `plan` 选择下一步，并按计划写入或提交续跑里程碑。
+ *
+ * 这些操作保持为无 I/O 的纯决策，持久化和调度仍由 Runtime 负责，避免恢复规则依赖具体存储实现。
+ */
+export const piRecovery = Object.freeze({
+  applyApprovalDecision: applyRecoveredPiApprovalDecision,
+  commitContinuation: commitPiRecoveryContinuation,
+  encodeMilestone: encodePiToolRecoveryMilestone,
+  plan: planPiToolRecovery,
+  replay: replayPiToolRecovery,
+  stageContinuation: stagePiRecoveryContinuation,
+});
+
+export * from "./approval";
+export * from "./tool-recovery";