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

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

@@ -1,1163 +0,0 @@
-import {
-  runAgentLoopContinue,
-  convertToLlm,
-  type AgentEvent,
-  type AgentMessage,
-  type AgentLoopConfig,
-  type ThinkingLevel,
-} from "@earendil-works/pi-agent-core";
-import type {
-  Api,
-  AssistantMessage,
-  Message,
-  Model,
-  Models,
-  ToolResultMessage,
-  UserMessage,
-} from "@earendil-works/pi-ai";
-import { isContextOverflow } from "@earendil-works/pi-ai";
-import { transformMessages } from "@earendil-works/pi-ai/api/transform-messages";
-import {
-  parkPiToolApproval,
-  parkPiToolInteraction,
-  requiresPiToolApproval,
-} from "../turn";
-import {
-  classifyPiTerminalStopReason,
-  PiChunkEncoder,
-} from "../message";
-import type { UIMessageChunk } from "ai";
-import { ChatStreamStalledError } from "agents/chat";
-import {
-  codeExecutionPiToolCandidate,
-  compilePiTools,
-  createPiToolGovernance,
-  type PiToolCandidate,
-  type PiToolInteractionSpec,
-  type PiToolGovernance,
-  type SettledPiToolCall,
-} from "../tool";
-import {
-  piToolRetryPolicy,
-  readPinnedPiRuntime,
-  type PreparedPiRuntime,
-} from "./assembly";
-import {
-  isRecoverableAssistantError,
-  isOpenRouterServerToolTimeout,
-  isModelStreamStallMessage,
-  withProviderRetry,
-  type PiGenerationLifecycleObserver,
-} from "./models";
-import { EXECUTION_LEVELS } from "../../lib/execution-level";
-import { projectToolOutputForModel } from "../../layers/context/budget/gate";
-import type { SpillWorkspace } from "../../lib/artifacts";
-
-// #region Single-run Pi bridge
-
-// 一片执行最多跑多少个模型回合。这是 CPU 预算边界，不是任务边界：DO 的
-// CPU 上限按 invocation 计，一条长回合跑在一次 invocation 里会把预算吃满并被驱逐，
-// 让步换来的是一次全新 invocation 和全新预算。
-const MAX_MODEL_TURNS_PER_SLICE = 30;
-
-// 一条 Submission 跨所有执行片最多跑多少个模型回合。这是任务边界:
-// 没有它,一个不收敛的工具循环会无限让步、无限唤醒、无限烧 token。
-export const MAX_MODEL_TURNS_PER_SUBMISSION = 300;
-
-// 预算耗尽时注入的收尾指令。跟着它一起把工具表清空,模型只能出文本,
-// 于是这一轮以一条正常的终止助手消息结束 —— 而不是硬判失败或继续让步。
-// 走 user 角色而非 assistant:多个 provider 拒绝以模型回合结尾的请求。
-const WRAP_UP_MESSAGE = "You have reached this run's model-turn budget. Stop " +
-  "calling tools now. Reply with a final message that states what you " +
-  "completed, what you did not finish, and the exact next step you would " +
-  "take. Do not start new work.";
-
-const TOOL_FAILURE_WRAP_UP_MESSAGE = "This turn reached its tool failure limit. " +
-  "Stop calling tools now. Reply with a final message that explains what " +
-  "failed and the exact next step the user should take. Do not start new work.";
-
-// 收尾开始后最多再放行几个模型回合。工具已经清空，正常一轮就结束了；
-// 留出余量是给 steering 消息，但不能因此把本片的 CPU 上限一起取消。
-const MAX_WRAP_UP_TURNS = 2;
-
-export class RetryableModelError extends Error {}
-
-export class RetryableModelSessionError extends RetryableModelError {}
-
-export class ContextOverflowError extends RetryableModelError {}
-
-function prepareToolArguments(
-  toolName: string,
-  input: unknown,
-  candidates: readonly PiToolCandidate[],
-): unknown {
-  const prepare = candidates.find(({ tool }) => tool.name === toolName)
-    ?.tool.prepareArguments;
-  if (!prepare) return input;
-  try {
-    return prepare(input);
-  } catch {
-    // Streaming inputs may still be incomplete. Preserve them so Pi can
-    // produce the normal validation ToolResult once the call is final.
-    return input;
-  }
-}
-
-function normalizeToolCallArguments(
-  message: AgentMessage,
-  candidates: readonly PiToolCandidate[],
-): void {
-  if (message.role !== "assistant") return;
-  for (const part of message.content) {
-    if (part.type === "toolCall") {
-      part.arguments = prepareToolArguments(
-        part.name,
-        part.arguments,
-        candidates,
-      ) as Record<string, unknown>;
-    }
-  }
-}
-
-function visibleAssistantContent(message: AssistantMessage) {
-  return message.content.filter((part) =>
-    part.type === "text"
-      ? part.text.trim()
-      : part.type === "thinking"
-        ? part.thinking.trim()
-        : false
-  );
-}
-
-interface PiTurnAdapterOptions {
-  readonly pi: {
-    readonly model: Model<Api>;
-    readonly thinkingLevel?: ThinkingLevel;
-  };
-  readonly models: Models;
-  readonly modelSessionId: string;
-  // 读取这次执行真正要交给 Pi 的 canonical transcript。
-  // PiTurnAdapter.run 在创建 Pi Loop 前调用它，宿主应返回当时最新的 transcript。
-  // 这里保留为延迟读取，是为了避免适配器创建后新增的恢复消息被旧快照漏掉。
-  readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
-  // 把工具的最终结果交回宿主持久化。
-  // 共享工具编译器在向 Pi 返回成功或规范化失败前调用它。
-  // 这个先落库再发布结果的顺序是恢复边界，不能改成事后异步补写。
-  readonly settle: (
-    call: SettledPiToolCall,
-  ) => void | Promise<void>;
-  readonly onGeneration?: PiGenerationLifecycleObserver;
-  // 在模型调用前通过 AgentLoopConfig.transformContext 调整上下文。
-  // 直接复用 Pi 的回调类型可避免这里维护另一套上下文转换约定。
-  readonly transformContext: NonNullable<AgentLoopConfig["transformContext"]>;
-  readonly workspace?: SpillWorkspace;
-  // 之前的执行片已经用掉的模型回合数。首次执行传 0。
-  readonly modelTurnsConsumed: number;
-}
-
-/**
- * 收集那些结果已经由工具自己收口的 Tool 名字。
- *
- * @remarks
- * `run` 在建 Pi Loop 前调用，把结果交给 `projectToolResultsForModel`。
- *
- * `outputBudget: "structure"` 的语义就是“这个结果不需要 Runtime 再替它省”：read
- * 按页返回并在页脚写明覆盖的行号，activate_skill 返回的是模型接下来要照做的指令，
- * Code Mode 的结果由它自己收口。对这些再套一次叶子上限，模型看到的正文会和结果里
- * 写明的范围对不上 —— 页脚说 `lines 1-307`，正文却被从中间挖空。
- *
- * 其余工具仍然照常压缩：这道闸按分类放行，不是整体放宽。
- */
-function selfBoundedToolNames(
-  candidates: readonly PiToolCandidate[],
-): ReadonlySet<string> {
-  return new Set(
-    candidates
-      .filter((candidate) => candidate.outputBudget?.kind === "structure")
-      .map((candidate) => candidate.tool.name),
-  );
-}
-
-function projectToolResultsForModel(
-  messages: readonly AgentMessage[],
-  selfBounded: ReadonlySet<string>,
-): AgentMessage[] {
-  let changed = false;
-  const projected = messages.map((message) => {
-    if (message.role !== "toolResult") return message;
-    if (selfBounded.has(message.toolName)) return message;
-    const payload = {
-      content: message.content,
-      details: message.details,
-    };
-    const next = projectToolOutputForModel(payload) as typeof payload;
-    if (next === payload) return message;
-    changed = true;
-    return {
-      ...message,
-      content: next.content,
-      details: next.details,
-    };
-  });
-  return changed ? projected : [...messages];
-}
-
-function orderLateToolResultsBeforeTurnAbortMarker(
-  messages: readonly AgentMessage[],
-): AgentMessage[] {
-  const ordered: AgentMessage[] = [];
-  for (let index = 0; index < messages.length; index += 1) {
-    const message = messages[index]!;
-    const previous = ordered.at(-1);
-    if (
-      message.role !== "custom" ||
-      message.customType !== "turn-aborted" ||
-      previous?.role !== "assistant"
-    ) {
-      ordered.push(message);
-      continue;
-    }
-    const pending = new Set(
-      previous.content.flatMap((part) =>
-        part.type === "toolCall" ? [part.id] : []
-      ),
-    );
-    let cursor = index + 1;
-    while (true) {
-      const result = messages[cursor];
-      if (result?.role !== "toolResult" || !pending.has(result.toolCallId)) {
-        break;
-      }
-      ordered.push(result);
-      cursor += 1;
-    }
-    ordered.push(message);
-    index = cursor - 1;
-  }
-  return ordered;
-}
-
-class PiTurnAdapter {
-  private readonly pendingSteers: UserMessage[] = [];
-  private readonly governance: PiToolGovernance;
-
-  // 创建一个 Turn 所需的短生命周期 Pi 执行器状态。
-  // PreparedPiTurnAdapter 只构造一次，并把运行、重试、转向和中止都交给它。
-  // 工具治理对象必须在这些路径间复用，因为它保存本 Turn 的重试次数和熔断状态。
-  constructor(private readonly opts: PiTurnAdapterOptions) {
-    this.governance = createPiToolGovernance();
-  }
-
-  // 把 Tool candidate 变成 Pi 可以执行的受治理 Tool。
-  // 正常运行会编译 Pinned Runtime 的整份列表，恢复时只编译指定 Tool candidate。
-  // 输出限额和持久化结算统一走共享编译器，避免恢复另开旁路。
-  private compile(candidates: readonly PiToolCandidate[]) {
-    return compilePiTools(candidates, {
-      governance: this.governance,
-      workspace: this.opts.workspace,
-      settle: this.opts.settle,
-    });
-  }
-
-  // 用正常 Turn 的受治理路径重新执行一次已知工具调用。
-  // recovery effect 和审批续跑在找到原调用记录对应的 Tool candidate 后调用它。
-  // Tool candidate 被过滤时返回 false，让调用方安全停止；实际执行仍保留结算和重试上限。
-  async retryTool(
-    candidate: PiToolCandidate,
-    toolCallId: string,
-    input: unknown,
-    signal?: AbortSignal,
-  ): Promise<boolean> {
-    const [tool] = this.compile([candidate]);
-    if (!tool) return false;
-    signal?.throwIfAborted();
-    await tool.execute(toolCallId, input, signal);
-    return true;
-  }
-
-  // 把一条用户消息排入当前 Turn。
-  // 提交仍在运行时收到扩展宿主消息，Runtime 会调用这里。
-  // Pi Loop 创建前先缓冲消息，可覆盖异步启动窗口，同时不引入第二份 transcript 来源。
-  steer(message: UserMessage): void {
-    this.pendingSteers.push(message);
-  }
-
-  // 从当前 canonical transcript 继续运行 Pi，并把生命周期事件交给监听器。
-  // Submission 的首次执行或恢复执行取得 Pinned Runtime 后，PreparedPiTurnAdapter 调用这里。
-  // 每次运行持有独立上下文；Loop 等待事件 sink 完成后才继续。
-  async run(
-    opts: {
-      readonly systemPrompt: string;
-      readonly tools: readonly PiToolCandidate[];
-      readonly signal?: AbortSignal;
-    },
-    listener: (event: AgentEvent) => void | Promise<void>,
-  ): Promise<PiTurnRunResult> {
-    const { systemPrompt, signal } = opts;
-    signal?.throwIfAborted();
-    const canonicalMessages = await this.opts.canonicalMessages();
-    signal?.throwIfAborted();
-    const tools = this.compile(opts.tools);
-    const selfBounded = selfBoundedToolNames(opts.tools);
-    // `modelTurns` 是跨执行片的累计数，`sliceTurns` 只数本片 —— 前者管任务预算，
-    // 后者管 CPU 预算，两个边界互不替代。
-    let modelTurns = this.opts.modelTurnsConsumed;
-    let sliceTurns = 0;
-    let reachedModelTurnLimit = false;
-    let wrapUpMessage: UserMessage | undefined;
-    let wrapUpTurns = 0;
-    const config: AgentLoopConfig = {
-      model: this.opts.pi.model,
-      reasoning: this.opts.pi.thinkingLevel === "off" ? undefined : this.opts.pi.thinkingLevel,
-      toolExecution: "parallel",
-      convertToLlm,
-      getSteeringMessages: async () => this.pendingSteers.splice(0, 1),
-      // transformMessages 在宿主上下文变换之后运行，确保跨 provider 的 tool call ID 格式兼容。
-      // OpenAI Responses API 生成含 `|` 的 450+ 字符 ID，Anthropic 只接受 ^[a-zA-Z0-9_-]+$(64 字符上限)；
-      // 切换 provider 或消息跨 provider 回放时若不规范化，provider 会静默拒绝。
-      transformContext: async (messages, signal) => {
-        const ctx = await this.opts.transformContext(messages, signal);
-        return transformMessages(
-          orderLateToolResultsBeforeTurnAbortMarker(
-            projectToolResultsForModel(
-              wrapUpMessage ? [...ctx, wrapUpMessage] : ctx,
-              selfBounded,
-            ),
-          ) as Message[],
-          this.opts.pi.model,
-        ) as AgentMessage[];
-      },
-      afterToolCall: this.governance.afterToolCall,
-      // Pi calls this only when another model turn is needed; counting belongs to turn_end.
-      prepareNextTurn: ({ context }) => {
-        if (wrapUpMessage) return undefined;
-        const toolFailureLimitReached = this.governance.wrapUpRequested();
-        if (
-          !toolFailureLimitReached &&
-          modelTurns < MAX_MODEL_TURNS_PER_SUBMISSION - 1
-        ) return undefined;
-        // Control instructions enter only the model projection, after official compaction.
-        // Keeping them out of Loop history preserves its canonical transcript boundary.
-        wrapUpMessage = {
-          role: "user",
-          content: [{
-            type: "text",
-            text: toolFailureLimitReached
-              ? TOOL_FAILURE_WRAP_UP_MESSAGE
-              : WRAP_UP_MESSAGE,
-          }],
-          timestamp: Date.now(),
-        };
-        return { context: { ...context, tools: [] } };
-      },
-      shouldStopAfterTurn: () => {
-        if (signal?.aborted === true) return true;
-        // 收尾那一轮必须跑完，否则让步会把唯一的终态机会顶掉。但「必须跑完」
-        // 不等于「不再有上限」：Pi 在这之后还会取 steering 和 follow-up 消息，
-        // 一直有新消息进来就会一直发模型请求，而且全在同一个 invocation 里 ——
-        // 那正是 MAX_MODEL_TURNS_PER_SLICE 要挡的 CPU 驱逐。
-        if (wrapUpMessage) return wrapUpTurns >= MAX_WRAP_UP_TURNS;
-        if (this.governance.wrapUpRequested() || modelTurns >= MAX_MODEL_TURNS_PER_SUBMISSION - 1) return false;
-        reachedModelTurnLimit = sliceTurns >= MAX_MODEL_TURNS_PER_SLICE;
-        return reachedModelTurnLimit;
-      },
-    };
-    await runAgentLoopContinue(
-      { systemPrompt, messages: [...canonicalMessages], tools: [...tools] },
-      config,
-      async (event) => {
-        await listener(event);
-        if (event.type === "turn_end") {
-          modelTurns += 1;
-          sliceTurns += 1;
-          if (wrapUpMessage) wrapUpTurns += 1;
-        }
-      },
-      signal,
-      withProviderRetry(
-        this.opts.models.streamSimple.bind(this.opts.models),
-        0,
-        this.opts.modelSessionId,
-        this.opts.onGeneration,
-      ),
-    );
-    return reachedModelTurnLimit
-      ? { kind: "yielded", modelTurns }
-      : { kind: "terminal", modelTurns };
-  }
-}
-
-// #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 执行前后调用它。
- * 持久化留在 Pi Loop 之外，恢复流程才能从 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 声明了 `interaction` 时，PreparedPiTurnAdapter 在执行前调用它，`execute` 不会被调用。
-   * 返回后必须再读一次 settlement —— 响应、取消和跨休眠恢复三条路径都只把结果留在 settlement 里。
-   */
-  requestToolInteraction(
-    interaction: import("../turn").PiToolInteraction,
-    settle: import("../tool").PiToolInteractionSpec,
-    signal?: AbortSignal,
-  ): 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 负责，避免在 Pi Loop 内复制一份。
- * Runtime、Submission、Turn、Prepared Runtime、Pinned Runtime、Tool candidate 和 transcript 沿用 `./index.ts` 的统一定义。
- */
-export interface CreatePreparedPiTurnOptions {
-  readonly prepared: PreparedPiRuntime;
-  readonly pinnedDescriptor: string;
-  /** Session 当前的稳定 Provider 路由身份；终态 Provider 故障可在下一 Submission 前旋转它。 */
-  readonly modelSessionId: string;
-  readonly submission: {
-    readonly id: string;
-    readonly requestId: string;
-    readonly messageId: string;
-    readonly startedAt: number;
-    readonly continuation: boolean;
-    readonly assistantOrdinal: number;
-    /** 之前的执行片已用掉的模型回合数；省略按 0 处理。 */
-    readonly modelTurnsConsumed?: number;
-  };
-  /**
-   * 在 Pi 启动前读取最新 canonical transcript。
-   *
-   * PiTurnAdapter.run 在创建 Pi Loop 前调用它，Runtime 应返回 transcript 当时已提交的消息。
-   * 延迟读取可纳入适配器创建后才物化的恢复结果，不能提前固化为数组快照。
-   */
-  readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
-  readonly durability: PiTurnDurability;
-  /** Reports paired model-generation lifecycle facts to the Runtime owner. */
-  readonly onGeneration?: PiGenerationLifecycleObserver;
-  /** Reports Code Mode child Tool starts without adding Pi recovery state. */
-  readonly onNestedToolStarted?: (input: Readonly<{
-    parentToolCallId: string;
-    toolCallId: string;
-    toolName: string;
-    input: unknown;
-    occurredAt: number;
-  }>) => void;
-  /** Reports Code Mode child Tool outcomes without adding Pi settlements. */
-  readonly onNestedToolFinished?: (input: Readonly<{
-    parentToolCallId: string;
-    toolCallId: string;
-    toolName: string;
-    outcome: "completed" | "failed" | "cancelled";
-    durationMs: number;
-    output?: import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
-    error?: unknown;
-    occurredAt: number;
-  }>) => void;
-  /** Reports model-requested Tools absent from the pinned Runtime surface. */
-  readonly onUnknownToolStarted?: (input: Readonly<{
-    toolCallId: string;
-    toolName: string;
-    input: unknown;
-    occurredAt: number;
-  }>) => void;
-  /** Reports the immediate Pi failure for a Tool absent from the pinned Runtime surface. */
-  readonly onUnknownToolFinished?: (input: Readonly<{
-    toolCallId: string;
-    toolName: string;
-    outcome: "failed";
-    output: import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
-    occurredAt: number;
-  }>) => void;
-  /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
-  readonly toolExecutors?: Readonly<Record<
-    string,
-    NonNullable<PiToolCandidate["tool"]["execute"]>
-  >>;
-  /**
-   * 调整 Pi 即将发送给模型的消息上下文。
-   *
-   * Pi Loop 在每次模型调用前使用它，Runtime 通过这里接入现有上下文处理。
-   * 直接沿用 AgentLoopConfig 的类型可确保参数和取消信号与 Pi 保持一致。
-   */
-  readonly transformContext: NonNullable<AgentLoopConfig["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;
-}
-
-export type PiTurnRunResult =
-  /** Turn 已产生权威结果，或已经收尾。 */
-  | { readonly kind: "terminal"; readonly modelTurns: number }
-  /** 本片让出执行，Turn 未结束；调用方必须排出续跑。 */
-  | { readonly kind: "yielded"; readonly modelTurns: number };
-
-// #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 abortController = new AbortController();
-  private readonly candidates: readonly PiToolCandidate[];
-  private assistantOrdinal: number;
-  private readonly encoder: PiChunkEncoder;
-  private readonly steerMessageIds: string[] = [];
-  private terminalIntent?: PiTurnTerminalIntent;
-  private readonly contextWindow: number;
-
-  /**
-   * 把 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,
-    );
-    this.contextWindow = state.snapshot.pi.model.contextWindow;
-    this.assistantOrdinal = options.submission.assistantOrdinal;
-    this.encoder = new PiChunkEncoder({
-      messageId: options.submission.messageId,
-      startedAt: options.submission.startedAt,
-      turnId: options.submission.id,
-    });
-    const bindCandidate = (
-      candidate: PiToolCandidate,
-      toolCallIdPrefix?: string,
-      recordRecoveryAttempt = true,
-    ): PiToolCandidate => ({
-      ...candidate,
-      tool: {
-        ...candidate.tool,
-        // 只在 Runtime 的持久化和策略门禁都放行后执行一个 Tool candidate。
-        // 实时运行由 Pi Loop 调用它，恢复或审批续跑则由 retryTool 进入同一路径。
-        // 顺序不能随便调整：门禁先于结果复用，审批可能生成结果，不确定的非幂等工作不能重放。
-        execute: async (toolCallId, input, signal, onUpdate) => {
-          if (toolCallIdPrefix) {
-            toolCallId = `${toolCallIdPrefix}:${toolCallId}`;
-          }
-          const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
-            ? await candidate.requiredExecutionLevelForInput(input)
-            : candidate.requiredExecutionLevel;
-          if (!EXECUTION_LEVELS.includes(requiredExecutionLevel)) {
-            throw new Error(
-              `SpringBrand Tool "${candidate.tool.name}" resolved an invalid execution level`,
-            );
-          }
-          await state.snapshot.bindings.platform.gateTool?.({
-            toolCallId,
-            toolName: candidate.tool.name,
-            input,
-            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 (
-            candidate.alwaysRequiresApproval ||
-            requiresPiToolApproval({
-              executionLevel: descriptor.executionLevel,
-              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,
-              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;
-          // 结果由客户端提供的 Tool 在这里 park，永远不走到下面的 execute。
-          // 放在审批之后：一个 Tool 既要审批又要客户端结算时，先过许可再问用户，
-          // 否则会先向用户要答案、再告诉他这事根本不许做。
-          if (candidate.interaction) {
-            // 必须先把 Tool 输入落成里程碑再 park。恢复出来的结算靠这条记录取回
-            // `args`;缺了它,Tool 醒来返回结果时 settleTool 会拿 undefined 的 args
-            // 去和真 args 比对,判成 "Conflicting durable Tool settlement" —— 整个
-            // Turn 就死在这。(审批那条路不受影响:批准后 Tool 真的执行,args 在
-            // 下面的 appendToolInput 里补上了。)
-            options.durability.appendToolInput({
-              toolCallId,
-              toolName: candidate.tool.name,
-              input,
-              retry: piToolRetryPolicy(candidate),
-            });
-            const parked = parkPiToolInteraction({
-              interactionId: `${options.submission.id}:${toolCallId}`,
-              requestId: options.submission.requestId,
-              toolCallId,
-              toolName: candidate.tool.name,
-              inputJson: JSON.stringify(input),
-              createdAt: Date.now(),
-            }).interaction;
-            await options.durability.requestToolInteraction(
-              parked,
-              candidate.interaction,
-              signal,
-            );
-            const responded = options.durability
-              .findToolSettlement(toolCallId);
-            if (!responded) {
-              throw new Error(
-                `Tool interaction produced no durable settlement: ${candidate.tool.name}`,
-              );
-            }
-            return responded.result;
-          }
-          if (recordRecoveryAttempt) {
-            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}`,
-              );
-            }
-          }
-          const execute = options.toolExecutors?.[candidate.tool.name] ??
-            candidate.tool.execute;
-          if (recordRecoveryAttempt || !toolCallIdPrefix) {
-            return execute(toolCallId, input, signal, onUpdate);
-          }
-          const startedAt = Date.now();
-          const telemetryToolCallId = toolCallId;
-          options.onNestedToolStarted?.({
-            parentToolCallId: toolCallIdPrefix,
-            toolCallId: telemetryToolCallId,
-            toolName: candidate.tool.name,
-            input,
-            occurredAt: startedAt,
-          });
-          try {
-            const output = await execute(toolCallId, input, signal, onUpdate);
-            const occurredAt = Date.now();
-            options.onNestedToolFinished?.({
-              parentToolCallId: toolCallIdPrefix,
-              toolCallId: telemetryToolCallId,
-              toolName: candidate.tool.name,
-              outcome: "completed",
-              durationMs: occurredAt - startedAt,
-              output,
-              occurredAt,
-            });
-            return output;
-          } catch (error) {
-            const occurredAt = Date.now();
-            options.onNestedToolFinished?.({
-              parentToolCallId: toolCallIdPrefix,
-              toolCallId: telemetryToolCallId,
-              toolName: candidate.tool.name,
-              outcome: signal?.aborted ? "cancelled" : "failed",
-              durationMs: occurredAt - startedAt,
-              error,
-              occurredAt,
-            });
-            throw error;
-          }
-        },
-      },
-    });
-    this.candidates = state.candidates.map((candidate) => {
-      if (candidate.tool.name !== "execute") return bindCandidate(candidate);
-      const factory = state.snapshot.bindings.codeExecution;
-      if (!factory) {
-        throw new Error("Prepared Code Mode Tool requires a Runtime factory");
-      }
-      return bindCandidate({
-        ...candidate,
-        tool: {
-          ...candidate.tool,
-          execute: (toolCallId, input, signal, onUpdate) => {
-            const runtimeCandidate = codeExecutionPiToolCandidate(
-              factory.create(state.codeExecutionCandidates.map((inner) =>
-                // Code Mode records its own connector calls. Pi persists the
-                // non-idempotent parent execute attempt/result; recording an inner
-                // input without a Pi settlement creates an orphan recovery
-                // action that cannot be found on the direct Tool surface.
-                bindCandidate(inner, toolCallId, false)
-              )),
-            );
-            return runtimeCandidate.tool.execute(
-              toolCallId,
-              input,
-              signal,
-              onUpdate,
-            );
-          },
-        },
-      });
-    });
-    this.turn = new PiTurnAdapter({
-      pi: {
-        model: state.snapshot.pi.model,
-        thinkingLevel: state.snapshot.pi.thinkingLevel,
-      },
-      models: dependencies.models,
-      modelSessionId: options.modelSessionId,
-      ...(options.onGeneration ? { onGeneration: options.onGeneration } : {}),
-      canonicalMessages: options.canonicalMessages,
-      // 被中断的 Turn 不写结算。它退场路上还会吐出「工具被中止」，而工具其实
-      // 没有产生任何结果 —— 结算是单调的，落了这条假结果，重建出来的续跑会
-      // 把一个从没跑过的工具当成跑过并失败。取消不走这里：取消要的就是终态。
-      settle: (call) =>
-        this.interrupted ? undefined : options.durability.settleTool(call),
-      transformContext: options.transformContext,
-      workspace: state.snapshot.bindings.workspace,
-      modelTurnsConsumed: options.submission.modelTurnsConsumed ?? 0,
-    });
-    this.systemPrompt = descriptor.systemPrompt;
-    this.options = options;
-  }
-
-  private readonly systemPrompt: string;
-  private readonly options: CreatePreparedPiTurnOptions;
-  private interrupted = false;
-
-  /**
-   * 请求取消这个 Turn。
-   *
-   * @remarks
-   * 活动提交被中止时 Runtime 会调用它，包括仍在异步启动的阶段。
-   * 同一取消信号覆盖历史读取、Loop 和工具重试。
-   */
-  abort(): void {
-    this.abortController.abort();
-  }
-
-  /**
-   * 中断这个 Turn，把它交给持久续跑接手。
-   *
-   * @remarks
-   * 宿主在 park 期间换掉装配后调用。与 `abort` 的差别只有一处、但很要命：
-   * 中断途中冒出来的工具结算一律丢弃。这条执行器的系统提示和工具表锁在它被
-   * 创建的那一刻，接下来跑的是另一条按新装配重建的执行器，两边共用同一批
-   * `toolCallId` —— 让退场路上的假结果先落盘，新那条就再也纠正不过来了。
-   */
-  interrupt(): void {
-    this.interrupted = true;
-    this.abort();
-  }
-
-  /**
-   * 把一条用户消息加入当前 Turn。
-   *
-   * @remarks
-   * 当前提交仍活动时收到消息，Runtime 的扩展宿主会调用它。
-   * 启动前与运行中都进入同一队列，Loop 每次消费一条；空闲时调用方直接追加 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,
-          this.abortController.signal,
-        )
-      : false;
-  }
-
-  /**
-   * 取回某个 Tool 的客户端结算声明，没有声明时返回 null。
-   *
-   * @remarks
-   * `Runtime.respondToolInteraction` 在把客户端响应映射成 ToolResult 前调用它。
-   *
-   * 声明里含函数，无法持久化；从 Pinned Runtime 的 candidate 现取，
-   * 可让「DO 一直醒着」和「park 期间睡过一觉」走同一条解析路径，而不是一条真解析、一条退化成缺省。
-   */
-  interactionSpec(toolName: string): PiToolInteractionSpec | null {
-    return this.candidates.find(
-      (item) => item.tool.name === toolName,
-    )?.interaction ?? null;
-  }
-
-  /**
-   * 运行这个 Turn，直到 Pi Loop 和所有等待中的事件回调结束。
-   *
-   * @remarks
-   * Submission 首次执行和续跑时，Runtime 都会在可恢复聊天任务中调用它。
-   * 适配器只传入 Pinned Runtime 的 system prompt 和 Tool candidate，再让所有事件经过 handleEvent，以保持 transcript 与流状态的顺序。
-   */
-  async run(
-    options: PiPreparedTurnRunOptions,
-  ): Promise<PiTurnRunResult> {
-    this.terminalIntent = undefined;
-    const signal = options.signal
-      ? AbortSignal.any([options.signal, this.abortController.signal])
-      : this.abortController.signal;
-    const result = await this.turn.run(
-      {
-        systemPrompt: this.systemPrompt,
-        tools: this.candidates,
-        signal,
-      },
-      (event) => this.handleEvent(event, signal),
-    );
-    if (this.terminalIntent) {
-      await this.options.onTerminal(this.terminalIntent);
-      return { kind: "terminal", modelTurns: result.modelTurns };
-    }
-    return result;
-  }
-
-  // 提交完成的 Pi 消息、推导终态意图，并把事件投影给可恢复流。
-  // Loop 等待每个事件的 Promise，canonical 提交失败时直接拒绝本次执行。
-  // canonical message 先于流投影提交，恢复才不会依赖仅供浏览器消费的记录；调整顺序必须复核 recovery effect。
-  private async handleEvent(event: AgentEvent, signal: AbortSignal): Promise<void> {
-    if (
-      event.type === "tool_execution_start" &&
-      !this.candidates.some(({ tool }) => tool.name === event.toolName)
-    ) {
-      this.options.onUnknownToolStarted?.({
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        input: event.args,
-        occurredAt: Date.now(),
-      });
-    } else if (
-      event.type === "tool_execution_end" &&
-      !this.candidates.some(({ tool }) => tool.name === event.toolName)
-    ) {
-      this.options.onUnknownToolFinished?.({
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        outcome: "failed",
-        output: event.result,
-        occurredAt: Date.now(),
-      });
-    }
-    if (
-      event.type === "message_start" ||
-      event.type === "message_update" ||
-      event.type === "message_end"
-    ) {
-      normalizeToolCallArguments(event.message, this.candidates);
-    }
-    if (
-      event.type === "message_update" &&
-      event.assistantMessageEvent.type === "toolcall_end"
-    ) {
-      const call = event.assistantMessageEvent.toolCall;
-      call.arguments = prepareToolArguments(
-        call.name,
-        call.arguments,
-        this.candidates,
-      ) as Record<string, unknown>;
-    }
-    if (
-      event.type === "message_update" &&
-      event.assistantMessageEvent.type === "error" &&
-      (isContextOverflow(
-        event.assistantMessageEvent.error,
-        this.contextWindow,
-      ) || isModelStreamStallMessage(
-        event.assistantMessageEvent.error.errorMessage,
-      ) ||
-        isRecoverableAssistantError(event.assistantMessageEvent.error) ||
-        isOpenRouterServerToolTimeout(event.assistantMessageEvent.error))
-    ) {
-      return;
-    }
-    let projectedEvent = event;
-    if (event.type === "message_end") {
-      const message = event.message;
-      if (message.role === "assistant") {
-        if (message.stopReason === "deferred") throw new Error("Deferred Pi responses are not supported by this Runtime");
-        if (isContextOverflow(message, this.contextWindow)) {
-          throw new ContextOverflowError(
-            message.errorMessage ?? "Model context window overflow",
-          );
-        }
-        const stalled = message.stopReason === "error" &&
-          isModelStreamStallMessage(message.errorMessage);
-        const resetModelSession = isOpenRouterServerToolTimeout(message);
-        const retryable = isRecoverableAssistantError(message);
-        if (stalled || retryable || resetModelSession) {
-          const content = visibleAssistantContent(message);
-          if (!resetModelSession && content.length > 0) {
-            this.assistantOrdinal += 1;
-            await this.options.onCanonicalMessage({
-              kind: "commit-turn",
-              ordinal: this.assistantOrdinal,
-              message: {
-                ...message,
-                content,
-              },
-            });
-          }
-          if (stalled) {
-            throw new ChatStreamStalledError(message.errorMessage!);
-          }
-          if (resetModelSession) {
-            throw new RetryableModelSessionError(message.errorMessage);
-          }
-          throw new RetryableModelError(message.errorMessage);
-        }
-      }
-      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?.() ?? (signal.aborted ? "Turn aborted" : undefined);
-        const authoritativeMessage =
-          message.role === "assistant" &&
-          message.stopReason !== "toolUse" &&
-          abortReason
-            ? {
-                ...message,
-                content: visibleAssistantContent(message),
-                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 = classifyPiTerminalStopReason(
-            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