@springbrand/agent-runtime 0.1.0

package/src/index.ts

@@ -0,0 +1,133 @@
+/**
+ * Agent Runtime 的公共入口。
+ *
+ * @remarks
+ * 核心术语统一以这里为准。
+ *
+ * - `Agent` 是一个可按名寻址的 Cloudflare Agents 实例，也是持有独立存储的 Durable Object。
+ * - `facet` 是挂在父 Agent 下的子 Agent；它与父节点同机运行，但使用独立的 SQLite 存储。
+ * - `Session` 是本项目的聊天会话边界，由一个 `UniversalAgent` facet 承载。
+ * - `Turn` 是 Session 中从一次提示被接纳到输出终态的一次执行。
+ * - `Host` 是承载 Runtime 的 Cloudflare Agent，并负责提供生命周期、存储和网络边界。
+ * - `Kernel` 是 Runtime 内部连接 Cloudflare Agent 生命周期与 Pi 执行的核心实现。
+ * - `Pi` 是负责模型、Tool 循环和 canonical transcript 的执行层。
+ * - `Workspace` 是 Tool 可以读取或修改的受控文件系统视图。
+ * - `Memory` 是可跨 Turn 读取或写入的长期上下文能力。
+ * - `Tool` 是模型在 Turn 中可以调用的一项受控能力。
+ * - `Tool Candidate` 是尚未完成治理和编译的内部 Tool 定义。
+ * - `Tool Settlement` 是 Tool 调用完成后写回模型循环的统一结果。
+ * - `Governance` 是对 Tool 可见性、审批和执行条件的集中约束。
+ * - `Artifact` 是 Runtime 保存并对外引用的结构化执行产物。
+ * - `Extension` 是 Pi 在装配期加载、并在 Turn 中参与执行的扩展模块。
+ * - `SubAgent` 是由父 Agent 发起、但拥有独立执行上下文的子任务执行者。
+ * - `canonical transcript` 是 Pi 持久化和恢复 Turn 时使用的权威消息历史。
+ * - `admission` 是提示进入 Turn 前的接纳、去重和状态登记流程。
+ * - `AgentConfig` 是应用交给 Runtime 的一次完整装配说明。
+ * - `AgentPlugin` 是一种能力的加载与贡献单元。
+ * - `PluginKind` 是 Plugin 的固定类别，也是贡献时的稳定排序依据。
+ * - `loader` 读取业务数据或外部绑定，并返回本次装配要使用的值。
+ * - `prepare` 执行 `loader`，但不会改动正在运行的 Runtime。
+ * - `RuntimeContributionContext` 是 Plugin 写入候选配置的受限接口。
+ * - `Port` 是 Runtime 调用外部能力时依赖的最小接口。
+ * - `RuntimeBindings` 是本次装配选中的 Port 和可执行对象集合。
+ * - `RuntimeBuilder` 是包内实现，用来校验贡献并生成候选结果。
+ * - `RuntimeCandidate` 是尚未生效的候选结果和提交前检查。
+ * - `RuntimeSnapshot` 是一次成功提交后供 Kernel 读取的冻结装配选择。
+ * - `commit guard` 在最终提交前重新确认容易过期的业务条件。
+ * - `degradation` 表示某项可选能力不可用，但整体仍可以启动。
+ * - `runtime key` 标识当前 Agent 实例实际加载的是哪一份业务配置。
+ * - `RuntimeProfile` 是 Runtime 对当前能力、限制和退化状态的只读说明。
+ *
+ * Snapshot 不允许替换已选集合，但不承诺把每个 Port 的内部对象深冻结。
+ *
+ * 正常调用顺序是 `loader → prepare → contribute → validate → guard → commit`。
+ * 待确认：当前实现先校验 Plugin kind，再在 `prepare` 中调用 `loader`；这里的阶段简写是否仍应作为对外文档保留，需要与实际命名统一。
+ *
+ * 应用只创建 `AgentConfig` 和 Plugin。
+ *
+ * Runtime 独占校验、排序和原子提交。
+ *
+ * @packageDocumentation
+ */
+export * from "./kernel/bindings";
+export * from "./kernel/extensions";
+export * from "./kernel/profile";
+export * from "./kernel/receipts";
+export * from "./runtime-agent";
+export * from "./kernel/state";
+export * from "./lib/execution-level";
+export { definePlugin } from "./plugins";
+export type {
+  AgentConfig,
+  AgentPlugin,
+  AgentPluginSpec,
+  PluginKind,
+  PluginLoadResult,
+  PreparedPlugin,
+  RuntimeContributionContext,
+  RuntimeDegradation,
+  RuntimeProfileContribution,
+} from "./plugins";
+export type { ModelOption } from "./lib/model-catalog";
+export {
+  assembleSubagentPrompt,
+  assembleSystemPrompt,
+} from "./lib/prompt";
+export { HttpGateway } from "./lib/egress";
+export { decideHostActions } from "./lib/host-actions";
+export type {
+  HostActionPolicy,
+  HostActionSelection,
+} from "./lib/host-actions";
+export {
+  AGENT_TYPES,
+} from "./layers/orchestration/subagents/agent-types/registry";
+export type {
+  AgentType,
+} from "./layers/orchestration/subagents/agent-types/contract";
+export { withProviderRetry } from "./pi/runtime-adapter";
+export { compilePiTools } from "./pi/tool";
+export type {
+  CompilePiToolsOptions,
+  PiToolCandidate,
+  SettledPiToolCall,
+} from "./pi/tool";
+export { basePiToolCandidates } from "./pi/tool";
+export { schedulePiToolCandidates } from "./pi/tool";
+export {
+  sandboxPiToolCandidates,
+  workspacePiToolCandidates,
+} from "./pi/tool";
+export { subagentPiToolCandidates } from "./pi/tool";
+export { skillPiToolCandidates } from "./pi/tool";
+export type { PiSkillBinding } from "./pi/tool";
+export {
+  browserQuickActionPiToolCandidates,
+} from "./pi/tool";
+export {
+  workspaceCodeExecutionPiToolCandidate,
+} from "./pi/tool";
+export {
+  assemblePiExtensions,
+  loadPiExtension,
+} from "./pi/assembly";
+export type {
+  TemporaryAgentApprovalDecision,
+  TemporaryAgentApprovalRequest,
+  TemporaryAgentExecutor,
+  TemporaryAgentRequest,
+  TemporaryAgentRunContext,
+} from "./layers/orchestration/temporary-agent/core";
+export {
+  bridgeTemporaryAgentToolApprovals,
+  temporaryAgentExtensionIsSafe,
+  temporaryAgentToolAllowed,
+} from "./layers/orchestration/temporary-agent/runner";
+export {
+  createTemporaryAgentWorkspace,
+} from "./layers/orchestration/temporary-agent/workspace";
+export {
+  createPiModels,
+  resolvePiApiKey,
+  resolvePiModel,
+} from "./pi/runtime-adapter/models";

