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

package/src/adapter/cloudflare/agent.ts

@@ -0,0 +1,1539 @@
+import {
+  RuntimeTelemetryCoordinator,
+  RuntimeTurnEvents,
+} from "../../telemetry";
+import {
+  Agent,
+  type AgentToolLifecycleResult,
+  type AgentToolRunInfo,
+  type Connection,
+} from "agents";
+import {
+  MessageType,
+  clearChatTerminal,
+  parseProtocolMessage,
+  recordChatTerminal,
+  sendIfOpen,
+} from "agents/chat";
+import {
+  isTerminalSubmissionStatus,
+  SubmissionLifecycle,
+  SubmissionAdmission,
+  SubmissionDelivery,
+  SubmissionFinalizer,
+  projectSubmissionReceipt,
+  PendingSteerDelivery,
+  type StoredSubmission,
+  type SubmitMessageOptions,
+  USER_STOP_REASON,
+  type ApprovalDecision,
+  type ApprovalReceipt,
+  type MessageDelivery,
+  type MessageDispatchReceipt,
+  type SubmissionReceipt,
+  type SubmissionExecutionMode,
+  type SubmissionHandle,
+} from "../../submission";
+import type { ExecutionLevel } from "../../lib/execution-level";
+import {
+  HarnessRuntimeConfig,
+  activateRuntimeCandidate,
+  type ActiveRuntime,
+  RuntimeLoadTracker,
+  prepareRuntimeCandidate,
+  projectRuntimeAssembly,
+  type PreparedPiRuntime,
+  type RuntimeAssemblyInput,
+  type RuntimeAssemblyView,
+  type RuntimeCandidate,
+} from "../../config";
+import type {
+  RuntimeExtensionPermissions,
+} from "../../context";
+import {
+  ConversationHistory,
+  HarnessConversationBridge,
+  bindHarnessStream,
+  projectSubmissionOutcome,
+  normalizeUIUserInput,
+  requestedCapabilitiesOf,
+  projectRuntimeState,
+  type PiCanonicalTranscriptSnapshot,
+  type PiCanonicalUserInput,
+  type RuntimeState,
+  type UIChatRequestBody,
+} from "../../conversation";
+import type { UIMessage, UIMessageChunk } from "ai";
+import type {
+  AssistantMessage,
+} from "@earendil-works/pi-ai";
+import { BACKGROUND_CONTEXT } from "@earendil-works/pi-agent-core/harness/context";
+import { openCloudflareSession } from "../../session";
+import { openSessionHarness, prepareSubmissionOperation } from "../../harness";
+import type { SessionHarness } from "../../harness";
+import {
+  compileHarnessTools,
+  decodeSubagentCompletion,
+  HarnessDecisionGate,
+  HarnessHumanDecisions,
+  runtimeSubagentRunMetadata,
+  TemporaryAgentCoordinator,
+  TemporaryAgentApprovals,
+  type TemporaryAgentApprovalDecision,
+  type TemporaryAgentApprovalRequest,
+  type TemporaryAgentExecutor,
+  type TemporaryAgentRequest,
+  type TemporaryAgentRunContext,
+} from "../../tools";
+import { sha256Hex } from "../../lib/artifacts";
+import { RuntimeDatabase } from "./database";
+
+/**
+ * 本文件负责把 Cloudflare Agent 的通信与持久化能力接到 Pi Turn。
+ *
+ * @remarks
+ * 核心术语见包入口 `index.ts`。
+ */
+
+// #region Runtime 内部数据与基础工具
+
+const SCHEDULED_STABLE_TIMEOUT_MS = 30_000;
+interface ActiveTurn {
+  submissionId: string;
+  requestId: string;
+  messageId: string;
+  startedAt: number;
+  continuation: boolean;
+  /** Execution adapter — use abort()/steer() instead of touching Pi directly. */
+  agent: {
+    abort(): Promise<void>;
+    interrupt(): void;
+    steer(message: PiCanonicalUserInput, messageId: string): Promise<void>;
+  };
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function json(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+export interface ToolInteractionResponsePreparation {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly toolInput: unknown;
+  readonly response: unknown;
+}
+
+// #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 Agent<Env, RuntimeState> {
+
+  initialState: RuntimeState = {
+    runtimeLoad: { status: "idle", available: false },
+  };
+
+  protected abstract ensureRuntimeReady(): Promise<void>;
+  /** Runs only before the first pin of a newly activated Submission. */
+  protected prepareRuntimeForSubmission(_submissionId: string): Promise<void> {
+    return this.ensureRuntimeReady();
+  }
+
+  protected ensureRuntimeVersion(_runtimeKey: string): Promise<void> {
+    return this.ensureRuntimeReady();
+  }
+  protected get submissionContext() {
+    return {
+      id: this.submissions.currentActive()?.submissionId ?? this.db.submissions.findRunning()?.submissionId,
+      unfinishedIds: this.db.submissions.listUnfinishedIds(),
+    };
+  }
+
+  /** Let the Host prepare a validated client response before Tool settlement. */
+  protected prepareToolInteractionResponse(
+    input: ToolInteractionResponsePreparation,
+  ): Promise<unknown | null> {
+    return Promise.resolve(input.response);
+  }
+
+  private activeRuntime?: ActiveRuntime;
+  private telemetryCoordinator?: RuntimeTelemetryCoordinator;
+  private activeHarness?: SessionHarness<object | undefined>;
+  private piAdapter?: HarnessRuntimeConfig;
+  private readonly transcript: ConversationHistory;
+  private conversationBridge?: HarnessConversationBridge;
+  private readonly submissions: SubmissionLifecycle<
+    StoredSubmission,
+    ActiveTurn
+  >;
+  private runtimeLoadTracker?: RuntimeLoadTracker;
+  private turnEventCoordinator?: RuntimeTurnEvents;
+  private db!: RuntimeDatabase;
+  private readonly temporaryAgents = new TemporaryAgentCoordinator();
+  private submissionAdmission?: SubmissionAdmission;
+  private submissionDelivery?: SubmissionDelivery;
+  private submissionFinalizer?: SubmissionFinalizer;
+  private humanDecisionCoordinator?: HarnessHumanDecisions;
+  private readonly temporaryAgentApprovals = new TemporaryAgentApprovals({
+    capture: (method, input) => this.telemetry.capture(method, input),
+    onChanged: () => this.broadcastApprovals(),
+  });
+
+  // #region 构造、装配与启动
+
+  private get pi(): HarnessRuntimeConfig {
+    return this.piAdapter ??= new HarnessRuntimeConfig();
+  }
+
+  /**
+   * Runtime 装载进度的状态机。
+   *
+   * @remarks
+   * 本类和 `defineRuntimeAgent` 生成的宿主共同驱动它：宿主管一轮尝试的起止，
+   * `initConfig` 管中途的阶段推进，因此它是 protected 而非 private。
+   *
+   * 写成惰性访问器而不是字段：本类有测试用 `Object.create(prototype)` 造替身，
+   * 那条路径既不跑构造函数也不跑字段初始化器。
+   */
+  protected get runtimeLoad(): RuntimeLoadTracker {
+    return this.runtimeLoadTracker ??= new RuntimeLoadTracker({
+      read: () => this.state.runtimeLoad,
+      publish: (runtimeLoad) => this.setState({ ...this.state, runtimeLoad }),
+      isAvailable: () => Boolean(this.activeRuntime),
+    });
+  }
+
+  private get telemetry(): RuntimeTelemetryCoordinator {
+    return this.telemetryCoordinator ??= new RuntimeTelemetryCoordinator({
+      outbox: () => this.db?.telemetry,
+      waitUntil: (promise) => this.ctx.waitUntil(promise),
+      scheduleRetry: async (delaySeconds, idempotent) => {
+        await this.schedule(
+          delaySeconds,
+          "_drainTelemetry",
+          undefined,
+          { idempotent },
+        );
+      },
+      onError: (error) => {
+        console.warn(
+          "[runtime-telemetry:degraded]",
+          json({ error: errorText(error) }),
+        );
+      },
+    });
+  }
+
+  /**
+   * 为一个 Cloudflare Durable Object 实例建立持久化与执行协作器。
+   *
+   * @remarks
+   * Cloudflare Runtime 创建由 `defineRuntimeAgent` 生成的类时，间接调用。
+   *
+   * 数据库 schema、Submission、Transcript 和 Approval 在同一构造路径绑定，
+   * 避免它们引用不同的事务边界或 Pi 适配器。
+   */
+  constructor(
+    ctx: DurableObjectState,
+    env: Env,
+    pi: HarnessRuntimeConfig = new HarnessRuntimeConfig(),
+  ) {
+    super(ctx, env);
+    this.piAdapter = pi;
+    this.db = new RuntimeDatabase(
+      this.sql.bind(this),
+      (fn) => this.ctx.storage.transactionSync(fn),
+    );
+    this.db.initializeSchema();
+    this.submissions = new SubmissionLifecycle({
+      store: this.db.submissions,
+      clearTerminal: () => clearChatTerminal(this.ctx.storage),
+      execute: (submissionId, mode) =>
+        this.executeSubmission(submissionId, mode),
+      commitTerminal: (submission, outcome, message) =>
+        this.commitTerminalOutcome(submission, outcome, message),
+      abortActive: (turn) => turn.agent.abort(),
+      abortDormant: (submission) =>
+        this.executeSubmission(submission.submissionId, "continuation")
+          .then(() => undefined),
+      interruptActive: (turn) => turn.agent.interrupt(),
+    });
+    this.transcript = new ConversationHistory(
+      this.ctx.storage,
+      {
+        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(),
+        listSessionEntrySubmissionLinks: () =>
+          this.db.submissions.listSessionEntrySubmissionLinks(),
+        findSubmissionProjection: (submissionId) =>
+          this.db.submissions.find(submissionId),
+        listApprovalViews: (submissionId) =>
+          this.db.approvals.listApprovalViews(submissionId),
+      },
+      () => this.submissions.isBusy(),
+    );
+  }
+  /** Prepare fully before replacing the active Runtime snapshot. */
+  protected async initConfig(input: RuntimeAssemblyInput): Promise<void> {
+    const candidate = await prepareRuntimeCandidate(input);
+    await this.initCandidate(candidate);
+  }
+
+  protected async initCandidate(candidate: RuntimeCandidate): Promise<void> {
+    await activateRuntimeCandidate(candidate, {
+      previous: this.activeRuntime,
+      pi: this.pi,
+      mcpHost: this,
+      sessionId: this.ctx.id.toString(),
+      createExtensionHostBinding: (permissions, labels) =>
+        this.createExtensionHostBinding(permissions, labels),
+      advance: (phase) => this.runtimeLoad.advance(phase),
+      isExecuting: () => Boolean(this.submissions.currentActive()),
+      commit: (runtime) => {
+        this.telemetry.configure(candidate.telemetry);
+        this.activeRuntime = runtime;
+      },
+    });
+  }
+
+  async _drainTelemetry(): Promise<void> {
+    await this.ensureRuntimeReady();
+    await this.telemetry.drainScheduled();
+  }
+
+  private get conversation(): HarnessConversationBridge {
+    return this.conversationBridge ??= new HarnessConversationBridge({
+      history: this.transcript,
+      send: (connection, body) => { sendIfOpen(connection, body); },
+      broadcast: (body, excluded) => this.broadcast(body, excluded),
+    });
+  }
+
+  private get humanDecisions(): HarnessHumanDecisions {
+    return this.humanDecisionCoordinator ??= new HarnessHumanDecisions({
+      approvals: this.db.approvals,
+      interactions: this.db.interactions,
+      transaction: (run) => this.db.transaction(run),
+      isSubmissionActive: (id) => {
+        const submission = this.db.submissions.find(id);
+        return Boolean(submission && !submission.abortReason && !isTerminalSubmissionStatus(submission.status));
+      },
+      telemetry: this.telemetry,
+    });
+  }
+
+  private get runtimeTurnEvents(): RuntimeTurnEvents {
+    return this.turnEventCoordinator ??= new RuntimeTurnEvents({
+      outbox: this.db.runtimeEvents,
+      transaction: (run) => this.db.transaction(run),
+      port: () => this.activeRuntime?.snapshot.bindings.turnEvents,
+      telemetry: this.telemetry,
+      waitUntil: (promise) => this.ctx.waitUntil(promise),
+      scheduleRetry: async (seconds, idempotent) => {
+        await this.schedule(seconds, "_drainRuntimeTurnEvents", undefined, { idempotent });
+      },
+    });
+  }
+
+  /** Recover entry ownership from Pi's durable operation boundary. */
+  private async associateHarnessEntries(
+    runtime: Awaited<ReturnType<typeof openSessionHarness>>,
+    submissionId: string,
+  ): Promise<void> {
+    const watch = await runtime.lane.watch(BACKGROUND_CONTEXT);
+    try {
+      this.db.transaction(() =>
+        this.db.submissions.associateSessionEntries(submissionId, watch.snapshot)
+      );
+    } finally {
+      watch.unsubscribe();
+    }
+  }
+
+  /**
+   * 在 Agent 实例启动或从休眠唤醒后恢复 Session 本地后台状态。
+   *
+   * @remarks
+   * Cloudflare Agents SDK 在任何 HTTP、WebSocket 或 RPC 调用前调用它。
+   *
+   * 先恢复审批续跑，再分类未完 Submission，
+   * 可避免把正在等待人的 Turn 当成普通中断直接重试。
+   *
+   * 待确认：Cloudflare 当前文档说 `DurableObjectState.waitUntil`
+   * 不会延长 Durable Object 生命；本文件仍在三处用它启动后台任务。
+   */
+  async onStart(): Promise<void> {
+    this.runtimeLoad.reset();
+    this.telemetry.recover(() => this.ensureRuntimeReady());
+    if (this.db.runtimeEvents.hasPending()) {
+      this.ctx.waitUntil(
+        this.ensureRuntimeReady().then(() => this.runtimeTurnEvents.drain()),
+      );
+    }
+    await this.broadcastApprovals();
+    const running = this.db.submissions.findRunning() as StoredSubmission | null;
+    if (running) {
+      if (
+        this.db.approvals.listPendingForSubmission(running.submissionId).length > 0 ||
+        this.db.interactions.listPendingForSubmission(running.submissionId).length > 0
+      ) {
+        return;
+      }
+    }
+    this.ctx.waitUntil(
+      this.submissions.recoverHead().then(() => undefined),
+    );
+  }
+
+  async _drainRuntimeTurnEvents(): Promise<void> {
+    await this.ensureRuntimeReady();
+    await this.runtimeTurnEvents.drain(false);
+  }
+
+  protected runTemporaryAgent(
+    request: TemporaryAgentRequest,
+    context: TemporaryAgentRunContext,
+    execute: TemporaryAgentExecutor,
+  ): Promise<string> {
+    const submissionId = this.db.submissions.findByRequestId(context.requestId)?.submissionId;
+    return this.temporaryAgents.run(request, execute, context.signal, submissionId
+      ? (event) => this.telemetry.temporaryAgent(submissionId, context.toolCallId, event)
+      : undefined);
+  }
+
+  /**
+   * 登记一条临时 Agent 的 Tool 审批并等待用户决定。
+   *
+   * @remarks
+   * Temporary Agent Host 在子执行需要人工授权时调用。
+   *
+   * 它与持久 Pi Tool 审批共用同一客户端投影，但只保存本次执行的 Promise，
+   * 因为临时 Agent 本身不参与 Session Turn 恢复。
+   */
+  async requestTemporaryAgentApproval(
+    request: TemporaryAgentApprovalRequest,
+  ): Promise<TemporaryAgentApprovalDecision> {
+    return this.temporaryAgentApprovals.request(
+      request,
+      this.db.submissions.findByRequestId(request.requestId)?.submissionId,
+    );
+  }
+
+  /**
+   * 取消一条仍在等待的临时 Agent 审批。
+   *
+   * @remarks
+   * Temporary Agent Host 在子执行停止或超时时调用。
+   *
+   * 先从内存表删除再解决 Promise，避免并发的批准请求再次命中已取消项。
+   */
+  async cancelTemporaryAgentApproval(
+    executionId: string,
+    reason = "temporary agent was cancelled",
+  ): Promise<{ ok: boolean }> {
+    return this.temporaryAgentApprovals.cancel(executionId, reason);
+  }
+
+  private requireRuntime(): ActiveRuntime {
+    if (!this.activeRuntime) throw new Error("Runtime must be assembled before use");
+    return this.activeRuntime;
+  }
+
+  private async normalizeUIUserInput(
+    message: UIMessage & { role: "user" },
+  ): Promise<PiCanonicalUserInput> {
+    if (requestedCapabilitiesOf(message.metadata).length > 0) await this.ensureRuntimeReady();
+    return normalizeUIUserInput(message, {
+      hasSkill: (name) => this.requireRuntime().snapshot.bindings.skills.sources
+        .some((skill) => skill.name === name),
+      hasTool: (name) => this.pi.hasTool(this.requireRuntime().pi, name),
+    });
+  }
+
+  protected readRuntimeAssembly(): RuntimeAssemblyView {
+    const runtime = this.requireRuntime();
+    return projectRuntimeAssembly(
+      runtime.snapshot,
+      runtime.revision,
+      runtime.pi,
+    );
+  }
+
+  /** Give each Extension only its authorized Host capabilities. */
+  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],
+      },
+    });
+  }
+
+  // #endregion
+
+  // #region Submission 准入与配置固定
+
+  /** Pin dynamic Context and execution policy before admission. */
+  private async admissionPin(fresh: boolean, submissionId: string): Promise<{
+    revision: string;
+    descriptor: string;
+  }> {
+    if (fresh) await this.prepareRuntimeForSubmission(submissionId);
+    else await this.ensureRuntimeReady();
+    return this.currentAssemblyPin();
+  }
+
+  // initConfig can call this inside its serialized load; re-entering ensureRuntimeReady would deadlock.
+  private async currentAssemblyPin(): Promise<{
+    revision: string;
+    descriptor: string;
+  }> {
+    await this.runtimeTurnEvents.drain();
+    const runtime = this.activeRuntime;
+    if (!runtime) {
+      throw new Error("Runtime revision is not initialized");
+    }
+    return this.pinAssembly(runtime.pi, runtime.revision);
+  }
+
+  private async pinAssembly(
+    prepared: PreparedPiRuntime,
+    baseRevision: string,
+  ): Promise<{ revision: string; descriptor: string }> {
+    const pinned = await this.pi.pin({
+      prepared,
+      baseRevision,
+      readExtensionContext: ({ label }) =>
+        this._hostGetContext(label),
+    });
+    if (pinned.degradations.length > 0) {
+      console.warn(
+        "[runtime-context:degraded]",
+        json({ degradations: pinned.degradations }),
+      );
+    }
+    return {
+      revision: await sha256Hex(pinned.descriptor),
+      descriptor: pinned.descriptor,
+    };
+  }
+
+  private get admission(): SubmissionAdmission {
+    return this.submissionAdmission ??= new SubmissionAdmission({
+      admissions: this.db.submissionAdmissions,
+      steers: this.db.steers,
+      submissions: this.db.submissions,
+      transaction: (run) => this.db.transaction(run),
+      prepareRuntime: async () => {
+        await this.ensureRuntimeReady();
+        return { runtimeKey: this.activeRuntime!.runtimeKey, admission: this.activeRuntime?.admission };
+      },
+      findUserMessage: (id) => this.transcript.findUserMessage(id),
+      onAdmitted: (submission, hostAccepted) =>
+        this.runtimeTurnEvents.submissionAdmitted(submission, hostAccepted),
+      onRejected: (submission) => this.runtimeTurnEvents.submissionTerminal(submission),
+      cancelHandoff: (id, reason) => this.finalizer.commit(id, "aborted", reason),
+    });
+  }
+
+  private async submitMessage(
+    userMessage: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+  ): Promise<SubmissionHandle<StoredSubmission>> {
+    const submitted = await this.submissions.submit(
+      this.admission.input(userMessage, options),
+    );
+    this.ctx.waitUntil(this.runtimeTurnEvents.drain());
+    await this.broadcastApprovals();
+    return submitted;
+  }
+
+  /** Scheduled work waits for a bounded stable window instead of interrupting a Turn. */
+  private async submitMessageWhenStable(
+    userMessage: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+    timeoutMs: number,
+  ): Promise<SubmissionHandle<StoredSubmission> | null> {
+    const submitted = await this.submissions.submitWhenStable(
+      this.admission.input(userMessage, options),
+      timeoutMs,
+    );
+    if (submitted) {
+      await this.runtimeTurnEvents.drain();
+      await this.broadcastApprovals();
+    }
+    return submitted;
+  }
+
+  // #endregion
+
+  // #region 持久化、恢复与终态提交
+
+  private get finalizer(): SubmissionFinalizer {
+    return this.submissionFinalizer ??= new SubmissionFinalizer({
+      submissions: this.db.submissions,
+      steers: this.db.steers,
+      messageUi: this.db.messageUi,
+      transaction: (run) => this.db.transaction(run),
+      conversation: this.transcript,
+      decisions: this.humanDecisions,
+      events: this.runtimeTurnEvents,
+      telemetry: this.telemetry,
+      releaseAbortedHarness: async () => {
+        const runtime = this.activeHarness;
+        if (!runtime) return;
+        await runtime.lane.waitForIdle(BACKGROUND_CONTEXT);
+        if (this.activeHarness === runtime) this.activeHarness = undefined;
+        await runtime.close(BACKGROUND_CONTEXT);
+      },
+      cancelQueued: async (id) => this.activeHarness?.lane.cancelQueued(id, BACKGROUND_CONTEXT),
+      submit: (message, options) => this.submitMessage(message, options),
+      waitUntil: (promise) => this.ctx.waitUntil(promise),
+    });
+  }
+
+  /** Commit Host terminal facts only after Pi has settled the operation. */
+  private async commitTerminalOutcome(
+    submission: StoredSubmission,
+    outcome: "succeeded" | "failed" | "aborted",
+    message?: string,
+  ): Promise<StoredSubmission> {
+    const terminal = await this.finalizer.finish(submission.submissionId, outcome, message);
+    await this.runtimeTurnEvents.drain();
+    await this.broadcastApprovals();
+    try {
+      if (
+        terminal.status === "error" ||
+        (terminal.status === "aborted" && terminal.error !== USER_STOP_REASON)
+      ) {
+        await recordChatTerminal(
+          this.ctx.storage,
+          terminal.requestId,
+          terminal.error ?? "",
+        );
+      } else {
+        await clearChatTerminal(this.ctx.storage);
+      }
+    } catch (error) {
+      console.error("[pi-terminal] resume marker failed", error);
+    }
+    return terminal;
+  }
+
+  // #region Turn 执行、流式记录与完成投影
+
+  /** Keep failure frames and stream cleanup around the entire Harness execution. */
+  private async executeSubmission(
+    submissionId: string,
+    mode: SubmissionExecutionMode = "fresh",
+  ): Promise<StoredSubmission> {
+    const submission = this.db.submissions.find(submissionId);
+    if (!submission) {
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
+    }
+    if (isTerminalSubmissionStatus(submission.status)) {
+      return submission;
+    }
+    if (submission.abortReason && submission.status === "pending") {
+      return this.submissions.finish(
+        submission,
+        "aborted",
+        submission.abortReason,
+      );
+    }
+    if (mode === "recovery") {
+      this.telemetry.capture("turnRecovering", {
+        submissionId,
+        reason: "runtime_restart",
+        attempt: 1,
+      });
+      await this.broadcastApprovals();
+    }
+    try {
+      return await this.executeHarnessSubmission(submission, mode);
+    } catch (error) {
+      const failed = await this.submissions.finish(
+        submission,
+        "failed",
+        errorText(error),
+      );
+      this.sendChatTerminal(
+        submission.requestId,
+        failed.status === "error"
+          ? failed.error ?? "SpringBrand turn failed"
+          : undefined,
+        mode !== "fresh",
+      );
+      return failed;
+    }
+  }
+
+  /** Run or recover the Submission through Pi's single durable AgentHarness. */
+  private async executeHarnessSubmission(
+    submission: StoredSubmission,
+    mode: SubmissionExecutionMode,
+  ): Promise<StoredSubmission> {
+    const continuation = mode !== "fresh";
+    const submissionId = submission.submissionId;
+    submission = await this.admission.pin(
+      submission,
+      () => this.admissionPin(mode === "fresh", submissionId),
+      mode === "fresh" ? undefined : (key) => this.ensureRuntimeVersion(key),
+    );
+    const activeRuntime = this.requireRuntime();
+    const harnessInput = this.pi.harnessInputs(
+      activeRuntime.pi,
+      submission.assemblyDescriptor,
+      {
+        modelSessionId: submissionId,
+        onGeneration: (event) => this.telemetry.generation(submissionId, event),
+      },
+    );
+    let runtime!: Awaited<ReturnType<typeof openSessionHarness>>;
+    let publishApprovalRequest = async (
+      _toolCallId: string,
+      _approvalId: string,
+    ): Promise<void> => {};
+    const gate = new HarnessDecisionGate({
+      submission: {
+        submissionId,
+        requestId: submission.requestId,
+        executionLevel: activeRuntime.snapshot.profile.executionLevel,
+      },
+      candidates: harnessInput.candidates,
+      telemetry: this.telemetry,
+      approvals: this.db.approvals,
+      interactions: this.db.interactions,
+      transaction: (run) => this.db.transaction(run),
+      release: (reason) => runtime.requestHumanRelease(reason),
+      onChanged: async (kind, id) => {
+        await this.broadcastApprovals();
+        if (kind === "approval") {
+          const approval = this.db.approvals.find(id);
+          if (approval) {
+            await publishApprovalRequest(approval.toolCallId, id);
+          }
+          try {
+            await activeRuntime.snapshot.bindings.turnEvents?.onApproval?.({
+              submissionId,
+              approvalExecutionId: id,
+            });
+          } catch (error) {
+            console.warn("[runtime-approval-projection:degraded]", json({
+              error: errorText(error),
+            }));
+          }
+        }
+      },
+      gateTool: harnessInput.platform.gateTool,
+    });
+    runtime = await openSessionHarness({
+      session: openCloudflareSession(this.ctx.storage),
+      models: harnessInput.models,
+      modelSessionId: submissionId,
+      model: harnessInput.model,
+      thinkingLevel: harnessInput.thinkingLevel,
+      systemPrompt: harnessInput.systemPrompt,
+      tools: compileHarnessTools(harnessInput.candidates, {
+        workspace: harnessInput.workspace,
+        authorize: gate.authorize.bind(gate),
+        resolveReplay: gate.resolveReplay.bind(gate),
+      }),
+      modelToolResultExemptions: harnessInput.candidates
+        .filter(({ outputBudget }) => outputBudget?.kind === "structure")
+        .map(({ tool }) => tool.name),
+      streamOptions: { maxRetries: 0 },
+      compaction: harnessInput.compaction,
+      toolExecution: "parallel",
+    }, BACKGROUND_CONTEXT);
+    this.activeHarness = runtime;
+    let stream: ReturnType<typeof bindHarnessStream> | undefined;
+    let deactivate = () => {};
+    try {
+      runtime.harness.hooks.on("before_tool", gate.beforeTool);
+      runtime.harness.hooks.on("before_drive", async (event, context) => {
+        if (this.db.submissions.find(submissionId)?.abortReason) {
+          await runtime.requestAbort(event.runId, context);
+        }
+      });
+
+      if (submission.abortReason && runtime.openOperation) {
+        await runtime.requestAbort(
+          runtime.openOperation.operationId,
+          BACKGROUND_CONTEXT,
+        );
+      }
+
+      await this.associateHarnessEntries(runtime, submissionId);
+      this.runtimeTurnEvents.backfill(submissionId, harnessInput.model, await this.transcript.storedEntries());
+
+      const preparation = await prepareSubmissionOperation(
+        runtime, submission,
+        (id) => this.transcript.regenerationTarget(id),
+        BACKGROUND_CONTEXT,
+      );
+      if (preparation.kind === "settled") {
+        const record = preparation.outcome;
+        const terminal = await this.submissions.finish(
+          submission,
+          record.status === "completed" || record.status === "declined"
+            ? "succeeded" : record.status === "aborted" ? "aborted" : "failed",
+          record.error?.message,
+        );
+        this.broadcast(json({
+          type: MessageType.CF_AGENT_CHAT_MESSAGES,
+          messages: await this.getMessages(),
+        }));
+        return terminal;
+      }
+
+      if (submission.status === "pending") {
+        this.db.submissions.transition(submissionId, "running", ["pending"]);
+        this.telemetry.capture("turnStarted", {
+          submissionId,
+          assemblyRevision: submission.assemblyRevision,
+        });
+        submission = this.db.submissions.find(submissionId)!;
+      }
+
+      const steerDelivery = new PendingSteerDelivery({
+        steers: this.db.steers,
+        messageUi: this.db.messageUi,
+        transaction: (run) => this.db.transaction(run),
+        enqueue: async (message) => {
+          const queued = await runtime.lane.steer(message, undefined, BACKGROUND_CONTEXT);
+          if (!queued.ok) throw queued.error;
+          return queued.value.entryId;
+        },
+      });
+      const uiMessageBody = submission.queuedUiMessageJson;
+      let initialUserSidecarPersisted = (await this.transcript.storedMessages())
+        .some((entry) =>
+          entry.submissionId === submissionId && entry.message.role === "user"
+        );
+      runtime.harness.events.on("entry_added", (event) => {
+        const entry = event.entry;
+        this.db.transaction(() => {
+          this.db.submissions.linkSessionEntry(entry.id, submissionId);
+          if (entry.type === "message" && entry.message.role === "user") {
+            if (!steerDelivery.settle(entry.id) && !initialUserSidecarPersisted && uiMessageBody) {
+              this.db.messageUi.upsert(entry.id, uiMessageBody);
+              initialUserSidecarPersisted = true;
+            }
+          }
+        });
+
+      });
+      const pendingWatch = await runtime.lane.watch(BACKGROUND_CONTEXT);
+      try {
+        await steerDelivery.reconcile(submissionId, pendingWatch.snapshot);
+      } finally {
+        pendingWatch.unsubscribe();
+      }
+
+      this.runtimeTurnEvents.observe(runtime.harness, submissionId, harnessInput.model);
+      stream = bindHarnessStream(runtime.harness.events, {
+        messageId: submission.assistantMessageId,
+        userMessageId: submission.userMessageId ?? undefined,
+        startedAt: submission.createdAt,
+        turnId: submissionId,
+        publish: async (chunks) => {
+          for (const chunk of chunks) {
+            this.conversation.broadcastResponse({
+              id: submission.requestId,
+              body: json(chunk),
+              done: false,
+              continuation,
+            });
+          }
+        },
+      });
+      publishApprovalRequest = stream.publishApprovalRequest;
+      this.conversation.activate(runtime.lane, submission);
+
+      const control = {
+        abort: async () => {
+          if (runtime.openOperation) {
+            await runtime.requestAbort(
+              runtime.openOperation.operationId,
+              BACKGROUND_CONTEXT,
+            );
+          }
+        },
+        interrupt: () => void runtime.close(BACKGROUND_CONTEXT),
+        steer: async (_message: PiCanonicalUserInput, messageId: string) => {
+          const steer = this.db.steers.findByMessageId(messageId);
+          if (steer) await steerDelivery.queue(steer);
+        },
+      };
+      const turn: ActiveTurn = {
+        submissionId,
+        requestId: submission.requestId,
+        messageId: submission.assistantMessageId,
+        startedAt: submission.createdAt,
+        continuation,
+        agent: control,
+      };
+      deactivate = this.submissions.activate(submission, turn);
+      const outcome = await runtime.run(preparation.request, BACKGROUND_CONTEXT, {
+        pollDeferred: !preparation.request,
+      });
+      this.db.submissions.clearQueuedPayload(submissionId);
+      if (outcome.kind === "released") {
+        if (
+          outcome.reason === "slice" ||
+          outcome.reason === "budget" ||
+          outcome.reason === "tool-failure"
+        ) {
+          await this.schedule(0, "_piHarnessContinuation", { submissionId }, {
+            idempotent: true,
+          });
+        }
+        return this.db.submissions.find(submissionId)!;
+      }
+      if (outcome.kind === "waiting") {
+        await this.schedule(
+          outcome.reason === "retry"
+            ? Math.max(0, Math.ceil((outcome.notBefore - Date.now()) / 1000))
+            : Math.max(0, Math.ceil((outcome.deferred.pollAfterMs ?? 1_000) / 1000)),
+          "_piHarnessContinuation",
+          { submissionId },
+          { idempotent: true },
+        );
+        return this.db.submissions.find(submissionId)!;
+      }
+      const record = outcome.outcome;
+      const status = record.status === "completed" || record.status === "declined"
+        ? "succeeded"
+        : record.status === "aborted"
+          ? "aborted"
+          : "failed";
+      this.runtimeTurnEvents.backfill(submissionId, harnessInput.model, await this.transcript.storedEntries());
+      const terminal = await this.submissions.finish(
+        submission,
+        status,
+        record.error?.message,
+      );
+      const projectedOutcome = projectSubmissionOutcome(record, terminal);
+      await stream.flushTerminal(projectedOutcome);
+      await this.conversation.settle(projectedOutcome);
+      this.broadcast(json({
+        type: MessageType.CF_AGENT_CHAT_MESSAGES,
+        messages: await this.getMessages(),
+      }));
+      return terminal;
+    } catch (error) {
+      console.warn("[runtime-harness:failed]", json({
+        submissionId,
+        error: errorText(error),
+      }));
+      throw error;
+    } finally {
+      await this.conversation.release(runtime.lane).catch((error) => {
+        console.warn("[runtime-stream:degraded]", errorText(error));
+      });
+      stream?.unsubscribe();
+      deactivate();
+      if (this.activeHarness === runtime) this.activeHarness = undefined;
+      await runtime.close(BACKGROUND_CONTEXT).catch(() => undefined);
+    }
+  }
+
+  async _piHarnessContinuation(
+    data?: { readonly submissionId?: string },
+  ): Promise<void> {
+    if (!data?.submissionId) return;
+    await this.ensureRuntimeReady();
+    await this.submissions.continueAfterCurrent(data.submissionId);
+  }
+
+  private sendChatTerminal(
+    requestId: string,
+    error?: string,
+    continuation = false,
+  ): void {
+    this.conversation.broadcastResponse({
+      id: requestId,
+      body: error
+        ? json({ type: "error", errorText: error } satisfies UIMessageChunk)
+        : "",
+      done: true,
+      continuation,
+    });
+  }
+
+  // #endregion
+
+  // #region Cloudflare Agent 通信生命周期
+
+  /** Start the native resume handshake from Pi's current lane snapshot. */
+  async onConnect(connection: Connection): Promise<void> {
+    this.conversation.disconnect(connection);
+    await this.conversation.resume(connection);
+  }
+
+  async onClose(connection: Connection, code: number, reason: string, wasClean: boolean): Promise<void> {
+    this.conversation.disconnect(connection);
+    await super.onClose(connection, code, reason, wasClean);
+  }
+
+  /** Serve chat hydration and delegate every other HTTP route to Agents SDK. */
+  async onRequest(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname.endsWith("/get-messages")) {
+      return Response.json(url.searchParams.get("view") === "hydration"
+        ? await this.conversation.messages("hydration")
+        : await this.getMessages());
+    }
+    return super.onRequest(request);
+  }
+
+  /** Validate chat protocol input before routing it to capability modules. */
+  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 = await this.normalizeUIUserInput(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;
+      }
+      await submitted.completion;
+      return;
+    }
+
+    if (event.type === "cancel") {
+      const submission = this.db.submissions.findByRequestId(event.id);
+      if (submission) {
+        await this.cancelSubmissionById(
+          submission.submissionId,
+          USER_STOP_REASON,
+        );
+      }
+      return;
+    }
+
+    if (event.type === "clear") {
+      if (this.submissions.isBusy()) return;
+      this.db.transaction(() => {
+        this.transcript.clear();
+        this.db.clearAll();
+      });
+      await this.broadcastApprovals();
+      this.broadcast(json({ type: MessageType.CF_AGENT_CHAT_CLEAR }));
+      return;
+    }
+
+    if (event.type === "stream-resume-request") {
+      // The mounted client receives the same Pi snapshot used by initial hydration,
+      // including any assistant text and Tools that have not settled yet.
+      await this.conversation.resume(connection, event.probeId);
+      return;
+    }
+
+    if (event.type === "stream-resume-ack") {
+      await this.conversation.acknowledge(connection, event.id);
+      return;
+    }
+
+    if (event.type === "tool-approval") {
+      const executionId = this.db.approvals.findPendingByToolCallId(
+        event.toolCallId,
+      );
+      if (!executionId) return;
+      await this.decideApproval(
+        executionId,
+        event.approved
+          ? { decision: "allow_once" }
+          : { decision: "deny", reason: "User denied the Tool" },
+      );
+    }
+  }
+
+  /** Return the complete canonical browser projection, including an active reply. */
+  async getMessages(): Promise<UIMessage[]> {
+    return this.conversation.messages("full");
+  }
+
+  /** 读取当前 canonical transcript 中最后一条助手文本。 */
+  protected async latestAssistantText(): Promise<string | undefined> {
+    const message = [...await this.transcript.canonicalMessages()]
+      .reverse()
+      .find((entry): entry is AssistantMessage => entry.role === "assistant");
+    const text = message?.content
+      .flatMap((part) => part.type === "text" ? [part.text] : [])
+      .join("")
+      .trim();
+    return text || undefined;
+  }
+
+  // #endregion
+
+  // #region Runtime Extension Host 回环端口
+
+  private async runtimeWorkspace() {
+    await this.ensureRuntimeReady();
+    const workspace = this.requireRuntime().snapshot.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);
+  }
+
+  async _hostWriteFile(
+    path: string,
+    content: string,
+  ): Promise<void> {
+    await (await this.runtimeWorkspace()).writeFile(path, content);
+  }
+
+  async _hostDeleteFile(path: string): Promise<boolean> {
+    const workspace = await this.runtimeWorkspace();
+    try {
+      await workspace.rm(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  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,
+    }));
+  }
+
+  async _hostGetContext(label: string): Promise<string | null> {
+    return this.db.extContext.get(label) ?? null;
+  }
+
+  async _hostSetContext(
+    label: string,
+    content: string,
+  ): Promise<void> {
+    this.db.extContext.set(label, content);
+  }
+
+  async _hostGetMessages(
+    limit?: number,
+  ): Promise<
+    Array<{ id: string; role: string; content: string }>
+  > {
+    return this.transcript.hostMessages(limit);
+  }
+
+  /** Steer an active Turn; append directly only while idle. */
+  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,
+          harnessEntryId: null,
+          canonicalJson: json(message),
+          uiMessageJson: null,
+          createdAt: message.timestamp,
+        });
+      });
+      await active.agent.steer(message, messageId).catch(() => undefined);
+      await this.broadcastApprovals();
+      return;
+    }
+    this.transcript.append(crypto.randomUUID(), message);
+  }
+
+  async _hostGetSessionInfo(): Promise<{ messageCount: number }> {
+    return {
+      messageCount: (await this._hostGetMessages()).length,
+    };
+  }
+
+  // #endregion
+
+  // #region Session 消息与 Submission 公开控制面
+
+  /** Export canonical history through one message for fork/import. */
+  async getCanonicalSnapshot(
+    throughMessageId: string,
+  ): Promise<PiCanonicalTranscriptSnapshot> {
+    return this.transcript.exportSnapshot(throughMessageId);
+  }
+
+  async addCanonicalSnapshot(
+    snapshot: PiCanonicalTranscriptSnapshot,
+  ): Promise<void> {
+    this.transcript.importSnapshot(snapshot);
+  }
+
+  /** Admit text and return immediately; completion continues in the Durable Object. */
+  async submitPrompt(
+    text: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<SubmissionReceipt> {
+    const submitted = await this.submitMessage({
+      role: "user",
+      content: [{ type: "text", text }],
+      timestamp: Date.now(),
+    }, {
+      requestId: crypto.randomUUID(),
+      idempotencyKey: options?.idempotencyKey,
+    });
+    this.ctx.waitUntil(submitted.completion);
+    return projectSubmissionReceipt(submitted.receipt);
+  }
+
+  private get delivery(): SubmissionDelivery {
+    return this.submissionDelivery ??= new SubmissionDelivery({
+      submissions: this.db.submissions,
+      steers: this.db.steers,
+      transaction: (run) => this.db.transaction(run),
+      lifecycle: this.submissions,
+      decisions: this.humanDecisions,
+      telemetry: this.telemetry,
+      events: this.runtimeTurnEvents,
+      normalize: (message) => this.normalizeUIUserInput(message),
+      submit: (message, options) => this.submitMessage(message, options),
+      onChanged: () => this.broadcastApprovals(),
+      waitUntil: (promise) => this.ctx.waitUntil(promise),
+    });
+  }
+
+  async dispatchMessage(message: UIMessage, delivery: MessageDelivery): Promise<MessageDispatchReceipt> {
+    return this.delivery.dispatch(message, delivery);
+  }
+
+  async steerQueuedSubmission(submissionId: string): Promise<MessageDispatchReceipt> {
+    return this.delivery.steerQueued(submissionId);
+  }
+
+  /** Admit scheduled work after a bounded stable wait, otherwise return 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) {
+      const skipped = this.db.transaction(() => {
+        const duplicate = options?.idempotencyKey
+          ? this.db.submissions.findByIdempotencyKey(options.idempotencyKey)
+          : this.db.submissions.findByRequestId(requestId);
+        return duplicate ?? this.admission.skip({
+          submissionId: requestId,
+          requestId,
+          idempotencyKey: options?.idempotencyKey ?? null,
+          createdAt: Date.now(),
+          code: "Runtime not stable within timeout",
+          retryable: true,
+        });
+      }) as StoredSubmission;
+      await this.runtimeTurnEvents.drain();
+      await this.broadcastApprovals();
+      return projectSubmissionReceipt(skipped);
+    }
+    this.ctx.waitUntil(submitted.completion.then(() => undefined));
+    return projectSubmissionReceipt(submitted.receipt);
+  }
+
+  /** Read the durable receipt rather than inferring status from process state. */
+  async getSubmission(
+    submissionId: string,
+  ): Promise<SubmissionReceipt | null> {
+    const submission = this.submissions.get(submissionId);
+    return submission ? projectSubmissionReceipt(submission) : null;
+  }
+
+  /** Persist abort intent before interrupting the active execution. */
+  async cancelSubmissionById(
+    submissionId: string,
+    reason?: string,
+  ): Promise<{ ok: boolean }> {
+    const result = await this.submissions.cancel(
+      submissionId,
+      reason ?? "Cancelled",
+    );
+    await this.broadcastApprovals();
+    return result;
+  }
+
+  /** Stop one request or the current unfinished queue through SubmissionLifecycle. */
+  async stopTurn(
+    requestId?: string,
+    reason?: string,
+  ): Promise<{ ok: boolean }> {
+    const result = await this.submissions.stop(
+      requestId,
+      reason ?? "Stopped",
+    );
+    await this.broadcastApprovals();
+    return result;
+  }
+
+  /** Stops every running, queued, or steered user request in this Session. */
+  async stopAllSubmissions(reason?: string): Promise<{ ok: boolean }> {
+    const result = await this.submissions.stopAll(reason ?? "Stopped");
+    await this.broadcastApprovals();
+    return result;
+  }
+
+  /** 返回当前已装配 User Agent 的执行档位，不提供 Session 覆盖。 */
+  executionLevel(): ExecutionLevel {
+    return this.requireRuntime().snapshot.profile.executionLevel;
+  }
+
+  /** Read trusted approval requirements before the Host applies allow_level. */
+  getPendingApproval(executionId: string): ApprovalReceipt | null {
+    const temporary = this.temporaryAgentApprovals.find(executionId);
+    if (temporary) return temporary;
+    const approval = this.db.approvals.find(executionId);
+    if (!approval || approval.status !== "pending") return null;
+    return {
+      executionId: approval.executionId,
+      source: approval.source as ApprovalReceipt["source"],
+      action: approval.toolName,
+      summary: approval.summary,
+      executionLevel: approval.executionLevel,
+      requiredExecutionLevel: approval.requiredExecutionLevel,
+      inputJson: approval.inputJson,
+      requestId: approval.requestId,
+    };
+  }
+
+  /** Validate a client-provided Tool result and resume its durable Submission. */
+  async respondToolInteraction(
+    toolCallId: string,
+    response: unknown,
+  ): Promise<{ ok: boolean }> {
+    const pending = this.db.interactions.findPendingByToolCallId(toolCallId);
+    if (!pending) return { ok: false };
+    const submission = this.db.submissions.find(pending.submissionId);
+    if (!submission || isTerminalSubmissionStatus(submission.status)) {
+      return { ok: false };
+    }
+    await this.ensureRuntimeReady();
+    const spec = this.pi.harnessInputs(
+      this.requireRuntime().pi,
+      submission.assemblyDescriptor,
+    ).candidates.find(({ tool }) => tool.name === pending.toolName)?.interaction;
+    if (!spec) return { ok: false };
+
+    const accepted = await this.humanDecisions.respond(
+      pending, spec, response,
+      (input) => this.prepareToolInteractionResponse(input),
+    );
+    if (!accepted) return { ok: false };
+    await this.broadcastApprovals();
+    this.ctx.waitUntil(
+      this.submissions.continueAfterCurrent(submission.submissionId)
+        .then(() => undefined),
+    );
+    return { ok: true };
+  }
+
+  /** Apply one decision; the Host must persist allow_level before resuming. */
+  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 = await this.temporaryAgentApprovals.decide(executionId, decision);
+    if (temporary) return temporary;
+    const result = this.humanDecisions.approve(executionId, decision);
+    if (result.submissionId) {
+      await this.broadcastApprovals();
+      this.ctx.waitUntil(
+        this.submissions.continueAfterCurrent(result.submissionId).then(() => undefined),
+      );
+    }
+    return { ok: result.ok };
+  }
+
+  /** Project Agents SDK child-run startup into canonical telemetry and state. */
+  override async onAgentToolStart(run: AgentToolRunInfo): Promise<void> {
+    await super.onAgentToolStart(run);
+    const metadata = runtimeSubagentRunMetadata(run.inputPreview);
+    if (metadata) await this.runtimeTurnEvents.subagentStarted(metadata, run);
+    await this.broadcastApprovals();
+  }
+
+  /** Rebuild activity after an Agent Tool reaches or approaches terminal state. */
+  override async onAgentToolFinish(
+    run: AgentToolRunInfo,
+    result: AgentToolLifecycleResult,
+  ): Promise<void> {
+    await super.onAgentToolFinish(run, result);
+    const metadata = runtimeSubagentRunMetadata(run.inputPreview);
+    if (metadata) await this.runtimeTurnEvents.subagentFinished(metadata, run, result);
+    await this.broadcastApprovals();
+  }
+
+  async _cfDetachedNotifyFinish(
+    run: AgentToolRunInfo,
+    result: AgentToolLifecycleResult,
+  ): Promise<void> {
+    const completion = decodeSubagentCompletion(result.summary);
+    const outcome = result.status === "completed"
+      ? completion
+        ? JSON.stringify(completion.output)
+        : result.summary ?? "Completed without a result."
+      : result.error ?? `Background run ${result.status}.`;
+    await this.submitPrompt(
+      [
+        "A background sub-agent run has finished.",
+        `runId: ${run.runId}`,
+        `status: ${result.status}`,
+        `result: ${outcome}`,
+      ].join("\n"),
+      { idempotencyKey: `detached-agent-tool:${run.runId}:${result.status}` },
+    );
+  }
+
+  /** Rebuild best-effort UI state from durable facts. */
+  protected async broadcastApprovals(): Promise<void> {
+    try {
+      const { state, changed } = projectRuntimeState({
+        approvals: this.db.approvals.listPendingActive(),
+        temporaryApprovals: this.temporaryAgentApprovals.list(),
+        running: this.db.submissions.findRunning(),
+        pending: this.db.submissions.listPending(),
+        hasPendingApproval: (id) => this.humanDecisions.isWaitingForApproval(id),
+        hasPendingInteraction: (id) => this.humanDecisions.isWaitingForInteraction(id),
+        hasPendingSteer: (id) => this.db.steers.listForSubmission(id).length > 0,
+        hasRunningAgentTools: this.db.agentTools.hasRunning(),
+        previousState: this.state,
+      });
+      if (changed) this.setState(state);
+      const projection = this.activeRuntime?.snapshot.bindings.turnEvents?.onActivityChanged?.(state.activity!);
+      if (projection) {
+        this.ctx.waitUntil(
+          projection.catch(() => undefined),
+        );
+      }
+    } catch {
+      // Approval projection is best effort and must not block execution.
+    }
+  }
+
+  // #endregion
+
+}