@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.10

package/src/runtime.ts

@@ -1,16 +1,23 @@
-import type { Connection } from "agents";
+import type {
+  AgentToolLifecycleResult,
+  AgentToolRunInfo,
+  Connection,
+} from "agents";
 import {
+  ChatStreamStalledError,
   MessageType,
   clearChatTerminal,
   parseProtocolMessage,
   recordChatTerminal,
   sendIfOpen,
+  type ChatRecoveryConfig,
 } from "agents/chat";
 import { RecoverableChatAgent } from "./kernel/recoverable-chat-agent";
 import {
   ApprovalLifecycle,
   type ApprovalContinuationData,
 } from "./kernel/approval-lifecycle";
+import { InteractionLifecycle } from "./kernel/interaction-lifecycle";
 import {
   SubmissionLifecycle,
   SubmissionQueueFullError,
@@ -27,29 +34,41 @@ 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 {
-  initializeRuntimeConfig,
-  type AgentConfig,
+  RuntimeLoadTracker,
+  withRuntimeLoadTimeout,
+} from "./kernel/runtime-load";
+import {
+  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 {
   PiRuntimeAdapter,
+  MODEL_STREAM_STALL_TIMEOUT_MS,
+  readModelStreamStallDetails,
+  RetryableModelError,
   type PiCanonicalUserInput,
   type PiCanonicalTranscriptSnapshot,
   type PiChatRecoveryData,
   type UIChatRequestBody,
+  type RequestedCapability,
   type PiDurableMutation,
   type PiRecoveryCommand,
   type PiRecoveryDecision,
@@ -61,7 +80,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,
@@ -91,6 +114,15 @@ import {
 
 const SCHEDULED_STABLE_TIMEOUT_MS = 30_000;
 const TURN_EVENT_RETRY_SECONDS = 10;
+export const CHAT_RECOVERY_MAX_ATTEMPTS = 5;
+// stall 单独收窄。理由不是「stall 更不值得救」,而是它的重试**期望值和别的错不一样**:
+// 瞬时错(5xx / 断流)重跑一次往往就好了;stall 的重跑是拿同一份 transcript 让模型
+// 重新想同样久,如果它本来就超预算,再跑几次也一样超。把看门狗放宽到 240s 之后,
+// 真该救的那一类已经在第一次就跑完了,剩下还在 stall 的基本是连接真死——
+// 那种情况下 5 次 × 240s ≈ 20 分钟的空转纯属折磨用户。3 次约 12 分钟封顶。
+export const CHAT_STALL_MAX_ATTEMPTS = 3;
+const CHAT_RECOVERY_TERMINAL_MESSAGE =
+  "多次恢复仍未成功，本次生成已停止，当前进度已保留。请发送新消息继续。";
 
 type RuntimeEventOutboxPayload =
   | { readonly type: "model-usage"; readonly event: RuntimeModelUsageEvent }
@@ -110,6 +142,8 @@ interface StoredSubmission extends SubmissionReceipt {
   queuedUiMessageJson?: string | null;
   userMessageId?: string | null;
   regenerateMessageId?: string | null;
+  recoveryErrorCount: number;
+  recoveryReason?: "no_meaningful_model_progress" | "transient_model_error";
 }
 
 interface SubmitMessageOptions {
@@ -144,6 +178,16 @@ function json(value: unknown): string {
   return JSON.stringify(value);
 }
 
+async function closeRuntimeGatewaySession(
+  session: RuntimeGatewaySession | undefined,
+  step: string,
+): Promise<void> {
+  if (!session) return;
+  await withRuntimeLoadTimeout(step, () => session.close()).catch(
+    () => undefined,
+  );
+}
+
 function assistantUsageEvent(
   eventId: string,
   submissionId: string,
@@ -165,6 +209,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"
@@ -173,20 +238,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 {
@@ -210,6 +297,11 @@ interface PendingTemporaryAgentApproval {
 export abstract class AgentRuntimeKernel<
   Env extends Cloudflare.Env = Cloudflare.Env,
 > extends RecoverableChatAgent<Env, RuntimeState, PiChatRecoveryData> {
+  override chatRecovery: ChatRecoveryConfig = {
+    maxAttempts: CHAT_RECOVERY_MAX_ATTEMPTS,
+    terminalMessage: CHAT_RECOVERY_TERMINAL_MESSAGE,
+  };
+
   initialState: RuntimeState = {
     runtimeLoad: { status: "idle", available: false },
   };
@@ -219,6 +311,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<
@@ -226,7 +321,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 =
@@ -241,6 +339,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 实例建立持久化与执行协作器。
    *
@@ -292,6 +408,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),
@@ -329,6 +446,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 里程碑。
@@ -352,15 +485,25 @@ export abstract class AgentRuntimeKernel<
         };
       },
       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}`,
-            };
+        try {
+          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}`,
+              };
+        } catch (error) {
+          if (
+            error instanceof ChatStreamStalledError ||
+            error instanceof RetryableModelError
+          ) {
+            return { status: "scheduled" as const };
+          }
+          throw error;
+        }
       },
       failTurn: async (submissionId, message) => {
         const submission = this.readSubmission(submissionId);
@@ -375,49 +518,121 @@ 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 withRuntimeLoadTimeout(
+          "gateway.open",
+          () => candidateSnapshot.bindings.gateway!.open(
+            `${this.ctx.id.toString()}:${crypto.randomUUID()}`,
+          ),
+          {
+            onLateResult: (session) =>
+              closeRuntimeGatewaySession(session, "gateway.close.late"),
+          },
+        );
+      } 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 closeRuntimeGatewaySession(gatewaySession, "gateway.close.failed");
+      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 closeRuntimeGatewaySession(gatewaySession, "gateway.close.contested");
       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 withRuntimeLoadTimeout(
+          "parked-submission.repin",
+          () => this.prepareParkedSubmissionRepin(prepared, revision),
+        )
+      : undefined;
+    let activated = false;
+    const previousGatewaySession = this.runtimeGatewaySession;
+    try {
+      for (const [index, guard] of candidate.commitGuards.entries()) {
+        await withRuntimeLoadTimeout(`commit-guard:${index}`, 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 closeRuntimeGatewaySession(gatewaySession, "gateway.close.aborted");
+      throw error;
     }
+    if (repin) {
+      await withRuntimeLoadTimeout(
+        "parked-submission.interrupt",
+        () => repin.interrupt(),
+      ).catch(() => undefined);
+    }
+    await closeRuntimeGatewaySession(
+      previousGatewaySession,
+      "gateway.close.previous",
+    );
+
     const degradations = prepared.degradations;
     if (degradations.length > 0) {
       console.warn(
@@ -450,7 +665,6 @@ export abstract class AgentRuntimeKernel<
     const startedAt = output.startedAt ?? Date.now();
     return this.pi.createTurn({
       prepared: this.preparedPi(),
-      baseRevision: this.baseRevision(),
       pinnedDescriptor: submission.assemblyDescriptor,
       submission: {
         id: submission.submissionId,
@@ -472,7 +686,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,
                 });
@@ -484,6 +698,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) =>
@@ -498,6 +716,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") {
@@ -565,7 +787,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()),
@@ -590,7 +812,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;
@@ -719,78 +941,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,
-    });
-  }
+  private async normalizeUIUserInput(
+    message: UIMessage & { role: "user" },
+  ): Promise<PiCanonicalUserInput> {
+    const capabilities = requestedCapabilitiesOf(message.metadata);
+    if (capabilities.length === 0) return this.pi.normalizeUserInput(message);
 
-  // 作用：推进当前 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,
-    });
+    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 回环绑定。
@@ -833,19 +1033,23 @@ export abstract class AgentRuntimeKernel<
       .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。
+  /**
+   * 正在被换装配中断、等待持久续跑接手的 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(
@@ -867,13 +1071,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),
     });
@@ -911,6 +1133,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 切成两套能力语义。
@@ -922,23 +1227,24 @@ export abstract class AgentRuntimeKernel<
       await this.hash(submission.assemblyDescriptor)
     ) {
       throw new Error(
-        "Pinned Runtime revision is unavailable for Pi recovery",
+        "Pinned Runtime assembly descriptor is invalid",
       );
     }
   }
 
-  // 作用：按当前内存预算和模型压缩 Pi 上下文。
+  // 作用：按当前模型输入预算压缩 Pi 上下文。
   // 调用：Pi Turn 适配器在发模型请求前通过 `transformContext` 回调。
-  // 原因：压缩必须使用本 Snapshot 的模型和密钥，不能脱离已固定的 Runtime 配置。
+  // 原因：模型窗口必须预留最大输出，压缩也必须使用本 Snapshot 的模型和密钥。
   private async transformPiContext(
     submissionId: string,
     messages: Parameters<PiRuntimeTranscript["compactContext"]>[0],
     signal?: AbortSignal,
   ): ReturnType<PiRuntimeTranscript["compactContext"]> {
     const snapshot = this.assembly();
+    const inputBudget = snapshot.pi.model.contextWindow -
+      snapshot.pi.model.maxTokens;
     const compacted = await this.transcript.compactContext(messages, {
-      compactAfterTokens:
-        snapshot.profile.memory.compactAfterTokens,
+      compactAfterTokens: inputBudget * 0.85,
       model: snapshot.pi.model,
       apiKey: this.pi.resolveApiKey(
         snapshot.bindings.provider,
@@ -1150,6 +1456,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,
@@ -1177,12 +1505,41 @@ export abstract class AgentRuntimeKernel<
       kind: "record-tool-input",
       record: input,
     });
-    return this.db.transaction(() =>
+    const appended = this.db.transaction(() =>
       this.applyPiRecoveryMutations(
         submission,
         decision.mutations,
       ),
     );
+    if (appended) this.announceToolStart(submission.submissionId, input);
+    return appended;
+  }
+
+  // 作用：把「这个 Tool 开始跑了」连同参数投给 Host。
+  // 调用：durable intent 第一次落库之后，Tool 真正执行之前。
+  // 原因：人在等的是「正在写一个网页」，不是三十秒后的「write 完成了」。
+  //
+  // 只在第一次落库时发：恢复重放会再走一遍这条路径，那时 Tool 可能早就结束了，
+  // 再宣布一次「开始」比不宣布更糟。也不进 durable outbox —— 这是活性信号，
+  // 补投一条迟到的开始事件没有意义，投失败就算了，终态有 onToolSettled 兜底。
+  private announceToolStart(
+    submissionId: string,
+    input: PiToolInputRecord,
+  ): void {
+    const turnEvents = this.turnEventsPort();
+    if (!turnEvents?.onToolStart) return;
+    const delivery = turnEvents.onToolStart({
+      submissionId,
+      toolCallId: input.toolCallId,
+      toolName: input.toolName,
+      args: input.input,
+    }).catch((error: unknown) => {
+      console.warn(
+        "[runtime-tool-start:degraded]",
+        json({ toolCallId: input.toolCallId, error: errorText(error) }),
+      );
+    });
+    this.ctx.waitUntil(delivery);
   }
 
   // 作用：持久化一次 Tool 结果，并推进相应的恢复里程碑。
@@ -1372,7 +1729,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 =
@@ -1435,20 +1796,20 @@ export abstract class AgentRuntimeKernel<
       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.
-      }
+    try {
+      await this.settleChatRecovery(
+        latest.requestId,
+        effectiveOutcome === "succeeded"
+          ? "completed"
+          : effectiveOutcome === "aborted"
+            ? "skipped"
+            : "failed",
+        effectiveMessage,
+      );
+    } catch (error) {
+      console.error("[chat-recovery] terminal settlement failed", error);
     }
-    await this.broadcastApprovals(inactiveActivity);
+    await this.broadcastApprovals();
     try {
       if (
         effectiveOutcome === "failed" ||
@@ -1478,6 +1839,16 @@ export abstract class AgentRuntimeKernel<
   ): Promise<boolean> {
     let decision = await this.materializeRecoveredToolResults(submission);
     for (let step = 0; step < 32; step += 1) {
+      const latest = this.readSubmission(submission.submissionId);
+      if (!latest || isTerminalSubmissionStatus(latest.status)) return false;
+      if (latest.abortReason) {
+        await this.submissions.finish(
+          latest,
+          "aborted",
+          latest.abortReason,
+        );
+        return false;
+      }
       this.db.transaction(() => {
         this.applyPiRecoveryMutations(
           submission,
@@ -1655,13 +2026,24 @@ export abstract class AgentRuntimeKernel<
         submission.abortReason,
       );
     }
-    if (recovery) await this.ensureRuntimeReady();
+    if (recovery) {
+      this.db.submissions.clearRecoveryReason(submissionId);
+      await this.broadcastApprovals();
+      await this.ensureRuntimeReady();
+    }
     try {
       return await this.executeNonTerminalSubmission(
         submission,
         recovery,
       );
     } catch (error) {
+      if (
+        recovery &&
+        (error instanceof ChatStreamStalledError ||
+          error instanceof RetryableModelError)
+      ) {
+        throw error;
+      }
       const failed = await this.submissions.finish(
         submission,
         "failed",
@@ -1677,6 +2059,7 @@ export abstract class AgentRuntimeKernel<
         failed.status === "error"
           ? failed.error ?? "Pi turn failed"
           : undefined,
+        recovery,
       );
       return failed;
     } finally {
@@ -1711,11 +2094,33 @@ export abstract class AgentRuntimeKernel<
     }
     const recoveryAdapter = this.createSubmissionExecutionAdapter(submission);
     if (recovery) {
-      const ready = await this.prepareRecoveredTurn(
-        submission,
-        recoveryAdapter,
-      );
-      if (!ready) return this.readSubmission(submissionId)!;
+      const deactivatePreparation = this.submissions.activate(submission, {
+        submissionId,
+        requestId: submission.requestId,
+        messageId: submission.assistantMessageId,
+        startedAt: submission.createdAt,
+        continuation: true,
+        agent: recoveryAdapter,
+      });
+      let ready: boolean;
+      try {
+        ready = await this.prepareRecoveredTurn(
+          submission,
+          recoveryAdapter,
+        );
+      } finally {
+        deactivatePreparation();
+      }
+      if (!ready) {
+        const latest = this.readSubmission(submissionId)!;
+        return latest.abortReason
+          ? this.submissions.finish(
+              latest,
+              "aborted",
+              latest.abortReason,
+            )
+          : latest;
+      }
     } else {
       await this.materializeRecoveredToolResults(submission);
     }
@@ -1754,7 +2159,9 @@ export abstract class AgentRuntimeKernel<
       continuation: recovery,
       assistantOrdinal,
       onRecord: (record) =>
-        this.persistAndBroadcastRecord(turn, record),
+        this.migratedSubmissions.has(submissionId)
+          ? undefined
+          : this.persistAndBroadcastRecord(turn, record),
       onTerminal: (intent) => {
         terminalIntent = intent;
         this.appendTerminalIntent(
@@ -1807,6 +2214,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:
@@ -1821,13 +2234,85 @@ 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)) {
+        const recoveryErrorCount = this.db.submissions
+          .incrementRecoveryErrorCount(
+            submissionId,
+            stalled
+              ? "no_meaningful_model_progress"
+              : "transient_model_error",
+          );
+        if (stalled) {
+          const stallDetails = readModelStreamStallDetails(errorText(error)) ?? {
+            lastMeaningfulActivityAt:
+              Date.now() - MODEL_STREAM_STALL_TIMEOUT_MS,
+            lastMeaningfulActivityType: "model_stream_started",
+            idleMs: MODEL_STREAM_STALL_TIMEOUT_MS,
+          };
+          this._emit("chat:stream:stalled", {
+            requestId: submission.requestId,
+            submissionId,
+            attempt: recoveryErrorCount,
+            timeoutMs: MODEL_STREAM_STALL_TIMEOUT_MS,
+            ...stallDetails,
+            reason: "no_meaningful_model_progress",
+          });
+        }
+        await this.broadcastApprovals();
+        const stoppedDuringRecovery = this.readSubmission(submissionId)
+          ?.abortReason;
+        if (
+          !stoppedDuringRecovery &&
+          recoveryErrorCount <
+            (stalled ? CHAT_STALL_MAX_ATTEMPTS : CHAT_RECOVERY_MAX_ATTEMPTS)
+        ) {
+          const recoveryOutcome = await this.scheduleChatRecoveryRetry(
+            {
+              submissionId,
+              requestId: submission.requestId,
+            },
+            async () => {
+              this.broadcast(json({
+                type: MessageType.CF_AGENT_CHAT_MESSAGES,
+                messages: await this.getMessages(),
+              }));
+              if (streamId) this.completeRecoverableStream(streamId);
+              this.sendChatResponse(submission.requestId, "", true, {
+                continuation: turn.continuation,
+              });
+            },
+          );
+          if (
+            recoveryOutcome !== "disabled" &&
+            !this.readSubmission(submissionId)?.abortReason
+          ) {
+            if (recovery && recoveryOutcome === "scheduled") throw error;
+            return this.readSubmission(submissionId)!;
+          }
+        } else if (!stoppedDuringRecovery) {
+          terminalIntent = {
+            outcome: "failed",
+            message: CHAT_RECOVERY_TERMINAL_MESSAGE,
+          };
+        }
+      }
       const latest = this.readSubmission(submissionId);
-      const intent = terminalIntent ?? {
-        outcome: latest?.abortReason
-          ? ("aborted" as const)
-          : ("failed" as const),
-        message: errorText(error),
-      };
+      const intent = terminalIntent ?? (latest?.abortReason
+        ? {
+            outcome: "aborted" as const,
+            message: latest.abortReason,
+          }
+        : {
+            outcome: "failed" as const,
+            message: errorText(error),
+          });
       const failed = await this.submissions.finish(
         submission,
         intent.outcome,
@@ -1856,28 +2341,37 @@ export abstract class AgentRuntimeKernel<
     }
   }
 
-  // 作用：先持久化一条 Pi 流记录，再广播给在线客户端。
+  // 作用：持久化一条 Pi 流记录并广播给在线客户端。
   // 调用：活跃 Turn 适配器每产生一条 stream record 时调用。
-  // 原因：耐久写入早于 WebSocket 发送，断线客户端才能从同一序列续传。
+  // 原因：先发 WebSocket 再等持久化完成，让客户端零延迟收到 token，同时
+  // await 保证 Pi 的事件循环不越过尚未落盘的 chunk，续传完整性不受影响。
   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);
+    const persist = streamId
+      ? this.appendRecoverableChunk(streamId, body)
+      : Promise.resolve();
+    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 },
     );
   }
 
@@ -1893,21 +2387,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(
@@ -2056,7 +2546,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,
@@ -2080,7 +2570,7 @@ export abstract class AgentRuntimeKernel<
       if (submission) {
         await this.cancelSubmissionById(
           submission.submissionId,
-          "Client cancelled",
+          USER_STOP_REASON,
         );
       }
       return;
@@ -2141,6 +2631,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 回环端口
@@ -2332,6 +2834,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,
@@ -2349,12 +2864,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) {
@@ -2387,6 +2916,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,
@@ -2660,6 +3197,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,
+    });
+  }
+
   /**
    * 对一条待处理执行应用一次允许或拒绝决定。
    *
@@ -2773,12 +3347,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(),
@@ -2821,7 +3430,25 @@ export abstract class AgentRuntimeKernel<
       );
       const turn: RuntimeTurnState = {
         ...(current
-          ? { activeSubmissionId: current.submissionId }
+          ? {
+              activeSubmissionId: current.submissionId,
+              ...(current.requestId
+                ? { activeRequestId: current.requestId }
+                : {}),
+              ...(current.recoveryErrorCount === undefined
+                ? {}
+                : {
+                    recoveryAttempt: current.recoveryErrorCount,
+                    // 上限按当前恢复原因取,否则 stall 会显示 "2/5" 却在第 3 次就终止。
+                    recoveryMax:
+                      current.recoveryReason === "no_meaningful_model_progress"
+                        ? CHAT_STALL_MAX_ATTEMPTS
+                        : CHAT_RECOVERY_MAX_ATTEMPTS,
+                    ...(current.recoveryReason
+                      ? { recoveryReason: current.recoveryReason }
+                      : {}),
+                  }),
+            }
           : {}),
         steerable: Boolean(
           current &&
@@ -2835,19 +3462,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 (
@@ -2863,8 +3496,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),