@springbrand/agent-runtime 0.1.3-alpha.2 → 0.1.3-alpha.4

package/src/kernel/interaction-lifecycle.ts

@@ -0,0 +1,395 @@
+import {
+  isTerminalSubmissionStatus,
+  type RuntimeDatabase,
+  type StoredToolInteraction,
+  type SubmissionStatus,
+} from "../db";
+import type {
+  PiDurableMutation,
+  PiRecoveryCommand,
+  PiRecoveryDecision,
+  PiRuntimeAdapter,
+  PiToolInteraction,
+  PiToolInteractionCancelReason,
+} from "../pi/runtime-adapter";
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+
+// #region 类型约定
+
+/**
+ * 提供 interaction 流程定位一次持久化提交所需的最小信息。
+ *
+ * @remarks
+ * 与 `ApprovalSubmission` 同形。这里只要求 park/续跑真正需要的字段，
+ * 避免 interaction 流程依赖完整提交模型。
+ */
+export interface InteractionSubmission {
+  readonly submissionId: string;
+  readonly requestId: string;
+  readonly assemblyRevision: string;
+  readonly status: SubmissionStatus;
+}
+
+/**
+ * 表示已经绑定到持久化提交的完整 interaction 记录。
+ */
+export interface InteractionRecord extends PiToolInteraction {
+  readonly submissionId: string;
+}
+
+/**
+ * 描述一次响应或取消要写入的 ToolResult 载荷。
+ *
+ * `content` / `details` 由 Tool 自己的 `settle` 映射产出 —— 本流程不解释响应体语义。
+ * 取消不带载荷，由纯函数层用固定文案兜底。
+ */
+export interface InteractionSettlementPayload {
+  readonly content: ToolResultMessage["content"];
+  readonly details: unknown;
+}
+
+// 宿主用这些依赖把 interaction 状态机接入数据库、Pi 恢复计算和 Turn 续跑。
+interface InteractionLifecycleOptions<
+  TSubmission extends InteractionSubmission,
+> {
+  readonly db: RuntimeDatabase;
+  readonly pi: PiRuntimeAdapter;
+  readonly findSubmission: (submissionId: string) => TSubmission | null;
+  readonly applyRecoveryMutations: (
+    submission: TSubmission,
+    mutations: readonly PiDurableMutation[],
+  ) => boolean;
+  readonly materializeRecoveredToolResults: (
+    submission: TSubmission,
+  ) => Promise<PiRecoveryDecision>;
+  /** 没有内存等待器时（DO 睡过一觉）把原 Turn 重新拉起来。 */
+  readonly resumeSubmission: (submissionId: string) => Promise<void>;
+  /**
+   * pending 集合发生变化后通知宿主重算活动状态投影。
+   *
+   * park 和结算都会触发。宿主的 needs-input 是 pending 行的纯函数，
+   * 没有这个回调，park 的那一刻不会有人去重算 —— 侧栏要等下一次广播才翻牌。
+   */
+  readonly onInteractionsChanged?: () => Promise<void>;
+}
+
+// #endregion
+
+// #region interaction 流程 API
+
+/**
+ * 管理「结果由客户端提供」的 Tool 从 park、等待、响应到续跑的完整过程。
+ *
+ * @remarks
+ * 与 `ApprovalLifecycle` 结构同源但显著更小 —— 不需要 `allow_level` 的 Host 协调、
+ * 不需要批准后 `retryTool`、不需要执行档位矩阵。两者的重复是**当前有意接受的**：
+ * 审批那条路已经跑在线上，等 interaction 跑稳后再考虑抽公共核，届时改的是这两个类，
+ * 不是恢复状态机。
+ *
+ * 续跑不走 interaction 专属的调度键：响应会同时写下一条权威 `tool-result` 里程碑，
+ * 因此复用 `planPiToolRecovery` 中既有的 `tool:<id>:settled` 分支。
+ */
+export class InteractionLifecycle<
+  TSubmission extends InteractionSubmission,
+> {
+  private readonly waiters = new Map<string, () => void>();
+
+  constructor(
+    private readonly options: InteractionLifecycleOptions<TSubmission>,
+  ) {}
+
+  /**
+   * 用工具调用标识查找唯一一条仍待响应的 interaction。
+   *
+   * @remarks
+   * `Runtime.respondToolInteraction` 调用它 —— 前端只有 `toolCallId`。
+   * 调用方必须把 `null` 当作没有安全匹配，不应猜测要处理哪条记录。
+   */
+  findPending(toolCallId: string): InteractionRecord | null {
+    const stored = this.options.db.interactions
+      .findPendingByToolCallId(toolCallId);
+    return stored ? toRecord(stored) : null;
+  }
+
+  /**
+   * 按 interactionId 读取一条完整记录，不存在时返回 null。
+   */
+  read(interactionId: string): InteractionRecord | null {
+    const stored = this.options.db.interactions.find(interactionId);
+    return stored ? toRecord(stored) : null;
+  }
+
+  /**
+   * 持久化一条 interaction，并暂停当前工具执行直到客户端投递响应。
+   *
+   * @remarks
+   * 执行适配器在 Tool 声明了 `interaction` 时调用它。
+   * 记录与恢复里程碑先在事务中落盘，再建立内存等待，保证重启仍能恢复 park 状态。
+   */
+  async request(
+    submission: TSubmission,
+    interaction: PiToolInteraction,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    const pending = this.options.db.transaction(() =>
+      this.ensurePending(submission, interaction)
+    );
+    // 必须在 wait 之前通知：wait 会一直挂到客户端投递，之后再通知就晚了一个回合。
+    await this.options.onInteractionsChanged?.();
+    return this.wait(pending, signal);
+  }
+
+  /**
+   * 应用客户端的首次响应，结算对应 Tool 并唤醒原 Turn。
+   *
+   * @remarks
+   * `Runtime.respondToolInteraction` 在校验并映射出 ToolResult 后调用它。
+   * 不存在、已结束或提交已终态都返回 `{ ok: false }`，不抛 —— 口径对齐 `ApprovalLifecycle.decide`。
+   */
+  async respond(
+    interactionId: string,
+    response: unknown,
+    payload: InteractionSettlementPayload,
+  ): Promise<{ ok: boolean }> {
+    return this.settle(interactionId, {
+      kind: "respond",
+      response,
+      result: payload,
+    });
+  }
+
+  /**
+   * 在用户没有作答的情况下结束一条 interaction 并让 Turn 继续。
+   *
+   * @remarks
+   * park 期间收到用户消息时调用（`user_replied_freeform`），提交进终态时也调用。
+   * 取消同样产出稳定 ToolResult，不是 Tool 失败 —— 否则模型会收到 tool_error 并倾向重试。
+   */
+  async cancel(
+    interactionId: string,
+    reason: PiToolInteractionCancelReason,
+  ): Promise<{ ok: boolean }> {
+    return this.settle(interactionId, { kind: "cancel", reason });
+  }
+
+  /**
+   * 把某次提交下仍待响应的全部 interaction 一次性取消。
+   *
+   * @remarks
+   * `dispatchMessage` 发现 park 期间来了用户消息时、以及提交进终态时调用。
+   * 返回是否真的取消过记录，调用方据此决定要不要广播。
+   */
+  async cancelPendingForSubmission(
+    submissionId: string,
+    reason: PiToolInteractionCancelReason,
+  ): Promise<boolean> {
+    const pending = this.options.db.interactions
+      .listPendingForSubmission(submissionId);
+    if (pending.length === 0) return false;
+    let cancelled = false;
+    for (const interactionId of pending) {
+      const result = await this.cancel(interactionId, reason);
+      cancelled ||= result.ok;
+    }
+    return cancelled;
+  }
+
+  /**
+   * 在同步终态事务里把某次提交下仍待响应的 interaction 全部取消。
+   *
+   * @remarks
+   * `Runtime.commitTerminalOutcome` 在提交终态的 `transaction` 内调用，因此必须是同步的。
+   * 这里只推进状态和里程碑，**不** materialize、**不** 续跑 —— Turn 正在结束，
+   * 调用方负责在同一事务内调用 `materializeRecoveredToolResultsSync`，口径对齐审批的 `rejectPending`。
+   *
+   * 返回是否真的取消过记录；没有 pending 时返回 false，调用方可据此跳过 materialize。
+   */
+  cancelPendingForSubmissionSync(
+    submission: TSubmission,
+    reason: PiToolInteractionCancelReason = "submission_terminal",
+  ): boolean {
+    const pending = this.options.db.interactions
+      .listPendingForSubmission(submission.submissionId);
+    if (pending.length === 0) return false;
+    for (const interactionId of pending) {
+      const decision = this.decideRecovery(submission, {
+        kind: "interaction-settlement",
+        interactionId,
+        settlement: { kind: "cancel", reason },
+      });
+      this.options.applyRecoveryMutations(submission, decision.mutations);
+    }
+    return true;
+  }
+
+  /**
+   * 判断某次提交当前是否停在等待客户端响应上。
+   *
+   * @remarks
+   * `dispatchMessage` 用它决定要不要把 delivery 提升成 steer —— 否则 enqueue 的消息
+   * 要等这个 Turn 结束，而这个 Turn 正在等一个不会来的答案，死锁。
+   */
+  hasPendingForSubmission(submissionId: string): boolean {
+    return this.options.db.interactions
+      .listPendingForSubmission(submissionId).length > 0;
+  }
+
+  // #endregion
+
+  // #region 内部
+
+  // 作用：把响应或取消统一走同一条持久化 + 唤醒路径。
+  // 调用：`respond` 和 `cancel`。
+  // 原因：两种结局的差别只在 ToolResult 从哪来，状态推进和续跑必须完全一致。
+  private async settle(
+    interactionId: string,
+    settlement:
+      | {
+          kind: "respond";
+          response: unknown;
+          result: InteractionSettlementPayload;
+        }
+      | { kind: "cancel"; reason: PiToolInteractionCancelReason },
+  ): Promise<{ ok: boolean }> {
+    const stored = this.read(interactionId);
+    if (!stored) return { ok: false };
+    const submission = this.options.findSubmission(stored.submissionId);
+    if (!submission || isTerminalSubmissionStatus(submission.status)) {
+      return { ok: false };
+    }
+    if (stored.status !== "pending") return { ok: false };
+
+    const decision = this.decideRecovery(submission, {
+      kind: "interaction-settlement",
+      interactionId,
+      settlement,
+    });
+    if (!decision.applied) return { ok: false };
+    this.options.db.transaction(() => {
+      this.options.applyRecoveryMutations(submission, decision.mutations);
+    });
+    const persisted = this.read(interactionId);
+    if (!persisted || persisted.status === "pending") {
+      return { ok: false };
+    }
+
+    // 把刚写下的权威 tool-result 落成 settlement 行 —— park 住的执行链醒来后
+    // 只认 findToolSettlement，不读里程碑。这一步必须早于唤醒。
+    await this.options.materializeRecoveredToolResults(submission);
+    // 先重算活动状态再唤醒：唤醒会把 Turn 一路跑下去，晚通知就会让「等待回复」
+    // 在续跑期间多挂一段时间。
+    await this.options.onInteractionsChanged?.();
+
+    const waiter = this.waiters.get(interactionId);
+    if (waiter) {
+      waiter();
+      return { ok: true };
+    }
+    // 没有内存等待器 = DO 在 park 期间睡过一觉，原 Turn 的执行栈已经没了。
+    // 走持久恢复把它重新拉起来，里程碑里的 tool-result 会被当成已结算结果复用。
+    await this.options.resumeSubmission(submission.submissionId);
+    return { ok: true };
+  }
+
+  // 作用：读取一个 Submission 的全部恢复里程碑正文。
+  // 原因：持久化历史必须作为恢复决策的唯一输入。
+  private milestoneBodies(submissionId: string): string[] {
+    return this.options.db.milestones.listBodies(submissionId);
+  }
+
+  // 作用：请求 Pi 根据当前里程碑给出下一步。
+  // 原因：所有路径共用同一决策入口，避免各自改写恢复状态。
+  private decideRecovery(
+    submission: TSubmission,
+    command: PiRecoveryCommand = { kind: "inspect" },
+  ): PiRecoveryDecision {
+    return this.options.pi.decideRecovery({
+      milestoneBodies: this.milestoneBodies(submission.submissionId),
+      identity: {
+        turnId: submission.submissionId,
+        assemblyRevision: submission.assemblyRevision,
+      },
+      command,
+      now: Date.now(),
+    });
+  }
+
+  // 作用：复用或创建一条 pending interaction。
+  // 调用：`request` 在准入事务内调用。
+  // 原因：已存在记录的字段冲突必须报错，不能把响应投给另一次调用。
+  private ensurePending(
+    submission: TSubmission,
+    interaction: PiToolInteraction,
+  ): InteractionRecord {
+    const existing = this.read(interaction.interactionId);
+    if (existing) {
+      if (
+        existing.requestId !== submission.requestId ||
+        existing.toolCallId !== interaction.toolCallId ||
+        existing.toolName !== interaction.toolName ||
+        existing.inputJson !== interaction.inputJson
+      ) {
+        throw new Error(
+          `Conflicting durable Tool interaction: ${interaction.toolCallId}`,
+        );
+      }
+      return existing;
+    }
+    // 表行和恢复里程碑都由 record-interaction 这一条命令产出，
+    // 不在这里直接 insert —— 两份状态分叉正是恢复最难查的一类 bug。
+    const decision = this.decideRecovery(submission, {
+      kind: "record-interaction",
+      interaction,
+    });
+    this.options.applyRecoveryMutations(submission, decision.mutations);
+    return { ...interaction, submissionId: submission.submissionId };
+  }
+
+  // 作用：等待当前进程里的客户端响应。
+  // 原因：内存 Promise 只负责唤醒当前请求，数据库仍负责持久状态以支持重启。
+  private wait(
+    interaction: InteractionRecord,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (interaction.status !== "pending") return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const abort = () => {
+        this.waiters.delete(interaction.interactionId);
+        reject(signal?.reason ?? new Error("Tool interaction aborted"));
+      };
+      if (signal?.aborted) {
+        abort();
+        return;
+      }
+      signal?.addEventListener("abort", abort, { once: true });
+      this.waiters.set(interaction.interactionId, () => {
+        signal?.removeEventListener("abort", abort);
+        this.waiters.delete(interaction.interactionId);
+        resolve();
+      });
+    });
+  }
+
+  // #endregion
+}
+
+// 把持久行转成流程内部使用的记录。
+// find / findPending 查到记录后调用，上层因而只看 Pi 的 interaction 形状。
+function toRecord(stored: StoredToolInteraction): InteractionRecord {
+  return {
+    interactionId: stored.interactionId,
+    submissionId: stored.submissionId,
+    requestId: stored.requestId,
+    toolCallId: stored.toolCallId,
+    toolName: stored.toolName,
+    inputJson: stored.inputJson,
+    status: stored.status,
+    createdAt: stored.createdAt,
+    ...(stored.respondedAt === null
+      ? {}
+      : { respondedAt: stored.respondedAt }),
+    ...(stored.responseJson === null
+      ? {}
+      : { responseJson: stored.responseJson }),
+  };
+}

