@downcity/agent 1.1.276 → 1.1.278

package/src/session/Session.ts

@@ -74,6 +74,10 @@ import { nanoid } from "nanoid";
 import { buildSessionInfo } from "@/session/browse/Browse.js";
 import { ensureSessionTitle } from "@/session/SessionTitle.js";
 import { readSessionMetadata } from "@/session/storage/Metadata.js";
+import {
+  read_session_instruction,
+  write_session_instruction,
+} from "@/session/storage/Instruction.js";
 import { to_executor_history } from "@/session/messages/SessionMessageCodec.js";
 import type { SessionMessage } from "@/types/session/SessionMessage.js";
 import type {
@@ -91,7 +95,6 @@ export class Session implements AgentSession {
   private readonly project_root: string;
   private readonly tools: Record<string, Tool>;
   private readonly logger: SessionOptions["logger"];
-  private readonly get_instruction_system_blocks: SessionOptions["getInstructionSystemBlocks"];
   private readonly get_managed_plugin_system_blocks: SessionOptions["getManagedPluginSystemBlocks"];
   private readonly ensure_configured_hook?: SessionOptions["ensureConfigured"];
   private readonly composer: SessionComposer;
@@ -105,6 +108,7 @@ export class Session implements AgentSession {
   private readonly get_agent_model: SessionOptions["getAgentModel"];
   private readonly get_agent_plugins: SessionOptions["get_agent_plugins"];
   private effective_instruction_system_blocks: AgentSessionSystemBlock[];
+  private instruction_initialize_promise: Promise<void> | null = null;
   private effective_agent_env: Record<string, string>;
   private effective_agent_plugins: AgentPluginExecutionRuntime;
   private readonly state: SessionState;
@@ -117,12 +121,11 @@ export class Session implements AgentSession {
     this.project_root = String(options.projectRoot || "").trim();
     this.tools = options.tools;
     this.logger = options.logger;
-    this.get_instruction_system_blocks = options.getInstructionSystemBlocks;
     this.get_agent_env = options.getAgentEnv;
     this.get_agent_model = options.getAgentModel;
     this.get_agent_plugins = options.get_agent_plugins;
     this.effective_instruction_system_blocks = options
-      .getInstructionSystemBlocks()
+      .instruction_system_blocks
       .map((block) => ({ ...block }));
     this.effective_agent_env = { ...options.getAgentEnv() };
     this.effective_agent_plugins = options.get_agent_plugins();
@@ -188,11 +191,35 @@ export class Session implements AgentSession {
    * 初始化当前 session。
    */
   async initialize(): Promise<this> {
-    await this.session_messages.initialize();
-    await this.state.initialize();
+    await Promise.all([
+      this.initialize_instruction(),
+      this.session_messages.initialize(),
+      this.state.initialize(),
+    ]);
     return this;
   }
 
+  /**
+   * 把当前 Session 生效的自定义 instruction 显式固化到 instruction.md。
+   *
+   * 关键点（中文）
+   * - 只写入 `instruction` 来源的 block，不包含 SDK core 与 plugin system。
+   * - 多个 instruction block 按原顺序合并为一个 Markdown 文档。
+   */
+  async snapshot(): Promise<void> {
+    await this.initialize_instruction();
+    const instruction = this.effective_instruction_system_blocks
+      .filter((block) => block.source === "instruction")
+      .map((block) => block.content)
+      .join("\n\n");
+    await write_session_instruction({
+      project_root: this.project_root,
+      agent_id: this.agentId,
+      session_id: this.id,
+      instruction,
+    });
+  }
+
   /**
    * 读取当前 session 配置快照。
    */
@@ -214,6 +241,7 @@ export class Session implements AgentSession {
    * 追加一条新的 Session prompt。
    */
   async prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
+    await this.initialize_instruction();
     return await this.session_turn.prompt(input);
   }
 
@@ -236,14 +264,6 @@ export class Session implements AgentSession {
    * 把 Agent configured state command 加入当前 Session 的统一输入队列。
    */
   enqueue_agent_command(command: AgentSessionCommand): void {
-    if (command.type === "instruction") {
-      this.session_turn.enqueue_command({
-        type: "agent_instruction",
-        command_id: command.command_id,
-        instruction_blocks: command.instruction_blocks,
-      });
-      return;
-    }
     if (command.type === "env") {
       this.session_turn.enqueue_command({
         type: "agent_env",
@@ -277,18 +297,6 @@ export class Session implements AgentSession {
       }
       return;
     }
-    if (command.type === "agent_instruction") {
-      this.effective_instruction_system_blocks = command.instruction_blocks.map(
-        (block) => ({ ...block }),
-      );
-      await this.emit_config_action_event({
-        id: `agent-instruction:${this.id}:${command.command_id}`,
-        title: "Agent instruction updated",
-        state: "completed",
-        turnId: turn_id,
-      });
-      return;
-    }
     if (command.type === "agent_env") {
       this.effective_agent_env = { ...command.env };
       await this.emit_config_action_event({
@@ -406,6 +414,7 @@ export class Session implements AgentSession {
    * 读取当前 session 生效的 system 快照。
    */
   async system(): Promise<AgentSessionSystemSnapshot> {
+    await this.initialize_instruction();
     const composed = await this.compose_for_view();
     const blocks = resolve_composed_system_blocks(composed);
     return {
@@ -533,6 +542,7 @@ export class Session implements AgentSession {
    * 在执行前确保 session 已完成初始化与宿主装配。
    */
   async ensureReadyForExecution(): Promise<void> {
+    await this.initialize_instruction();
     await this.state.ensure_ready_for_execution();
   }
 
@@ -543,7 +553,9 @@ export class Session implements AgentSession {
       sessionId: session_id,
       tools: this.tools,
       logger: this.logger,
-      getInstructionSystemBlocks: this.get_instruction_system_blocks,
+      instruction_system_blocks: this.effective_instruction_system_blocks.map(
+        (block) => ({ ...block }),
+      ),
       getAgentEnv: this.get_agent_env,
       get_agent_plugins: this.get_agent_plugins,
       getManagedPluginSystemBlocks: this.get_managed_plugin_system_blocks,
@@ -567,6 +579,36 @@ export class Session implements AgentSession {
     return new SessionClass(options) as this;
   }
 
+  /** 恢复显式固化的 instruction.md；文件不存在时保留创建时 instruction。 */
+  private async initialize_instruction(): Promise<void> {
+    if (!this.instruction_initialize_promise) {
+      this.instruction_initialize_promise = (async () => {
+        const persisted_instruction = await read_session_instruction({
+          project_root: this.project_root,
+          agent_id: this.agentId,
+          session_id: this.id,
+        });
+        if (persisted_instruction === null) return;
+
+        const instruction = persisted_instruction.trim();
+        const stable_system_blocks = this.effective_instruction_system_blocks
+          .filter((block) => block.source !== "instruction")
+          .map((block) => ({ ...block }));
+        this.effective_instruction_system_blocks = [
+          ...(instruction
+            ? [{
+                source: "instruction" as const,
+                name: "agent",
+                content: instruction,
+              }]
+            : []),
+          ...stable_system_blocks,
+        ];
+      })();
+    }
+    await this.instruction_initialize_promise;
+  }
+
   private create_message_store(): JsonlSessionMessageStore {
     const session_dir_path = getSdkAgentSessionDirPath(
       this.project_root,

package/src/session/messages/SessionAssistantMessageWriter.ts

@@ -12,6 +12,7 @@ import {
   to_session_json_value,
   to_session_provider_metadata,
 } from "@/session/messages/SessionJsonValue.js";
+import { SessionToolPartGate } from "@/session/messages/SessionToolPartGate.js";
 import type {
   SessionAssistantFilePart,
   SessionAssistantMessage,
@@ -32,6 +33,7 @@ export class SessionAssistantMessageWriter {
   >();
   private readonly active_text_part_ids = new Map<string, string>();
   private readonly current_step_part_ids = new Set<string>();
+  private readonly tool_part_gate = new SessionToolPartGate();
   private write_chain: Promise<void> = Promise.resolve();
   private step_index = 0;
   private step_active = false;
@@ -108,8 +110,8 @@ export class SessionAssistantMessageWriter {
   /** 释放异常结束的 step 作用域并保留已经写入的 canonical Parts。 */
   async abort_step(): Promise<void> {
     await this.enqueue_write(async () => {
-      if (!this.step_active) return;
-      this.reset_step_state();
+      this.tool_part_gate.reject_pending("Assistant canonical step was aborted");
+      if (this.step_active) this.reset_step_state();
     });
   }
 
@@ -196,7 +198,7 @@ export class SessionAssistantMessageWriter {
           });
           return;
         }
-        await this.upsert_tool(chunk.toolCallId, {
+        await this.create_tool(chunk.toolCallId, {
           tool_name: chunk.toolName,
           state: "input-streaming",
           input_text: "",
@@ -210,6 +212,7 @@ export class SessionAssistantMessageWriter {
           ...(tool_metadata !== undefined ? { tool_metadata } : {}),
           ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
         });
+        this.tool_part_gate.mark_available(chunk.toolCallId);
         return;
       }
       case "tool-input-delta": {
@@ -251,7 +254,7 @@ export class SessionAssistantMessageWriter {
           });
           return;
         }
-        await this.upsert_tool(chunk.toolCallId, {
+        const changes = {
           tool_name: chunk.toolName,
           state: "ready",
           input: to_session_json_value(chunk.input),
@@ -264,7 +267,13 @@ export class SessionAssistantMessageWriter {
           ...(chunk.title !== undefined ? { title: chunk.title } : {}),
           ...(tool_metadata !== undefined ? { tool_metadata } : {}),
           ...(chunk.dynamic !== undefined ? { dynamic: chunk.dynamic } : {}),
-        });
+        } as const;
+        if (tool) {
+          await this.upsert_tool(chunk.toolCallId, changes);
+        } else {
+          await this.create_tool(chunk.toolCallId, changes);
+          this.tool_part_gate.mark_available(chunk.toolCallId);
+        }
         return;
       }
       case "tool-input-error": {
@@ -449,18 +458,21 @@ export class SessionAssistantMessageWriter {
 
   /** Executor 在调用 Tool 实现前写入完整输入。 */
   async prepare_tool_input(input: SessionToolInputReady): Promise<void> {
+    await this.tool_part_gate.wait_until_available(input.tool_call_id);
     await this.enqueue_write(async () => {
+      if (this.closed) throw new Error("Assistant Message writer is closed");
       const current = this.find_tool(input.tool_call_id);
-      if (current && current.state !== "input-streaming" && current.state !== "ready") {
+      if (!current) {
+        throw new Error(
+          `Assistant canonical Tool Part not found: ${input.tool_call_id}`,
+        );
+      }
+      if (current.state !== "input-streaming" && current.state !== "ready") {
         throw new Error(
           `Tool input cannot be prepared from ${current.state}: ${input.tool_call_id}`,
         );
       }
-      await this.upsert_tool(input.tool_call_id, {
-        tool_name: input.tool_name,
-        state: "ready",
-        input: to_session_json_value(input.input),
-      });
+      await this.write_prepared_tool_input(input);
     });
   }
 
@@ -692,23 +704,59 @@ export class SessionAssistantMessageWriter {
     this.pending_text_parts.delete(part_id);
   }
 
-  /** 创建或更新 Tool Part 完整快照。 */
+  /** 更新已经由 canonical stream 创建的 Tool Part。 */
   private async upsert_tool(
     tool_call_id: string,
     changes: Pick<SessionAssistantToolPart, "tool_name" | "state"> &
       Partial<Omit<SessionAssistantToolPart, "part_id" | "type" | "tool_call_id" | "tool_name" | "state">>,
   ): Promise<void> {
     const current = this.find_tool(tool_call_id);
+    if (!current) {
+      throw new Error(
+        `Assistant canonical Tool Part not found: ${tool_call_id}`,
+      );
+    }
     await this.upsert_part({
-      ...(current || {}),
+      ...current,
       part_id: `tool:${tool_call_id}`,
-      sequence: current?.sequence || this.next_part_sequence(),
+      sequence: current.sequence,
       type: "tool",
       tool_call_id,
       ...changes,
     });
   }
 
+  /** 仅由 Tool 输入 stream chunk 创建 canonical Tool Part。 */
+  private async create_tool(
+    tool_call_id: string,
+    changes: Pick<SessionAssistantToolPart, "tool_name" | "state"> &
+      Partial<Omit<SessionAssistantToolPart, "part_id" | "type" | "tool_call_id" | "tool_name" | "state">>,
+  ): Promise<void> {
+    if (this.find_tool(tool_call_id)) {
+      throw new Error(
+        `Assistant canonical Tool Part already exists: ${tool_call_id}`,
+      );
+    }
+    await this.upsert_part({
+      part_id: `tool:${tool_call_id}`,
+      sequence: this.next_part_sequence(),
+      type: "tool",
+      tool_call_id,
+      ...changes,
+    });
+  }
+
+  /** 将 Executor 完整输入写入已经由 stream 创建的 Tool Part。 */
+  private async write_prepared_tool_input(
+    input: SessionToolInputReady,
+  ): Promise<void> {
+    await this.upsert_tool(input.tool_call_id, {
+      tool_name: input.tool_name,
+      state: "ready",
+      input: to_session_json_value(input.input),
+    });
+  }
+
   /** 串行执行对当前 Assistant Message 的全部写操作。 */
   private async enqueue_write(operation: () => Promise<void>): Promise<void> {
     const current = this.write_chain.then(operation, operation);
@@ -721,6 +769,9 @@ export class SessionAssistantMessageWriter {
     status: "completed" | "stopped" | "failed",
   ): Promise<void> {
     if (this.closed) return;
+    this.tool_part_gate.close(
+      `Assistant Message writer closed with status ${status}`,
+    );
     this.reset_step_state();
     await this.recorder.complete_assistant_message(this.message_id, status);
     this.closed = true;

package/src/session/messages/SessionToolPartGate.ts

@@ -0,0 +1,67 @@
+/**
+ * canonical Tool Part 的并发等待门。
+ *
+ * Gate 只协调单个 `tool_call_id` 的可用状态，不接触 Message、Recorder 或
+ * Tool 输入。不同 Tool 使用独立 Promise，因此不会形成全局执行锁。
+ */
+
+import type { SessionToolPartWaiter } from "@/types/session/SessionTool.js";
+
+/** 按 Tool Call 隔离的 canonical Part 等待门。 */
+export class SessionToolPartGate {
+  private readonly available_tool_call_ids = new Set<string>();
+  private readonly pending_waiters = new Map<string, SessionToolPartWaiter>();
+  private closed_error: Error | null = null;
+
+  /** 等待指定 Tool Part 成功持久化；已经可用时立即完成。 */
+  wait_until_available(tool_call_id: string): Promise<void> {
+    if (this.closed_error) return Promise.reject(this.closed_error);
+    if (this.available_tool_call_ids.has(tool_call_id)) return Promise.resolve();
+
+    const current = this.pending_waiters.get(tool_call_id);
+    if (current) return current.promise;
+
+    const waiter = this.create_waiter();
+    this.pending_waiters.set(tool_call_id, waiter);
+    return waiter.promise;
+  }
+
+  /** 标记指定 Tool Part 已持久化，并只释放该 Tool 的等待者。 */
+  mark_available(tool_call_id: string): void {
+    if (this.closed_error) throw this.closed_error;
+    if (this.available_tool_call_ids.has(tool_call_id)) return;
+
+    this.available_tool_call_ids.add(tool_call_id);
+    const waiter = this.pending_waiters.get(tool_call_id);
+    if (!waiter) return;
+    this.pending_waiters.delete(tool_call_id);
+    waiter.resolve();
+  }
+
+  /** 拒绝当前尚未出现 canonical Part 的全部等待者。 */
+  reject_pending(reason: string): void {
+    for (const [tool_call_id, waiter] of this.pending_waiters) {
+      waiter.reject(new Error(`${reason}: ${tool_call_id}`));
+    }
+    this.pending_waiters.clear();
+  }
+
+  /** 永久关闭 Gate，并拒绝当前及后续等待。 */
+  close(reason: string): void {
+    if (this.closed_error) return;
+    this.closed_error = new Error(reason);
+    this.reject_pending(reason);
+    this.available_tool_call_ids.clear();
+  }
+
+  /** 创建单个 Tool Call 使用的异步等待句柄。 */
+  private create_waiter(): SessionToolPartWaiter {
+    let resolve!: () => void;
+    let reject!: (error: Error) => void;
+    const promise = new Promise<void>((resolve_promise, reject_promise) => {
+      resolve = resolve_promise;
+      reject = reject_promise;
+    });
+    return { promise, resolve, reject };
+  }
+}

package/src/session/storage/Instruction.ts

@@ -0,0 +1,59 @@
+/**
+ * Session instruction 显式快照存储。
+ *
+ * 关键点（中文）
+ * - instruction.md 是可选文件，不存在时由 Session 使用 Agent 当前 instruction。
+ * - 空文件也是有效快照，用于显式固化没有自定义 instruction 的状态。
+ * - 写入使用同目录临时文件替换，避免进程中断留下半份内容。
+ */
+
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import fs from "fs-extra";
+import { getSdkAgentSessionInstructionPath } from "@/session/storage/Paths.js";
+import type {
+  SessionInstructionStorageLocation,
+  WriteSessionInstructionInput,
+} from "@/types/session/SessionInstruction.js";
+
+/** 读取 Session 显式固化的 instruction；文件不存在时返回 null。 */
+export async function read_session_instruction(
+  input: SessionInstructionStorageLocation,
+): Promise<string | null> {
+  const instruction_path = getSdkAgentSessionInstructionPath(
+    input.project_root,
+    input.agent_id,
+    input.session_id,
+  );
+  try {
+    return await fs.readFile(instruction_path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** 原子覆盖当前 Session 的 instruction.md。 */
+export async function write_session_instruction(
+  input: WriteSessionInstructionInput,
+): Promise<void> {
+  const instruction_path = getSdkAgentSessionInstructionPath(
+    input.project_root,
+    input.agent_id,
+    input.session_id,
+  );
+  const temporary_path = [
+    instruction_path,
+    process.pid,
+    Date.now(),
+    randomUUID(),
+    "tmp",
+  ].join(".");
+  await fs.ensureDir(path.dirname(instruction_path));
+  try {
+    await fs.writeFile(temporary_path, input.instruction, "utf8");
+    await fs.move(temporary_path, instruction_path, { overwrite: true });
+  } finally {
+    await fs.remove(temporary_path);
+  }
+}

package/src/session/storage/Paths.ts

@@ -129,6 +129,24 @@ export function getSdkAgentSessionDirPath(
   );
 }
 
+/**
+ * 单个 session 显式固化的 instruction.md 路径。
+ *
+ * 关键点（中文）
+ * - 文件不存在表示 Session 恢复时继续采用 Agent 当前 instruction。
+ * - 空文件表示调用方显式固化了空 instruction。
+ */
+export function getSdkAgentSessionInstructionPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionDirPath(projectRoot, agentId, sessionId),
+    "instruction.md",
+  );
+}
+
 /**
  * 单个 session 的消息目录路径。
  */

package/src/types/agent/SessionActor.ts

@@ -125,6 +125,9 @@ export interface AgentSession extends AgentSessionActor {
   /** 写入当前 session 默认配置。 */
   set(input: AgentSessionSetInput): Promise<void>;
 
+  /** 把当前 Session 生效的自定义 instruction 显式固化到 instruction.md。 */
+  snapshot(): Promise<void>;
+
   /** 从当前 session 创建一个分叉会话。 */
   fork(input?: AgentSessionForkInput | string): Promise<AgentSession>;
 }

package/src/types/session/SessionInstruction.ts

@@ -0,0 +1,24 @@
+/**
+ * Session instruction 显式快照存储类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 instruction.md 的定位与写入输入。
+ * - 文件存在性本身用于表达 Session 是否启用显式 instruction 快照。
+ */
+
+/** Session instruction.md 的稳定定位信息。 */
+export interface SessionInstructionStorageLocation {
+  /** 当前项目根目录。 */
+  project_root: string;
+  /** 当前 Agent 稳定标识。 */
+  agent_id: string;
+  /** 当前 Session 稳定标识。 */
+  session_id: string;
+}
+
+/** 原子写入 Session instruction.md 使用的完整输入。 */
+export interface WriteSessionInstructionInput
+  extends SessionInstructionStorageLocation {
+  /** 当前 Session 生效的自定义 instruction Markdown。 */
+  instruction: string;
+}

package/src/types/session/SessionOptions.ts

@@ -74,9 +74,13 @@ export interface SessionOptions {
   logger: Logger;
 
   /**
-   * 读取当前 SDK 调用方传入的 instruction system blocks。
+   * 当前 Session 创建时绑定的 instruction system blocks。
+   *
+   * 关键点（中文）
+   * - Session 创建后不再动态读取 Agent instruction。
+   * - `session.snapshot()` 只会把其中 `instruction` 来源的内容显式写入本地文件。
    */
-  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+  instruction_system_blocks: AgentSessionSystemBlock[];
 
   /**
    * 读取当前 Agent configured env。

package/src/types/session/SessionQueue.ts

@@ -4,7 +4,7 @@
  * 队列只保存明确的输入事实，不保存可执行闭包。SessionTurn 是这些输入的唯一解释者。
  */
 
-import type { AgentSessionConfigSnapshot, AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
@@ -23,16 +23,6 @@ export interface SessionModelQueueCommand {
   action_title?: string;
 }
 
-/** Agent instruction 在 Session Step 检查点生效的命令。 */
-export interface SessionInstructionQueueCommand {
-  /** 命令种类固定为 Agent instruction 更新。 */
-  type: "agent_instruction";
-  /** 当前命令的稳定唯一标识。 */
-  command_id: string;
-  /** 下一 Step 使用的完整 instruction blocks。 */
-  instruction_blocks: AgentSessionSystemBlock[];
-}
-
 /** Agent env 在 Session Step 检查点生效的命令。 */
 export interface SessionEnvQueueCommand {
   /** 命令种类固定为 Agent env 更新。 */
@@ -66,29 +56,19 @@ export interface SessionCompactQueueCommand {
 /** Session FIFO 中允许出现的领域命令。 */
 export type SessionQueueCommand =
   | SessionModelQueueCommand
-  | SessionInstructionQueueCommand
   | SessionEnvQueueCommand
   | SessionPluginsQueueCommand
   | SessionCompactQueueCommand;
 
 /** Agent configured state 广播给既有 Session 的输入。 */
-export type AgentSessionCommand =
-  | {
-      /** 当前修改固定为 instruction。 */
-      type: "instruction";
-      /** 当前命令唯一标识。 */
-      command_id: string;
-      /** 下一 Session Step 使用的 instruction blocks。 */
-      instruction_blocks: AgentSessionSystemBlock[];
-    }
-  | {
-      /** 当前修改固定为 env。 */
-      type: "env";
-      /** 当前命令唯一标识。 */
-      command_id: string;
-      /** 下一 Session Step 使用的完整 Agent env。 */
-      env: Record<string, string>;
-    }
+export type AgentSessionCommand = {
+    /** 当前修改固定为 env。 */
+    type: "env";
+    /** 当前命令唯一标识。 */
+    command_id: string;
+    /** 下一 Session Step 使用的完整 Agent env。 */
+    env: Record<string, string>;
+  }
   | {
       /** 当前修改固定为 plugins。 */
       type: "plugins";

package/src/types/session/SessionTool.ts

@@ -23,3 +23,13 @@ export interface SessionToolInputReady {
   /** 已完成解析的 Tool 输入。 */
   input: unknown;
 }
+
+/** 等待单个 canonical Tool Part 到达的异步句柄。 */
+export interface SessionToolPartWaiter {
+  /** Tool Part 成功持久化后完成，异常结束时拒绝。 */
+  promise: Promise<void>;
+  /** Tool Part 已按 canonical 顺序持久化时释放等待。 */
+  resolve: () => void;
+  /** 当前 step 或 Gate 异常结束时拒绝等待。 */
+  reject: (error: Error) => void;
+}