@springbrand/agent-runtime 0.1.0

package/src/runtime.ts

@@ -0,0 +1,2880 @@
+import type { Connection } from "agents";
+import {
+  MessageType,
+  clearChatTerminal,
+  parseProtocolMessage,
+  recordChatTerminal,
+  sendIfOpen,
+} from "agents/chat";
+import { RecoverableChatAgent } from "./kernel/recoverable-chat-agent";
+import {
+  ApprovalLifecycle,
+  type ApprovalContinuationData,
+} from "./kernel/approval-lifecycle";
+import {
+  SubmissionLifecycle,
+  SubmissionQueueFullError,
+  type SubmissionInput,
+  type SubmissionStore,
+  type SubmissionHandle,
+} from "./kernel/submission-lifecycle";
+import {
+  USER_STOP_REASON,
+  type ApprovalDecision,
+  type ApprovalReceipt,
+  type MessageDelivery,
+  type MessageDispatchReceipt,
+  type SubmissionReceipt,
+} from "./kernel/receipts";
+import type { ExecutionLevel } from "./lib/execution-level";
+import type {
+  RuntimeExtensionPermissions,
+} from "./kernel/extensions";
+import type {
+  RuntimeActivity,
+  RuntimeLoadPhase,
+  RuntimeLoadState,
+  RuntimeState,
+  RuntimeTurnState,
+} from "./kernel/state";
+import {
+  initializeRuntimeConfig,
+  type AgentConfig,
+  type RuntimeSnapshot,
+} from "./plugins";
+import { connectConfiguredMcpServers } from "./lib/mcp";
+import { installConsoleSink } from "./lib/telemetry-dev";
+import {
+  PiRuntimeAdapter,
+  type PiCanonicalUserInput,
+  type PiCanonicalTranscriptSnapshot,
+  type PiChatRecoveryData,
+  type UIChatRequestBody,
+  type PiDurableMutation,
+  type PiRecoveryCommand,
+  type PiRecoveryDecision,
+  type PiRuntimeTranscript,
+  type PiToolInputRecord,
+  type PiStoredToolSettlement,
+  type PiToolSettlement,
+  type PreparedPiRuntime,
+  type PreparedPiTurnAdapter,
+} from "./pi/runtime-adapter";
+import type { UIMessage, UIMessageChunk } from "ai";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type {
+  RuntimeModelUsageEvent,
+  RuntimeToolSettlementEvent,
+} from "./kernel/bindings";
+import {
+  isTerminalSubmissionStatus,
+  RuntimeDatabase,
+  type SubmissionStatus,
+} from "./db/index";
+import {
+  TemporaryAgentCoordinator,
+  type TemporaryAgentApprovalDecision,
+  type TemporaryAgentApprovalRequest,
+  type TemporaryAgentExecutor,
+  type TemporaryAgentRequest,
+  type TemporaryAgentRunContext,
+} from "./layers/orchestration/temporary-agent/core";
+
+/**
+ * 本文件负责把 Cloudflare Agent 的通信与持久化能力接到 Pi Turn。
+ *
+ * @remarks
+ * 核心术语见包入口 `index.ts`。
+ */
+
+// #region Runtime 内部数据与基础工具
+
+const SCHEDULED_STABLE_TIMEOUT_MS = 30_000;
+const TURN_EVENT_RETRY_SECONDS = 10;
+
+type RuntimeEventOutboxPayload =
+  | { readonly type: "model-usage"; readonly event: RuntimeModelUsageEvent }
+  | {
+      readonly type: "tool-settlement";
+      readonly event: RuntimeToolSettlementEvent;
+    };
+interface StoredSubmission extends SubmissionReceipt {
+  status: SubmissionStatus;
+  requestId: string;
+  idempotencyKey?: string;
+  assemblyRevision: string;
+  assemblyDescriptor: string;
+  assistantMessageId: string;
+  abortReason?: string;
+  queuedInputJson?: string | null;
+  queuedUiMessageJson?: string | null;
+  userMessageId?: string | null;
+  regenerateMessageId?: string | null;
+}
+
+interface SubmitMessageOptions {
+  requestId: string;
+  idempotencyKey?: string;
+  userMessageId?: string;
+  userMessage?: UIMessage & { role: "user" };
+  regenerate?: boolean;
+}
+
+interface ActiveTurn {
+  submissionId: string;
+  requestId: string;
+  messageId: string;
+  startedAt: number;
+  continuation: boolean;
+  /** Execution adapter — use abort()/steer() instead of touching Pi directly. */
+  agent: PreparedPiTurnAdapter;
+}
+
+// 作用：把任意异常整理成可以持久化或发给客户端的文字。
+// 调用：Turn 执行、恢复和业务投影捕获 `unknown` 异常时调用。
+// 原因：错误边界不能假定抛出值一定是 `Error`。
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// 作用：用同一种 JSON 序列化方式生成持久化或传输文本。
+// 调用：本文件写里程碑、WebSocket 帧和比较投影时调用。
+// 原因：收口序列化入口，避免同一数据在不同路径产生不同文本。
+function json(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function assistantUsageEvent(
+  eventId: string,
+  submissionId: string,
+  message: AssistantMessage,
+): RuntimeModelUsageEvent {
+  return {
+    eventId,
+    submissionId,
+    kind: "assistant",
+    api: message.api,
+    provider: message.provider,
+    model: message.model,
+    ...(message.responseModel ? { responseModel: message.responseModel } : {}),
+    stopReason: message.stopReason,
+    usage: message.usage,
+  };
+}
+
+// 作用：把用户消息内容变成可比较的稳定形状。
+// 调用：重新生成回答时，提交入口用它核对客户端与已存用户消息。
+// 原因：字符串和分段内容必须先归一化，否则语义相同的消息会被误判为不同。
+function userContentKey(message: PiCanonicalUserInput): string {
+  return json(
+    typeof message.content === "string"
+      ? [{ type: "text", text: message.content }]
+      : message.content,
+  );
+}
+
+function submissionNeedsInput(
+  messages: readonly UIMessage[],
+  assistantMessageId: string,
+): boolean {
+  const assistant = messages.find(
+    (message) =>
+      message.id === assistantMessageId && message.role === "assistant",
+  );
+  return assistant?.parts.some(
+    (part) =>
+      part.type === "dynamic-tool" &&
+      part.toolName === "ask_user" &&
+      part.state === "output-available",
+  ) ?? false;
+}
+
+interface PendingTemporaryAgentApproval {
+  receipt: ApprovalReceipt;
+  resolve(decision: TemporaryAgentApprovalDecision): void;
+}
+
+// #endregion
+
+/**
+ * 这是 UniversalAgent 唯一的生产 Runtime Kernel。
+ *
+ * @remarks
+ * Cloudflare Agent 负责 Durable Object 生命周期、SQLite、facet、
+ * WebSocket、定时任务和 fiber。
+ *
+ * Pi 负责模型与 Tool 循环和 canonical transcript。
+ *
+ * 生产 Agent 由 `defineRuntimeAgent` 生成子类，应用不直接实例化本类。
+ */
+export abstract class AgentRuntimeKernel<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+> extends RecoverableChatAgent<Env, RuntimeState, PiChatRecoveryData> {
+  initialState: RuntimeState = {
+    runtimeLoad: { status: "idle", available: false },
+  };
+
+  protected abstract ensureRuntimeReady(): Promise<void>;
+
+  private runtimeSnapshot?: RuntimeSnapshot;
+  private runtimeRevision?: string;
+  private runtimePi?: PreparedPiRuntime;
+  private piAdapter?: PiRuntimeAdapter;
+  private readonly transcript: PiRuntimeTranscript;
+  private readonly submissions: SubmissionLifecycle<
+    StoredSubmission,
+    ActiveTurn
+  >;
+  private readonly approvals: ApprovalLifecycle<StoredSubmission>;
+  private readonly streamBySubmission = new Map<string, string>();
+  private db!: RuntimeDatabase;
+  private readonly temporaryAgents = new TemporaryAgentCoordinator();
+  private readonly temporaryAgentApprovals =
+    new Map<string, PendingTemporaryAgentApproval>();
+
+  // #region 构造、装配与启动
+
+  // 作用：返回当前 Kernel 唯一的 Pi 适配器。
+  // 调用：构造和后续所有 Pi 装配、Turn 与恢复路径都通过它访问。
+  // 原因：允许构造时注入适配器，同时为未注入场景保留惰性单例。
+  private get pi(): PiRuntimeAdapter {
+    return this.piAdapter ??= new PiRuntimeAdapter();
+  }
+
+  /**
+   * 为一个 Cloudflare Durable Object 实例建立持久化与执行协作器。
+   *
+   * @remarks
+   * Cloudflare Runtime 创建由 `defineRuntimeAgent` 生成的类时，间接调用。
+   *
+   * 数据库 schema、Submission、Transcript 和 Approval 在同一构造路径绑定，
+   * 避免它们引用不同的事务边界或 Pi 适配器。
+   */
+  constructor(
+    ctx: DurableObjectState,
+    env: Env,
+    pi: PiRuntimeAdapter = new PiRuntimeAdapter(),
+  ) {
+    super(ctx, env, {
+      fiberPrefix: "__cf_internal_pi_turn:",
+      snapshotKey: "__cfPiFiberSnapshot",
+      snapshotKind: "pi-turn",
+    });
+    this.piAdapter = pi;
+    this.db = new RuntimeDatabase(
+      this.sql.bind(this),
+      (fn) => this.ctx.storage.transactionSync(fn),
+    );
+    this.db.initializeSchema();
+    const submissionStore: SubmissionStore<StoredSubmission> = {
+      transaction: (run) => this.db.transaction(run),
+      find: (submissionId) => this.readSubmission(submissionId),
+      findByRequestId: (requestId) =>
+        this.findSubmissionByRequest(requestId),
+      findByIdempotencyKey: (key) => this.findSubmissionByKey(key),
+      countUnfinished: () =>
+        this.db.submissions.countUnfinished(),
+      countPending: () => this.db.submissions.countPending(),
+      findRunning: () =>
+        this.db.submissions.findRunning() as StoredSubmission | null,
+      findNextPending: () =>
+        this.db.submissions.findNextPending() as StoredSubmission | null,
+      updateAbortReason: (submissionId, reason) =>
+        this.db.submissions.updateAbortReason(submissionId, reason),
+    };
+    this.submissions = new SubmissionLifecycle({
+      store: submissionStore,
+      clearTerminal: () => clearChatTerminal(this.ctx.storage),
+      execute: (submissionId, recovery) =>
+        this.executeSubmission(submissionId, recovery),
+      appendAbortIntent: (submission, reason) =>
+        this.appendTerminalIntent(submission, "aborted", reason),
+      commitTerminal: (submission, outcome, message) =>
+        this.commitTerminalOutcome(submission, outcome, message),
+      abortActive: (turn) => turn.agent.abort(),
+    });
+    this.transcript = this.pi.createTranscript({
+      sql: this.sql.bind(this),
+      durability: {
+        transaction: (run) => this.db.transaction(run),
+        upsertUserSidecar: (id, body) =>
+          this.db.messageUi.upsert(id, body),
+        readUserSidecar: (id) => this.db.messageUi.get(id),
+        clearUserSidecars: () => this.db.messageUi.clear(),
+        listMessageSubmissionLinks: () =>
+          this.db.submissions.listMessageSubmissionLinks(),
+        findSubmissionProjection: (submissionId) =>
+          this.readSubmission(submissionId),
+        listApprovalViews: (submissionId) =>
+          this.db.approvals.listApprovalViews(submissionId),
+      },
+      hasActiveTurn: () => this.submissions.isBusy(),
+    });
+    this.approvals = new ApprovalLifecycle({
+      db: this.db,
+      pi: this.pi,
+      findSubmission: (submissionId) =>
+        this.readSubmission(submissionId),
+      applyRecoveryMutations: (submission, mutations) =>
+        this.applyPiRecoveryMutations(submission, mutations),
+      materializeRecoveredToolResults: (submission) =>
+        this.materializeRecoveredToolResults(submission),
+      scheduleContinuation: async (data) => {
+        await this.schedule(
+          0,
+          "_piApprovalContinuation",
+          data,
+          { idempotent: true },
+        );
+      },
+      onApprovalsChanged: () => this.broadcastApprovals(),
+    });
+  }
+
+  // 作用：把通用聊天恢复协议接到本 Runtime 的 Submission 和 Pi 里程碑。
+  // 调用：`RecoverableChatAgent` 第一次需要分类或重试中断 Turn 时惰性调用。
+  // 原因：传输层不应认识 Pi 数据库，所以用窄端口隔开通用恢复与领域决策。
+  protected createRecoveryPort() {
+    return this.pi.createRecovery({
+      readRecoveryState: (requestId) => {
+        const submission = this.findSubmissionByRequest(requestId);
+        if (!submission) return null;
+        return {
+          submissionId: submission.submissionId,
+          requestId: submission.requestId,
+          terminal: isTerminalSubmissionStatus(submission.status),
+          milestoneBodies: this.recoveryMilestoneBodies(
+            submission.submissionId,
+          ),
+          settledToolCount: this.db.settlements.countForSubmission(
+            submission.submissionId,
+          ),
+        };
+      },
+      retryTurn: async (submissionId) => {
+        const receipt = await this.submissions.recover(submissionId);
+        return receipt.status === "completed"
+          ? { status: "completed" as const }
+          : {
+              status: "failed" as const,
+              error:
+                receipt.error ??
+                `Pi recovery ended with status ${receipt.status}`,
+            };
+      },
+      failTurn: async (submissionId, message) => {
+        const submission = this.readSubmission(submissionId);
+        if (submission) {
+          await this.submissions.finish(submission, "failed", message);
+        }
+      },
+      hasPendingInteraction: () => this.approvals.countPending() > 0,
+    });
+  }
+
+  // 作用：准备并原子切换一份新的 Runtime 配置。
+  // 调用：生成 Agent 在首次启动或显式重载 Runtime key 时调用。
+  // 原因：先完整 prepare 再替换 Snapshot，且活跃 Turn 期间禁止换 revision，可避免半装配和恢复时能力漂移。
+  protected async initConfig(config: AgentConfig): Promise<void> {
+    const previous = this.runtimeSnapshot;
+    let next: RuntimeSnapshot | undefined;
+    this.advanceRuntimeLoad("plugins");
+    await initializeRuntimeConfig(config, (snapshot) => {
+      next = snapshot;
+    });
+    if (!next) throw new Error("Runtime assembly did not produce a snapshot");
+    const candidateSnapshot = next;
+
+    this.advanceRuntimeLoad("mcp");
+    await connectConfiguredMcpServers(
+      this,
+      candidateSnapshot.profile.mcpServers,
+    );
+    this.advanceRuntimeLoad("pi");
+    const prepared = await this.pi.prepare({
+      snapshot: candidateSnapshot,
+      mcpHost: this,
+      createExtensionHostBinding: (permissions, ownContextLabels) =>
+        this.createExtensionHostBinding(
+          permissions,
+          ownContextLabels,
+        ),
+    });
+    const revision = await this.hash(prepared.revisionDescriptor);
+    if (
+      previous &&
+      revision !== this.runtimeRevision &&
+      this.submissions.isBusy()
+    ) {
+      throw new Error(
+        "Cannot reload Runtime while a revision-pinned Pi Turn is active",
+      );
+    }
+    this.pi.activate(candidateSnapshot);
+    this.runtimeSnapshot = candidateSnapshot;
+    this.runtimeRevision = revision;
+    this.runtimePi = prepared;
+
+    if (candidateSnapshot.bindings.platform.telemetryConsole) {
+      installConsoleSink();
+    }
+    const degradations = prepared.degradations;
+    if (degradations.length > 0) {
+      console.warn(
+        "[runtime-load:degraded]",
+        json({ degradations }),
+      );
+    }
+  }
+
+  // 作用：为某个已准入 Submission 建立一次 Pi Turn 执行适配器。
+  // 调用：新 Turn、恢复 Turn 和审批后重试 Tool 都在开始 Pi 执行前调用。
+  // 原因：在这里一次性固定 revision、持久化回调与终态回调，防止各执行路径绕过同一耐久性规则。
+  private createSubmissionExecutionAdapter(
+    submission: StoredSubmission,
+    output: {
+      readonly startedAt?: number;
+      readonly continuation?: boolean;
+      readonly assistantOrdinal?: number;
+      readonly onRecord?: (
+        chunk: UIMessageChunk,
+      ) => void | Promise<void>;
+      readonly onTerminal?: (
+        terminal: {
+          outcome: "succeeded" | "failed" | "aborted";
+          message?: string;
+        },
+      ) => void | Promise<void>;
+    } = {},
+  ): PreparedPiTurnAdapter {
+    const startedAt = output.startedAt ?? Date.now();
+    return this.pi.createTurn({
+      prepared: this.preparedPi(),
+      baseRevision: this.baseRevision(),
+      pinnedDescriptor: submission.assemblyDescriptor,
+      submission: {
+        id: submission.submissionId,
+        requestId: submission.requestId,
+        messageId: submission.assistantMessageId,
+        startedAt,
+        continuation: output.continuation ?? false,
+        assistantOrdinal: output.assistantOrdinal ?? 0,
+      },
+      canonicalMessages: () => this.transcript.canonicalMessages(),
+      durability: {
+        findToolSettlement: (toolCallId) =>
+          this.readToolSettlement(submission.submissionId, toolCallId),
+        requestToolApproval: (approval, signal, onCreated) =>
+          this.approvals.request(
+            submission,
+            approval,
+            signal,
+            async (created) => {
+              await onCreated?.();
+              try {
+                await this.assembly().bindings.turnEvents?.onApproval?.({
+                  submissionId: submission.submissionId,
+                  approvalExecutionId: created.executionId,
+                });
+              } catch (error) {
+                console.warn(
+                  "[runtime-approval-projection:degraded]",
+                  json({ error: errorText(error) }),
+                );
+              }
+            },
+          ),
+        appendToolInput: (input) =>
+          this.appendToolInput(submission, input),
+        settleTool: (call) =>
+          this.settleTool(submission.submissionId, call),
+      },
+      onToolTelemetry: (event) => {
+        this._emit("ua:tool" as never, { ...event });
+      },
+      transformContext: (messages, signal) =>
+        this.transformPiContext(submission.submissionId, messages, signal),
+      abortReason: () =>
+        this.readSubmission(submission.submissionId)?.abortReason,
+      onRecord: output.onRecord ?? (() => undefined),
+      onCanonicalMessage: async (commit) => {
+        let consumedSteer = false;
+        this.db.transaction(() => {
+          if (commit.kind !== "append-user") {
+            const persisted = this.transcript.commitAdapterMessage(
+              submission.submissionId,
+              commit,
+            );
+            if (persisted.inserted && commit.message.role === "assistant") {
+              const event = assistantUsageEvent(
+                persisted.id,
+                submission.submissionId,
+                commit.message,
+              );
+              this.db.runtimeEvents.insert({
+                eventId: event.eventId,
+                body: json({ type: "model-usage", event }),
+                createdAt: commit.message.timestamp,
+              });
+            }
+            return;
+          }
+          const pending = this.db.steers.findByMessageId(commit.id);
+          if (!pending) {
+            this.transcript.commitAdapterMessage(
+              submission.submissionId,
+              commit,
+            );
+            return;
+          }
+          if (pending.submissionId !== submission.submissionId) {
+            throw new Error(
+              `Steer ${pending.steerId} belongs to another submission`,
+            );
+          }
+          const uiMessage = pending.uiMessageJson
+            ? JSON.parse(pending.uiMessageJson) as UIMessage & {
+                role: "user";
+              }
+            : undefined;
+          this.transcript.append(commit.id, commit.message, {
+            submissionId: submission.submissionId,
+            createdAt: commit.message.timestamp,
+            ...(uiMessage ? { userMessage: uiMessage } : {}),
+          });
+          this.db.steers.deleteByMessageId(commit.id);
+          consumedSteer = true;
+        });
+        await this.drainRuntimeEvents();
+        if (consumedSteer) await this.broadcastApprovals();
+      },
+      onTerminal: output.onTerminal ?? (() => undefined),
+    });
+  }
+
+  /**
+   * 在 Agent 实例启动或从休眠唤醒后恢复 Session 本地后台状态。
+   *
+   * @remarks
+   * Cloudflare Agents SDK 在任何 HTTP、WebSocket 或 RPC 调用前调用它。
+   *
+   * 先恢复审批续跑，再分类未完 Submission，
+   * 可避免把正在等待人的 Turn 当成普通中断直接重试。
+   *
+   * 待确认：Cloudflare 当前文档说 `DurableObjectState.waitUntil`
+   * 不会延长 Durable Object 生命；本文件仍在三处用它启动后台任务。
+   */
+  async onStart(): Promise<void> {
+    this.publishRuntimeLoad({ status: "idle", available: false });
+    if (this.db.runtimeEvents.hasPending()) {
+      this.ctx.waitUntil(
+        this.ensureRuntimeReady().then(() => this.drainRuntimeEvents()),
+      );
+    }
+    await this.broadcastApprovals();
+    await this.approvals.dispatchPendingContinuations();
+    const running = this.db.submissions.findRunning() as StoredSubmission | null;
+    if (running) {
+      const effect = this.decidePiRecovery(running).effect;
+      if (
+        effect.kind === "wait" &&
+        (effect.reason === "approval" ||
+          effect.reason === "uncertain-tool")
+      ) {
+        return;
+      }
+    }
+    this.ctx.waitUntil(
+      this.submissions.recoverHead().then(() => undefined),
+    );
+  }
+
+  private async drainRuntimeEvents(idempotentRetry = true): Promise<void> {
+    const turnEvents = this.runtimeSnapshot?.bindings.turnEvents;
+    if (!turnEvents) return;
+
+    let failed = false;
+    for (const row of this.db.runtimeEvents.listPending()) {
+      try {
+        const payload = JSON.parse(row.body) as RuntimeEventOutboxPayload;
+        if (payload.type === "model-usage") {
+          if (!turnEvents.onModelUsage) continue;
+          await turnEvents.onModelUsage(payload.event);
+        } else {
+          if (!turnEvents.onToolSettled) continue;
+          await turnEvents.onToolSettled(payload.event);
+        }
+        this.db.transaction(() =>
+          this.db.runtimeEvents.markDelivered(row.eventId, Date.now())
+        );
+      } catch (error) {
+        failed = true;
+        console.warn(
+          "[runtime-turn-event:degraded]",
+          json({ eventId: row.eventId, error: errorText(error) }),
+        );
+      }
+    }
+    if (!failed) return;
+
+    try {
+      await this.schedule(
+        TURN_EVENT_RETRY_SECONDS,
+        "_drainRuntimeTurnEvents",
+        undefined,
+        { idempotent: idempotentRetry },
+      );
+    } catch (error) {
+      console.warn(
+        "[runtime-turn-event-retry:degraded]",
+        json({ error: errorText(error) }),
+      );
+    }
+  }
+
+  async _drainRuntimeTurnEvents(): Promise<void> {
+    await this.ensureRuntimeReady();
+    await this.drainRuntimeEvents(false);
+  }
+
+  // 作用：重新读取当前 Snapshot 以刷新动态 Context 依赖。
+  // 调用：生成 Agent 的 `refreshMemoryContext` 在确保配置已加载后调用。
+  // 原因：统一经过 `assembly` 的已初始化检查，不再引入第二份配置状态。
+  async refreshContext(): Promise<void> {
+    this.assembly();
+  }
+
+  // 作用：在当前 Session 内启动一个临时 Agent 执行。
+  // 调用：临时 Agent Tool 通过 `RuntimeAgentConfigContext` 带着本次信号调用。
+  // 原因：协调器统一跟踪运行和取消，不把临时子执行塞进持久 Submission 模型。
+  protected runTemporaryAgent(
+    request: TemporaryAgentRequest,
+    context: TemporaryAgentRunContext,
+    execute: TemporaryAgentExecutor,
+  ): Promise<string> {
+    return this.temporaryAgents.run(request, execute, context.signal);
+  }
+
+  /**
+   * 登记一条临时 Agent 的 Tool 审批并等待用户决定。
+   *
+   * @remarks
+   * Temporary Agent Host 在子执行需要人工授权时调用。
+   *
+   * 它与持久 Pi Tool 审批共用同一客户端投影，但只保存本次执行的 Promise，
+   * 因为临时 Agent 本身不参与 Session Turn 恢复。
+   */
+  async requestTemporaryAgentApproval(
+    request: TemporaryAgentApprovalRequest,
+  ): Promise<TemporaryAgentApprovalDecision> {
+    if (this.temporaryAgentApprovals.has(request.executionId)) {
+      throw new Error(
+        `temporary agent approval already pending: ${request.executionId}`,
+      );
+    }
+    return new Promise((resolve, reject) => {
+      this.temporaryAgentApprovals.set(request.executionId, {
+        receipt: {
+          executionId: request.executionId,
+          source: "temporary-agent",
+          action: request.toolName,
+          summary: `${request.subagentName} requests ${request.toolName}`,
+          executionLevel: request.executionLevel,
+          requiredExecutionLevel: request.requiredExecutionLevel,
+          inputJson: JSON.stringify(request.input ?? null),
+          requestId: request.requestId,
+        },
+        resolve,
+      });
+      void this.broadcastApprovals().catch((error) => {
+        this.temporaryAgentApprovals.delete(request.executionId);
+        reject(error);
+      });
+    });
+  }
+
+  /**
+   * 取消一条仍在等待的临时 Agent 审批。
+   *
+   * @remarks
+   * Temporary Agent Host 在子执行停止或超时时调用。
+   *
+   * 先从内存表删除再解决 Promise，避免并发的批准请求再次命中已取消项。
+   */
+  async cancelTemporaryAgentApproval(
+    executionId: string,
+    reason = "temporary agent was cancelled",
+  ): Promise<{ ok: boolean }> {
+    const pending = this.temporaryAgentApprovals.get(executionId);
+    if (!pending) return { ok: false };
+    this.temporaryAgentApprovals.delete(executionId);
+    pending.resolve({ approved: false, reason });
+    await this.broadcastApprovals();
+    return { ok: true };
+  }
+
+  // 作用：返回已生效的 Runtime Snapshot。
+  // 调用：所有需要模型、工作区、扩展或投影绑定的运行时路径调用。
+  // 原因：未初始化时立即失败，比在深层路径触发空值更容易定位。
+  private assembly(): RuntimeSnapshot {
+    if (!this.runtimeSnapshot) {
+      throw new Error(
+        "AgentConfig must be initialized before using the Runtime",
+      );
+    }
+    return this.runtimeSnapshot;
+  }
+
+  // 作用：发布一次 Runtime 装载尝试的公开状态。
+  // 调用：生成 Agent 的首次加载/重载入口，以及本类的 Plugin、MCP、Pi 装配边界。
+  // 原因：复用 Agent state 的现有同步协议，让浏览器无需理解内部 Loader 实现。
+  protected publishRuntimeLoad(runtimeLoad: RuntimeLoadState): void {
+    this.setState({ ...this.state, runtimeLoad });
+  }
+
+  // 作用：开始一轮新的 Runtime 装载尝试。
+  // 调用：生成 Agent 在调用应用 createConfig 前调用。
+  // 原因：config 阶段可能包含身份、D1 和 Resource 解析，必须在首个慢请求前可见。
+  protected beginRuntimeLoad(): void {
+    const now = Date.now();
+    this.publishRuntimeLoad({
+      status: "loading",
+      phase: "config",
+      available: Boolean(this.runtimeSnapshot),
+      startedAt: now,
+      updatedAt: now,
+    });
+  }
+
+  // 作用：推进当前 Runtime 装载尝试的阶段。
+  // 调用：initConfig 在进入 Plugin、MCP 和 Pi 边界时调用。
+  // 原因：保持一个稳定的粗粒度协议，不向前端泄漏具体 Plugin 实现和并发细节。
+  private advanceRuntimeLoad(phase: RuntimeLoadPhase): void {
+    const current = this.state.runtimeLoad;
+    const now = Date.now();
+    this.publishRuntimeLoad({
+      status: "loading",
+      phase,
+      available: Boolean(this.runtimeSnapshot),
+      startedAt:
+        current?.status === "loading" ? current.startedAt : now,
+      updatedAt: now,
+    });
+  }
+
+  // 作用：把成功提交的 Runtime 装载尝试标记为可用。
+  // 调用：生成 Agent 在 initConfig 和 Runtime key 提交完成后调用。
+  // 原因：只有完整原子提交后才能向客户端承诺 ready。
+  protected completeRuntimeLoad(): void {
+    const current = this.state.runtimeLoad;
+    const now = Date.now();
+    this.publishRuntimeLoad({
+      status: "ready",
+      available: true,
+      startedAt:
+        current?.status === "loading" ? current.startedAt : now,
+      completedAt: now,
+    });
+  }
+
+  // 作用：记录 Runtime 装载失败，同时保留旧 Runtime 是否仍可用的信息。
+  // 调用：生成 Agent 收口 createConfig 或 initConfig 的异常时调用。
+  // 原因：前端需要状态但不应接收可能包含存储细节的底层错误文本。
+  protected failRuntimeLoad(): void {
+    const current = this.state.runtimeLoad;
+    const now = Date.now();
+    this.publishRuntimeLoad({
+      status: "error",
+      phase: current?.status === "loading" ? current.phase : "config",
+      available: Boolean(this.runtimeSnapshot),
+      startedAt:
+        current?.status === "loading" ? current.startedAt : now,
+      failedAt: now,
+    });
+  }
+
+  // 作用：为 Runtime Extension 创建只包含授权能力的 Worker 回环绑定。
+  // 调用：Pi 准备扩展时，按每个扩展的权限和 Context label 调用。
+  // 原因：`ctx.exports` 是 Cloudflare 提供的 Worker 内回环入口，在边界上裁剪权限可避免扩展接触整个 Agent。
+  private createExtensionHostBinding(
+    permissions: RuntimeExtensionPermissions,
+    ownContextLabels: readonly string[],
+  ): Fetcher {
+    const exports = this.ctx.exports as unknown as {
+      HostBridgeLoopback(input: {
+        props: {
+          agentClassName: string;
+          agentId: string;
+          permissions: RuntimeExtensionPermissions;
+          ownContextLabels: string[];
+        };
+      }): Fetcher;
+    };
+    return exports.HostBridgeLoopback({
+      props: {
+        agentClassName: this.constructor.name,
+        agentId: this.ctx.id.toString(),
+        permissions,
+        ownContextLabels: [...ownContextLabels],
+      },
+    });
+  }
+
+  // 作用：计算一段描述文本的 SHA-256 十六进制指纹。
+  // 调用：配置激活、Submission 准入和恢复校验在比较 revision 时调用。
+  // 原因：只持久化稳定短指纹，即可验证完整描述没有在 Turn 中途改变。
+  private async hash(value: string): Promise<string> {
+    const digest = await crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(value),
+    );
+    return [...new Uint8Array(digest)]
+      .map((byte) => byte.toString(16).padStart(2, "0"))
+      .join("");
+  }
+
+  // 作用：返回当前已激活配置的 revision。
+  // 调用：创建 Pi Turn 适配器时调用。
+  // 原因：把初始化不变式收口在一处，避免执行层带着空 revision 继续。
+  private baseRevision(): string {
+    if (!this.runtimeRevision) {
+      throw new Error("Runtime revision is not initialized");
+    }
+    return this.runtimeRevision;
+  }
+
+  // 作用：返回当前已准备好的 Pi Runtime。
+  // 调用：创建 Turn 适配器或准入固定装配时调用。
+  // 原因：明确区分“已有 Snapshot”和“Pi 已完成准备”，防止半初始化状态进入 Turn。
+  private preparedPi(): PreparedPiRuntime {
+    if (!this.runtimePi) {
+      throw new Error(
+        "Pi Runtime must be prepared before starting a Turn",
+      );
+    }
+    return this.runtimePi;
+  }
+
+  // #endregion
+
+  // #region Submission 准入与配置固定
+
+  // 作用：为新 Submission 生成包含当前 Context 的不可变装配描述。
+  // 调用：Submission 通过去重和忙碌检查后，在真正写入前调用。
+  // 原因：把动态 Context 和执行档位固定在准入时，恢复时才能按原配置继续。
+  private async admissionPin(): Promise<{
+    revision: string;
+    descriptor: string;
+  }> {
+    await this.ensureRuntimeReady();
+    await this.drainRuntimeEvents();
+    if (!this.runtimeRevision) {
+      throw new Error("Runtime revision is not initialized");
+    }
+    const pinned = await this.pi.pin({
+      prepared: this.preparedPi(),
+      baseRevision: this.runtimeRevision,
+      readExtensionContext: ({ label }) =>
+        this._hostGetContext(label),
+    });
+    if (pinned.degradations.length > 0) {
+      console.warn(
+        "[runtime-context:degraded]",
+        json({ degradations: pinned.degradations }),
+      );
+    }
+    return {
+      revision: await this.hash(pinned.descriptor),
+      descriptor: pinned.descriptor,
+    };
+  }
+
+  private async pinSubmissionAssembly(
+    submission: StoredSubmission,
+  ): Promise<StoredSubmission> {
+    if (submission.assemblyRevision && submission.assemblyDescriptor) {
+      return submission;
+    }
+    if (submission.assemblyRevision || submission.assemblyDescriptor) {
+      throw new Error("Submission assembly pin is incomplete");
+    }
+    const { revision, descriptor } = await this.admissionPin();
+    this.db.submissions.pinAssembly(
+      submission.submissionId,
+      revision,
+      descriptor,
+    );
+    const pinned = this.readSubmission(submission.submissionId);
+    if (!pinned?.assemblyRevision || !pinned.assemblyDescriptor) {
+      throw new Error("Submission ended before Runtime assembly was pinned");
+    }
+    return pinned;
+  }
+
+  // 作用：检查 Submission 保存的装配描述与 revision 仍然匹配。
+  // 调用：普通恢复和审批续跑在重建 Pi Turn 前调用。
+  // 原因：若持久描述已变，继续执行会把同一 Turn 切成两套能力语义。
+  private async assertPinnedSubmission(
+    submission: StoredSubmission,
+  ): Promise<void> {
+    if (
+      submission.assemblyRevision !==
+      await this.hash(submission.assemblyDescriptor)
+    ) {
+      throw new Error(
+        "Pinned Runtime revision is unavailable for Pi recovery",
+      );
+    }
+  }
+
+  // 作用：按当前内存预算和模型压缩 Pi 上下文。
+  // 调用：Pi Turn 适配器在发模型请求前通过 `transformContext` 回调。
+  // 原因：压缩必须使用本 Snapshot 的模型和密钥，不能脱离已固定的 Runtime 配置。
+  private async transformPiContext(
+    submissionId: string,
+    messages: Parameters<PiRuntimeTranscript["compactContext"]>[0],
+    signal?: AbortSignal,
+  ): ReturnType<PiRuntimeTranscript["compactContext"]> {
+    const snapshot = this.assembly();
+    const compacted = await this.transcript.compactContext(messages, {
+      compactAfterTokens:
+        snapshot.profile.memory.compactAfterTokens,
+      model: snapshot.pi.model,
+      apiKey: this.pi.resolveApiKey(
+        snapshot.bindings.provider,
+        snapshot.pi.model.id,
+      ),
+      signal,
+      submissionId,
+      onCompactionPersisted: (event) =>
+        this.db.runtimeEvents.insert({
+          eventId: event.eventId,
+          body: json({ type: "model-usage", event }),
+          createdAt: Date.now(),
+        }),
+    });
+    await this.drainRuntimeEvents();
+    return compacted;
+  }
+
+  // 作用：按 Submission ID 读取一条 Runtime 提交记录。
+  // 调用：执行、恢复、审批和终态路径需要当前持久状态时调用。
+  // 原因：在 Kernel 边界统一收窄为 `StoredSubmission`，避免上层分散重复转型。
+  private readSubmission(
+    submissionId: string,
+  ): StoredSubmission | null {
+    return this.db.submissions.find(submissionId) as StoredSubmission | null;
+  }
+
+  // 作用：按客户端 request ID 找到对应 Submission。
+  // 调用：聊天取消、恢复分类和提交去重时调用。
+  // 原因：request ID 是传输层身份，在此集中完成它到领域 Submission 的映射。
+  private findSubmissionByRequest(
+    requestId: string,
+  ): StoredSubmission | null {
+    return this.db.submissions.findByRequestId(requestId) as StoredSubmission | null;
+  }
+
+  // 作用：按业务幂等键找到已接收的 Submission。
+  // 调用：SubmissionLifecycle 在新提交准入前调用。
+  // 原因：去重必须查持久层，只看内存无法覆盖 Durable Object 重启。
+  private findSubmissionByKey(
+    idempotencyKey: string,
+  ): StoredSubmission | null {
+    return this.db.submissions.findByIdempotencyKey(idempotencyKey) as StoredSubmission | null;
+  }
+
+  // 作用：组装一个可由 SubmissionLifecycle 原子准入的用户消息。
+  // 调用：即时提交和等待稳定的定时提交共用。
+  // 原因：延迟真正写入到事务内，可让去重、忙碌检查、revision 固定和 transcript 更新一起成功或失败。
+  private submissionInput(
+    userMessage: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+  ): SubmissionInput<StoredSubmission> {
+    return {
+      requestId: options.requestId,
+      ...(options.idempotencyKey
+        ? { idempotencyKey: options.idempotencyKey }
+        : {}),
+      prepareAdmission: async () => {
+        const regenerateEntry =
+          options.regenerate && options.userMessageId
+            ? await this.transcript.findUserMessage(options.userMessageId)
+            : undefined;
+        return () => {
+          const submissionId = crypto.randomUUID();
+          const assistantMessageId = crypto.randomUUID();
+          const createdAt = userMessage.timestamp;
+          const userMessageId =
+            options.userMessageId ?? crypto.randomUUID();
+          if (options.regenerate) {
+            if (
+              !regenerateEntry ||
+              userContentKey(regenerateEntry) !==
+                userContentKey(userMessage)
+            ) {
+              throw new Error(
+                "Regenerate request must match an existing user message",
+              );
+            }
+          }
+          this.db.submissions.insert({
+            submissionId,
+            requestId: options.requestId,
+            idempotencyKey: options.idempotencyKey ?? null,
+            createdAt,
+            assemblyRevision: "",
+            assemblyDescriptor: "",
+            assistantMessageId,
+            queuedInputJson: json(userMessage),
+            queuedUiMessageJson: options.userMessage
+              ? json(options.userMessage)
+              : null,
+            userMessageId,
+            regenerateMessageId: options.regenerate
+              ? options.userMessageId ?? null
+              : null,
+          });
+          return this.readSubmission(submissionId)!;
+        };
+      },
+    };
+  }
+
+  // 作用：立即尝试准入一条用户消息并返回执行句柄。
+  // 调用：WebSocket 聊天、RPC prompt 和其他同步入口在收到消息时调用。
+  // 原因：所有即时入口收口到同一 SubmissionLifecycle，才会共享去重和单 Turn 约束。
+  private submitMessage(
+    userMessage: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+  ): Promise<SubmissionHandle<StoredSubmission>> {
+    return this.submitMessageAndBroadcast(userMessage, options);
+  }
+
+  private async submitMessageAndBroadcast(
+    userMessage: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+  ): Promise<SubmissionHandle<StoredSubmission>> {
+    const submitted = await this.submissions.submit(
+      this.submissionInput(userMessage, options),
+    );
+    await this.broadcastApprovals();
+    return submitted;
+  }
+
+  // 作用：等待 Runtime 稳定后再准入一条用户消息。
+  // 调用：定时任务在不应打断正在运行的 Turn 时调用。
+  // 原因：有界等待比无限排队更适合定时任务，超时可返回明确的 skipped 回执。
+  private async submitMessageWhenStable(
+    userMessage: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+    timeoutMs: number,
+  ): Promise<SubmissionHandle<StoredSubmission> | null> {
+    const submitted = await this.submissions.submitWhenStable(
+      this.submissionInput(userMessage, options),
+      timeoutMs,
+    );
+    if (submitted) await this.broadcastApprovals();
+    return submitted;
+  }
+
+  // #endregion
+
+  // #region 持久化、恢复与终态提交
+
+  // 作用：更新 Submission 状态并返回数据库中的最新记录。
+  // 调用：终态提交在决定 completed、aborted 或 error 后调用。
+  // 原因：完成时间只能跟终态一起写入，然后必须回读以防止返回过期对象。
+  private updateSubmission(
+    submissionId: string,
+    status: SubmissionStatus,
+    error?: string,
+  ): StoredSubmission {
+    const completedAt = isTerminalSubmissionStatus(status) ? Date.now() : null;
+    this.db.submissions.updateTerminal(
+      submissionId,
+      status,
+      error,
+      completedAt ?? undefined,
+    );
+    const submission = this.readSubmission(submissionId);
+    if (!submission) {
+      throw new Error(`Unknown Pi submission: ${submissionId}`);
+    }
+    return submission;
+  }
+
+  // 作用：读取某个 Submission 已持久的全部 Pi 恢复里程碑。
+  // 调用：恢复决策器每次检查或应用命令前调用。
+  // 原因：决策只依赖持久事实，重启后才会得到同样结果。
+  private recoveryMilestoneBodies(submissionId: string): string[] {
+    return this.db.milestones.listBodies(submissionId);
+  }
+
+  // 作用：让 Pi 根据已持久里程碑决定下一个恢复动作。
+  // 调用：Tool 输入与结果、审批、终态和唤醒恢复路径调用。
+  // 原因：决策集中在 Pi 状态机，Kernel 只提供身份和事实，避免两份恢复规则漂移。
+  private decidePiRecovery(
+    submission: StoredSubmission,
+    command: PiRecoveryCommand = { kind: "inspect" },
+    now = Date.now(),
+  ): PiRecoveryDecision {
+    return this.pi.decideRecovery({
+      milestoneBodies: this.recoveryMilestoneBodies(
+        submission.submissionId,
+      ),
+      identity: {
+        turnId: submission.submissionId,
+        assemblyRevision: submission.assemblyRevision,
+      },
+      command,
+      now,
+    });
+  }
+
+  // 作用：把 Pi 恢复决策产生的变更写入 Runtime 数据库。
+  // 调用：记录 Tool、终态、审批或恢复步骤时，通常在事务内调用。
+  // 原因：upsert 保证重放幂等，而 terminal intent 允许后来的更强结果更新早期意图。
+  private applyPiRecoveryMutations(
+    submission: StoredSubmission,
+    mutations: readonly PiDurableMutation[],
+  ): boolean {
+    let appended = false;
+    for (const mutation of mutations) {
+      if (mutation.kind === "decide-approval") {
+        this.db.approvals.decide(
+          mutation.executionId,
+          mutation.status as any,
+          mutation.decidedAt,
+          mutation.reason,
+        );
+        continue;
+      }
+      const inserted = this.db.milestones.upsert(
+        submission.submissionId,
+        mutation.key,
+        mutation.body,
+      );
+      appended ||= inserted;
+      if (!inserted && mutation.key === "terminal:intent") {
+        this.db.milestones.updateTerminalIntent(
+          submission.submissionId,
+          mutation.body,
+        );
+      }
+    }
+    return appended;
+  }
+
+  // 作用：在 Tool 执行前持久记录它的名称和输入。
+  // 调用：Pi Turn 适配器通过 durability 回调在每个 Tool 开始时调用。
+  // 原因：先留下 durable intent，中断后才能区分“未执行”和“结果不确定”。
+  private appendToolInput(
+    submission: StoredSubmission,
+    input: PiToolInputRecord,
+  ): boolean {
+    const decision = this.decidePiRecovery(submission, {
+      kind: "record-tool-input",
+      record: input,
+    });
+    return this.db.transaction(() =>
+      this.applyPiRecoveryMutations(
+        submission,
+        decision.mutations,
+      ),
+    );
+  }
+
+  // 作用：持久化一次 Tool 结果，并推进相应的恢复里程碑。
+  // 调用：正常 Tool 执行和恢复 Tool 结果落地时调用。
+  // 原因：同一 `toolCallId` 只允许内容完全相同的重放，冲突结果必须立即失败以保护恢复确定性。
+  private settleTool(
+    submissionId: string,
+    call: PiToolSettlement & { readonly createdAt?: number },
+  ): Promise<void> {
+    this.db.transaction(() => this.settleToolSync(submissionId, call));
+    return this.drainRuntimeEvents();
+  }
+
+  // 终态事务用这个同步内核先补齐 ToolResult，再在同一事务末尾写 marker。
+  private settleToolSync(
+    submissionId: string,
+    call: PiToolSettlement & { readonly createdAt?: number },
+  ): void {
+    const submission = this.readSubmission(submissionId);
+    if (!submission) {
+      throw new Error(`Unknown Pi submission: ${submissionId}`);
+    }
+    const existing = this.db.settlements.find(submissionId, call.toolCallId);
+    const args = json(call.args);
+    const result = json(call.result);
+    const createdAt = existing?.createdAt ?? call.createdAt ?? Date.now();
+    if (existing) {
+      if (
+        existing.toolName !== call.toolName ||
+        existing.args !== args ||
+        existing.result !== result ||
+        existing.isError !== call.isError
+      ) {
+        throw new Error(
+          `Conflicting durable Tool settlement: ${call.toolCallId}`,
+        );
+      }
+    } else {
+      this.db.settlements.insert({
+        toolCallId: call.toolCallId,
+        submissionId,
+        toolName: call.toolName,
+        args,
+        result,
+        isError: call.isError,
+        createdAt,
+      });
+      const event: RuntimeToolSettlementEvent = {
+        eventId: `${submissionId}:tool:${call.toolCallId}`,
+        submissionId,
+        toolCallId: call.toolCallId,
+        toolName: call.toolName,
+        status: call.isError ? "error" : "success",
+      };
+      this.db.runtimeEvents.insert({
+        eventId: event.eventId,
+        body: json({ type: "tool-settlement", event }),
+        createdAt,
+      });
+    }
+    const decision = this.decidePiRecovery(submission, {
+      kind: "record-tool-result",
+      toolCallId: call.toolCallId,
+      toolName: call.toolName,
+      result: call.result,
+      isError: call.isError,
+      timestamp: createdAt,
+    });
+    this.applyPiRecoveryMutations(submission, decision.mutations);
+    this.approvals.commitContinuation(submission, call.toolCallId);
+  }
+
+  // 作用：按 Submission 和 Tool Call ID 读取已持久结果。
+  // 调用：Pi 执行去重、恢复物化和审批续跑在重做 Tool 前调用。
+  // 原因：只在边界解析 JSON，数据库仍保留可精确比较的原始文本。
+  private readToolSettlement(
+    submissionId: string,
+    toolCallId: string,
+  ): {
+    toolName: string;
+    args: unknown;
+    result: PiStoredToolSettlement["result"];
+    isError: boolean;
+    createdAt: number;
+  } | null {
+    const row = this.db.settlements.find(submissionId, toolCallId);
+    return row
+      ? {
+          toolName: row.toolName,
+          args: JSON.parse(row.args) as unknown,
+          result: JSON.parse(
+            row.result,
+          ) as PiStoredToolSettlement["result"],
+          isError: row.isError,
+          createdAt: row.createdAt,
+        }
+      : null;
+  }
+
+  // 作用：把恢复状态机已知的 Tool 结果补全到 settlement 和 transcript 投影。
+  // 调用：Turn 恢复、审批决定和终态收尾在继续前调用。
+  // 原因：恢复记录可能比浏览器 transcript 更新，先去重落库再按 canonical 顺序投影才不会丢失或重复 ToolResult。
+  private materializeRecoveredToolResultsSync(
+    submission: StoredSubmission,
+  ): PiRecoveryDecision {
+    let decision = this.decidePiRecovery(submission);
+    for (const settlement of decision.recoveredToolSettlements) {
+      if (
+        this.readToolSettlement(
+          submission.submissionId,
+          settlement.toolCallId,
+        )
+      ) {
+        continue;
+      }
+      this.settleToolSync(submission.submissionId, settlement);
+      decision = this.decidePiRecovery(submission);
+    }
+    const results = this.transcript.orderRecoveredToolSettlements(
+      decision.recoveredToolSettlements,
+    );
+    for (const recovered of results) {
+      this.transcript.appendRecoveredToolSettlement(
+        submission.submissionId,
+        recovered,
+      );
+    }
+    return decision;
+  }
+
+  private async materializeRecoveredToolResults(
+    submission: StoredSubmission,
+  ): Promise<PiRecoveryDecision> {
+    const decision = this.db.transaction(() =>
+      this.materializeRecoveredToolResultsSync(submission)
+    );
+    await this.drainRuntimeEvents();
+    return decision;
+  }
+
+  // 作用：在改写 Submission 终态前持久化 Turn 的结束意图。
+  // 调用：模型终止回调、取消和最终提交都会调用。
+  // 原因：intent 早于状态行落地，即使两步之间中断，恢复也能重建权威结果。
+  private appendTerminalIntent(
+    submission: StoredSubmission,
+    outcome: "succeeded" | "failed" | "aborted",
+    message?: string,
+  ): void {
+    const decision = this.decidePiRecovery(submission, {
+      kind: "record-terminal",
+      phase: "intent",
+      outcome,
+      ...(message === undefined ? {} : { message }),
+    });
+    this.applyPiRecoveryMutations(submission, decision.mutations);
+  }
+
+  // 作用：把 Turn 的权威结果一次提交到 Submission、恢复里程碑和聊天续传标记。
+  // 调用：SubmissionLifecycle 完成成功、失败或取消时调用。
+  // 原因：已持久的 abort 和 terminal intent 优先于调用方参数，可避免并发收尾覆盖更早的真实结果。
+  private async commitTerminalOutcome(
+    submission: StoredSubmission,
+    outcome: "succeeded" | "failed" | "aborted",
+    message?: string,
+  ): Promise<StoredSubmission> {
+    const latest = this.readSubmission(submission.submissionId);
+    if (!latest) {
+      throw new Error(
+        `Unknown Pi submission: ${submission.submissionId}`,
+      );
+    }
+    if (isTerminalSubmissionStatus(latest.status)) return latest;
+
+    const durableIntent = this.decidePiRecovery(latest).terminal;
+    const effectiveOutcome = latest.abortReason
+      ? "aborted"
+      : durableIntent?.outcome ?? outcome;
+    const effectiveMessage =
+      latest.abortReason ?? durableIntent?.message ?? message;
+    const terminal = this.db.transaction(() => {
+      this.appendTerminalIntent(
+        latest,
+        effectiveOutcome,
+        effectiveMessage,
+      );
+      const closedApprovals = this.approvals.rejectPending(
+        latest,
+        effectiveMessage ?? "Turn ended before approval",
+      );
+      if (closedApprovals) {
+        this.materializeRecoveredToolResultsSync(latest);
+      }
+      const status =
+        effectiveOutcome === "succeeded"
+          ? "completed"
+          : effectiveOutcome === "aborted"
+            ? "aborted"
+            : "error";
+      for (const steer of this.db.steers.listForSubmission(
+        latest.submissionId,
+      )) {
+        if (!this.db.submissions.findByRequestId(steer.messageId)) {
+          this.db.submissions.insert({
+            submissionId: steer.steerId,
+            requestId: steer.messageId,
+            idempotencyKey: steer.messageId,
+            createdAt: steer.createdAt,
+            assemblyRevision: latest.assemblyRevision,
+            assemblyDescriptor: latest.assemblyDescriptor,
+            assistantMessageId: crypto.randomUUID(),
+            queuedInputJson: steer.canonicalJson,
+            queuedUiMessageJson: steer.uiMessageJson,
+            userMessageId: steer.messageId,
+            regenerateMessageId: null,
+          });
+        }
+        this.db.steers.deleteByMessageId(steer.messageId);
+      }
+      const terminal = this.updateSubmission(
+        latest.submissionId,
+        status,
+        effectiveMessage,
+      );
+      if (
+        effectiveOutcome === "aborted" &&
+        effectiveMessage === USER_STOP_REASON
+      ) {
+        if (terminal.completedAt == null) {
+          throw new Error(
+            `Aborted Pi submission has no completion time: ${latest.submissionId}`,
+          );
+        }
+        this.transcript.appendTurnAbortedMarker(
+          latest.submissionId,
+          terminal.completedAt,
+        );
+      }
+      const committed = this.decidePiRecovery(latest, {
+        kind: "record-terminal",
+        phase: "committed",
+        outcome: effectiveOutcome,
+        ...(effectiveMessage === undefined
+          ? {}
+          : { message: effectiveMessage }),
+      });
+      this.applyPiRecoveryMutations(
+        latest,
+        committed.mutations,
+      );
+      return terminal;
+    });
+    await this.drainRuntimeEvents();
+    let inactiveActivity: RuntimeActivity = "idle";
+    if (terminal.status === "completed") {
+      try {
+        if (submissionNeedsInput(
+          await this.getMessages(),
+          terminal.assistantMessageId,
+        )) {
+          inactiveActivity = "needs-input";
+        }
+      } catch {
+        // Transcript projection is retried by the normal terminal path.
+      }
+    }
+    await this.broadcastApprovals(inactiveActivity);
+    try {
+      if (
+        effectiveOutcome === "failed" ||
+        (effectiveOutcome === "aborted" &&
+          effectiveMessage !== USER_STOP_REASON)
+      ) {
+        await recordChatTerminal(
+          this.ctx.storage,
+          latest.requestId,
+          effectiveMessage ?? "",
+        );
+      } else {
+        await clearChatTerminal(this.ctx.storage);
+      }
+    } catch (error) {
+      console.error("[pi-terminal] resume marker failed", error);
+    }
+    return terminal;
+  }
+
+  // 作用：按持久事实把一个中断 Turn 推进到可继续或已收尾状态。
+  // 调用：`executeNonTerminalSubmission` 以 recovery 模式重起 Pi Turn 前调用。
+  // 原因：用有界循环执行状态机效果，既允许 Tool 重试产生新事实，也防止错误规则无限自旋。
+  private async prepareRecoveredTurn(
+    submission: StoredSubmission,
+    adapter: PreparedPiTurnAdapter,
+  ): Promise<boolean> {
+    let decision = await this.materializeRecoveredToolResults(submission);
+    for (let step = 0; step < 32; step += 1) {
+      this.db.transaction(() => {
+        this.applyPiRecoveryMutations(
+          submission,
+          decision.mutations,
+        );
+      });
+      switch (decision.effect.kind) {
+        case "wait":
+          return false;
+        case "retry-tool": {
+          try {
+            if (
+              !await adapter.retryTool({
+                toolName: decision.effect.toolName,
+                toolCallId: decision.effect.toolCallId,
+                input: decision.effect.input,
+              })
+            ) {
+              return false;
+            }
+          } catch {
+            // The governed Tool persisted its bounded error ToolResult.
+          }
+          decision = await this.materializeRecoveredToolResults(
+            submission,
+          );
+          continue;
+        }
+        case "schedule-continuation":
+          await this.approvals.dispatchContinuation(
+            submission,
+            decision.effect.approvalExecutionId,
+          );
+          return false;
+        case "finish":
+          await this.submissions.finish(
+            submission,
+            decision.effect.outcome,
+            decision.effect.message,
+          );
+          return false;
+        case "resume-turn": {
+          const last = (await this.transcript.canonicalMessages()).at(-1);
+          return last?.role === "user" || last?.role === "toolResult";
+        }
+      }
+    }
+    throw new Error("Pi recovery plan did not converge");
+  }
+
+  // #endregion
+
+  // #region Turn 执行、流式记录与完成投影
+
+  private async activateQueuedSubmission(
+    submission: StoredSubmission,
+  ): Promise<StoredSubmission> {
+    if (!submission.queuedInputJson) {
+      this.db.submissions.transition(
+        submission.submissionId,
+        "running",
+        ["pending"],
+      );
+      const activated = this.readSubmission(submission.submissionId)!;
+      await this.broadcastApprovals();
+      return activated;
+    }
+
+    const userMessage = JSON.parse(
+      submission.queuedInputJson,
+    ) as PiCanonicalUserInput;
+    if (
+      userMessage?.role !== "user" ||
+      typeof userMessage.timestamp !== "number" ||
+      !submission.userMessageId
+    ) {
+      throw new Error("Queued Pi user message is invalid");
+    }
+    const uiMessage = submission.queuedUiMessageJson
+      ? JSON.parse(submission.queuedUiMessageJson) as UIMessage & {
+          role: "user";
+        }
+      : undefined;
+    if (uiMessage && uiMessage.role !== "user") {
+      throw new Error("Queued UI user message is invalid");
+    }
+    if (submission.regenerateMessageId) {
+      const regenerateEntry = await this.transcript.findUserMessage(
+        submission.regenerateMessageId,
+      );
+      if (
+        !regenerateEntry ||
+        userContentKey(regenerateEntry) !== userContentKey(userMessage)
+      ) {
+        throw new Error(
+          "Regenerate request must match an existing user message",
+        );
+      }
+    }
+
+    const activated = this.db.transaction(() => {
+      const latest = this.readSubmission(submission.submissionId);
+      if (!latest || latest.status !== "pending") {
+        if (!latest) {
+          throw new Error(
+            `Unknown Pi submission: ${submission.submissionId}`,
+          );
+        }
+        return latest;
+      }
+      const running = this.db.submissions.findRunning();
+      if (running) {
+        throw new Error(
+          `Pi submission ${running.submissionId} is already running`,
+        );
+      }
+      if (submission.regenerateMessageId) {
+        this.transcript.moveLeaf(submission.regenerateMessageId);
+      } else {
+        const appended = this.transcript.append(
+          submission.userMessageId!,
+          userMessage,
+          {
+            submissionId: submission.submissionId,
+            createdAt: userMessage.timestamp,
+            ...(uiMessage ? { userMessage: uiMessage } : {}),
+          },
+        );
+        if (!appended) {
+          throw new Error(
+            `Pi Session message ${submission.userMessageId} already exists`,
+          );
+        }
+      }
+      if (!this.db.submissions.transition(
+        submission.submissionId,
+        "running",
+        ["pending"],
+      )) {
+        throw new Error(
+          `Pi submission ${submission.submissionId} could not activate`,
+        );
+      }
+      this.db.submissions.clearQueuedPayload(
+        submission.submissionId,
+      );
+      return this.readSubmission(submission.submissionId)!;
+    });
+    this.broadcast(json({
+      type: MessageType.CF_AGENT_CHAT_MESSAGES,
+      messages: await this.getMessages(),
+    }));
+    await this.broadcastApprovals();
+    return activated;
+  }
+
+  // 作用：执行一条 Submission，并保证任何异常都被收口为持久终态。
+  // 调用：SubmissionLifecycle 启动新提交或恢复未完提交时调用。
+  // 原因：把失败帧、可续传流和 pre-stream 清理放在最外层，避免内部分支遗留半开传输状态。
+  private async executeSubmission(
+    submissionId: string,
+    recovery = false,
+  ): Promise<StoredSubmission> {
+    const submission = this.readSubmission(submissionId);
+    if (!submission) {
+      throw new Error(`Unknown Pi submission: ${submissionId}`);
+    }
+    if (isTerminalSubmissionStatus(submission.status)) {
+      return submission;
+    }
+    if (submission.abortReason) {
+      return this.submissions.finish(
+        submission,
+        "aborted",
+        submission.abortReason,
+      );
+    }
+    if (recovery) await this.ensureRuntimeReady();
+    try {
+      return await this.executeNonTerminalSubmission(
+        submission,
+        recovery,
+      );
+    } catch (error) {
+      const failed = await this.submissions.finish(
+        submission,
+        "failed",
+        errorText(error),
+      );
+      const streamId =
+        this.streamBySubmission.get(submission.submissionId);
+      if (streamId) {
+        this.failRecoverableStream(streamId);
+      }
+      this.sendChatTerminal(
+        submission.requestId,
+        failed.status === "error"
+          ? failed.error ?? "Pi turn failed"
+          : undefined,
+      );
+      return failed;
+    } finally {
+      const streamId =
+        this.streamBySubmission.get(submission.submissionId);
+      if (streamId) {
+        this.streamBySubmission.delete(submission.submissionId);
+      }
+      this.settlePreStream(submission.requestId);
+    }
+  }
+
+  // 作用：运行一条未结束 Submission 的完整 Pi Turn。
+  // 调用：外层 `executeSubmission` 确认记录存在且未终态后调用。
+  // 原因：恢复补全、状态迁移、fiber、流式记录与终态投影必须保持固定顺序，否则唤醒后会重复执行或丢失回答。
+  private async executeNonTerminalSubmission(
+    submission: StoredSubmission,
+    recovery: boolean,
+  ): Promise<StoredSubmission> {
+    const submissionId = submission.submissionId;
+    if (submission.abortReason) {
+      return this.submissions.finish(
+        submission,
+        "aborted",
+        submission.abortReason,
+      );
+    }
+    submission = await this.pinSubmissionAssembly(submission);
+    await this.assertPinnedSubmission(submission);
+    if (submission.status === "pending" && !recovery) {
+      submission = await this.activateQueuedSubmission(submission);
+    }
+    const recoveryAdapter = this.createSubmissionExecutionAdapter(submission);
+    if (recovery) {
+      const ready = await this.prepareRecoveredTurn(
+        submission,
+        recoveryAdapter,
+      );
+      if (!ready) return this.readSubmission(submissionId)!;
+    } else {
+      await this.materializeRecoveredToolResults(submission);
+    }
+
+    const ready = this.readSubmission(submissionId);
+    if (!ready) {
+      throw new Error(`Unknown Pi submission: ${submissionId}`);
+    }
+    if (isTerminalSubmissionStatus(ready.status)) return ready;
+    if (ready.abortReason) {
+      return this.submissions.finish(
+        ready,
+        "aborted",
+        ready.abortReason,
+      );
+    }
+    if (ready.status === "pending") {
+      this.db.submissions.transition(submissionId, "running", ["pending"]);
+    }
+    const storedMessages = await this.transcript.storedMessages();
+    const assistantOrdinal = storedMessages.filter(
+      (entry) =>
+        entry.submissionId === submissionId &&
+        entry.message.role === "assistant",
+    ).length;
+    let terminalIntent:
+      | {
+          outcome: "succeeded" | "failed" | "aborted";
+          message?: string;
+        }
+      | undefined;
+    const startedAt = ready.createdAt;
+    let turn!: ActiveTurn;
+    const adapter = this.createSubmissionExecutionAdapter(submission, {
+      startedAt,
+      continuation: recovery,
+      assistantOrdinal,
+      onRecord: (record) =>
+        this.persistAndBroadcastRecord(turn, record),
+      onTerminal: (intent) => {
+        terminalIntent = intent;
+        this.appendTerminalIntent(
+          submission,
+          intent.outcome,
+          intent.message,
+        );
+      },
+    });
+    for (const pending of this.db.steers.listForSubmission(submissionId)) {
+      const message = JSON.parse(
+        pending.canonicalJson,
+      ) as PiCanonicalUserInput;
+      if (message?.role !== "user") {
+        throw new Error(`Pending steer ${pending.steerId} is invalid`);
+      }
+      adapter.steer(message, pending.messageId);
+    }
+    turn = {
+      submissionId,
+      requestId: submission.requestId,
+      messageId: submission.assistantMessageId,
+      startedAt,
+      continuation: recovery,
+      agent: adapter,
+    };
+    let streamId: string | undefined;
+
+    const deactivate = this.submissions.activate(submission, turn);
+    await this.broadcastApprovals();
+    try {
+      await this.runRecoverableChatFiber(
+        {
+          requestId: submission.requestId,
+          messageId: submission.assistantMessageId,
+          continuation: recovery,
+          messages: await this.transcript.snapshotMessages(),
+          recoveryData: {
+            submissionId,
+            requestId: submission.requestId,
+          },
+        },
+        async (_fiber, activeStreamId) => {
+          streamId = activeStreamId;
+          this.streamBySubmission.set(submissionId, streamId);
+          try {
+            await adapter.run({});
+          } finally {
+            this.streamBySubmission.delete(submissionId);
+          }
+        },
+      );
+      const intent = terminalIntent ?? {
+        outcome: "failed" as const,
+        message:
+          "Pi turn ended without an authoritative assistant message",
+      };
+      const terminal = await this.submissions.finish(
+        submission,
+        intent.outcome,
+        intent.message,
+      );
+      if (streamId) this.settleRecoverableStream(streamId, terminal);
+      await this.projectTerminal(turn, terminal);
+      return terminal;
+    } catch (error) {
+      const latest = this.readSubmission(submissionId);
+      const intent = terminalIntent ?? {
+        outcome: latest?.abortReason
+          ? ("aborted" as const)
+          : ("failed" as const),
+        message: errorText(error),
+      };
+      const failed = await this.submissions.finish(
+        submission,
+        intent.outcome,
+        intent.message,
+      );
+      if (streamId) this.settleRecoverableStream(streamId, failed);
+      await this.projectTerminal(turn, failed);
+      return failed;
+    } finally {
+      deactivate();
+    }
+  }
+
+  private settleRecoverableStream(
+    streamId: string,
+    submission: StoredSubmission,
+  ): void {
+    if (
+      submission.status === "completed" ||
+      (submission.status === "aborted" &&
+        submission.error === USER_STOP_REASON)
+    ) {
+      this.completeRecoverableStream(streamId);
+    } else {
+      this.failRecoverableStream(streamId);
+    }
+  }
+
+  // 作用：先持久化一条 Pi 流记录，再广播给在线客户端。
+  // 调用：活跃 Turn 适配器每产生一条 stream record 时调用。
+  // 原因：耐久写入早于 WebSocket 发送，断线客户端才能从同一序列续传。
+  private async persistAndBroadcastRecord(
+    turn: ActiveTurn,
+    chunk: UIMessageChunk,
+  ): Promise<void> {
+    const streamId = this.streamBySubmission.get(turn.submissionId);
+    const body = json(chunk);
+    if (streamId) {
+      await this.appendRecoverableChunk(streamId, body);
+    }
+    this.sendChatResponse(turn.requestId, body, false);
+  }
+
+  private sendChatTerminal(requestId: string, error?: string): void {
+    this.sendChatResponse(
+      requestId,
+      error
+        ? json({ type: "error", errorText: error } satisfies UIMessageChunk)
+        : "",
+      true,
+    );
+  }
+
+  // 作用：把已提交的 Submission 终态投影到聊天协议、审批状态和可选业务事件。
+  // 调用：非终态 Turn 成功收尾且可续传流已标记完成后调用。
+  // 原因：Submission 是权威状态，其他都是后续投影；业务投影失败只降级记录，不能推翻已完成 Turn。
+  private async projectTerminal(
+    turn: ActiveTurn,
+    submission: StoredSubmission,
+  ): Promise<void> {
+    this.sendChatTerminal(
+      turn.requestId,
+      submission.status === "error"
+        ? submission.error ?? "Pi turn failed"
+        : undefined,
+    );
+    const messages = await this.getMessages();
+    await this.broadcastApprovals(
+      submission.status === "completed" &&
+          submissionNeedsInput(messages, submission.assistantMessageId)
+        ? "needs-input"
+        : "idle",
+    );
+    this.broadcast(
+      json({
+        type: MessageType.CF_AGENT_CHAT_MESSAGES,
+        messages,
+      }),
+    );
+    const events = this.assembly().bindings.turnEvents;
+    if (events) {
+      try {
+        await events.onResponse(
+          messages.flatMap((message) =>
+            message.role === "user" || message.role === "assistant"
+              ? [
+                  {
+                    role: message.role,
+                    text: message.parts
+                      .filter(
+                        (
+                          part,
+                        ): part is Extract<UIMessage["parts"][number], { type: "text" }> =>
+                          part.type === "text",
+                      )
+                      .map((part) => part.text)
+                      .join(""),
+                  },
+                ]
+              : [],
+          ),
+        );
+      } catch (error) {
+        console.warn(
+          "[runtime-turn-projection:degraded]",
+          json({ error: errorText(error) }),
+        );
+      }
+      try {
+        if (
+          submission.status === "completed" ||
+          submission.status === "aborted" ||
+          submission.status === "skipped" ||
+          submission.status === "error"
+        ) {
+          await events.onSubmissionTerminal?.({
+            submissionId: submission.submissionId,
+            status: submission.status,
+            ...(submission.error ? { error: submission.error } : {}),
+            resultMessageId: submission.assistantMessageId,
+          });
+        }
+      } catch (error) {
+        console.warn(
+          "[runtime-terminal-projection:degraded]",
+          json({ error: errorText(error) }),
+        );
+      }
+    }
+  }
+
+  // #endregion
+
+  // #region Cloudflare Agent 通信生命周期
+
+  /**
+   * 在新 WebSocket 建立后向该连接发送当前聊天快照。
+   *
+   * @remarks
+   * Cloudflare Agents SDK 为每条新 WebSocket 连接调用。
+   *
+   * 先发送 transcript，再让恢复基类通知正在续传的流，
+   * 使普通历史和恢复握手保持各自的协议帧。
+   */
+  async onConnect(connection: Connection): Promise<void> {
+    sendIfOpen(
+      connection,
+      json({
+        type: MessageType.CF_AGENT_CHAT_MESSAGES,
+        messages: await this.getMessages(),
+      }),
+    );
+    await super.onConnect(connection);
+  }
+
+  /**
+   * 处理直接发给 Agent 实例的 HTTP 请求。
+   *
+   * @remarks
+   * Cloudflare Agents SDK 在每个非 WebSocket HTTP 请求到达时调用。
+   *
+   * Kernel 只拦截 `get-messages` 读取口，其余路由基类处理，
+   * 避免在这里复制 Agents SDK 的默认协议行为。
+   */
+  async onRequest(request: Request): Promise<Response> {
+    if (new URL(request.url).pathname.endsWith("/get-messages")) {
+      return Response.json(await this.getMessages());
+    }
+    return super.onRequest(request);
+  }
+
+  /**
+   * 验证并处理一条来自聊天 WebSocket 的协议消息。
+   *
+   * @remarks
+   * Cloudflare Agents SDK 在已连接 WebSocket 收到消息时调用。
+   *
+   * 提交、取消、清空、续传和 Tool 审批都在这一信任边界先验证再分流，
+   * 这样领域层不会接到半解析的客户端输入。
+   */
+  async onMessage(
+    connection: Connection,
+    raw: string | ArrayBuffer,
+  ): Promise<void> {
+    if (typeof raw !== "string") return;
+    const event = parseProtocolMessage(raw);
+    if (!event) return;
+
+    if (event.type === "chat-request") {
+      let body: UIChatRequestBody;
+      try {
+        body = JSON.parse(
+          String(event.init.body ?? "{}"),
+        ) as UIChatRequestBody;
+      } catch {
+        this.sendChatTerminal(event.id, "Chat request body is invalid JSON");
+        return;
+      }
+      const latest = Array.isArray(body.messages)
+        ? [...body.messages].reverse().find(
+            (message): message is UIMessage & { role: "user" } =>
+              message?.role === "user",
+          )
+        : undefined;
+      if (
+        !latest ||
+        latest.role !== "user" ||
+        typeof latest.id !== "string" ||
+        !Array.isArray(latest.parts) ||
+        !latest.parts.every((part) => {
+          if (part === null || typeof part !== "object") return false;
+          return part.type === "text"
+            ? typeof part.text === "string"
+            : part.type === "file" &&
+              typeof part.mediaType === "string" &&
+              typeof part.url === "string" &&
+              (part.filename === undefined || typeof part.filename === "string");
+        }) ||
+        (body.trigger !== "submit-message" &&
+          body.trigger !== "regenerate-message")
+      ) {
+        this.sendChatTerminal(event.id, "Chat request user message is invalid");
+        return;
+      }
+      let submitted: Awaited<
+        ReturnType<AgentRuntimeKernel["submitMessage"]>
+      >;
+      try {
+        const normalized = this.pi.normalizeUserInput(latest);
+        submitted = await this.submitMessage(normalized, {
+          requestId: event.id,
+          idempotencyKey: event.id,
+          userMessageId: latest.id,
+          userMessage: latest,
+          regenerate: body.trigger === "regenerate-message",
+        });
+      } catch (error) {
+        this.sendChatTerminal(event.id, errorText(error));
+        return;
+      }
+      if (submitted.receipt.accepted) {
+        this.beginPreStream(event.id);
+      }
+      await submitted.completion;
+      return;
+    }
+
+    if (event.type === "cancel") {
+      const submission = this.findSubmissionByRequest(event.id);
+      if (submission) {
+        await this.cancelSubmissionById(
+          submission.submissionId,
+          "Client cancelled",
+        );
+      }
+      return;
+    }
+
+    if (event.type === "clear") {
+      if (this.submissions.isBusy()) return;
+      this.db.transaction(() => {
+        this.transcript.clear();
+        this.db.clearAll();
+        this.clearRecoverableStreamStorage();
+      });
+      this.clearRecoverableChatState();
+      await this.broadcastApprovals();
+      this.broadcast(json({ type: MessageType.CF_AGENT_CHAT_CLEAR }));
+      return;
+    }
+
+    if (event.type === "stream-resume-request") {
+      await this.handleResumeRequest(
+        connection,
+        event.probeId,
+      );
+      return;
+    }
+
+    if (event.type === "stream-resume-ack") {
+      await this.handleResumeAck(
+        connection,
+        event.id,
+      );
+      return;
+    }
+
+    if (event.type === "tool-approval") {
+      const executionId = this.approvals.findPendingExecution(
+        event.toolCallId,
+      );
+      if (!executionId) return;
+      await this.decideApproval(
+        executionId,
+        event.approved
+          ? { decision: "allow_once" }
+          : { decision: "deny", reason: "User denied the Tool" },
+      );
+    }
+  }
+
+  /**
+   * 返回当前 canonical transcript 的浏览器投影。
+   *
+   * @remarks
+   * 新连接、HTTP 读取、Turn 完成投影和 RPC 调用方需要消息快照时调用。
+   *
+   * 统一从 transcript 生成完整视图；活跃 assistant 也必须随首帧恢复，后续流按相同消息 ID 接管。
+   */
+  async getMessages(): Promise<UIMessage[]> {
+    return this.transcript.browserMessages();
+  }
+
+  // #endregion
+
+  // #region Runtime Extension Host 回环端口
+
+  // 作用：代表扩展从当前 Runtime Workspace 读取文件。
+  // 调用：已获文件读权限的 HostBridgeLoopback 在处理扩展请求时调用。
+  // 原因：扩展只经过已裁剪的 Host 端口访问工作区，不直接持有平台绑定。
+  private async runtimeWorkspace() {
+    await this.ensureRuntimeReady();
+    const workspace = this.assembly().bindings.workspace;
+    if (!workspace) throw new Error("Runtime Workspace is unavailable");
+    return workspace;
+  }
+
+  async _hostReadFile(path: string): Promise<string | null> {
+    return (await this.runtimeWorkspace()).readFile(path);
+  }
+
+  // 作用：代表扩展把文本写入当前 Runtime Workspace。
+  // 调用：已获文件写权限的 HostBridgeLoopback 在处理扩展请求时调用。
+  // 原因：统一在 Session 边界检查 Workspace 是否可用，避免扩展自行解析平台能力。
+  async _hostWriteFile(
+    path: string,
+    content: string,
+  ): Promise<void> {
+    await (await this.runtimeWorkspace()).writeFile(path, content);
+  }
+
+  // 作用：代表扩展删除当前 Runtime Workspace 中的路径。
+  // 调用：已获文件删除权限的 HostBridgeLoopback 在处理扩展请求时调用。
+  // 原因：Host 契约用布尔值表示删除结果，所以 Workspace 抛错在这一边界被收窄为 `false`。
+  async _hostDeleteFile(path: string): Promise<boolean> {
+    const workspace = await this.runtimeWorkspace();
+    try {
+      await workspace.rm(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // 作用：代表扩展列出当前 Runtime Workspace 目录。
+  // 调用：已获目录读权限的 HostBridgeLoopback 在处理扩展请求时调用。
+  // 原因：只投影稳定的名称、类型、大小和路径，不把 Workspace 的内部目录对象泄漏给扩展。
+  async _hostListFiles(
+    dir: string,
+  ): Promise<
+    Array<{ name: string; type: string; size: number; path: string }>
+  > {
+    const workspace = await this.runtimeWorkspace();
+    return (await workspace.readDir(dir)).map((entry) => ({
+      name: entry.name,
+      type: entry.type,
+      size: entry.size,
+      path: entry.path,
+    }));
+  }
+
+  // 作用：读取一份按 label 保存的 Runtime Extension Context。
+  // 调用：已获对应 label 读权限的 HostBridgeLoopback 在扩展运行期调用。
+  // 原因：Context 与 Durable Object 共享 SQLite 持久性，唤醒后不需要从扩展重建。
+  async _hostGetContext(label: string): Promise<string | null> {
+    return this.db.extContext.get(label) ?? null;
+  }
+
+  // 作用：按 label 写入一份 Runtime Extension Context。
+  // 调用：已获对应 label 写权限的 HostBridgeLoopback 在扩展运行期调用。
+  // 原因：由 Host 集中选择持久存储，扩展不必获得任意 SQL 访问权。
+  async _hostSetContext(
+    label: string,
+    content: string,
+  ): Promise<void> {
+    this.db.extContext.set(label, content);
+  }
+
+  // 作用：为扩展返回精简的 Session 消息历史。
+  // 调用：已获消息读权限的 HostBridgeLoopback 按需传入数量上限时调用。
+  // 原因：使用 transcript 的 Host 投影，避免把 Pi 专用 part 和持久化细节暴露给扩展。
+  async _hostGetMessages(
+    limit?: number,
+  ): Promise<
+    Array<{ id: string; role: string; content: string }>
+  > {
+    return this.transcript.hostMessages(limit);
+  }
+
+  // 作用：把扩展生成的文本作为用户消息送入当前 Session。
+  // 调用：已获消息写权限的 HostBridgeLoopback 在扩展需要追加或 steer 时调用。
+  // 原因：有活跃 Turn 时交给它的 adapter steer，空闲时才直接写 transcript，从而保持单一执行流。
+  async _hostSendMessage(content: string): Promise<void> {
+    if (typeof content !== "string" || content.trim().length === 0) {
+      throw new Error("Extension message content is required");
+    }
+    const message: PiCanonicalUserInput = {
+      role: "user",
+      content: [{ type: "text", text: content }],
+      timestamp: Date.now(),
+    };
+    const active = this.submissions.currentActive();
+    if (active) {
+      const messageId = crypto.randomUUID();
+      this.db.transaction(() => {
+        this.db.steers.insert({
+          steerId: crypto.randomUUID(),
+          submissionId: active.submissionId,
+          messageId,
+          canonicalJson: json(message),
+          uiMessageJson: null,
+          createdAt: message.timestamp,
+        });
+      });
+      active.agent.steer(message, messageId);
+      await this.broadcastApprovals();
+      return;
+    }
+    this.transcript.append(crypto.randomUUID(), message, {
+      createdAt: message.timestamp,
+    });
+  }
+
+  // 作用：返回扩展可见的当前 Session 摘要。
+  // 调用：HostBridgeLoopback 在扩展请求 Session 信息时调用。
+  // 原因：先只提供真实需要的消息数，不暴露 Durable Object 身份或数据库结构。
+  async _hostGetSessionInfo(): Promise<{ messageCount: number }> {
+    return {
+      messageCount: (await this._hostGetMessages()).length,
+    };
+  }
+
+  // #endregion
+
+  // #region Session 消息与 Submission 公开控制面
+
+  /**
+   * 把一组已有消息导入当前 canonical transcript。
+   *
+   * @remarks
+   * Inbox 只在真实 fork 或 import 会话历史时调用。
+   *
+   * 导入统一交给 transcript 并传入当前模型，
+   * 避免外部调用方自行拼接 Pi 的持久化形式。
+   */
+  async getCanonicalSnapshot(
+    throughMessageId: string,
+  ): Promise<PiCanonicalTranscriptSnapshot> {
+    return this.transcript.exportSnapshot(throughMessageId);
+  }
+
+  async addCanonicalSnapshot(
+    snapshot: PiCanonicalTranscriptSnapshot,
+  ): Promise<void> {
+    this.transcript.importSnapshot(snapshot);
+  }
+
+  // 作用：把一段纯文本包装成标准用户消息并提交。
+  // 调用：公开 `submitPrompt` 为 RPC 调用创建 request ID 时调用。
+  // 原因：RPC 只需提供文本，内部仍走与 WebSocket 相同的 canonical admission。
+  private submitText(
+    text: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<SubmissionHandle<StoredSubmission>> {
+    const requestId = crypto.randomUUID();
+    const userMessage: PiCanonicalUserInput = {
+      role: "user",
+      content: [{ type: "text", text }],
+      timestamp: Date.now(),
+    };
+    return this.submitMessage(userMessage, {
+      requestId,
+      idempotencyKey: options?.idempotencyKey,
+    });
+  }
+
+  /**
+   * 可靠提交一段用户文本，并立即返回可查询回执。
+   *
+   * @remarks
+   * Inbox、子任务或其他 RPC 调用方需要启动新 Turn 时调用。
+   *
+   * 接口不等待模型完成，而是把同一 completion 留给 Durable Object 继续处理，
+   * 调用方用 Submission ID 查询状态。
+   */
+  async submitPrompt(
+    text: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<SubmissionReceipt> {
+    const submitted = await this.submitText(text, options);
+    this.ctx.waitUntil(submitted.completion);
+    return submitted.receipt;
+  }
+
+  async dispatchMessage(
+    message: UIMessage,
+    delivery: MessageDelivery,
+  ): Promise<MessageDispatchReceipt> {
+    if (
+      message.role !== "user" ||
+      !message.id ||
+      !Array.isArray(message.parts) ||
+      (delivery !== "steer" && delivery !== "enqueue")
+    ) {
+      return {
+        kind: "rejected",
+        code: "invalid_message",
+        message: "A valid user message is required",
+      };
+    }
+
+    const userMessage = this.pi.normalizeUserInput(
+      message as UIMessage & { role: "user" },
+    );
+    if (delivery === "steer") {
+      const active = this.submissions.currentActive();
+      const target = active ??
+        this.db.submissions.findRunning() ??
+        this.db.submissions.findNextPending();
+      if (target) {
+        if (
+          this.db.approvals.listPendingForSubmission(
+            target.submissionId,
+          ).length > 0
+        ) {
+          return {
+            kind: "rejected",
+            code: "not_steerable",
+            message: "The current Turn is waiting for approval",
+          };
+        }
+        const inserted = this.db.transaction(() => {
+          if (this.db.steers.findByMessageId(message.id)) return false;
+          this.db.steers.insert({
+            steerId: crypto.randomUUID(),
+            submissionId: target.submissionId,
+            messageId: message.id,
+            canonicalJson: json(userMessage),
+            uiMessageJson: json(message),
+            createdAt: userMessage.timestamp,
+          });
+          return true;
+        });
+        if (inserted) {
+          if (active?.submissionId === target.submissionId) {
+            active.agent.steer(userMessage, message.id);
+          }
+          await this.broadcastApprovals();
+        }
+        return {
+          kind: "accepted",
+          submissionId: target.submissionId,
+          messageId: message.id,
+        };
+      }
+    }
+
+    try {
+      const submitted = await this.submitMessage(userMessage, {
+        requestId: message.id,
+        idempotencyKey: message.id,
+        userMessageId: message.id,
+        userMessage: message as UIMessage & { role: "user" },
+      });
+      this.ctx.waitUntil(submitted.completion);
+      const position = this.db.submissions.listPending()
+        .findIndex((item) =>
+          item.submissionId === submitted.receipt.submissionId
+        ) + 1;
+      return position > 0
+        ? {
+            kind: "queued",
+            submission: submitted.receipt,
+            position,
+          }
+        : {
+            kind: "accepted",
+            submissionId: submitted.receipt.submissionId,
+            messageId: message.id,
+          };
+    } catch (error) {
+      if (error instanceof SubmissionQueueFullError) {
+        return {
+          kind: "rejected",
+          code: "queue_full",
+          message: error.message,
+        };
+      }
+      throw error;
+    }
+  }
+
+  async steerQueuedSubmission(
+    submissionId: string,
+  ): Promise<MessageDispatchReceipt> {
+    const active = this.submissions.currentActive();
+    const target = active ??
+      this.db.submissions.findRunning() ??
+      this.db.submissions.findNextPending();
+    if (
+      !target ||
+      this.db.approvals.listPendingForSubmission(
+        target.submissionId,
+      ).length > 0
+    ) {
+      return {
+        kind: "rejected",
+        code: "not_steerable",
+        message: "The current Turn is not accepting steering",
+      };
+    }
+
+    const queued = this.readSubmission(submissionId);
+    if (
+      !queued ||
+      queued.submissionId === target.submissionId ||
+      queued.status !== "pending" ||
+      !queued.queuedInputJson ||
+      !queued.userMessageId
+    ) {
+      return {
+        kind: "rejected",
+        code: "invalid_message",
+        message: "The queued message is no longer available",
+      };
+    }
+    const message = JSON.parse(
+      queued.queuedInputJson,
+    ) as PiCanonicalUserInput;
+    if (message?.role !== "user") {
+      return {
+        kind: "rejected",
+        code: "invalid_message",
+        message: "The queued message is invalid",
+      };
+    }
+    const uiMessage = queued.queuedUiMessageJson
+      ? JSON.parse(queued.queuedUiMessageJson) as UIMessage
+      : undefined;
+    if (
+      uiMessage &&
+      (uiMessage.role !== "user" || uiMessage.id !== queued.userMessageId)
+    ) {
+      return {
+        kind: "rejected",
+        code: "invalid_message",
+        message: "The queued message is invalid",
+      };
+    }
+
+    const moved = this.db.transaction(() => {
+      const latest = this.readSubmission(submissionId);
+      const current = this.db.submissions.findRunning() ??
+        this.db.submissions.findNextPending();
+      if (
+        !latest ||
+        latest.status !== "pending" ||
+        current?.submissionId !== target.submissionId ||
+        this.db.steers.findByMessageId(queued.userMessageId!)
+      ) {
+        return false;
+      }
+      this.db.steers.insert({
+        steerId: crypto.randomUUID(),
+        submissionId: target.submissionId,
+        messageId: queued.userMessageId!,
+        canonicalJson: queued.queuedInputJson!,
+        uiMessageJson: queued.queuedUiMessageJson ?? null,
+        createdAt: queued.createdAt,
+      });
+      const reason = "Moved to active Turn";
+      this.appendTerminalIntent(latest, "aborted", reason);
+      this.db.submissions.updateAbortReason(submissionId, reason);
+      this.updateSubmission(submissionId, "aborted", reason);
+      return true;
+    });
+    if (!moved) {
+      return {
+        kind: "rejected",
+        code: "invalid_message",
+        message: "The queued message is no longer available",
+      };
+    }
+
+    try {
+      if (active?.submissionId === target.submissionId) {
+        active.agent.steer(message, queued.userMessageId);
+      }
+    } finally {
+      await this.broadcastApprovals();
+    }
+    return {
+      kind: "steered",
+      submissionId: target.submissionId,
+      messageId: queued.userMessageId,
+      ...(uiMessage ? { message: uiMessage } : {}),
+    };
+  }
+
+  /**
+   * 等待 Session 稳定后提交定时提示，并在准入后立即返回。
+   *
+   * @remarks
+   * Agent 定时回调在不应与人工 Turn 并发时调用。
+   *
+   * 最多等待固定的稳定窗口；超时返回 skipped，
+   * 避免定时任务无限占住调用链。
+   */
+  async submitScheduledPrompt(
+    prompt: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<SubmissionReceipt> {
+    const requestId = crypto.randomUUID();
+    const submitted = await this.submitMessageWhenStable(
+      {
+        role: "user",
+        content: [{ type: "text", text: prompt }],
+        timestamp: Date.now(),
+      },
+      {
+        requestId,
+        idempotencyKey: options?.idempotencyKey,
+      },
+      SCHEDULED_STABLE_TIMEOUT_MS,
+    );
+    if (!submitted) {
+      return {
+        submissionId: crypto.randomUUID(),
+        status: "skipped",
+        accepted: false,
+        error: "Runtime not stable within timeout",
+        createdAt: Date.now(),
+      };
+    }
+    this.ctx.waitUntil(submitted.completion.then(() => undefined));
+    return submitted.receipt;
+  }
+
+  /**
+   * 按 Submission ID 读取当前回执。
+   *
+   * @remarks
+   * 提交后的 RPC 调用方用它轮询或核对终态。
+   *
+   * 直接读取 SubmissionLifecycle 的持久存储，不用内存执行状态猜测结果。
+   */
+  async getSubmission(
+    submissionId: string,
+  ): Promise<SubmissionReceipt | null> {
+    return this.submissions.get(submissionId);
+  }
+
+  /**
+   * 取消一条指定 Submission。
+   *
+   * @remarks
+   * Inbox 或调度清理路径在已知 Submission ID 时调用。
+   *
+   * 取消交给 SubmissionLifecycle 先持久化 abort intent 再停活跃 adapter，
+   * 避免重启后丢失取消决定。
+   */
+  async cancelSubmissionById(
+    submissionId: string,
+    reason?: string,
+  ): Promise<{ ok: boolean }> {
+    const result = await this.submissions.cancel(
+      submissionId,
+      reason ?? "Cancelled",
+    );
+    await this.broadcastApprovals();
+    return result;
+  }
+
+  /**
+   * 按 request ID 停止 Turn，未给 ID 时停止所有未完成提交。
+   *
+   * @remarks
+   * Inbox 的停止控制面或 Agent 内部清理在传输请求结束前调用。
+   *
+   * 复用 SubmissionLifecycle 的批量选择与取消语义，
+   * 避免再从活跃 Pi adapter 反向推断持久记录。
+   */
+  async stopTurn(
+    requestId?: string,
+    reason?: string,
+  ): Promise<{ ok: boolean }> {
+    const result = await this.submissions.stop(
+      requestId,
+      reason ?? "Stopped",
+    );
+    await this.broadcastApprovals();
+    return result;
+  }
+
+  /** 返回当前已装配 User Agent 的执行档位，不提供 Session 覆盖。 */
+  executionLevel(): ExecutionLevel {
+    return this.assembly().profile.executionLevel;
+  }
+
+  /**
+   * 读取一条仍待决定的 Tool 或临时 Agent 执行。
+   *
+   * @remarks
+   * Host 在处理 `allow_level` 前读取可信的 Tool 所需档位，客户端不能提交目标档位。
+   */
+  getPendingApproval(executionId: string): ApprovalReceipt | null {
+    const temporary = this.temporaryAgentApprovals.get(executionId);
+    if (temporary) return temporary.receipt;
+    const approval = this.approvals.read(executionId);
+    if (!approval || approval.status !== "pending") return null;
+    return {
+      executionId: approval.executionId,
+      source: approval.source,
+      action: approval.toolName,
+      summary: approval.summary,
+      executionLevel: approval.executionLevel,
+      requiredExecutionLevel: approval.requiredExecutionLevel,
+      inputJson: approval.inputJson,
+      requestId: approval.requestId,
+    };
+  }
+
+  /**
+   * 对一条待处理执行应用一次允许或拒绝决定。
+   *
+   * @remarks
+   * `allow_level` 必须由 Host 先更新 User Agent，再以 `allow_once` 续跑当前固定 Turn。
+   */
+  async decideApproval(
+    executionId: string,
+    decision: ApprovalDecision,
+  ): Promise<{ ok: boolean }> {
+    if (decision.decision === "allow_level") {
+      throw new Error(
+        "allow_level must be applied by the User Agent Host before resuming the Tool",
+      );
+    }
+    const temporary = this.temporaryAgentApprovals.get(executionId);
+    if (temporary) {
+      this.temporaryAgentApprovals.delete(executionId);
+      temporary.resolve(
+        decision.decision === "allow_once"
+          ? { approved: true }
+          : { approved: false, reason: decision.reason },
+      );
+      await this.broadcastApprovals();
+      return { ok: true };
+    }
+    return this.approvals.decide(executionId, decision);
+  }
+
+  // 作用：在用户做出持久 Tool 审批决定后续跑对应 Submission。
+  // 调用：Cloudflare Agents SDK 按 `schedule` 保存的回调名唤醒 Agent 时调用。
+  // 原因：审批等待可跨 Durable Object 休眠，因此续跑必须重读持久决定、去重 Tool 结果并重进恢复入口。
+  async _piApprovalContinuation(
+    data?: ApprovalContinuationData,
+  ): Promise<void> {
+    if (!data?.submissionId || !data.approvalExecutionId) return;
+    const submission = this.readSubmission(data.submissionId);
+    if (!submission || isTerminalSubmissionStatus(submission.status)) {
+      return;
+    }
+    const approval = this.approvals.read(data.approvalExecutionId);
+    if (!approval) {
+      await this.submissions.finish(
+        submission,
+        "failed",
+        `Approval continuation is missing: ${data.approvalExecutionId}`,
+      );
+      return;
+    }
+    await this.ensureRuntimeReady();
+    try {
+      await this.assertPinnedSubmission(submission);
+      let decision = await this.materializeRecoveredToolResults(
+        submission,
+      );
+      if (approval.status === "approved") {
+        const settled = this.readToolSettlement(
+          submission.submissionId,
+          approval.toolCallId,
+        );
+        if (!settled) {
+          const adapter = this.createSubmissionExecutionAdapter(submission);
+          let available = true;
+          try {
+            available = await adapter.retryTool({
+              toolName: approval.toolName,
+              toolCallId: approval.toolCallId,
+              input: JSON.parse(approval.inputJson),
+            });
+          } catch {
+            // The governed Tool persisted its bounded error ToolResult.
+          }
+          if (!available) {
+            throw new Error(
+              `Approved Tool is denied: ${approval.toolName}`,
+            );
+          }
+          if (!this.readToolSettlement(
+            submission.submissionId,
+            approval.toolCallId,
+          )) {
+            throw new Error(
+              `Approved Tool produced no durable settlement: ${approval.toolName}`,
+            );
+          }
+        }
+        decision = await this.materializeRecoveredToolResults(
+          submission,
+        );
+      }
+      if (approval.status === "rejected") {
+        decision = await this.materializeRecoveredToolResults(
+          submission,
+        );
+      }
+      const result = decision.recoveredToolSettlements.find(
+        (item) => item.toolCallId === approval.toolCallId,
+      );
+      if (!result) {
+        throw new Error(
+          `Approval continuation has no ToolResult: ${approval.toolCallId}`,
+        );
+      }
+      await this.submissions.recover(submission.submissionId);
+    } catch (error) {
+      await this.submissions.finish(
+        submission,
+        "failed",
+        errorText(error),
+      );
+    }
+  }
+
+  // 作用：把审批、队列和 Session 活动投影到 Agent 可广播状态。
+  // 调用：启动、准入、审批变化和 Turn 完成时调用。
+  // 原因：这些都是可重建的 UI 投影，相同内容不重复 `setState`，投影失败也不能阻断执行。
+  private async broadcastApprovals(
+    inactiveActivity?: RuntimeActivity,
+  ): Promise<void> {
+    try {
+      const approvals = [
+        ...this.approvals.list(),
+        ...[...this.temporaryAgentApprovals.values()].map(
+          ({ receipt }) => receipt,
+        ),
+      ];
+      const running = this.db.submissions.findRunning();
+      const pending = this.db.submissions.listPending();
+      const current = running ?? pending[0];
+      const queued = (running ? pending : pending.slice(1)).map(
+        (submission, index) => {
+          let preview = "Queued message";
+          if (submission.queuedInputJson) {
+            try {
+              const message = JSON.parse(
+                submission.queuedInputJson,
+              ) as PiCanonicalUserInput;
+              preview = (typeof message.content === "string"
+                ? message.content
+                : message.content
+                    .flatMap((part) =>
+                      part.type === "text" ? [part.text] : []
+                    )
+                    .join(" ")
+              ).trim().slice(0, 160) || preview;
+            } catch {
+              // Corrupt payload is surfaced when the queue pump activates it.
+            }
+          }
+          return {
+            submissionId: submission.submissionId,
+            messageId:
+              submission.userMessageId ?? submission.submissionId,
+            preview,
+            position: index + 1,
+            createdAt: submission.createdAt,
+          };
+        },
+      );
+      const turn: RuntimeTurnState = {
+        ...(current
+          ? { activeSubmissionId: current.submissionId }
+          : {}),
+        steerable: Boolean(
+          current &&
+          this.db.approvals.listPendingForSubmission(
+            current.submissionId,
+          ).length === 0
+        ),
+        hasPendingSteer: Boolean(
+          current &&
+          this.db.steers.listForSubmission(current.submissionId).length > 0
+        ),
+        queued,
+      };
+      const activity: RuntimeActivity = approvals.length > 0
+        ? "needs-input"
+        : current || queued.length > 0
+          ? "working"
+          : inactiveActivity ??
+            (this.state.activity?.activity === "needs-input"
+              ? "needs-input"
+              : "idle");
+      const currentActivity = this.state.activity;
+      const nextActivity = currentActivity?.activity === activity
+        ? currentActivity
+        : {
+            activity,
+            revision: (currentActivity?.revision ?? 0) + 1,
+          };
+      if (
+        this.state?.approvals === undefined ||
+        json(this.state.approvals) !== json(approvals) ||
+        json(this.state.turn) !== json(turn) ||
+        nextActivity !== currentActivity
+      ) {
+        this.setState({
+          ...this.state,
+          activity: nextActivity,
+          approvals,
+          turn,
+        });
+      }
+      const projection = this.runtimeSnapshot?.bindings.turnEvents
+        ?.onActivityChanged?.(nextActivity);
+      if (projection) {
+        this.ctx.waitUntil(
+          projection.catch(() => undefined),
+        );
+      }
+    } catch {
+      // Approval projection is best effort and must not block execution.
+    }
+  }
+
+  // #endregion
+
+}