package/src/kernel/approval-lifecycle.ts

@@ -0,0 +1,552 @@
+import {
+  isTerminalSubmissionStatus,
+  type RuntimeDatabase,
+  type SubmissionStatus,
+} from "../db";
+import type {
+  PiDurableMutation,
+  PiRecoveryCommand,
+  PiRecoveryDecision,
+  PiRuntimeAdapter,
+  PiToolApproval,
+} from "../pi/runtime-adapter";
+import type { ApprovalDecision, ApprovalReceipt } from "./receipts";
+
+// #region 类型约定
+
+/**
+ * 提供审批流程定位一次持久化提交所需的最小信息。
+ *
+ * @remarks
+ * `Runtime` 创建审批流程并传入自己的提交记录时使用这个约束。
+ * 调用方要提供稳定的提交标识、请求标识、装配版本和当前状态。
+ * 这里只要求审批与恢复真正需要的字段，避免审批流程依赖完整提交模型。
+ * `Runtime` 等核心术语沿用包入口 `../index.ts` 的定义。
+ */
+export interface ApprovalSubmission {
+  readonly submissionId: string;
+  readonly requestId: string;
+  readonly assemblyRevision: string;
+  readonly status: SubmissionStatus;
+}
+
+/**
+ * 描述一次审批恢复任务重新进入 `Runtime` 时携带的数据。
+ *
+ * @remarks
+ * `ApprovalLifecycle` 安排恢复任务时写入它，`Runtime` 的调度回调触发时读取它。
+ * 调用方应原样传递这些字段，不要自行拼接恢复标识。
+ * 可选字段允许调度入口安全接收不完整数据，再由入口拒绝无效任务。
+ *
+ * TODO(待确认): 当前 `_piApprovalContinuation` 只读取 `submissionId` 和
+ * `approvalExecutionId`，`requestId` 与 `continuationKey` 尚未被消费。
+ */
+export interface ApprovalContinuationData {
+  readonly submissionId: string;
+  readonly requestId: string;
+  readonly continuationKey?: string;
+  readonly approvalExecutionId?: string;
+}
+
+/**
+ * 表示已经绑定到持久化提交的完整工具审批记录。
+ *
+ * @remarks
+ * 审批流程读取数据库后返回它，`Runtime` 的决定与恢复入口会使用它。
+ * 调用方应把 `executionId` 当作审批操作标识，把 `submissionId` 用于回查提交。
+ * 该类型复用 Pi 的审批字段，只补充数据库归属，避免维护第二份审批模型。
+ */
+export interface ApprovalRecord extends PiToolApproval {
+  readonly submissionId: string;
+}
+
+type RuntimeApprovalDecision = Exclude<
+  ApprovalDecision,
+  { decision: "allow_level" }
+>;
+
+// 宿主用这些依赖把审批状态机接入数据库、Pi 恢复计算和 Runtime 调度。
+interface ApprovalLifecycleOptions<
+  TSubmission extends ApprovalSubmission,
+> {
+  readonly db: RuntimeDatabase;
+  readonly pi: PiRuntimeAdapter;
+  readonly findSubmission: (submissionId: string) => TSubmission | null;
+  readonly applyRecoveryMutations: (
+    submission: TSubmission,
+    mutations: readonly PiDurableMutation[],
+  ) => boolean;
+  readonly materializeRecoveredToolResults: (
+    submission: TSubmission,
+  ) => Promise<PiRecoveryDecision>;
+  readonly scheduleContinuation: (
+    data: ApprovalContinuationData,
+  ) => Promise<void>;
+  readonly onApprovalsChanged: () => Promise<void>;
+}
+
+// #endregion
+
+// #region 审批流程 API
+
+/**
+ * 管理持久化工具审批从登记、等待、决定到恢复调度的完整过程。
+ *
+ * @remarks
+ * `Runtime` 为每个运行实例创建一个对象，并把 Pi Turn、用户决定和启动恢复都交给它。
+ * 调用方通过公开方法推进审批，但恢复后的 Pi Turn 仍由 `Runtime` 执行。
+ * 数据库记录和恢复里程碑必须在这里同步推进，否则重启后两份状态会分叉。
+ * `Runtime`、装配版本等核心术语沿用包入口 `../index.ts` 的定义。
+ */
+export class ApprovalLifecycle<
+  TSubmission extends ApprovalSubmission,
+> {
+  private readonly waiters = new Map<string, () => void>();
+
+  /**
+   * 接好审批流程需要的宿主依赖。
+   *
+   * @remarks
+   * `Runtime` 在构造自身时调用一次，后续方法都复用同一组数据库和恢复能力。
+   * 调用方应传入同一运行实例的依赖，不要跨实例共享提交查询或调度回调。
+   * 依赖由宿主注入，是为了让本类只协调审批，不接管 Turn 执行和外部调度。
+   */
+  constructor(
+    private readonly options: ApprovalLifecycleOptions<TSubmission>,
+  ) {}
+
+  /**
+   * 返回当前仍在运行的提交里有多少条待审批记录。
+   *
+   * @remarks
+   * `Runtime` 的恢复端口检查是否仍有人机交互等待时调用它。
+   * 调用方只应把结果用于判断当前是否繁忙，不要据此定位具体审批。
+   * 这里查询持久化活动记录而不是内存等待器，因为内存等待器会在重启时消失。
+   */
+  countPending(): number {
+    return this.options.db.approvals.countPendingActive();
+  }
+
+  /**
+   * 用工具调用标识查找唯一一条仍待处理的审批操作。
+   *
+   * @remarks
+   * `Runtime` 收到 `tool-approval` 客户端事件时调用它，再转交批准或拒绝入口。
+   * 调用方必须把 `null` 当作没有安全匹配，不应猜测要处理哪条记录。
+   * 数据库查询只在恰好一个匹配时返回标识，避免同名调用造成歧义决定。
+   */
+  findPendingExecution(toolCallId: string): string | null {
+    return this.options.db.approvals.findPendingByToolCallId(toolCallId);
+  }
+
+  /**
+   * 列出当前需要展示给用户的持久化审批。
+   *
+   * @remarks
+   * `Runtime` 广播审批状态时调用它，并与临时 Agent 的审批合并。
+   * 调用方应直接消费返回的 `ApprovalReceipt`，不要再从内存等待器推导状态。
+   * 这里只投影活动提交中的待处理记录，避免已结束 Turn 的旧审批重新出现。
+   */
+  list(): ApprovalReceipt[] {
+    return this.options.db.approvals.listPendingActive().map((row) => ({
+      executionId: row.executionId,
+      source: row.source as ApprovalReceipt["source"],
+      action: row.toolName,
+      summary: row.summary,
+      executionLevel: row.executionLevel,
+      requiredExecutionLevel: row.requiredExecutionLevel,
+      inputJson: row.inputJson,
+      requestId: row.requestId,
+    }));
+  }
+
+  /**
+   * 按审批操作标识读取一条完整的持久化审批。
+   *
+   * @remarks
+   * 决定审批、恢复回调和本类内部的幂等检查都会在需要最新状态时调用它。
+   * 调用方必须处理 `null`，因为记录可能不存在或已经被本地数据清理。
+   * 数据库是审批状态的来源。
+   * 内存等待器只负责唤醒当前请求，不能代替读取。
+   */
+  read(executionId: string): ApprovalRecord | null {
+    const stored = this.options.db.approvals.find(executionId);
+    if (!stored) return null;
+    return {
+      executionId: stored.executionId,
+      submissionId: stored.submissionId,
+      requestId: stored.requestId,
+      source: stored.source as ApprovalReceipt["source"],
+      toolCallId: stored.toolCallId,
+      toolName: stored.toolName,
+      summary: stored.summary,
+      executionLevel: stored.executionLevel,
+      requiredExecutionLevel: stored.requiredExecutionLevel,
+      inputJson: stored.inputJson,
+      status: stored.status,
+      createdAt: stored.createdAt,
+      ...(stored.decidedAt ? { decidedAt: stored.decidedAt } : {}),
+      ...(stored.reason ? { reason: stored.reason } : {}),
+    };
+  }
+
+  /**
+   * 持久化一条工具审批，并暂停当前工具执行直到有人作出决定。
+   *
+   * @remarks
+   * Pi Turn 在受控工具需要人工审批时调用它，可传入中止信号和首次创建回调。
+   * 调用方应等待返回的 Promise。
+   * 审批已存在时不会重复广播或调用 `onApproval`。
+   * 记录与恢复里程碑先在事务中落盘，再建立内存等待，保证重启仍能恢复审批。
+   */
+  async request(
+    submission: TSubmission,
+    approval: PiToolApproval,
+    signal?: AbortSignal,
+    onApproval?: (
+      approval: ApprovalRecord,
+    ) => void | Promise<void>,
+  ): Promise<void> {
+    const pending = this.options.db.transaction(() =>
+      this.ensurePending(submission, approval)
+    );
+    if (pending.created) {
+      await this.options.onApprovalsChanged();
+      await onApproval?.(pending.approval);
+    }
+    return this.wait(pending.approval, signal);
+  }
+
+  /**
+   * 在已批准工具结果落盘后，确认对应恢复调度已经完成。
+   *
+   * @remarks
+   * `Runtime.settleTool` 保存工具结果和恢复里程碑后调用它。
+   * 调用方只应在同一持久化事务内、确认工具结果已保存后调用。
+   * 提交点放在工具结果之后，避免恢复记录显示完成但实际结果尚未持久化。
+   */
+  commitContinuation(
+    submission: TSubmission,
+    toolCallId: string,
+  ): void {
+    const approval = this.read(
+      `${submission.submissionId}:${toolCallId}`,
+    );
+    if (!approval || approval.status === "pending") return;
+    const decision = this.decideRecovery(submission);
+    if (
+      decision.effect.kind !== "schedule-continuation" ||
+      !decision.effect.continuationKey.startsWith(
+        `approval:${approval.executionId}:`,
+      )
+    ) {
+      return;
+    }
+    const committed = this.decideRecovery(submission, {
+      kind: "commit-continuation",
+      continuationKey: decision.effect.continuationKey,
+    });
+    this.options.applyRecoveryMutations(
+      submission,
+      committed.mutations,
+    );
+  }
+
+  /**
+   * 把某次提交下仍待处理的全部审批统一拒绝。
+   *
+   * @remarks
+   * `Runtime` 提交终态时调用它，确保已经结束的 Turn 不再留下可操作审批。
+   * 调用方应把返回值理解为是否找到待审批记录，并负责随后广播最新状态。
+   * 这里通过 Pi 恢复决策写入拒绝结果，不直接改表，避免数据库与恢复里程碑分叉。
+   */
+  rejectPending(
+    submission: TSubmission,
+    reason: string,
+  ): boolean {
+    const pendingIds = this.options.db.approvals
+      .listPendingForSubmission(submission.submissionId);
+    if (pendingIds.length === 0) return false;
+
+    for (const executionId of pendingIds) {
+      const stored = this.read(executionId);
+      if (!stored) continue;
+      const pending = this.decideRecovery(submission, {
+        kind: "record-approval",
+        approval: stored,
+      });
+      this.options.applyRecoveryMutations(
+        submission,
+        pending.mutations,
+      );
+      const decision = this.decideRecovery(submission, {
+        kind: "approval-decision",
+        executionId: stored.executionId,
+        approved: false,
+        reason,
+      });
+      this.options.applyRecoveryMutations(
+        submission,
+        decision.mutations,
+      );
+    }
+    return true;
+  }
+
+  /**
+   * 接受一次批准或拒绝，并唤醒当前工具执行或安排恢复任务。
+   *
+   * @remarks
+   * `Runtime.approve` 和 `Runtime.reject` 收到用户决定时调用它。
+   * 调用方应使用审批 `executionId`，并根据 `ok` 判断本次决定是否真正生效。
+   * 决定及里程碑在同一事务中写入。
+   * 有内存等待器时直接唤醒，没有时走持久化调度。
+   * 不存在的标识按幂等成功处理，终态提交或重复决定则返回 `ok: false`。
+   */
+  async decide(
+    executionId: string,
+    input: RuntimeApprovalDecision,
+  ): Promise<{ ok: boolean }> {
+    const approved = input.decision === "allow_once";
+    const reason = input.decision === "deny" ? input.reason : undefined;
+    const stored = this.read(executionId);
+    if (!stored) return { ok: true };
+    const submission = this.options.findSubmission(stored.submissionId);
+    if (!submission || isTerminalSubmissionStatus(submission.status)) {
+      return { ok: false };
+    }
+    if (stored.status !== "pending") {
+      if (!this.waiters.has(stored.executionId)) {
+        await this.dispatchContinuation(
+          submission,
+          stored.executionId,
+        );
+      }
+      return { ok: false };
+    }
+
+    const pending = this.decideRecovery(submission, {
+      kind: "record-approval",
+      approval: stored,
+    });
+    const decision = this.decideRecovery(
+      submission,
+      {
+        kind: "approval-decision",
+        executionId: stored.executionId,
+        approved,
+        reason,
+      },
+      [
+        ...this.milestoneBodies(submission.submissionId),
+        ...pending.mutations.flatMap((mutation) =>
+          mutation.kind === "append-milestone"
+            ? [mutation.body]
+            : []
+        ),
+      ],
+    );
+    if (!decision.applied) return { ok: false };
+    this.options.db.transaction(() => {
+      this.options.applyRecoveryMutations(
+        submission,
+        [...pending.mutations, ...decision.mutations],
+      );
+    });
+    const persisted = this.read(stored.executionId);
+    if (!persisted || persisted.status === "pending") {
+      return { ok: false };
+    }
+    const waiter = this.waiters.get(stored.executionId);
+    if (!approved && waiter) {
+      await this.options.materializeRecoveredToolResults(submission);
+    }
+    await this.options.onApprovalsChanged();
+
+    if (waiter) {
+      waiter();
+      return { ok: true };
+    }
+
+    await this.dispatchContinuation(
+      submission,
+      persisted.executionId,
+    );
+    return { ok: true };
+  }
+
+  /**
+   * 为一条已决定审批安排可恢复的后续执行。
+   *
+   * @remarks
+   * 没有内存等待器的决定、启动扫描和通用恢复循环会调用它。
+   * 调用方应传入审批所属提交和对应 `executionId`；不匹配的恢复计划会安全返回。
+   * 顺序必须保持为先记录 pending、再调度；只有 durable ToolResult 落盘后才能记录 committed，
+   * 否则调度回调在 Runtime 装配失败时会失去下一次启动的补发依据。
+   */
+  async dispatchContinuation(
+    submission: TSubmission,
+    executionId: string,
+  ): Promise<void> {
+    if (isTerminalSubmissionStatus(submission.status)) return;
+    const decision = this.decideRecovery(submission);
+    if (
+      decision.effect.kind !== "schedule-continuation" ||
+      !decision.effect.continuationKey.startsWith(
+        `approval:${executionId}:`,
+      )
+    ) {
+      return;
+    }
+    this.options.db.transaction(() => {
+      this.options.applyRecoveryMutations(
+        submission,
+        decision.mutations,
+      );
+    });
+    await this.options.scheduleContinuation({
+      submissionId: submission.submissionId,
+      requestId: submission.requestId,
+      continuationKey: decision.effect.continuationKey,
+      approvalExecutionId: executionId,
+    });
+  }
+
+  /**
+   * 扫描持久化决定，并补发仍需要执行的审批恢复任务。
+   *
+   * @remarks
+   * `Runtime.onStart` 在广播当前审批后调用它。
+   * 调用方应等待扫描结束，再继续普通的提交恢复流程。
+   * 重启会丢失内存等待器，所以这里从数据库重建后续动作，并复用幂等调度路径。
+   */
+  async dispatchPendingContinuations(): Promise<void> {
+    for (const approval of this.options.db.approvals.listDecided()) {
+      const submission = this.options.findSubmission(
+        approval.submissionId,
+      );
+      if (submission) {
+        await this.dispatchContinuation(
+          submission,
+          approval.executionId,
+        );
+      }
+    }
+  }
+
+  // #endregion
+
+  // #region 恢复辅助方法
+
+  // 作用：读取一个 Submission 的全部恢复里程碑正文。
+  // 调用：恢复计算在每次生成决策前调用。
+  // 原因：持久化历史必须作为恢复决策的唯一输入。
+  private milestoneBodies(submissionId: string): string[] {
+    return this.options.db.milestones.listBodies(submissionId);
+  }
+
+  // 作用：请求 Pi 根据当前里程碑给出下一步。
+  // 调用：审批请求、决定、终态拒绝和恢复调度路径调用。
+  // 原因：所有路径共用同一决策入口，避免各自改写恢复状态。
+  private decideRecovery(
+    submission: TSubmission,
+    command: PiRecoveryCommand = { kind: "inspect" },
+    milestoneBodies = this.milestoneBodies(submission.submissionId),
+  ): PiRecoveryDecision {
+    return this.options.pi.decideRecovery({
+      milestoneBodies,
+      identity: {
+        turnId: submission.submissionId,
+        assemblyRevision: submission.assemblyRevision,
+      },
+      command,
+      now: Date.now(),
+    });
+  }
+
+  // 作用：复用或创建一条 pending Approval。
+  // 调用：`request` 在准入事务内调用。
+  // 原因：已存在记录的字段冲突必须报错，不能覆盖旧审批。
+  private ensurePending(
+    submission: TSubmission,
+    approval: PiToolApproval,
+  ): { approval: ApprovalRecord; created: boolean } {
+    const existing = this.read(
+      `${submission.submissionId}:${approval.toolCallId}`,
+    );
+    if (existing) {
+      if (
+        existing.requestId !== submission.requestId ||
+        existing.toolName !== approval.toolName ||
+        existing.executionLevel !== approval.executionLevel ||
+        existing.requiredExecutionLevel !==
+          approval.requiredExecutionLevel ||
+        existing.inputJson !== approval.inputJson
+      ) {
+        throw new Error(
+          `Conflicting durable Tool approval: ${approval.toolCallId}`,
+        );
+      }
+      return { approval: existing, created: false };
+    }
+
+    this.options.db.approvals.insert({
+      executionId: approval.executionId,
+      submissionId: submission.submissionId,
+      requestId: approval.requestId,
+      source: approval.source,
+      toolCallId: approval.toolCallId,
+      toolName: approval.toolName,
+      summary: approval.summary,
+      executionLevel: approval.executionLevel,
+      requiredExecutionLevel: approval.requiredExecutionLevel,
+      inputJson: approval.inputJson,
+      status: approval.status,
+      createdAt: approval.createdAt,
+    });
+    const decision = this.decideRecovery(submission, {
+      kind: "record-approval",
+      approval,
+    });
+    this.options.applyRecoveryMutations(
+      submission,
+      decision.mutations,
+    );
+    return {
+      approval: {
+        ...approval,
+        submissionId: submission.submissionId,
+      },
+      created: true,
+    };
+  }
+
+  // 作用：等待当前进程里的审批决定。
+  // 调用：`request` 在持久化 pending Approval 后调用。
+  // 原因：内存 Promise 只负责唤醒当前请求，数据库仍负责持久状态以支持重启。
+  private wait(
+    approval: ApprovalRecord,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (approval.status !== "pending") return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      // 清掉本地等待器并转发中止原因。AbortSignal 触发或已中止检查都会走这里。
+      const abort = () => {
+        this.waiters.delete(approval.executionId);
+        reject(signal?.reason ?? new Error("Tool execution aborted"));
+      };
+      if (signal?.aborted) {
+        abort();
+        return;
+      }
+      signal?.addEventListener("abort", abort, { once: true });
+      this.waiters.set(approval.executionId, () => {
+        signal?.removeEventListener("abort", abort);
+        this.waiters.delete(approval.executionId);
+        resolve();
+      });
+    });
+  }
+
+  // #endregion
+}