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

package/src/kernel/interaction-lifecycle.ts

@@ -1,433 +0,0 @@
-import {
-  isTerminalSubmissionStatus,
-  type RuntimeDatabase,
-  type StoredToolInteraction,
-  type SubmissionStatus,
-} from "../db";
-import type {
-  PiDurableMutation,
-  PiRecoveryCommand,
-  PiRecoveryDecision,
-  PiRuntimeAdapter,
-  PiToolInteraction,
-  PiToolInteractionCancelReason,
-} from "../pi/runtime-adapter";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-
-// #region 类型约定
-
-/**
- * 提供 interaction 流程定位一次持久化提交所需的最小信息。
- *
- * @remarks
- * 与 `ApprovalSubmission` 同形。这里只要求 park/续跑真正需要的字段，
- * 避免 interaction 流程依赖完整提交模型。
- */
-export interface InteractionSubmission {
-  readonly submissionId: string;
-  readonly requestId: string;
-  readonly assemblyRevision: string;
-  readonly status: SubmissionStatus;
-}
-
-/**
- * 表示已经绑定到持久化提交的完整 interaction 记录。
- */
-export interface InteractionRecord extends PiToolInteraction {
-  readonly submissionId: string;
-}
-
-/**
- * 描述一次响应或取消要写入的 ToolResult 载荷。
- *
- * `content` / `details` 由 Tool 自己的 `settle` 映射产出 —— 本流程不解释响应体语义。
- * 取消不带载荷，由纯函数层用固定文案兜底。
- */
-export type InteractionSettlementPayload = Omit<
-  AgentToolResult<unknown>,
-  "terminate"
->;
-
-// 宿主用这些依赖把 interaction 状态机接入数据库、Pi 恢复计算和 Turn 续跑。
-interface InteractionLifecycleOptions<
-  TSubmission extends InteractionSubmission,
-> {
-  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>;
-  /** 没有内存等待器时（DO 睡过一觉）把原 Turn 重新拉起来。 */
-  readonly resumeSubmission: (submissionId: string) => Promise<void>;
-  /**
-   * pending 集合发生变化后通知宿主重算活动状态投影。
-   *
-   * park 和结算都会触发。宿主的 needs-input 是 pending 行的纯函数，
-   * 没有这个回调，park 的那一刻不会有人去重算 —— 侧栏要等下一次广播才翻牌。
-   */
-  readonly onInteractionsChanged?: () => Promise<void>;
-  readonly onTelemetryRequested?: (interaction: InteractionRecord) => void;
-  readonly onTelemetrySettled?: (interaction: InteractionRecord) => void;
-}
-
-// #endregion
-
-// #region interaction 流程 API
-
-/**
- * 管理「结果由客户端提供」的 Tool 从 park、等待、响应到续跑的完整过程。
- *
- * @remarks
- * 与 `ApprovalLifecycle` 结构同源但显著更小 —— 不需要 `allow_level` 的 Host 协调、
- * 不需要批准后 `retryTool`、不需要执行档位矩阵。两者的重复是**当前有意接受的**：
- * 审批那条路已经跑在线上，等 interaction 跑稳后再考虑抽公共核，届时改的是这两个类，
- * 不是恢复状态机。
- *
- * 续跑不走 interaction 专属的调度键：响应会同时写下一条权威 `tool-result` 里程碑，
- * 因此复用 `planPiToolRecovery` 中既有的 `tool:<id>:settled` 分支。
- */
-export class InteractionLifecycle<
-  TSubmission extends InteractionSubmission,
-> {
-  private readonly waiters = new Map<string, () => void>();
-
-  constructor(
-    private readonly options: InteractionLifecycleOptions<TSubmission>,
-  ) {}
-
-  /**
-   * 用工具调用标识查找唯一一条仍待响应的 interaction。
-   *
-   * @remarks
-   * `Runtime.respondToolInteraction` 调用它 —— 前端只有 `toolCallId`。
-   * 调用方必须把 `null` 当作没有安全匹配，不应猜测要处理哪条记录。
-   */
-  findPending(toolCallId: string): InteractionRecord | null {
-    const stored = this.options.db.interactions
-      .findPendingByToolCallId(toolCallId);
-    return stored ? toRecord(stored) : null;
-  }
-
-  /**
-   * 按 interactionId 读取一条完整记录，不存在时返回 null。
-   */
-  read(interactionId: string): InteractionRecord | null {
-    const stored = this.options.db.interactions.find(interactionId);
-    return stored ? toRecord(stored) : null;
-  }
-
-  /**
-   * 持久化一条 interaction，并暂停当前工具执行直到客户端投递响应。
-   *
-   * @remarks
-   * 执行适配器在 Tool 声明了 `interaction` 时调用它。
-   * 记录与恢复里程碑先在事务中落盘，再建立内存等待，保证重启仍能恢复 park 状态。
-   */
-  async request(
-    submission: TSubmission,
-    interaction: PiToolInteraction,
-    signal?: AbortSignal,
-  ): Promise<void> {
-    const pending = this.options.db.transaction(() => {
-      const value = this.ensurePending(submission, interaction);
-      if (value.created) {
-        try {
-          this.options.onTelemetryRequested?.(value.interaction);
-        } catch {
-          // Observability must not change interaction durability.
-        }
-      }
-      return value.interaction;
-    });
-    // Register synchronously, then publish while waiting for the person. An
-    // early response must release this execution instead of starting recovery.
-    const waiting = this.wait(pending, signal);
-    try {
-      await Promise.all([
-        waiting,
-        (async () => { await this.options.onInteractionsChanged?.(); })(),
-      ]);
-    } catch (error) {
-      this.waiters.get(pending.interactionId)?.();
-      throw error;
-    }
-  }
-
-  /**
-   * 应用客户端的首次响应，结算对应 Tool 并唤醒原 Turn。
-   *
-   * @remarks
-   * `Runtime.respondToolInteraction` 在校验并映射出 ToolResult 后调用它。
-   * 不存在、已结束或提交已终态都返回 `{ ok: false }`，不抛 —— 口径对齐 `ApprovalLifecycle.decide`。
-   */
-  async respond(
-    interactionId: string,
-    response: unknown,
-    payload: InteractionSettlementPayload,
-  ): Promise<{ ok: boolean }> {
-    return this.settle(interactionId, {
-      kind: "respond",
-      response,
-      result: payload,
-    });
-  }
-
-  /**
-   * 在用户没有作答的情况下结束一条 interaction 并让 Turn 继续。
-   *
-   * @remarks
-   * park 期间收到用户消息时调用（`user_replied_freeform`），提交进终态时也调用。
-   * 取消同样产出稳定 ToolResult，不是 Tool 失败 —— 否则模型会收到 tool_error 并倾向重试。
-   */
-  async cancel(
-    interactionId: string,
-    reason: PiToolInteractionCancelReason,
-  ): Promise<{ ok: boolean }> {
-    return this.settle(interactionId, { kind: "cancel", reason });
-  }
-
-  /**
-   * 把某次提交下仍待响应的全部 interaction 一次性取消。
-   *
-   * @remarks
-   * `dispatchMessage` 发现 park 期间来了用户消息时、以及提交进终态时调用。
-   * 返回是否真的取消过记录，调用方据此决定要不要广播。
-   */
-  async cancelPendingForSubmission(
-    submissionId: string,
-    reason: PiToolInteractionCancelReason,
-  ): Promise<boolean> {
-    const pending = this.options.db.interactions
-      .listPendingForSubmission(submissionId);
-    if (pending.length === 0) return false;
-    let cancelled = false;
-    for (const interactionId of pending) {
-      const result = await this.cancel(interactionId, reason);
-      cancelled ||= result.ok;
-    }
-    return cancelled;
-  }
-
-  /**
-   * 在同步终态事务里把某次提交下仍待响应的 interaction 全部取消。
-   *
-   * @remarks
-   * `Runtime.commitTerminalOutcome` 在提交终态的 `transaction` 内调用，因此必须是同步的。
-   * 这里只推进状态和里程碑，**不** materialize、**不** 续跑 —— Turn 正在结束，
-   * 调用方负责在同一事务内调用 `materializeRecoveredToolResultsSync`，口径对齐审批的 `rejectPending`。
-   *
-   * 返回是否真的取消过记录；没有 pending 时返回 false，调用方可据此跳过 materialize。
-   */
-  cancelPendingForSubmissionSync(
-    submission: TSubmission,
-    reason: PiToolInteractionCancelReason = "submission_terminal",
-  ): boolean {
-    const pending = this.options.db.interactions
-      .listPendingForSubmission(submission.submissionId);
-    if (pending.length === 0) return false;
-    for (const interactionId of pending) {
-      const decision = this.decideRecovery(submission, {
-        kind: "interaction-settlement",
-        interactionId,
-        settlement: { kind: "cancel", reason },
-      });
-      this.options.applyRecoveryMutations(submission, decision.mutations);
-      const settled = this.read(interactionId);
-      if (settled) {
-        try {
-          this.options.onTelemetrySettled?.(settled);
-        } catch {
-          // Observability must not change terminal cleanup.
-        }
-      }
-    }
-    return true;
-  }
-
-  /**
-   * 判断某次提交当前是否停在等待客户端响应上。
-   *
-   * @remarks
-   * `dispatchMessage` 用它决定要不要把 delivery 提升成 steer —— 否则 enqueue 的消息
-   * 要等这个 Turn 结束，而这个 Turn 正在等一个不会来的答案，死锁。
-   */
-  hasPendingForSubmission(submissionId: string): boolean {
-    return this.options.db.interactions
-      .listPendingForSubmission(submissionId).length > 0;
-  }
-
-  // #endregion
-
-  // #region 内部
-
-  // 作用：把响应或取消统一走同一条持久化 + 唤醒路径。
-  // 调用：`respond` 和 `cancel`。
-  // 原因：两种结局的差别只在 ToolResult 从哪来，状态推进和续跑必须完全一致。
-  private async settle(
-    interactionId: string,
-    settlement:
-      | {
-          kind: "respond";
-          response: unknown;
-          result: InteractionSettlementPayload;
-        }
-      | { kind: "cancel"; reason: PiToolInteractionCancelReason },
-  ): Promise<{ ok: boolean }> {
-    const stored = this.read(interactionId);
-    if (!stored) return { ok: false };
-    const submission = this.options.findSubmission(stored.submissionId);
-    if (!submission || isTerminalSubmissionStatus(submission.status)) {
-      return { ok: false };
-    }
-    if (stored.status !== "pending") return { ok: false };
-
-    const decision = this.decideRecovery(submission, {
-      kind: "interaction-settlement",
-      interactionId,
-      settlement,
-    });
-    if (!decision.applied) return { ok: false };
-    this.options.db.transaction(() => {
-      this.options.applyRecoveryMutations(submission, decision.mutations);
-      const settled = this.read(interactionId);
-      if (settled && settled.status !== "pending") {
-        try {
-          this.options.onTelemetrySettled?.(settled);
-        } catch {
-          // Observability must not change interaction settlement.
-        }
-      }
-    });
-    const persisted = this.read(interactionId);
-    if (!persisted || persisted.status === "pending") {
-      return { ok: false };
-    }
-
-    // 把刚写下的权威 tool-result 落成 settlement 行 —— park 住的执行链醒来后
-    // 只认 findToolSettlement，不读里程碑。这一步必须早于唤醒。
-    await this.options.materializeRecoveredToolResults(submission);
-    // 先重算活动状态再唤醒：唤醒会把 Turn 一路跑下去，晚通知就会让「等待回复」
-    // 在续跑期间多挂一段时间。
-    await this.options.onInteractionsChanged?.();
-
-    const waiter = this.waiters.get(interactionId);
-    if (waiter) {
-      waiter();
-      return { ok: true };
-    }
-    // 没有内存等待器 = DO 在 park 期间睡过一觉，原 Turn 的执行栈已经没了。
-    // 走持久恢复把它重新拉起来，里程碑里的 tool-result 会被当成已结算结果复用。
-    await this.options.resumeSubmission(submission.submissionId);
-    return { ok: true };
-  }
-
-  // 作用：读取一个 Submission 的全部恢复里程碑正文。
-  // 原因：持久化历史必须作为恢复决策的唯一输入。
-  private milestoneBodies(submissionId: string): string[] {
-    return this.options.db.milestones.listBodies(submissionId);
-  }
-
-  // 作用：请求 Pi 根据当前里程碑给出下一步。
-  // 原因：所有路径共用同一决策入口，避免各自改写恢复状态。
-  private decideRecovery(
-    submission: TSubmission,
-    command: PiRecoveryCommand = { kind: "inspect" },
-  ): PiRecoveryDecision {
-    return this.options.pi.decideRecovery({
-      milestoneBodies: this.milestoneBodies(submission.submissionId),
-      identity: {
-        turnId: submission.submissionId,
-        assemblyRevision: submission.assemblyRevision,
-      },
-      command,
-      now: Date.now(),
-    });
-  }
-
-  // 作用：复用或创建一条 pending interaction。
-  // 调用：`request` 在准入事务内调用。
-  // 原因：已存在记录的字段冲突必须报错，不能把响应投给另一次调用。
-  private ensurePending(
-    submission: TSubmission,
-    interaction: PiToolInteraction,
-  ): { interaction: InteractionRecord; created: boolean } {
-    const existing = this.read(interaction.interactionId);
-    if (existing) {
-      if (
-        existing.requestId !== submission.requestId ||
-        existing.toolCallId !== interaction.toolCallId ||
-        existing.toolName !== interaction.toolName ||
-        existing.inputJson !== interaction.inputJson
-      ) {
-        throw new Error(
-          `Conflicting durable Tool interaction: ${interaction.toolCallId}`,
-        );
-      }
-      return { interaction: existing, created: false };
-    }
-    // 表行和恢复里程碑都由 record-interaction 这一条命令产出，
-    // 不在这里直接 insert —— 两份状态分叉正是恢复最难查的一类 bug。
-    const decision = this.decideRecovery(submission, {
-      kind: "record-interaction",
-      interaction,
-    });
-    this.options.applyRecoveryMutations(submission, decision.mutations);
-    return {
-      interaction: { ...interaction, submissionId: submission.submissionId },
-      created: true,
-    };
-  }
-
-  // 作用：等待当前进程里的客户端响应。
-  // 原因：内存 Promise 只负责唤醒当前请求，数据库仍负责持久状态以支持重启。
-  private wait(
-    interaction: InteractionRecord,
-    signal?: AbortSignal,
-  ): Promise<void> {
-    if (interaction.status !== "pending") return Promise.resolve();
-    return new Promise((resolve, reject) => {
-      const abort = () => {
-        this.waiters.delete(interaction.interactionId);
-        reject(signal?.reason ?? new Error("Tool interaction aborted"));
-      };
-      if (signal?.aborted) {
-        abort();
-        return;
-      }
-      signal?.addEventListener("abort", abort, { once: true });
-      this.waiters.set(interaction.interactionId, () => {
-        signal?.removeEventListener("abort", abort);
-        this.waiters.delete(interaction.interactionId);
-        resolve();
-      });
-    });
-  }
-
-  // #endregion
-}
-
-// 把持久行转成流程内部使用的记录。
-// find / findPending 查到记录后调用，上层因而只看 Pi 的 interaction 形状。
-function toRecord(stored: StoredToolInteraction): InteractionRecord {
-  return {
-    interactionId: stored.interactionId,
-    submissionId: stored.submissionId,
-    requestId: stored.requestId,
-    toolCallId: stored.toolCallId,
-    toolName: stored.toolName,
-    inputJson: stored.inputJson,
-    status: stored.status,
-    createdAt: stored.createdAt,
-    ...(stored.respondedAt === null
-      ? {}
-      : { respondedAt: stored.respondedAt }),
-    ...(stored.responseJson === null
-      ? {}
-      : { responseJson: stored.responseJson }),
-  };
-}