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

package/src/pi/turn/approval.ts

@@ -1,181 +0,0 @@
-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

@@ -1,82 +0,0 @@
-/**
- * 集中导出 Pi Turn 的审批和崩溃恢复规则。
- *
- * @remarks
- * Runtime 适配器通过本入口判断审批、重放持久记录并选择恢复动作。
- *
- * 本目录统一使用以下术语：
- *
- * - **审批（approval）**：Tool handler 运行前持久化的用户许可；`pending` 状态会暂停 Turn。
- * - **交互（interaction）**：结果由客户端投递而非 `execute()` 产出的 Tool 调用；`pending` 状态同样暂停 Turn。
- *   与审批的差别只在响应体：审批是三态枚举，交互是任意 JSON。
- * - **里程碑（milestone）**：属于同一个 `turnId` 和 `assemblyRevision` 的持久 JSON 记录。
- * - **结算结果（settled ToolResult）**：已持久化且恢复时必须复用、不能再次执行副作用的 Tool 结果。
- * - **续跑（continuation）**：审批或 Tool 结算后恢复原 Turn 的动作；先记 `pending`，再记 `committed`。
- * - **权威结果（canonical ToolResult）**：同一 `toolCallId` 第一次成功重放出的结算结果。
- *
- * 这些定义对应 Runtime 的持久记录和恢复状态机；其他文件应引用本入口，不要另写一套含义。
- *
- * @packageDocumentation
- */
-
-import {
-  parkPiToolApproval,
-  requiresPiToolApproval,
-} from "./approval";
-import { parkPiToolInteraction } from "./interaction";
-import {
-  applyRecoveredPiApprovalDecision,
-  applyRecoveredPiToolInteractionSettlement,
-  commitPiRecoveryContinuation,
-  encodePiToolRecoveryMilestone,
-  planPiToolRecovery,
-  recordRecoveredPiToolInteraction,
-  replayPiToolRecovery,
-  stagePiAssemblyRepin,
-  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,
-  applyInteractionSettlement: applyRecoveredPiToolInteractionSettlement,
-  commitContinuation: commitPiRecoveryContinuation,
-  encodeMilestone: encodePiToolRecoveryMilestone,
-  plan: planPiToolRecovery,
-  recordInteraction: recordRecoveredPiToolInteraction,
-  replay: replayPiToolRecovery,
-  stageAssemblyRepin: stagePiAssemblyRepin,
-  stageContinuation: stagePiRecoveryContinuation,
-});
-
-/**
- * 提供 Pi Tool interaction（结果由客户端提供的 Tool）的 park 入口。
- *
- * 执行适配器发现 Tool 声明了 `interaction` 后调用 `park` 生成待响应状态；
- * 响应与取消是有状态操作，走 `piRecovery.applyInteractionSettlement`，不放在这个门面里。
- */
-export const piInteraction = Object.freeze({
-  park: parkPiToolInteraction,
-});
-
-export * from "./approval";
-export * from "./interaction";
-export * from "./tool-recovery";

package/src/pi/turn/interaction.ts