package/src/kernel/public-contracts.ts

@@ -11,6 +11,8 @@
  * @packageDocumentation
  */
 export * from "./profile";
+export * from "./runtime-assembly-view";
+export * from "./runtime-config";
 export * from "../pi/message";
 export * from "./receipts";
 export * from "./state";

package/src/kernel/recoverable-chat-agent.ts

@@ -465,13 +465,20 @@ export abstract class RecoverableChatAgent<
    * @remarks
    * 子类在发送增量记录、成功终态或失败终态时调用；`done` 表示轮次终态，`error` 只在终态失败时设置。
    *
+   * `continuation` 必须与本轮 `runRecoverableChatFiber` 的取值一致。重放帧由
+   * `ResumableStream` 从 `is_continuation` 列自动补上这个标记，实时帧只能由调用方给出：
+   * 少了它，客户端会为续跑另建一个空的累加器，把已经渲染出来的那半条回答整条换掉。
+   *
    * 广播显式排除正在续传握手的连接，避免它们在历史流重放完成前同时收到实时帧。
    */
   protected sendChatResponse(
     requestId: string,
     body: string,
     done: boolean,
-    error = false,
+    options: {
+      readonly error?: boolean;
+      readonly continuation?: boolean;
+    } = {},
   ): void {
     this.broadcast(
       json({
@@ -479,7 +486,8 @@ export abstract class RecoverableChatAgent<
         id: requestId,
         body,
         done,
-        ...(error ? { error: true } : {}),
+        ...(options.error ? { error: true } : {}),
+        ...(options.continuation ? { continuation: true } : {}),
       }),
       [...this.pendingResumeConnections],
     );

package/src/kernel/runtime-assembly-view.ts

@@ -0,0 +1,37 @@
+import type { RuntimeDegradation } from "./degradation";
+import type {
+  RuntimeMemoryProfile,
+  RuntimeMcpServer,
+  ThinkingEffort,
+} from "./profile";
+import type { ExecutionLevel } from "../lib/execution-level";
+
+export interface RuntimeAssemblySkillBinding {
+  readonly name: string;
+  readonly description: string;
+  readonly script: {
+    readonly network: "none" | "full";
+    readonly workspace: "none" | "read" | "read-write";
+    readonly tools: readonly string[];
+  };
+}
+
+export interface RuntimeAssemblyExtension {
+  readonly name: string;
+  readonly version: string;
+}
+
+export interface RuntimeAssemblyView {
+  readonly revision: string | null;
+  readonly model: string;
+  readonly thinking: ThinkingEffort;
+  readonly executionLevel: ExecutionLevel;
+  readonly systemPrompt?: string;
+  readonly memory: RuntimeMemoryProfile;
+  readonly toolDeny: readonly string[];
+  readonly skills: readonly RuntimeAssemblySkillBinding[];
+  readonly extensions: readonly RuntimeAssemblyExtension[];
+  readonly subagents: readonly string[];
+  readonly mcpServers: readonly RuntimeMcpServer[];
+  readonly degradations: readonly RuntimeDegradation[];
+}

package/src/kernel/runtime-assembly.ts

@@ -0,0 +1,41 @@
+import type { RuntimeSnapshot } from "../runtime-assembler";
+import type { PreparedPiRuntime } from "../pi/runtime-adapter";
+import type { RuntimeAssemblyView } from "./runtime-assembly-view";
+export type * from "./runtime-assembly-view";
+
+/**
+ * Serializable view of the Runtime Snapshot currently installed on a Session facet.
+ *
+ * @remarks
+ * UI debug panels and Host tooling call `getRuntimeAssembly` to read what the
+ * Agent actually assembled, not what upstream configuration merely declared.
+ */
+export function projectRuntimeAssembly(
+  snapshot: RuntimeSnapshot,
+  revision: string | null,
+  prepared: Pick<PreparedPiRuntime, "degradations" | "extensions">,
+): RuntimeAssemblyView {
+  const { profile, bindings } = snapshot;
+  return {
+    revision,
+    model: profile.model,
+    thinking: profile.thinking,
+    executionLevel: profile.executionLevel,
+    ...(profile.systemPrompt ? { systemPrompt: profile.systemPrompt } : {}),
+    memory: { ...profile.memory },
+    toolDeny: [...(profile.denyPolicy?.deny ?? [])],
+    skills: bindings.skills.sources.map((binding) => ({
+      name: binding.name,
+      description: binding.description,
+      script: {
+        network: binding.script.network,
+        workspace: binding.script.workspace,
+        tools: [...binding.script.tools],
+      },
+    })),
+    extensions: prepared.extensions.map((extension) => ({ ...extension })),
+    subagents: [...profile.enabledSubagents],
+    mcpServers: profile.mcpServers.map((server) => ({ ...server })),
+    degradations: prepared.degradations.map((degradation) => ({ ...degradation })),
+  };
+}

package/src/kernel/runtime-config.ts

@@ -0,0 +1,4 @@
+export interface RuntimeConfigUpdateResult<Change> {
+  readonly change: Change;
+  readonly runtime: "unchanged" | "reloaded" | "reload-failed";
+}

package/src/kernel/runtime-load.ts

@@ -0,0 +1,102 @@
+import type { RuntimeLoadPhase, RuntimeLoadState } from "./state";
+
+/**
+ * 装载状态机与宿主之间的全部接触面。
+ *
+ * @remarks
+ * 只有这三项：读上一次发布的状态、发布新状态、回答旧 Runtime 是否仍可服务。
+ * 追踪器碰不到 Kernel 的 Snapshot、数据库或 Submission，因此它的行为可以脱离
+ * Durable Object 单独验证。
+ */
+export interface RuntimeLoadPort {
+  read(): RuntimeLoadState | undefined;
+  publish(next: RuntimeLoadState): void;
+  /** 旧 Runtime 是否仍在服务；强制重载失败时它可能仍为 true。 */
+  isAvailable(): boolean;
+}
+
+/**
+ * 维护一次 Runtime 装载尝试的公开状态机。
+ *
+ * @remarks
+ * 宿主在装载的各个边界调用 `begin` / `advance` / `complete` / `fail`，
+ * 由本类统一发布 `RuntimeLoadState` 的形状与时间戳。
+ *
+ * `startedAt` 表示一次尝试的开始时刻：`begin` 重置它，其余转移沿用它，
+ * 使前端可以按同一基准显示耗时。
+ */
+export class RuntimeLoadTracker {
+  constructor(
+    private readonly port: RuntimeLoadPort,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  // 作用：把状态清回未装载。
+  // 调用：Durable Object 启动时调用。
+  // 原因：实例刚被唤醒时没有任何在途尝试，旧记录里的 ready 不能继续对外承诺。
+  reset(): void {
+    this.port.publish({ status: "idle", available: false });
+  }
+
+  // 作用：开始一轮新的装载尝试。
+  // 调用：宿主在调用 Definition config.read 前调用。
+  // 原因：config 阶段可能包含身份、D1 和 Resource 解析，必须在首个慢请求前可见。
+  begin(): void {
+    const now = this.now();
+    this.port.publish({
+      status: "loading",
+      phase: "config",
+      available: this.port.isAvailable(),
+      startedAt: now,
+      updatedAt: now,
+    });
+  }
+
+  // 作用：推进当前装载尝试的阶段。
+  // 调用：宿主在进入 Assembly、MCP 和 Pi 边界时调用。
+  // 原因：保持一个稳定的粗粒度协议，不向前端泄漏具体能力准备和并发细节。
+  advance(phase: RuntimeLoadPhase): void {
+    const now = this.now();
+    this.port.publish({
+      status: "loading",
+      phase,
+      available: this.port.isAvailable(),
+      startedAt: this.startedAt(now),
+      updatedAt: now,
+    });
+  }
+
+  // 作用：把成功提交的装载尝试标记为可用。
+  // 调用：宿主在配置初始化和 Runtime key 提交完成后调用。
+  // 原因：只有完整原子提交后才能向客户端承诺 ready。
+  complete(): void {
+    const now = this.now();
+    this.port.publish({
+      status: "ready",
+      available: true,
+      startedAt: this.startedAt(now),
+      completedAt: now,
+    });
+  }
+
+  // 作用：记录装载失败，同时保留旧 Runtime 是否仍可用的信息。
+  // 调用：宿主收口 Config 读取或 Runtime 装配异常时调用。
+  // 原因：前端需要状态但不应接收可能包含存储细节的底层错误文本。
+  fail(): void {
+    const now = this.now();
+    const current = this.port.read();
+    this.port.publish({
+      status: "error",
+      phase: current?.status === "loading" ? current.phase : "config",
+      available: this.port.isAvailable(),
+      startedAt: this.startedAt(now),
+      failedAt: now,
+    });
+  }
+
+  // 同一轮尝试内沿用原开始时刻；不在装载中说明这是一次孤立转移，只能以当下为准。
+  private startedAt(now: number): number {
+    const current = this.port.read();
+    return current?.status === "loading" ? current.startedAt : now;
+  }
+}

package/src/kernel/state.ts

@@ -1,11 +1,18 @@
 import type { ApprovalReceipt } from "./receipts";
 
-export type RuntimeLoadPhase = "config" | "plugins" | "mcp" | "pi";
+export type RuntimeLoadPhase = "config" | "assembly" | "mcp" | "pi";
 
 export type RuntimeActivity = "idle" | "working" | "needs-input";
 
 export interface RuntimeActivityProjection {
   activity: RuntimeActivity;
+  /**
+   * 是否仍有 Agent Tool 子运行在执行。
+   *
+   * `activity` 三态互斥，表达不了「等人回应的同时后台还在跑」。Host 的列表需要
+   * 这两件事各自成立，所以它是一个独立维度，而不是第四种活动值。
+   */
+  backgroundWork: boolean;
   revision: number;
 }
 

package/src/kernel/submission-lifecycle.ts

@@ -202,6 +202,13 @@ interface SubmissionLifecycleOptions<
   // 调用：`cancel` 命中活动执行器，或 `activate` 发现早到取消时调用。
   // 原因：生命周期不依赖具体执行器类型，只通过这个回调中断。
   abortActive(active: TActive): void;
+  /**
+   * 中断活动执行器，但让这条提交留给持久续跑接手。
+   *
+   * `interrupt` 调用。与 `abortActive` 的差别在结局而不在动作：中断不写终态，
+   * 也不接受这条执行器退场路上产生的任何工具结算。
+   */
+  interruptActive(active: TActive): void;
 }
 
 // #endregion
@@ -528,6 +535,29 @@ export class SubmissionLifecycle<
     };
   }
 
+  /**
+   * 中断一条提交的活动执行器，但不写取消原因，也不写终态。
+   *
+   * @remarks
+   * 宿主在 park 期间换掉装配后调用：内存里那条执行器的系统提示和工具表锁在它
+   * 自己被创建的那一刻，续跑不可能带上新能力，必须让位给持久续跑路径重建一条。
+   *
+   * 返回的 Promise 在旧执行器真正退场后才完成，调用方必须等它 —— 否则决策会
+   * 看到还没散场的内存等待器，又把这一轮唤回旧装配上。没有活动执行器时是空操作。
+   */
+  async interrupt(
+    submissionId: string,
+    afterAbort?: () => void,
+  ): Promise<void> {
+    const active = this.activeBySubmission.get(submissionId);
+    if (!active) return;
+    // 先中断再拆等待器：反过来的话，park 住的工具会先醒来、发现自己没有结算，
+    // 然后真的把工具跑一遍 —— 而这一轮本来就该让位。
+    this.options.interruptActive(active);
+    afterAbort?.();
+    await this.executions.get(submissionId)?.catch(() => undefined);
+  }
+
   /**
    * 返回当前唯一活动的执行器。
    *