@springbrand/agent-runtime 0.1.0

package/src/pi/runtime-adapter/execution.ts

@@ -0,0 +1,683 @@
+import {
+  Agent as PiCore,
+  convertToLlm,
+  type AgentEvent,
+  type AgentMessage,
+  type AgentOptions,
+  type ThinkingLevel,
+} from "@earendil-works/pi-agent-core";
+import type {
+  Api,
+  AssistantMessage,
+  Model,
+  Models,
+  ToolResultMessage,
+  UserMessage,
+} from "@earendil-works/pi-ai";
+import { requiresPiToolApproval, parkPiToolApproval } from "../turn";
+import { PiChunkEncoder } from "../message";
+import type { UIMessageChunk } from "ai";
+import {
+  compilePiTools,
+  createPiToolGovernance,
+  type PiToolCandidate,
+  type PiToolGovernance,
+  type PiToolTelemetry,
+  type SettledPiToolCall,
+} from "../tool";
+import {
+  piToolRetryPolicy,
+  readPinnedPiRuntime,
+  type PreparedPiRuntime,
+} from "./assembly";
+import { resolvePiApiKey, withProviderRetry } from "./models";
+
+// #region Single-run Pi bridge
+
+/**
+ * 把 Pi 的终止原因翻译成本仓的回合结局。
+ *
+ * 调用：终态提交(`onTerminal`)与流式记录的 `turnStatus` 共用这一处,
+ * 保证服务端只有一份判据 —— 两处各写一遍三元链正是它们悄悄分叉的原因。
+ *
+ * 为什么未知取值判失败而不是成功:`stopReason` 是上游会扩的联合体
+ * (0.83 就加了 `"pending"`)。把认不出的结局宣称成「成功」，等于让一次
+ * 异常结束伪装成正常完成 —— 这是本仓明确禁止的假完成，
+ * 也是 Pi 自己在 0.83 的选择(认不出的终止原因直接抛错而非压平成 stop)。
+ * 前端对未知取值取 `"running"`(未知即未定)，最终由服务端这份权威判据校正。
+ */
+function classifyPiStopReason(stopReason: string | undefined): {
+  outcome: PiTurnTerminalIntent["outcome"];
+  turnStatus: "completed" | "error" | "aborted";
+  message?: string;
+} {
+  switch (stopReason) {
+    case "stop":
+    case "length":
+      return { outcome: "succeeded", turnStatus: "completed" };
+    case "aborted":
+      return { outcome: "aborted", turnStatus: "aborted" };
+    case "error":
+      return { outcome: "failed", turnStatus: "error" };
+    default:
+      return {
+        outcome: "failed",
+        turnStatus: "error",
+        message: `Pi ended the turn with an unrecognized stop reason: ${
+          stopReason ?? "(none)"
+        }`,
+      };
+  }
+}
+
+interface PiTurnAdapterOptions {
+  readonly pi: {
+    readonly model: Model<Api>;
+    readonly thinkingLevel?: ThinkingLevel;
+  };
+  readonly models: Models;
+  readonly apiKey: string;
+  // 读取这次执行真正要交给 Pi 的 canonical transcript。
+  // PiTurnAdapter.run 在创建 PiCore 前调用它，宿主应返回当时最新的 transcript。
+  // 这里保留为延迟读取，是为了避免适配器创建后新增的恢复消息被旧快照漏掉。
+  readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
+  readonly denyTools?: readonly string[];
+  // 把工具的最终结果交回宿主持久化。
+  // 共享工具编译器在向 Pi 返回成功或规范化失败前调用它。
+  // 这个先落库再发布结果的顺序是恢复边界，不能改成事后异步补写。
+  readonly settle: (
+    call: SettledPiToolCall,
+  ) => void | Promise<void>;
+  // 上报工具执行耗时、结果大小和成败。
+  // 工具治理层在每次执行结束时调用它，宿主可选择不提供。
+  // 该回调只负责观测，工具治理层会吞掉它的异常以免改变执行结果。
+  readonly onToolTelemetry?: (event: PiToolTelemetry) => void;
+  // 在模型调用前调整 Pi 的消息上下文。
+  // PiCore 通过 AgentOptions.transformContext 调用它，Runtime 用它接入现有上下文处理。
+  // 直接复用 Pi 的回调类型可避免这里维护另一套上下文转换约定。
+  readonly transformContext: NonNullable<AgentOptions["transformContext"]>;
+}
+
+class PiTurnAdapter {
+  private piInstance?: PiCore;
+  private abortRequested = false;
+  private readonly pendingSteers: UserMessage[] = [];
+  private readonly governance: PiToolGovernance;
+
+  // 创建一个 Turn 所需的短生命周期 Pi 执行器状态。
+  // PreparedPiTurnAdapter 只构造一次，并把运行、重试、转向和中止都交给它。
+  // 工具治理对象必须在这些路径间复用，因为它保存本 Turn 的重试次数和熔断状态。
+  constructor(private readonly opts: PiTurnAdapterOptions) {
+    this.governance = createPiToolGovernance(opts.onToolTelemetry);
+  }
+
+  // 把 Tool candidate 变成 Pi 可以执行的受治理 Tool。
+  // 正常运行会编译 Pinned Runtime 的整份列表，恢复时只编译指定 Tool candidate。
+  // 拒绝规则、重名检查、输出限额和持久化结算统一走共享编译器，避免恢复另开旁路。
+  private compile(candidates: readonly PiToolCandidate[]) {
+    return compilePiTools(candidates, {
+      deny: this.opts.denyTools,
+      governance: this.governance,
+      settle: this.opts.settle,
+    });
+  }
+
+  // 用正常 Turn 的受治理路径重新执行一次已知工具调用。
+  // recovery effect 和审批续跑在找到原调用记录对应的 Tool candidate 后调用它。
+  // Tool candidate 被过滤时返回 false，让调用方安全停止；实际执行仍保留结算和重试上限。
+  async retryTool(
+    candidate: PiToolCandidate,
+    toolCallId: string,
+    input: unknown,
+  ): Promise<boolean> {
+    const [tool] = this.compile([candidate]);
+    if (!tool) return false;
+    await tool.execute(toolCallId, input);
+    return true;
+  }
+
+  // 在 Pi 运行实例可用后尽快停止这个 Turn。
+  // Runtime 可能在 run() 之前或期间发出取消，因此尚未创建 PiCore 时先记住请求。
+  // canonical transcript 读取是异步的，其间没有可中止的 Pi 实例，所以不能删掉启动前标记。
+  abort(): void {
+    if (this.piInstance) this.piInstance.abort();
+    else this.abortRequested = true;
+  }
+
+  // 把一条用户消息排入当前 Turn。
+  // 提交仍在运行时收到扩展宿主消息，Runtime 会调用这里。
+  // PiCore 创建前先缓冲消息，可覆盖异步启动窗口，同时不引入第二份 transcript 来源。
+  steer(message: UserMessage): void {
+    if (this.piInstance) this.piInstance.steer(message);
+    else this.pendingSteers.push(message);
+  }
+
+  // 从当前 canonical transcript 继续运行 Pi，并把生命周期事件交给监听器。
+  // Submission 的首次执行或恢复执行取得 Pinned Runtime 后，PreparedPiTurnAdapter 调用这里。
+  // 每次新建 PiCore 可隔离运行状态；等待订阅回调并在 finally 清理可保住 Pi 的事件屏障语义。
+  async run(
+    opts: {
+      readonly systemPrompt: string;
+      readonly tools: readonly PiToolCandidate[];
+      readonly signal?: AbortSignal;
+    },
+    listener: (event: AgentEvent) => void | Promise<void>,
+  ): Promise<void> {
+    const { systemPrompt, signal } = opts;
+    signal?.throwIfAborted();
+    const canonicalMessages = await this.opts.canonicalMessages();
+    const tools = this.compile(opts.tools);
+    const pi = new PiCore({
+      convertToLlm,
+      streamFn: withProviderRetry(
+        this.opts.models.streamSimple.bind(this.opts.models),
+      ),
+      getApiKey: () => this.opts.apiKey,
+      transformContext: this.opts.transformContext,
+      afterToolCall: this.governance.afterToolCall,
+      initialState: {
+        model: this.opts.pi.model,
+        systemPrompt,
+        messages: [...canonicalMessages],
+        tools: [...tools],
+        ...(this.opts.pi.thinkingLevel !== undefined
+          ? { thinkingLevel: this.opts.pi.thinkingLevel }
+          : {}),
+      },
+    });
+
+    this.piInstance = pi;
+    for (const message of this.pendingSteers.splice(0)) {
+      pi.steer(message);
+    }
+    const unsubscribe = pi.subscribe(listener);
+    // 把调用方的 AbortSignal 转发给只存在于本方法内的 Pi 运行实例。
+    // continue() 尚未结束时信号监听器会调用它，所有退出路径都在 finally 中移除监听。
+    // addEventListener 和 removeEventListener 必须使用同一函数引用，因此这里保留稳定的局部函数。
+    const abort = (): void => pi.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      const running = pi.continue();
+      if (this.abortRequested) {
+        this.abortRequested = false;
+        pi.abort();
+      }
+      await running;
+    } finally {
+      signal?.removeEventListener("abort", abort);
+      unsubscribe();
+      if (this.piInstance === pi) this.piInstance = undefined;
+    }
+  }
+}
+
+// #endregion
+
+// #region Public prepared-Turn contracts
+
+/** 表示可直接复用、无需再次执行工具的持久化结果。 */
+export interface PiStoredToolSettlement {
+  readonly result: import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
+  readonly isError: boolean;
+}
+
+export type PiCanonicalUserInput = UserMessage;
+export type PiToolSettlement = SettledPiToolCall;
+
+/** 表示工具真正执行前写入的持久化输入证据。 */
+export interface PiToolInputRecord {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly input: unknown;
+  readonly retry: "idempotent" | "non-idempotent";
+}
+
+/**
+ * 提供 Pi Turn 执行期间需要的持久化读写能力。
+ *
+ * @remarks
+ * Runtime 为每个 Submission 实现这个端口，PreparedPiTurnAdapter 会在审批和 Tool 执行前后调用它。
+ * 持久化留在 PiCore 之外，恢复流程才能从 Runtime 数据库重建决定，而不是依赖已丢失的内存状态。
+ */
+export interface PiTurnDurability {
+  /**
+   * 查找某次工具调用已经保存的结果。
+   *
+   * @remarks
+   * PreparedPiTurnAdapter 会在审批前查询一次，并在审批可能生成拒绝结果后再查询一次。
+   * 两次读取分别防止重复执行已完成工作，以及漏掉 Turn 暂停期间产生的结果。
+   */
+  findToolSettlement(toolCallId: string): PiStoredToolSettlement | null;
+  /**
+   * 保存工具审批请求并等待决定。
+   *
+   * @remarks
+   * Pinned Runtime 的 approval mode 和 Tool candidate 风险要求审批时，PreparedPiTurnAdapter 才会调用它；onCreated 在记录创建后发布回执。
+   * 通过 onCreated 发布可保证持久化请求早于浏览器事件，调用方必须保留这个顺序。
+   */
+  requestToolApproval(
+    approval: import("../turn").PiToolApproval,
+    signal?: AbortSignal,
+    onCreated?: () => void | Promise<void>,
+  ): Promise<void>;
+  /**
+   * 记录工具输入，并返回它是否是第一次持久化尝试。
+   *
+   * @remarks
+   * Tool candidate 没有已存结算结果时，PreparedPiTurnAdapter 会在真正执行前调用它。
+   * 恢复逻辑会把返回值和重试策略一起用于阻止结果不确定的非幂等重放，因此不能混淆 true 与 false。
+   */
+  appendToolInput(input: PiToolInputRecord): boolean;
+  /**
+   * 保存受治理工具调用经过限额处理后的最终结果。
+   *
+   * @remarks
+   * compilePiTools 会在返回成功或向 Pi 发布规范化失败前调用它。
+   * 这个先写结果的边界让后续重试能看到原始结局，因此必须留在受治理包装器内部。
+   */
+  settleTool(call: PiToolSettlement): void | Promise<void>;
+}
+
+/**
+ * 描述把一个 Submission 的 Pinned Runtime 接入 Pi 执行所需的全部依赖。
+ *
+ * @remarks
+ * Submission 首次执行或恢复时，Runtime 把它传给 PiRuntimeAdapter.createTurn。
+ * 这些回调让 transcript、持久化状态、流投影和终态仍由 Runtime 负责，避免在 PiCore 内复制一份。
+ * Runtime、Submission、Turn、Prepared Runtime、Pinned Runtime、Tool candidate 和 transcript 沿用 `./index.ts` 的统一定义。
+ */
+export interface CreatePreparedPiTurnOptions {
+  readonly prepared: PreparedPiRuntime;
+  readonly baseRevision: string;
+  readonly pinnedDescriptor: string;
+  readonly submission: {
+    readonly id: string;
+    readonly requestId: string;
+    readonly messageId: string;
+    readonly startedAt: number;
+    readonly continuation: boolean;
+    readonly assistantOrdinal: number;
+  };
+  /**
+   * 在 Pi 启动前读取最新 canonical transcript。
+   *
+   * PiTurnAdapter.run 在创建 PiCore 前调用它，Runtime 应返回 transcript 当时已提交的消息。
+   * 延迟读取可纳入适配器创建后才物化的恢复结果，不能提前固化为数组快照。
+   */
+  readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
+  readonly durability: PiTurnDurability;
+  /**
+   * 上报受治理工具的耗时、结果大小和成败。
+   *
+   * 工具治理层在执行结束时调用它，Runtime 可用它发出工具遥测事件。
+   * 该回调只负责观测，工具治理层会隔离它的异常，避免遥测改变工具结果。
+   */
+  readonly onToolTelemetry?: (event: PiToolTelemetry) => void;
+  /**
+   * 调整 Pi 即将发送给模型的消息上下文。
+   *
+   * PiCore 在每次模型调用前使用它，Runtime 通过这里接入现有上下文处理。
+   * 直接沿用 AgentOptions 的类型可确保参数和取消信号与 Pi 保持一致。
+   */
+  readonly transformContext: NonNullable<AgentOptions["transformContext"]>;
+  /**
+   * 在提交终止助手消息前读取已保存的取消原因。
+   *
+   * handleEvent 收到非工具调用的助手终止消息时调用它，Runtime 可省略该能力。
+   * 以持久化原因为准可覆盖模型随后到达的普通完成结果，避免已取消提交被记为成功。
+   */
+  readonly abortReason?: () => string | undefined;
+  /**
+   * 保存并广播一条投影后的 Pi 流 chunk。
+   *
+   * 工具审批创建和 handleEvent 生成可见记录时会调用它，Runtime 决定具体存储与广播方式。
+   * 适配器会等待该回调，以免 Pi 的后续事件越过尚未落地的前一条记录。
+   */
+  readonly onRecord: (
+    chunk: UIMessageChunk,
+  ) => void | Promise<void>;
+  /**
+   * 把一条完成的 Pi 消息提交到 Runtime 的 transcript。
+   *
+   * handleEvent 收到 user、assistant 或 toolResult 的 message_end 时调用它。
+   * 只在 message_end 提交可避免把流式中间态当成恢复依据，调用方应保持幂等写入。
+   */
+  readonly onCanonicalMessage: (
+    commit: PiCanonicalMessageCommit,
+  ) => void | Promise<void>;
+  /**
+   * 记录终止助手消息给出的权威 Turn 结果。
+   *
+   * handleEvent 处理非 toolUse 的助手 message_end 时调用它，Runtime 用它推进提交终态。
+   * 工具调用消息不是 Turn 终点，因此不能在 stopReason 为 toolUse 时调用。
+   */
+  readonly onTerminal: (
+    terminal: PiTurnTerminalIntent,
+  ) => void | Promise<void>;
+}
+
+export type PiCanonicalMessageCommit =
+  | {
+      readonly kind: "append-user";
+      readonly id: string;
+      readonly message: UserMessage;
+    }
+  | {
+      readonly kind: "commit-turn";
+      readonly ordinal: number;
+      readonly message: AssistantMessage | ToolResultMessage;
+    };
+
+export interface PiTurnTerminalIntent {
+  readonly outcome: "succeeded" | "failed" | "aborted";
+  readonly message?: string;
+}
+
+export interface PiPreparedTurnRunOptions {
+  readonly signal?: AbortSignal;
+}
+
+// #endregion
+
+// #region Durable prepared-Turn execution
+
+/**
+ * 执行一个 Submission 的 Pinned Runtime，同时把持久化职责交给 Runtime。
+ *
+ * @remarks
+ * PiRuntimeAdapter 为实时执行、恢复和审批续跑创建本类，调用方随后使用 run()、retryTool()、steer() 或 abort()。
+ * 构造时会核对 Prepared Runtime 的归属和 revision descriptor，避免执行过程悄悄切换到新的提示词、模型或 Tool candidate 集合。
+ * 核心术语沿用 `./index.ts` 的统一定义。
+ */
+export class PreparedPiTurnAdapter {
+  private readonly turn: PiTurnAdapter;
+  private readonly candidates: readonly PiToolCandidate[];
+  private assistantOrdinal: number;
+  private readonly encoder: PiChunkEncoder;
+  private readonly steerMessageIds: string[] = [];
+  private terminalIntent?: PiTurnTerminalIntent;
+
+  /**
+   * 把 Prepared Runtime 和 Submission 持久化端口绑定成一个可执行 Turn。
+   *
+   * @remarks
+   * PiRuntimeAdapter.createTurn 是预期调用方，它会传入私有归属令牌和已配置的模型注册表。
+   * 每个 Tool candidate 会先被包装，确保平台门禁、已有结算、审批和不确定重试检查都早于原始 execute 函数。
+   */
+  constructor(
+    options: CreatePreparedPiTurnOptions,
+    dependencies: {
+      readonly owner: object;
+      readonly models: Models;
+    },
+  ) {
+    const { state, descriptor } = readPinnedPiRuntime(
+      options.prepared,
+      dependencies.owner,
+      options.pinnedDescriptor,
+      options.baseRevision,
+    );
+    this.assistantOrdinal = options.submission.assistantOrdinal;
+    this.encoder = new PiChunkEncoder({
+      messageId: options.submission.messageId,
+      startedAt: options.submission.startedAt,
+    });
+    this.candidates = state.candidates.map((candidate) => ({
+      ...candidate,
+      tool: {
+        ...candidate.tool,
+        // 只在 Runtime 的持久化和策略门禁都放行后执行一个 Tool candidate。
+        // 实时运行由 PiCore 调用它，恢复或审批续跑则由 retryTool 进入同一路径。
+        // 顺序不能随便调整：已有结果优先，审批可能生成结果，不确定的非幂等工作不能重放。
+        execute: async (toolCallId, input, signal, onUpdate) => {
+          await state.snapshot.bindings.platform.gateTool?.({
+            toolCallId,
+            toolName: candidate.tool.name,
+            input,
+            requiredExecutionLevel: candidate.requiredExecutionLevel,
+            signal: signal ?? new AbortController().signal,
+          });
+          const settled = options.durability.findToolSettlement(toolCallId);
+          if (settled) {
+            if (settled.isError) {
+              const text = settled.result.content
+                .flatMap((part) => part.type === "text" ? [part.text] : [])
+                .join("");
+              throw new Error(text || "Tool execution failed");
+            }
+            return settled.result;
+          }
+          if (requiresPiToolApproval({
+            executionLevel: descriptor.executionLevel,
+            requiredExecutionLevel: candidate.requiredExecutionLevel,
+          })) {
+            const approval = parkPiToolApproval({
+              executionId: `${options.submission.id}:${toolCallId}`,
+              requestId: options.submission.requestId,
+              source: candidate.source ?? "action",
+              toolCallId,
+              toolName: candidate.tool.name,
+              summary:
+                candidate.summary ??
+                candidate.tool.label ??
+                candidate.tool.name,
+              executionLevel: descriptor.executionLevel,
+              requiredExecutionLevel: candidate.requiredExecutionLevel,
+              inputJson: JSON.stringify(input),
+              createdAt: Date.now(),
+            }).approval;
+            await options.durability.requestToolApproval(
+              approval,
+              signal,
+              () => this.publishChunks(
+                this.encoder.approvalRequested(
+                  toolCallId,
+                  approval.executionId,
+                ),
+              ),
+            );
+            const approvalSettlement = options.durability
+              .findToolSettlement(toolCallId);
+            await this.publishChunks(this.encoder.approvalResponded(
+              toolCallId,
+              approval.executionId,
+              !approvalSettlement?.isError,
+              approvalSettlement?.isError
+                ? approvalSettlement.result.content
+                    .flatMap((part) => part.type === "text" ? [part.text] : [])
+                    .join("") || "Tool execution denied"
+                : undefined,
+            ));
+          }
+          const afterApproval = options.durability
+            .findToolSettlement(toolCallId);
+          if (afterApproval) return afterApproval.result;
+          const retry = piToolRetryPolicy(candidate);
+          const firstAttempt = options.durability.appendToolInput({
+            toolCallId,
+            toolName: candidate.tool.name,
+            input,
+            retry,
+          });
+          if (!firstAttempt && retry === "non-idempotent") {
+            throw new Error(
+              `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
+            );
+          }
+          return candidate.tool.execute(
+            toolCallId,
+            input,
+            signal,
+            onUpdate,
+          );
+        },
+      },
+    }));
+    this.turn = new PiTurnAdapter({
+      pi: {
+        model: state.snapshot.pi.model,
+        thinkingLevel: state.snapshot.pi.thinkingLevel,
+      },
+      models: dependencies.models,
+      apiKey: resolvePiApiKey(
+        state.snapshot.bindings.provider,
+        state.snapshot.pi.model.id,
+      ),
+      canonicalMessages: options.canonicalMessages,
+      denyTools: descriptor.deny,
+      settle: options.durability.settleTool,
+      onToolTelemetry: options.onToolTelemetry,
+      transformContext: options.transformContext,
+    });
+    this.systemPrompt = descriptor.systemPrompt;
+    this.options = options;
+  }
+
+  private readonly systemPrompt: string;
+  private readonly options: CreatePreparedPiTurnOptions;
+
+  /**
+   * 请求取消这个 Turn。
+   *
+   * @remarks
+   * 活动提交被中止时 Runtime 会调用它，包括仍在异步启动的阶段。
+   * 转交给 PiTurnAdapter 可保留启动前取消标记；run() 之前还没有可直接调用的 PiCore。
+   */
+  abort(): void {
+    this.turn.abort();
+  }
+
+  /**
+   * 把一条用户消息加入当前 Turn。
+   *
+   * @remarks
+   * 当前提交仍活动时收到消息，Runtime 的扩展宿主会调用它。
+   * 转交后，启动前缓冲和 PiCore 转向队列共用一条路径；只有没有活动 Turn 时调用方才应直接追加 transcript。
+   */
+  steer(
+    message: UserMessage,
+    messageId: string = crypto.randomUUID(),
+  ): void {
+    this.steerMessageIds.push(messageId);
+    this.turn.steer(message);
+  }
+
+  /**
+   * 按记录的名称重新执行 Pinned Runtime 中的 Tool candidate。
+   *
+   * @remarks
+   * recovery effect 和审批通过后的续跑会传入原始调用标识与输入；返回 false 表示 Tool candidate 不存在或已被拒绝。
+   * 先查 Pinned Runtime 的 Tool candidate 再走正常编译器，可防止恢复绕过授权、治理或持久化结算。
+   */
+  async retryTool(request: {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly input: unknown;
+  }): Promise<boolean> {
+    const candidate = this.candidates.find(
+      (item) => item.tool.name === request.toolName,
+    );
+    return candidate
+      ? this.turn.retryTool(
+          candidate,
+          request.toolCallId,
+          request.input,
+        )
+      : false;
+  }
+
+  /**
+   * 运行这个 Turn，直到 PiCore 和所有等待中的事件回调结束。
+   *
+   * @remarks
+   * Submission 首次执行和续跑时，Runtime 都会在可恢复聊天任务中调用它。
+   * 适配器只传入 Pinned Runtime 的 system prompt 和 Tool candidate，再让所有事件经过 handleEvent，以保持 transcript 与流状态的顺序。
+   */
+  async run(
+    options: PiPreparedTurnRunOptions,
+  ): Promise<void> {
+    this.terminalIntent = undefined;
+    await this.turn.run(
+      {
+        systemPrompt: this.systemPrompt,
+        tools: this.candidates,
+        signal: options.signal,
+      },
+      (event) => this.handleEvent(event),
+    );
+    if (this.terminalIntent) {
+      await this.options.onTerminal(this.terminalIntent);
+    }
+  }
+
+  // 提交完成的 Pi 消息、推导终态意图，并把事件投影给可恢复流。
+  // PiTurnAdapter 会对每个 AgentEvent 调用它，PiCore 会等待该 Promise 后再越过订阅事件屏障。
+  // canonical message 先于流投影提交，恢复才不会依赖仅供浏览器消费的记录；调整顺序必须复核 recovery effect。
+  private async handleEvent(event: AgentEvent): Promise<void> {
+    let projectedEvent = event;
+    if (event.type === "message_end") {
+      const message = event.message;
+      if (message.role === "user") {
+        await this.options.onCanonicalMessage({
+          kind: "append-user",
+          id: this.steerMessageIds.shift() ?? crypto.randomUUID(),
+          message,
+        });
+      } else if (
+        message.role === "assistant" ||
+        message.role === "toolResult"
+      ) {
+        const abortReason = this.options.abortReason?.();
+        const authoritativeMessage =
+          message.role === "assistant" &&
+          message.stopReason !== "toolUse" &&
+          abortReason
+            ? {
+                ...message,
+                content: [],
+                stopReason: "aborted" as const,
+                errorMessage: abortReason,
+              }
+            : message;
+        if (authoritativeMessage.role === "assistant") {
+          this.assistantOrdinal += 1;
+        }
+        await this.options.onCanonicalMessage({
+          kind: "commit-turn",
+          ordinal: this.assistantOrdinal,
+          message: authoritativeMessage,
+        });
+        projectedEvent = {
+          ...event,
+          message: authoritativeMessage,
+        };
+        if (
+          authoritativeMessage.role === "assistant" &&
+          authoritativeMessage.stopReason !== "toolUse"
+        ) {
+          const terminal = classifyPiStopReason(
+            authoritativeMessage.stopReason,
+          );
+          this.terminalIntent = {
+            outcome: terminal.outcome,
+            ...(authoritativeMessage.errorMessage
+              ? { message: authoritativeMessage.errorMessage }
+              : terminal.message
+                ? { message: terminal.message }
+                : {}),
+          };
+        }
+      }
+    }
+
+    await this.publishChunks(this.encoder.encode(projectedEvent));
+  }
+
+  private async publishChunks(chunks: readonly UIMessageChunk[]): Promise<void> {
+    for (const chunk of chunks) {
+      await this.options.onRecord(chunk);
+    }
+  }
+}
+
+// #endregion