@@ -1,181 +0,0 @@
-import type { ToolResultMessage } from "@earendil-works/pi-ai";
-
-/**
- * 表示一个 Pi Tool 在等待客户端投递结果时的持久 park 记录。
- *
- * Runtime 在带 `interaction` 声明的 Tool 进入执行链时保存它，恢复路径按 `interactionId` 读取并应用一次响应。
- *
- * Tool 输入随记录一起保存，才能在 Durable Object 重建后把响应映射回原始调用，而不是重新推断它。
- */
-export interface PiToolInteraction {
-  interactionId: string;
-  requestId: string;
-  toolCallId: string;
-  toolName: string;
-  inputJson: string;
-  createdAt: number;
-  status: "pending" | "responded" | "cancelled";
-  respondedAt?: number;
-  responseJson?: string;
-}
-
-/**
- * 说明一次 interaction 为什么在没有拿到用户选择的情况下结束。
- *
- * 目前只有一种：用户没有点选项，而是直接在聊天里发了消息。
- * 新增成员时必须同步更新 `cancelText` 与解码器的枚举校验。
- */
-export type PiToolInteractionCancelReason =
-  | "user_replied_freeform"
-  | "submission_terminal";
-
-/**
- * 描述一次 interaction 状态转换要求调用方采取的动作。
- *
- * `park` 表示继续等待，`settle` 表示已得到权威 ToolResult 可以续跑，`noop` 表示重复投递应被忽略。
- *
- * 状态转换与 I/O 分开，使同一套幂等规则同时服务在线执行和崩溃恢复 —— 与审批同构。
- */
-export type PiToolInteractionOutcome =
-  | { kind: "park"; interactionId: string; requestId: string }
-  | {
-      kind: "settle";
-      interactionId: string;
-      requestId: string;
-      toolCallId: string;
-      toolResult: ToolResultMessage;
-    }
-  | { kind: "noop"; interactionId: string };
-
-/**
- * 把 interaction 的新状态和对应动作绑定为一个不可拆分的结果。
- *
- * 在线执行与恢复调用方应同时消费 `interaction` 和 `outcome`，不要只持久化其中一半。
- */
-export interface PiToolInteractionTransition {
-  interaction: PiToolInteraction;
-  outcome: PiToolInteractionOutcome;
-}
-
-/**
- * 用户改为自由发言时写进 ToolResult 的提示语。
- *
- * 刻意**不包含用户原文** —— 紧随其后的那条用户消息里就有，复制进来模型会读到两遍。
- * 这段文字是模型判断「那句话算不算答案」的唯一依据，改动前先想清楚它会怎么读。
- */
-const CANCEL_TEXT: Record<PiToolInteractionCancelReason, string> = {
-  user_replied_freeform:
-    "The user did not pick an option. They replied in the chat instead — " +
-    "read their next message and treat it as the answer if it addresses " +
-    "the question; otherwise follow whatever they actually asked for.",
-  submission_terminal:
-    "The turn ended before the user answered. Do not assume any option was chosen.",
-};
-
-/**
- * 创建一条待响应的 interaction，并告诉调用方暂停当前 Tool。
- *
- * 执行适配器确认 Tool 声明了 `interaction` 后调用它，再把返回的记录持久化并等待客户端投递。
- *
- * 此处不填写响应时间或响应体，保证新记录只有一个明确的 `pending` 起点。
- */
-export function parkPiToolInteraction(
-  input: Omit<
-    PiToolInteraction,
-    "status" | "respondedAt" | "responseJson"
-  >,
-): PiToolInteractionTransition {
-  return {
-    interaction: { ...input, status: "pending" },
-    outcome: {
-      kind: "park",
-      interactionId: input.interactionId,
-      requestId: input.requestId,
-    },
-  };
-}
-
-/**
- * 把客户端的首次响应应用到待响应记录。
- *
- * 在线 RPC 与恢复路径在读到持久记录后调用它；已经结束的记录返回 `noop`，调用方不得再次结算 Tool。
- *
- * `toolResult` 由调用方按 Tool 自己的 `settle` 映射产出 —— 本函数不解释响应体语义，只负责状态单调前进。
- */
-export function respondPiToolInteraction(
-  interaction: PiToolInteraction,
-  input: {
-    response: unknown;
-    toolResult: ToolResultMessage;
-    respondedAt: number;
-  },
-): PiToolInteractionTransition {
-  if (interaction.status !== "pending") {
-    return {
-      interaction,
-      outcome: { kind: "noop", interactionId: interaction.interactionId },
-    };
-  }
-  return {
-    interaction: {
-      ...interaction,
-      status: "responded",
-      respondedAt: input.respondedAt,
-      responseJson: JSON.stringify(input.response),
-    },
-    outcome: {
-      kind: "settle",
-      interactionId: interaction.interactionId,
-      requestId: interaction.requestId,
-      toolCallId: interaction.toolCallId,
-      toolResult: input.toolResult,
-    },
-  };
-}
-
-/**
- * 在用户没有作答的情况下结束一条 interaction。
- *
- * `dispatchMessage` 发现 park 期间来了用户消息时调用，Submission 进终态收尾时也调用。
- *
- * 取消同样产出 `isError: false` 的稳定 ToolResult —— 它不是 Tool 失败，而是一个「没选」的已处理结果；
- * 改成异常会让模型收到 tool_error 并倾向于重试，那恰恰是我们不想要的。
- */
-export function cancelPiToolInteraction(
-  interaction: PiToolInteraction,
-  input: {
-    reason: PiToolInteractionCancelReason;
-    cancelledAt: number;
-    toolResult?: ToolResultMessage;
-  },
-): PiToolInteractionTransition {
-  if (interaction.status !== "pending") {
-    return {
-      interaction,
-      outcome: { kind: "noop", interactionId: interaction.interactionId },
-    };
-  }
-  const toolResult: ToolResultMessage = input.toolResult ?? {
-    role: "toolResult",
-    toolCallId: interaction.toolCallId,
-    toolName: interaction.toolName,
-    content: [{ type: "text", text: CANCEL_TEXT[input.reason] }],
-    details: { cancelled: true, reason: input.reason },
-    isError: false,
-    timestamp: input.cancelledAt,
-  };
-  return {
-    interaction: {
-      ...interaction,
-      status: "cancelled",
-      respondedAt: input.cancelledAt,
-    },
-    outcome: {
-      kind: "settle",
-      interactionId: interaction.interactionId,
-      requestId: interaction.requestId,
-      toolCallId: interaction.toolCallId,
-      toolResult,
-    },
-  };
-}