@springbrand/agent-runtime 0.1.3-alpha.3 → 0.1.3-alpha.5

package/src/runtime.ts

@@ -1,4 +1,8 @@
-import type { Connection } from "agents";
+import type {
+  AgentToolLifecycleResult,
+  AgentToolRunInfo,
+  Connection,
+} from "agents";
 import {
   ChatStreamStalledError,
   MessageType,
@@ -13,6 +17,7 @@ import {
   ApprovalLifecycle,
   type ApprovalContinuationData,
 } from "./kernel/approval-lifecycle";
+import { InteractionLifecycle } from "./kernel/interaction-lifecycle";
 import {
   SubmissionLifecycle,
   SubmissionQueueFullError,
@@ -29,21 +34,26 @@ import {
   type SubmissionReceipt,
 } from "./kernel/receipts";
 import type { ExecutionLevel } from "./lib/execution-level";
+import type { RuntimeGatewaySession } from "./kernel/bindings";
+import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
+import { projectRuntimeAssembly } from "./kernel/runtime-assembly";
 import type {
   RuntimeExtensionPermissions,
 } from "./kernel/extensions";
 import type {
   RuntimeActivity,
-  RuntimeLoadPhase,
-  RuntimeLoadState,
   RuntimeState,
   RuntimeTurnState,
 } from "./kernel/state";
+import { RuntimeLoadTracker } from "./kernel/runtime-load";
 import {
-  initializeRuntimeConfig,
-  type AgentConfig,
+  prepareRuntimeCandidate,
+  type RuntimeAssemblyInput,
+  type RuntimeCandidate,
   type RuntimeSnapshot,
-} from "./plugins";
+} from "./runtime-assembler";
+import type { RuntimeAgentHooks } from "./runtime-definition";
+import type { RuntimeTurnEventsPort } from "./kernel/bindings";
 import { connectConfiguredMcpServers } from "./lib/mcp";
 import { installConsoleSink } from "./lib/telemetry-dev";
 import {
@@ -55,6 +65,7 @@ import {
   type PiCanonicalTranscriptSnapshot,
   type PiChatRecoveryData,
   type UIChatRequestBody,
+  type RequestedCapability,
   type PiDurableMutation,
   type PiRecoveryCommand,
   type PiRecoveryDecision,
@@ -66,7 +77,11 @@ import {
   type PreparedPiTurnAdapter,
 } from "./pi/runtime-adapter";
 import type { UIMessage, UIMessageChunk } from "ai";
-import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type {
+  AssistantMessage,
+  ToolResultMessage,
+} from "@earendil-works/pi-ai";
+import { serializeOutput } from "./lib/artifacts";
 import type {
   RuntimeModelUsageEvent,
   RuntimeToolSettlementEvent,
@@ -181,6 +196,27 @@ function assistantUsageEvent(
 // 作用：把用户消息内容变成可比较的稳定形状。
 // 调用：重新生成回答时，提交入口用它核对客户端与已存用户消息。
 // 原因：字符串和分段内容必须先归一化，否则语义相同的消息会被误判为不同。
+// 把 park 时存下的 Tool 输入还原成对象，交给该 Tool 自己的 settle 映射。
+// respondToolInteraction 调用；解析失败按 undefined 处理，因为映射函数是否用得到它由 Tool 决定。
+function safeParseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+// Tool 没有提供 settle 时的缺省映射：响应原样成为 ToolResult 的 details。
+// text 用 serializeOutput 而不是裸 JSON.stringify，与其他 Tool 结果的文本形态保持一致。
+function defaultInteractionResult(
+  response: unknown,
+): { content: ToolResultMessage["content"]; details: unknown } {
+  return {
+    content: [{ type: "text", text: serializeOutput(response).text }],
+    details: response,
+  };
+}
+
 function userContentKey(message: PiCanonicalUserInput): string {
   return json(
     typeof message.content === "string"
@@ -189,20 +225,42 @@ function userContentKey(message: PiCanonicalUserInput): string {
   );
 }
 
-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;
+function requestedCapabilitiesOf(metadata: unknown): RequestedCapability[] {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return [];
+  }
+  const record = metadata as Record<string, unknown>;
+  if (!("requestedCapabilities" in record)) return [];
+  if (!Array.isArray(record.requestedCapabilities)) {
+    throw new Error("requestedCapabilities must be an array");
+  }
+
+  const result: RequestedCapability[] = [];
+  const seen = new Set<string>();
+  for (const value of record.requestedCapabilities) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("requestedCapabilities contains an invalid capability");
+    }
+    const capability = value as Record<string, unknown>;
+    if (
+      (capability.kind !== "skill" && capability.kind !== "plan") ||
+      typeof capability.name !== "string" ||
+      !capability.name.trim() ||
+      typeof capability.label !== "string" ||
+      !capability.label.trim()
+    ) {
+      throw new Error("requestedCapabilities contains an invalid capability");
+    }
+    const key = `${capability.kind}:${capability.name}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push({
+      kind: capability.kind,
+      name: capability.name,
+      label: capability.label,
+    });
+  }
+  return result;
 }
 
 interface PendingTemporaryAgentApproval {
@@ -240,6 +298,9 @@ export abstract class AgentRuntimeKernel<
   private runtimeSnapshot?: RuntimeSnapshot;
   private runtimeRevision?: string;
   private runtimePi?: PreparedPiRuntime;
+  private runtimeGatewaySession?: RuntimeGatewaySession;
+  private runtimeTurnEvents?: RuntimeTurnEventsPort;
+  private runtimeHooks?: RuntimeAgentHooks;
   private piAdapter?: PiRuntimeAdapter;
   private readonly transcript: PiRuntimeTranscript;
   private readonly submissions: SubmissionLifecycle<
@@ -247,7 +308,10 @@ export abstract class AgentRuntimeKernel<
     ActiveTurn
   >;
   private readonly approvals: ApprovalLifecycle<StoredSubmission>;
+  private readonly interactions: InteractionLifecycle<StoredSubmission>;
+  private runtimeLoadTracker?: RuntimeLoadTracker;
   private readonly streamBySubmission = new Map<string, string>();
+  private migratedSubmissionIds?: Set<string>;
   private db!: RuntimeDatabase;
   private readonly temporaryAgents = new TemporaryAgentCoordinator();
   private readonly temporaryAgentApprovals =
@@ -262,6 +326,24 @@ export abstract class AgentRuntimeKernel<
     return this.piAdapter ??= new PiRuntimeAdapter();
   }
 
+  /**
+   * 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.runtimeSnapshot),
+    });
+  }
+
   /**
    * 为一个 Cloudflare Durable Object 实例建立持久化与执行协作器。
    *
@@ -313,6 +395,7 @@ export abstract class AgentRuntimeKernel<
       commitTerminal: (submission, outcome, message) =>
         this.commitTerminalOutcome(submission, outcome, message),
       abortActive: (turn) => turn.agent.abort(),
+      interruptActive: (turn) => turn.agent.interrupt(),
     });
     this.transcript = this.pi.createTranscript({
       sql: this.sql.bind(this),
@@ -350,6 +433,22 @@ export abstract class AgentRuntimeKernel<
       },
       onApprovalsChanged: () => this.broadcastApprovals(),
     });
+    this.interactions = new InteractionLifecycle({
+      db: this.db,
+      pi: this.pi,
+      findSubmission: (submissionId) =>
+        this.readSubmission(submissionId),
+      applyRecoveryMutations: (submission, mutations) =>
+        this.applyPiRecoveryMutations(submission, mutations),
+      materializeRecoveredToolResults: (submission) =>
+        this.materializeRecoveredToolResults(submission),
+      // 与审批不同，这里不经 `schedule` 绕一圈：RPC 已经把 DO 叫醒了，
+      // 而 interaction 没有自己的续跑键，续跑就是普通的「已结算 Tool 恢复原 Turn」。
+      resumeSubmission: async (submissionId) => {
+        await this.submissions.recover(submissionId);
+      },
+      onInteractionsChanged: () => this.broadcastApprovals(),
+    });
   }
 
   // 作用：把通用聊天恢复协议接到本 Runtime 的 Submission 和 Pi 里程碑。
@@ -406,49 +505,103 @@ export abstract class AgentRuntimeKernel<
   // 作用：准备并原子切换一份新的 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;
+  protected async initConfig(input: RuntimeAssemblyInput): Promise<void> {
+    const candidate = await prepareRuntimeCandidate(input);
+    await this.initCandidate(candidate);
+  }
+
+  private turnEventsPort(): RuntimeTurnEventsPort | undefined {
+    return this.runtimeTurnEvents ?? this.runtimeSnapshot?.bindings.turnEvents;
+  }
 
-    this.advanceRuntimeLoad("mcp");
+  protected async initCandidate(candidate: RuntimeCandidate): Promise<void> {
+    this.runtimeTurnEvents =
+      candidate.turnEvents ?? candidate.snapshot.bindings.turnEvents;
+    this.runtimeHooks = candidate.hooks;
+    const previous = this.runtimeSnapshot;
+    const candidateSnapshot = candidate.snapshot;
+    this.runtimeLoad.advance("assembly");
+    this.runtimeLoad.advance("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 gatewayDegradations = [];
+    let gatewaySession: RuntimeGatewaySession | undefined;
+    if (candidateSnapshot.bindings.gateway) {
+      try {
+        gatewaySession = await candidateSnapshot.bindings.gateway.open(
+          `${this.ctx.id.toString()}:${crypto.randomUUID()}`,
+        );
+      } catch {
+        gatewayDegradations.push({
+          capability: "connector" as const,
+          reason: "unavailable" as const,
+          detail: "Connector Gateway MCP",
+        });
+      }
+    }
+
+    this.runtimeLoad.advance("pi");
+    let prepared: PreparedPiRuntime;
+    try {
+      prepared = await this.pi.prepare({
+        snapshot: candidateSnapshot,
+        mcpHost: this,
+        gatewaySession,
+        additionalDegradations: gatewayDegradations,
+        createExtensionHostBinding: (permissions, ownContextLabels) =>
+          this.createExtensionHostBinding(
+            permissions,
+            ownContextLabels,
+          ),
+      });
+    } catch (error) {
+      await gatewaySession?.close().catch(() => undefined);
+      throw error;
+    }
     const revision = await this.hash(prepared.revisionDescriptor);
-    if (
-      previous &&
+    // 停在人机等待上的 Submission 是「未完成」，但没有任何模型请求在飞、
+    // 没有任何工具在执行 —— 换装配对它是安全的，而且这正是「决定时才装上
+    // 新能力，同一轮接着跑」所依赖的那一步。真正在执行的 Turn 仍然被挡住。
+    const contested = Boolean(previous) &&
       revision !== this.runtimeRevision &&
-      this.submissions.isBusy()
-    ) {
+      this.submissions.isBusy();
+    const parked = contested && this.db.everyUnfinishedSubmissionParked();
+    if (contested && !parked) {
+      await gatewaySession?.close().catch(() => undefined);
       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 repin = parked
+      ? await this.prepareParkedSubmissionRepin(prepared, revision)
+      : undefined;
+    let activated = false;
+    const previousGatewaySession = this.runtimeGatewaySession;
+    try {
+      for (const guard of candidate.commitGuards) await guard();
+      if (candidateSnapshot.bindings.platform.telemetryConsole) {
+        installConsoleSink();
+      }
+      this.pi.activate(candidateSnapshot);
+      activated = true;
+      repin?.commit();
+      this.runtimeSnapshot = candidateSnapshot;
+      this.runtimeRevision = revision;
+      this.runtimePi = prepared;
+      this.runtimeGatewaySession = gatewaySession;
+    } catch (error) {
+      repin?.abort();
+      if (activated && previous) this.pi.activate(previous);
+      await gatewaySession?.close().catch(() => undefined);
+      throw error;
     }
+    await repin?.interrupt().catch((error) => {
+      console.error("[runtime-repin:interrupt-failed]", error);
+    });
+    await previousGatewaySession?.close().catch(() => undefined);
+
     const degradations = prepared.degradations;
     if (degradations.length > 0) {
       console.warn(
@@ -502,7 +655,7 @@ export abstract class AgentRuntimeKernel<
             async (created) => {
               await onCreated?.();
               try {
-                await this.assembly().bindings.turnEvents?.onApproval?.({
+                await this.turnEventsPort()?.onApproval?.({
                   submissionId: submission.submissionId,
                   approvalExecutionId: created.executionId,
                 });
@@ -514,6 +667,10 @@ export abstract class AgentRuntimeKernel<
               }
             },
           ),
+        // spec 在这里用不上：响应侧一律从重新装配出的 candidate 按 toolName 取回同一份，
+        // 好让「DO 一直醒着」和「park 期间睡过一觉」走完全相同的一条代码路径。
+        requestToolInteraction: (interaction, _spec, signal) =>
+          this.interactions.request(submission, interaction, signal),
         appendToolInput: (input) =>
           this.appendToolInput(submission, input),
         settleTool: (call) =>
@@ -528,6 +685,10 @@ export abstract class AgentRuntimeKernel<
         this.readSubmission(submission.submissionId)?.abortReason,
       onRecord: output.onRecord ?? (() => undefined),
       onCanonicalMessage: async (commit) => {
+        // 换装配把这条执行器中断掉了。它退场路上还会吐出「工具被中止」这样的
+        // 消息 —— 那不是这一轮的事实，写进权威 transcript 会让重建出来的续跑
+        // 看到一份自己从没产生过的工具结果。
+        if (this.migratedSubmissions.has(submission.submissionId)) return;
         let consumedSteer = false;
         this.db.transaction(() => {
           if (commit.kind !== "append-user") {
@@ -595,7 +756,7 @@ export abstract class AgentRuntimeKernel<
    * 不会延长 Durable Object 生命；本文件仍在三处用它启动后台任务。
    */
   async onStart(): Promise<void> {
-    this.publishRuntimeLoad({ status: "idle", available: false });
+    this.runtimeLoad.reset();
     if (this.db.runtimeEvents.hasPending()) {
       this.ctx.waitUntil(
         this.ensureRuntimeReady().then(() => this.drainRuntimeEvents()),
@@ -620,7 +781,7 @@ export abstract class AgentRuntimeKernel<
   }
 
   private async drainRuntimeEvents(idempotentRetry = true): Promise<void> {
-    const turnEvents = this.runtimeSnapshot?.bindings.turnEvents;
+    const turnEvents = this.turnEventsPort();
     if (!turnEvents) return;
 
     let failed = false;
@@ -749,78 +910,56 @@ export abstract class AgentRuntimeKernel<
   private assembly(): RuntimeSnapshot {
     if (!this.runtimeSnapshot) {
       throw new Error(
-        "AgentConfig must be initialized before using the Runtime",
+        "Runtime must be assembled before use",
       );
     }
     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,
-    });
-  }
+  private async normalizeUIUserInput(
+    message: UIMessage & { role: "user" },
+  ): Promise<PiCanonicalUserInput> {
+    const capabilities = requestedCapabilitiesOf(message.metadata);
+    if (capabilities.length === 0) return this.pi.normalizeUserInput(message);
 
-  // 作用：把成功提交的 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,
-    });
+    await this.ensureRuntimeReady();
+    const installedSkills = new Set(
+      this.assembly().bindings.skills.sources.map(({ name }) => name),
+    );
+    const context: string[] = [];
+    for (const capability of capabilities) {
+      if (capability.kind === "skill") {
+        if (!installedSkills.has(capability.name)) {
+          throw new Error(
+            `Requested Skill is not installed: ${capability.name}`,
+          );
+        }
+        context.push(
+          `requested capability: skill/${capability.name}`,
+          `required action: call activate_skill for "${capability.name}" before handling the task`,
+        );
+        continue;
+      }
+      if (capability.name !== "plan") {
+        throw new Error(`Unknown plan capability: ${capability.name}`);
+      }
+      context.push(
+        "requested capability: plan/plan",
+        "required action: call update_plan with the complete plan before other work, then wait for user confirmation before execution",
+      );
+    }
+    return this.pi.normalizeUserInput(message, context.join("\n"));
   }
 
-  // 作用：记录 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 Snapshot 投影成可序列化的调试视图。
+  // 调用：Session facet 的 `getRuntimeAssembly` RPC。
+  // 原因：UI 需要读取真实装配结果，而不是上层配置声明。
+  protected readRuntimeAssembly(): RuntimeAssemblyView {
+    return projectRuntimeAssembly(
+      this.assembly(),
+      this.runtimeRevision ?? null,
+      this.preparedPi(),
+    );
   }
 
   // 作用：为 Runtime Extension 创建只包含授权能力的 Worker 回环绑定。
@@ -866,6 +1005,20 @@ export abstract class AgentRuntimeKernel<
   // 作用：返回当前已准备好的 Pi Runtime。
   // 调用：创建 Turn 适配器或准入固定装配时调用。
   // 原因：明确区分“已有 Snapshot”和“Pi 已完成准备”，防止半初始化状态进入 Turn。
+  /**
+   * 正在被换装配中断、等待持久续跑接手的 Submission。
+   *
+   * 中断和取消在执行路径上长得一模一样（都是 abort），但结局相反：取消要写终态，
+   * 换装配中断必须让 Submission 停在 running，等决策把它交给续跑。这个集合是
+   * 两者唯一的区分依据，只在一次 `repinParkedSubmissions` 的窗口内有成员。
+   *
+   * 写成惰性访问器而不是字段：本类有测试用 `Object.create(prototype)` 造替身，
+   * 那条路径不跑字段初始化器。
+   */
+  private get migratedSubmissions(): Set<string> {
+    return this.migratedSubmissionIds ??= new Set<string>();
+  }
+
   private preparedPi(): PreparedPiRuntime {
     if (!this.runtimePi) {
       throw new Error(
@@ -887,13 +1040,31 @@ export abstract class AgentRuntimeKernel<
     descriptor: string;
   }> {
     await this.ensureRuntimeReady();
+    return this.currentAssemblyPin();
+  }
+
+  // 作用：按当前已装配的 Runtime 生成一份不可变装配描述。
+  // 调用：准入 pin 走 `admissionPin`；`initConfig` 内部的重新 pin 直接调用本方法。
+  // 原因：`initConfig` 已经在装配串行入口里面，再走 `ensureRuntimeReady` 会等自己，
+  // 所以「确保装配就绪」和「按当前装配取 pin」必须是两步。
+  private async currentAssemblyPin(): Promise<{
+    revision: string;
+    descriptor: string;
+  }> {
     await this.drainRuntimeEvents();
     if (!this.runtimeRevision) {
       throw new Error("Runtime revision is not initialized");
     }
+    return this.pinAssembly(this.preparedPi(), this.runtimeRevision);
+  }
+
+  private async pinAssembly(
+    prepared: PreparedPiRuntime,
+    baseRevision: string,
+  ): Promise<{ revision: string; descriptor: string }> {
     const pinned = await this.pi.pin({
-      prepared: this.preparedPi(),
-      baseRevision: this.runtimeRevision,
+      prepared,
+      baseRevision,
       readExtensionContext: ({ label }) =>
         this._hostGetContext(label),
     });
@@ -931,6 +1102,89 @@ export abstract class AgentRuntimeKernel<
     return pinned;
   }
 
+  /** 准备 parked Submission 的续跑切换，持久 pin 只在最终 commit 中修改。 */
+  private async prepareParkedSubmissionRepin(
+    prepared: PreparedPiRuntime,
+    baseRevision: string,
+  ): Promise<{ commit(): void; interrupt(): Promise<void>; abort(): void }> {
+    await this.drainRuntimeEvents();
+    const { revision, descriptor } = await this.pinAssembly(
+      prepared,
+      baseRevision,
+    );
+    const plans: Array<{
+      submission: StoredSubmission;
+      decision: PiRecoveryDecision;
+    }> = [];
+    for (const submissionId of this.db.submissions.listUnfinishedIds()) {
+      const submission = this.readSubmission(submissionId);
+      if (
+        !submission?.assemblyRevision ||
+        !submission.assemblyDescriptor ||
+        submission.assemblyRevision === revision
+      ) {
+        continue;
+      }
+      const decision = this.decidePiRecovery(submission, {
+        kind: "repin-assembly",
+        nextAssemblyRevision: revision,
+      });
+      plans.push({ submission, decision });
+    }
+    let settled = false;
+    let committed = false;
+    const cleanup = () => {
+      for (const { submission } of plans) {
+        this.migratedSubmissions.delete(submission.submissionId);
+      }
+    };
+    return {
+      commit: () => {
+        if (settled) throw new Error("Parked Submission repin already settled");
+        for (const { submission } of plans) {
+          this.migratedSubmissions.add(submission.submissionId);
+        }
+        try {
+          this.db.transaction(() => {
+            for (const { submission, decision } of plans) {
+              this.applyPiRecoveryMutations(submission, decision.mutations);
+              this.db.submissions.repinAssembly(
+                submission.submissionId,
+                revision,
+                descriptor,
+              );
+            }
+          });
+          committed = true;
+        } catch (error) {
+          settled = true;
+          cleanup();
+          throw error;
+        }
+      },
+      interrupt: async () => {
+        if (!committed || settled) return;
+        try {
+          for (const { submission } of plans) {
+            const submissionId = submission.submissionId;
+            await this.submissions.interrupt(
+              submissionId,
+              () => this.approvals.discardWaiters(submissionId),
+            );
+          }
+        } finally {
+          settled = true;
+          cleanup();
+        }
+      },
+      abort: () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+      },
+    };
+  }
+
   // 作用：检查 Submission 保存的装配描述与 revision 仍然匹配。
   // 调用：普通恢复和审批续跑在重建 Pi Turn 前调用。
   // 原因：若持久描述已变，继续执行会把同一 Turn 切成两套能力语义。
@@ -1171,6 +1425,28 @@ export abstract class AgentRuntimeKernel<
         );
         continue;
       }
+      if (mutation.kind === "record-interaction") {
+        this.db.interactions.insert({
+          interactionId: mutation.interaction.interactionId,
+          submissionId: submission.submissionId,
+          requestId: mutation.interaction.requestId,
+          toolCallId: mutation.interaction.toolCallId,
+          toolName: mutation.interaction.toolName,
+          inputJson: mutation.interaction.inputJson,
+          status: "pending",
+          createdAt: mutation.interaction.createdAt,
+        });
+        continue;
+      }
+      if (mutation.kind === "settle-interaction") {
+        this.db.interactions.settle(
+          mutation.interactionId,
+          mutation.status,
+          mutation.settledAt,
+          mutation.responseJson,
+        );
+        continue;
+      }
       const inserted = this.db.milestones.upsert(
         submission.submissionId,
         mutation.key,
@@ -1393,7 +1669,11 @@ export abstract class AgentRuntimeKernel<
         latest,
         effectiveMessage ?? "Turn ended before approval",
       );
-      if (closedApprovals) {
+      // 还挂着的 interaction 同样要收尾，否则 Turn 结束后 pending 行会变成孤儿，
+      // 用户还能看见一张点了没反应的卡。
+      const closedInteractions = this.interactions
+        .cancelPendingForSubmissionSync(latest);
+      if (closedApprovals || closedInteractions) {
         this.materializeRecoveredToolResultsSync(latest);
       }
       const status =
@@ -1469,20 +1749,7 @@ export abstract class AgentRuntimeKernel<
     } catch (error) {
       console.error("[chat-recovery] terminal settlement failed", error);
     }
-    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);
+    await this.broadcastApprovals();
     try {
       if (
         effectiveOutcome === "failed" ||
@@ -1732,6 +1999,7 @@ export abstract class AgentRuntimeKernel<
         failed.status === "error"
           ? failed.error ?? "Pi turn failed"
           : undefined,
+        recovery,
       );
       return failed;
     } finally {
@@ -1884,6 +2152,12 @@ export abstract class AgentRuntimeKernel<
           }
         },
       );
+      // 换装配把这条执行器中断掉了：Submission 没有结束，它在等持久续跑用新
+       // 装配重建一条接着跑。这里写终态会把那一轮当场杀掉。
+      if (this.migratedSubmissions.has(submissionId)) {
+        if (streamId) this.failRecoverableStream(streamId);
+        return this.readSubmission(submissionId)!;
+      }
       const intent = terminalIntent ?? {
         outcome: "failed" as const,
         message:
@@ -1898,6 +2172,11 @@ export abstract class AgentRuntimeKernel<
       await this.projectTerminal(turn, terminal);
       return terminal;
     } catch (error) {
+      // 同上：中断出来的 abort 不是失败，也不是取消。
+      if (this.migratedSubmissions.has(submissionId)) {
+        if (streamId) this.failRecoverableStream(streamId);
+        return this.readSubmission(submissionId)!;
+      }
       const stalled = error instanceof ChatStreamStalledError;
       const abortReason = this.readSubmission(submissionId)?.abortReason;
       if (!abortReason && (stalled || error instanceof RetryableModelError)) {
@@ -1943,7 +2222,9 @@ export abstract class AgentRuntimeKernel<
                 messages: await this.getMessages(),
               }));
               if (streamId) this.completeRecoverableStream(streamId);
-              this.sendChatResponse(submission.requestId, "", true);
+              this.sendChatResponse(submission.requestId, "", true, {
+                continuation: turn.continuation,
+              });
             },
           );
           if (
@@ -2011,17 +2292,24 @@ export abstract class AgentRuntimeKernel<
     const persist = streamId
       ? this.appendRecoverableChunk(streamId, body)
       : Promise.resolve();
-    this.sendChatResponse(turn.requestId, body, false);
+    this.sendChatResponse(turn.requestId, body, false, {
+      continuation: turn.continuation,
+    });
     await persist;
   }
 
-  private sendChatTerminal(requestId: string, error?: string): void {
+  private sendChatTerminal(
+    requestId: string,
+    error?: string,
+    continuation = false,
+  ): void {
     this.sendChatResponse(
       requestId,
       error
         ? json({ type: "error", errorText: error } satisfies UIMessageChunk)
         : "",
       true,
+      { continuation },
     );
   }
 
@@ -2037,21 +2325,17 @@ export abstract class AgentRuntimeKernel<
       submission.status === "error"
         ? submission.error ?? "Pi turn failed"
         : undefined,
+      turn.continuation,
     );
     const messages = await this.getMessages();
-    await this.broadcastApprovals(
-      submission.status === "completed" &&
-          submissionNeedsInput(messages, submission.assistantMessageId)
-        ? "needs-input"
-        : "idle",
-    );
+    await this.broadcastApprovals();
     this.broadcast(
       json({
         type: MessageType.CF_AGENT_CHAT_MESSAGES,
         messages,
       }),
     );
-    const events = this.assembly().bindings.turnEvents;
+    const events = this.turnEventsPort();
     if (events) {
       try {
         await events.onResponse(
@@ -2200,7 +2484,7 @@ export abstract class AgentRuntimeKernel<
         ReturnType<AgentRuntimeKernel["submitMessage"]>
       >;
       try {
-        const normalized = this.pi.normalizeUserInput(latest);
+        const normalized = await this.normalizeUIUserInput(latest);
         submitted = await this.submitMessage(normalized, {
           requestId: event.id,
           idempotencyKey: event.id,
@@ -2285,6 +2569,18 @@ export abstract class AgentRuntimeKernel<
     return this.transcript.browserMessages();
   }
 
+  /** 读取当前 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 回环端口
@@ -2476,6 +2772,19 @@ export abstract class AgentRuntimeKernel<
     return submitted.receipt;
   }
 
+  // 作用：找出当前停在「等客户端结算某个 Tool」上的 Submission。
+  // 调用：dispatchMessage 判断要不要把 delivery 提升成 steer 时调用。
+  // 原因：park 期间 DO 可能已经睡过一觉，内存里的 active turn 不可信，只能问数据库。
+  private findInteractionParkedSubmission(): StoredSubmission | null {
+    const running = this.db.submissions.findRunning() as
+      | StoredSubmission
+      | null;
+    return running &&
+      this.interactions.hasPendingForSubmission(running.submissionId)
+      ? running
+      : null;
+  }
+
   async dispatchMessage(
     message: UIMessage,
     delivery: MessageDelivery,
@@ -2493,12 +2802,26 @@ export abstract class AgentRuntimeKernel<
       };
     }
 
-    const userMessage = this.pi.normalizeUserInput(
-      message as UIMessage & { role: "user" },
-    );
-    if (delivery === "steer") {
+    let userMessage: PiCanonicalUserInput;
+    try {
+      userMessage = await this.normalizeUIUserInput(
+        message as UIMessage & { role: "user" },
+      );
+    } catch (error) {
+      return {
+        kind: "rejected",
+        code: "invalid_message",
+        message: errorText(error),
+      };
+    }
+    // 停在 interaction park 上的 Turn 一律按 steer 处理，哪怕客户端发的是 enqueue：
+    // enqueue 要等本 Turn 结束，而本 Turn 正在等一个永远不会来的答案 —— 死锁。
+    const parked = this.findInteractionParkedSubmission();
+    const effectiveDelivery = parked ? "steer" : delivery;
+    if (effectiveDelivery === "steer") {
       const active = this.submissions.currentActive();
-      const target = active ??
+      const target = parked ??
+        active ??
         this.db.submissions.findRunning() ??
         this.db.submissions.findNextPending();
       if (target) {
@@ -2531,6 +2854,14 @@ export abstract class AgentRuntimeKernel<
           }
           await this.broadcastApprovals();
         }
+        // 先落 steer 再取消：取消会唤醒 park 住的 Tool 让 Turn 继续跑，
+        // 顺序反过来 Turn 可能在这条消息落盘前就跑完了。
+        if (parked?.submissionId === target.submissionId) {
+          await this.interactions.cancelPendingForSubmission(
+            target.submissionId,
+            "user_replied_freeform",
+          );
+        }
         return {
           kind: "accepted",
           submissionId: target.submissionId,
@@ -2804,6 +3135,43 @@ export abstract class AgentRuntimeKernel<
     };
   }
 
+  /**
+   * 把客户端投递的响应作为某次 Tool 调用的结果，并续跑原 Turn。
+   *
+   * @remarks
+   * 前端经 WS RPC 调用，只带 `toolCallId` —— 它不知道 submissionId，也不该知道。
+   *
+   * 这是「结果由客户端提供」的 Tool 的唯一入口。与审批不同，这里没有任何业务身份
+   * （审批的 `allow_level` 要改 User Agent 授权档位，所以必须经 Host），因此留在 Runtime。
+   *
+   * 查无、已结算、Tool 未声明 `interaction`、响应体不过校验，一律返回 `{ ok: false }` 而不抛 ——
+   * 口径对齐 `cancelSubmissionById`：客户端重复点击不该看到异常。
+   */
+  async respondToolInteraction(
+    toolCallId: string,
+    response: unknown,
+  ): Promise<{ ok: boolean }> {
+    const pending = this.interactions.findPending(toolCallId);
+    if (!pending) return { ok: false };
+    const submission = this.readSubmission(pending.submissionId);
+    if (!submission) return { ok: false };
+    await this.ensureRuntimeReady();
+
+    const adapter = this.createSubmissionExecutionAdapter(submission);
+    const spec = adapter.interactionSpec(pending.toolName);
+    if (!spec) return { ok: false };
+    if (!spec.validateResponse(response)) return { ok: false };
+
+    const input = safeParseJson(pending.inputJson);
+    const settled = spec.settle
+      ? spec.settle(input, response)
+      : defaultInteractionResult(response);
+    return this.interactions.respond(pending.interactionId, response, {
+      content: settled.content,
+      details: settled.details,
+    });
+  }
+
   /**
    * 对一条待处理执行应用一次允许或拒绝决定。
    *
@@ -2917,12 +3285,47 @@ export abstract class AgentRuntimeKernel<
     }
   }
 
+  // 作用：Agent Tool 子运行开始后重算一次活动投影。
+  // 调用：Agents SDK 在登记子运行后调用。
+  // 原因：分离的子运行不进 Submission 表，不在这里重算，Host 的列表会显示成已经空闲。
+  override async onAgentToolStart(run: AgentToolRunInfo): Promise<void> {
+    await super.onAgentToolStart(run);
+    await this.broadcastApprovals();
+  }
+
+  // 作用：Agent Tool 子运行结束后重算一次活动投影。
+  // 调用：Agents SDK 在子运行进入终态或被中断后调用。
+  // 原因：中断且子进程仍在跑时活动不能落回空闲，判定只在 `hasRunningAgentTools` 一处。
+  override async onAgentToolFinish(
+    run: AgentToolRunInfo,
+    result: AgentToolLifecycleResult,
+  ): Promise<void> {
+    await super.onAgentToolFinish(run, result);
+    await this.broadcastApprovals();
+  }
+
+  async _cfDetachedNotifyFinish(
+    run: AgentToolRunInfo,
+    result: AgentToolLifecycleResult,
+  ): Promise<void> {
+    const outcome = result.status === "completed"
+      ? 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}` },
+    );
+  }
+
   // 作用：把审批、队列和 Session 活动投影到 Agent 可广播状态。
-  // 调用：启动、准入、审批变化和 Turn 完成时调用。
+  // 调用：启动、准入、审批变化、interaction 变化、子运行变化和 Turn 完成时调用。
   // 原因：这些都是可重建的 UI 投影，相同内容不重复 `setState`，投影失败也不能阻断执行。
-  private async broadcastApprovals(
-    inactiveActivity?: RuntimeActivity,
-  ): Promise<void> {
+  protected async broadcastApprovals(): Promise<void> {
     try {
       const approvals = [
         ...this.approvals.list(),
@@ -2997,19 +3400,25 @@ export abstract class AgentRuntimeKernel<
         ),
         queued,
       };
-      const activity: RuntimeActivity = approvals.length > 0
+      // activity 与这里其他字段一样，是当前 DB 的纯函数：不接受调用方的提示，
+      // 也不粘住上一次的值。needs-input 只有一个意思 —— 此刻真挂着一件等人回应
+      // 的事（审批，或结果由客户端结算的 Tool）。可重算因而能自愈：任何一次广播
+      // 都会把陈旧状态冲掉，不需要谁记得来清。
+      const activity: RuntimeActivity = approvals.length > 0 ||
+          (current &&
+            this.interactions.hasPendingForSubmission(current.submissionId))
         ? "needs-input"
         : current || queued.length > 0
           ? "working"
-          : inactiveActivity ??
-            (this.state.activity?.activity === "needs-input"
-              ? "needs-input"
-              : "idle");
+          : "idle";
+      const backgroundWork = this.db.agentTools.hasRunning();
       const currentActivity = this.state.activity;
-      const nextActivity = currentActivity?.activity === activity
+      const nextActivity = currentActivity?.activity === activity &&
+          currentActivity.backgroundWork === backgroundWork
         ? currentActivity
         : {
             activity,
+            backgroundWork,
             revision: (currentActivity?.revision ?? 0) + 1,
           };
       if (
@@ -3025,8 +3434,7 @@ export abstract class AgentRuntimeKernel<
           turn,
         });
       }
-      const projection = this.runtimeSnapshot?.bindings.turnEvents
-        ?.onActivityChanged?.(nextActivity);
+      const projection = this.turnEventsPort()?.onActivityChanged?.(nextActivity);
       if (projection) {
         this.ctx.waitUntil(
           projection.catch(() => undefined),