@downcity/agent 1.1.276 → 1.1.278

package/bin/types/session/SessionQueue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SessionQueue.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionQueue.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SessionQueue.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionQueue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AACnF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E,mCAAmC;AACnC,MAAM,WAAW,wBAAwB;IACvC,4BAA4B;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,0BAA0B,CAAC;IACnC,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,8CAA8C;AAC9C,MAAM,WAAW,0BAA0B;IACzC,+BAA+B;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,OAAO,EAAE,2BAA2B,CAAC;CACtC;AAED,mBAAmB;AACnB,MAAM,WAAW,0BAA0B;IACzC,uBAAuB;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,+BAA+B;AAC/B,MAAM,MAAM,mBAAmB,GAC3B,wBAAwB,GACxB,sBAAsB,GACtB,0BAA0B,GAC1B,0BAA0B,CAAC;AAE/B,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,mBAAmB;IACnB,IAAI,EAAE,KAAK,CAAC;IACZ,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,GACC;IACE,uBAAuB;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,gBAAgB;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,2BAA2B,CAAC;CACtC,CAAC;AAEN,wBAAwB;AACxB,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,sBAAsB;IACtB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,oBAAoB;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC7B;AAED,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IAClC,uBAAuB;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,wBAAwB;IACxB,KAAK,EAAE,uBAAuB,CAAC;IAC/B,0CAA0C;IAC1C,eAAe,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;CAC/D;AAED,6BAA6B;AAC7B,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC"}

package/bin/types/session/SessionTool.d.ts

@@ -20,4 +20,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;
+}
 //# sourceMappingURL=SessionTool.d.ts.map

package/bin/types/session/SessionTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SessionTool.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionTool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAElF,wCAAwC;AACxC,MAAM,WAAW,4BAA4B;IAC3C,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,IAAI,EAAE,wBAAwB,CAAC;CAChC;AAED,oCAAoC;AACpC,MAAM,WAAW,qBAAqB;IACpC,uBAAuB;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB"}
+{"version":3,"file":"SessionTool.d.ts","sourceRoot":"","sources":["../../../src/types/session/SessionTool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAElF,wCAAwC;AACxC,MAAM,WAAW,4BAA4B;IAC3C,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,IAAI,EAAE,wBAAwB,CAAC;CAChC;AAED,oCAAoC;AACpC,MAAM,WAAW,qBAAqB;IACpC,uBAAuB;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wCAAwC;AACxC,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,yCAAyC;IACzC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,gCAAgC;IAChC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.276",
+  "version": "1.1.278",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",

package/scripts/session-config-turn-boundary.test.mjs

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 第一次 provider 请求保持阻塞，用来制造真实的运行中配置修改窗口。
- * - instruction、env 与 plugin registry 修改不能改变已经开始的请求。
+ * - Agent instruction 修改不能改变已有 Session；env 与 plugin registry 修改在 step 检查点生效。
  * - config 与 steer 在同一个 Session step 检查点提交，并继续使用同一个 turn id。
  */
 
@@ -58,7 +58,7 @@ function create_stream_text_result(text) {
   };
 }
 
-test("running Agent config changes and steer apply at the same Session step checkpoint", async () => {
+test("Agent instruction changes only affect newly created Sessions", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-config-turn-boundary-"),
   );
@@ -133,8 +133,8 @@ test("running Agent config changes and steer apply at the same Session step chec
     assert.equal((await steer_turn.finished).success, true);
     assert.equal(plugin_stop_count, 1);
     assert.equal(provider_prompts.length, 2);
-    assert.match(provider_prompts[1], /instruction:new/);
-    assert.doesNotMatch(provider_prompts[1], /instruction:old/);
+    assert.match(provider_prompts[1], /instruction:old/);
+    assert.doesNotMatch(provider_prompts[1], /instruction:new/);
     assert.doesNotMatch(provider_prompts[1], /plugin-env:old/);
 
     const messages = await session.messages();
@@ -142,16 +142,167 @@ test("running Agent config changes and steer apply at the same Session step chec
       .filter((message) => message.type === "action" && message.status === "completed")
       .map((message) => message.title);
     assert.deepEqual(completed_actions, [
-      "Agent instruction updated",
       "Agent environment updated",
       "Agent plugin runtime-config unregistered",
     ]);
+
+    // 未显式 snapshot 的 Session 重新装载时使用 Agent 当前 instruction。
+    await agent.sessions.clear_messages(session.id);
+    const restored_session = await agent.sessions.get(session.id);
+    const restored_system = await restored_session.system();
+    const restored_system_text = restored_system.blocks
+      .map((block) => block.content)
+      .join("\n");
+    assert.match(restored_system_text, /instruction:new/);
+    assert.doesNotMatch(restored_system_text, /instruction:old/);
+
+    const new_session = await agent.sessions.create({
+      sessionId: "config_turn_boundary_new_session",
+    });
+    const new_system = await new_session.system();
+    const new_system_text = new_system.blocks
+      .map((block) => block.content)
+      .join("\n");
+    assert.match(new_system_text, /instruction:new/);
+    assert.doesNotMatch(new_system_text, /instruction:old/);
   } finally {
     release_first_provider_request.resolve();
     await agent.dispose();
   }
 });
 
+test("Session snapshot explicitly persists instruction.md", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-instruction-restart-"),
+  );
+  const model = new MockLanguageModelV3({ modelId: "instruction-restart-model" });
+  const first_agent = new Agent({
+    id: "instruction_restart_agent",
+    path: agent_path,
+    model,
+    instruction: ["instruction:old"],
+  });
+
+  try {
+    const session = await first_agent.sessions.create({
+      sessionId: "instruction_restart_session",
+    });
+    const first_system = await session.system();
+    assert.match(
+      first_system.blocks.map((block) => block.content).join("\n"),
+      /instruction:old/,
+    );
+    await session.snapshot();
+
+    const instruction_path = path.join(
+      agent_path,
+      ".downcity",
+      "agents",
+      "instruction_restart_agent",
+      "sessions",
+      "instruction_restart_session",
+      "instruction.md",
+    );
+    assert.equal(await fs.readFile(instruction_path, "utf8"), "instruction:old");
+
+    await fs.writeFile(instruction_path, "instruction:manual", "utf8");
+    await session.snapshot();
+    assert.equal(await fs.readFile(instruction_path, "utf8"), "instruction:old");
+  } finally {
+    await first_agent.dispose();
+  }
+
+  const restarted_agent = new Agent({
+    id: "instruction_restart_agent",
+    path: agent_path,
+    model,
+    instruction: ["instruction:new"],
+  });
+  try {
+    const restored_session = await restarted_agent.sessions.get(
+      "instruction_restart_session",
+    );
+    const restored_system = await restored_session.system();
+    const restored_system_text = restored_system.blocks
+      .map((block) => block.content)
+      .join("\n");
+    assert.match(restored_system_text, /instruction:old/);
+    assert.doesNotMatch(restored_system_text, /instruction:new/);
+  } finally {
+    await restarted_agent.dispose();
+  }
+
+  const instruction_path = path.join(
+    agent_path,
+    ".downcity",
+    "agents",
+    "instruction_restart_agent",
+    "sessions",
+    "instruction_restart_session",
+    "instruction.md",
+  );
+  await fs.rm(instruction_path);
+
+  const fallback_agent = new Agent({
+    id: "instruction_restart_agent",
+    path: agent_path,
+    model,
+    instruction: ["instruction:new"],
+  });
+  try {
+    const fallback_session = await fallback_agent.sessions.get(
+      "instruction_restart_session",
+    );
+    const fallback_system = await fallback_session.system();
+    const fallback_system_text = fallback_system.blocks
+      .map((block) => block.content)
+      .join("\n");
+    assert.match(fallback_system_text, /instruction:new/);
+    assert.doesNotMatch(fallback_system_text, /instruction:old/);
+  } finally {
+    await fallback_agent.dispose();
+    await fs.rm(agent_path, { recursive: true, force: true });
+  }
+});
+
+test("empty Session snapshot suppresses Agent instruction after restart", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-empty-instruction-snapshot-"),
+  );
+  const model = new MockLanguageModelV3({ modelId: "empty-snapshot-model" });
+  const first_agent = new Agent({
+    id: "empty_snapshot_agent",
+    path: agent_path,
+    model,
+  });
+  try {
+    const session = await first_agent.sessions.create({
+      sessionId: "empty_snapshot_session",
+    });
+    await session.snapshot();
+  } finally {
+    await first_agent.dispose();
+  }
+
+  const restarted_agent = new Agent({
+    id: "empty_snapshot_agent",
+    path: agent_path,
+    model,
+    instruction: ["instruction:must-not-appear"],
+  });
+  try {
+    const session = await restarted_agent.sessions.get("empty_snapshot_session");
+    const system = await session.system();
+    assert.doesNotMatch(
+      system.blocks.map((block) => block.content).join("\n"),
+      /instruction:must-not-appear/,
+    );
+  } finally {
+    await restarted_agent.dispose();
+    await fs.rm(agent_path, { recursive: true, force: true });
+  }
+});
+
 test("running session model changes apply with steer at the next Session step", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-session-step-boundary-"),

package/scripts/session-messages.test.mjs

@@ -49,6 +49,24 @@ class PausingAssistantMessageStore extends JsonlSessionMessageStore {
   }
 }
 
+/** 可让下一次 Assistant 草稿更新失败，用于验证持久化失败边界。 */
+class FailingAssistantMessageStore extends JsonlSessionMessageStore {
+  next_assistant_error = null;
+
+  fail_next_assistant_write(message) {
+    this.next_assistant_error = new Error(message);
+  }
+
+  async write_assistant_message(message) {
+    const error = this.next_assistant_error;
+    if (error) {
+      this.next_assistant_error = null;
+      throw error;
+    }
+    await super.write_assistant_message(message);
+  }
+}
+
 async function create_recorder(
   session_id = "session-recorder-test",
   create_store = (options) => new JsonlSessionMessageStore(options),
@@ -703,7 +721,7 @@ test("Approval Broker 只接受已经准备完整输入的 Tool", async () => {
   );
   assert.equal(approval_broker.list().length, 0);
 
-  await writer.prepare_tool_input({
+  const tool_input_ready = writer.prepare_tool_input({
     tool_call_id: "call-ready-barrier",
     tool_name: "shell_exec",
     input: {
@@ -712,6 +730,14 @@ test("Approval Broker 只接受已经准备完整输入的 Tool", async () => {
       reason: "Inspect requested desktop files",
     },
   });
+  await writer.flush();
+  assert.deepEqual(recorder.get_message(writer.message_id).parts, []);
+  await writer.apply_chunk({
+    type: "tool-input-start",
+    toolCallId: "call-ready-barrier",
+    toolName: "shell_exec",
+  });
+  await tool_input_ready;
   const approval_handle = await approval_broker.request(approval_input);
 
   const tool = recorder.get_message(writer.message_id).parts[0];
@@ -734,7 +760,7 @@ test("Approval Broker 只接受已经准备完整输入的 Tool", async () => {
     events
       .filter((event) => event.variant === "part" && event.type === "tool")
       .map((event) => event.part.state),
-    ["ready", "approval-required", "failed"],
+    ["input-streaming", "ready", "approval-required", "failed"],
   );
 });
 
@@ -749,6 +775,11 @@ test("流式更新与 Approval 共享 Assistant revision 写队列", async () =>
     turn_id: "turn-approval-race",
     segment_index: 1,
   });
+  await writer.apply_chunk({
+    type: "tool-input-start",
+    toolCallId: "call-approval-race",
+    toolName: "shell_exec",
+  });
   await writer.prepare_tool_input({
     tool_call_id: "call-approval-race",
     tool_name: "shell_exec",
@@ -789,7 +820,7 @@ test("流式更新与 Approval 共享 Assistant revision 写队列", async () =>
   const assistant = recorder.get_message(writer.message_id);
   const tool = assistant.parts.find((part) => part.type === "tool");
   const text_part = assistant.parts.find((part) => part.type === "text");
-  assert.equal(assistant.revision, 6);
+  assert.equal(assistant.revision, 7);
   assert.equal(tool.state, "approval-required");
   assert.equal(tool.approval.approval_id, approval_handle.approval_id);
   assert.equal(tool.input.cmd, "ls -la ~");
@@ -798,7 +829,7 @@ test("流式更新与 Approval 共享 Assistant revision 写队列", async () =>
     events
       .filter((event) => event.message_id === writer.message_id)
       .map((event) => event.revision),
-    [1, 2, 3, 4, 5, 6],
+    [1, 2, 3, 4, 5, 6, 7],
   );
   assert.equal(
     events.some(
@@ -1017,6 +1048,151 @@ test("空 Text Start 不会抢占后续 Tool 的真实顺序", async () => {
   );
 });
 
+test("Tool 执行先到时等待 stream 固定 canonical Part 顺序", async () => {
+  const { recorder, file_path } = await create_recorder("pending-tool-input-order-test");
+  const writer = await recorder.open_assistant_message({
+    turn_id: "turn-pending-tool-input",
+    segment_index: 1,
+  });
+
+  await writer.begin_step();
+  const tool_input_ready = writer.prepare_tool_input({
+    tool_call_id: "call-pending",
+    tool_name: "search",
+    input: { query: "downcity" },
+  });
+  await writer.flush();
+  assert.deepEqual(recorder.get_message(writer.message_id).parts, []);
+
+  await writer.apply_chunk({ type: "text-start", id: "text-0" });
+  await writer.apply_chunk({ type: "text-delta", id: "text-0", delta: "第一段" });
+  await writer.apply_chunk({ type: "text-end", id: "text-0" });
+  await writer.apply_chunk({ type: "text-start", id: "text-1" });
+  await writer.apply_chunk({ type: "text-delta", id: "text-1", delta: "第二段" });
+  await writer.apply_chunk({ type: "text-end", id: "text-1" });
+  await writer.apply_chunk({
+    type: "tool-input-start",
+    toolCallId: "call-pending",
+    toolName: "search",
+  });
+  await tool_input_ready;
+  await writer.apply_chunk({
+    type: "tool-input-available",
+    toolCallId: "call-pending",
+    toolName: "search",
+    input: { query: "downcity" },
+  });
+  await writer.apply_chunk({
+    type: "tool-output-available",
+    toolCallId: "call-pending",
+    output: "result",
+  });
+  await writer.finish_step([
+    {
+      part_id: "text-final-0",
+      sequence: 1,
+      type: "text",
+      text: "第一段",
+      state: "done",
+    },
+    {
+      part_id: "text-final-1",
+      sequence: 2,
+      type: "text",
+      text: "第二段",
+      state: "done",
+    },
+    {
+      part_id: "call-pending",
+      sequence: 3,
+      type: "tool",
+      tool_call_id: "call-pending",
+      tool_name: "search",
+      state: "completed",
+      input: { query: "downcity" },
+      output: "result",
+    },
+  ]);
+  await writer.complete();
+
+  const assistant = (await read_jsonl(file_path))[0];
+  assert.deepEqual(assistant.parts.map((part) => part.type), ["text", "text", "tool"]);
+  assert.deepEqual(assistant.parts.map((part) => part.sequence), [1, 2, 3]);
+  assert.deepEqual(assistant.parts[2].input, { query: "downcity" });
+});
+
+test("step abort 与 writer close 会拒绝未释放的 Tool 输入屏障", async () => {
+  const { recorder } = await create_recorder("pending-tool-input-cleanup-test");
+  const aborted_writer = await recorder.open_assistant_message({
+    turn_id: "turn-aborted-tool-input",
+    segment_index: 1,
+  });
+  await aborted_writer.begin_step();
+  const aborted_input = assert.rejects(
+    aborted_writer.prepare_tool_input({
+      tool_call_id: "call-aborted",
+      tool_name: "search",
+      input: { query: "aborted" },
+    }),
+    /canonical step was aborted: call-aborted/,
+  );
+  await aborted_writer.flush();
+  await aborted_writer.abort_step();
+  await aborted_input;
+  await aborted_writer.fail("aborted");
+
+  const closed_writer = await recorder.open_assistant_message({
+    turn_id: "turn-closed-tool-input",
+    segment_index: 2,
+  });
+  const closed_input = assert.rejects(
+    closed_writer.prepare_tool_input({
+      tool_call_id: "call-closed",
+      tool_name: "search",
+      input: { query: "closed" },
+    }),
+    /writer closed with status stopped: call-closed/,
+  );
+  await closed_writer.flush();
+  await closed_writer.stop();
+  await closed_input;
+});
+
+test("Tool Part 持久化失败时不会释放对应执行等待", async () => {
+  const { recorder, store } = await create_recorder(
+    "tool-part-persistence-gate-test",
+    (options) => new FailingAssistantMessageStore(options),
+  );
+  const writer = await recorder.open_assistant_message({
+    turn_id: "turn-tool-part-persistence",
+    segment_index: 1,
+  });
+  await writer.begin_step();
+  const tool_input = assert.rejects(
+    writer.prepare_tool_input({
+      tool_call_id: "call-persistence-failed",
+      tool_name: "search",
+      input: { query: "downcity" },
+    }),
+    /canonical step was aborted: call-persistence-failed/,
+  );
+
+  store.fail_next_assistant_write("disk full");
+  await assert.rejects(
+    writer.apply_chunk({
+      type: "tool-input-start",
+      toolCallId: "call-persistence-failed",
+      toolName: "search",
+    }),
+    /disk full/,
+  );
+  assert.deepEqual(recorder.get_message(writer.message_id).parts, []);
+
+  await writer.abort_step();
+  await tool_input;
+  await writer.fail("disk full");
+});
+
 test("step 最终快照缺少 canonical Tool chunk 时拒绝猜测顺序", async () => {
   const { recorder, events, file_path } = await create_recorder("final-reconcile-order-test");
   const writer = await recorder.open_assistant_message({ turn_id: "turn-1", segment_index: 1 });

package/scripts/session-tool-part-gate.test.mjs

@@ -0,0 +1,58 @@
+/**
+ * @file 验证 canonical Tool Part Gate 按 Tool Call 独立协调等待与释放。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { SessionToolPartGate } from "../bin/session/messages/SessionToolPartGate.js";
+
+test("不同 Tool Call 独立释放，不形成全局执行锁", async () => {
+  const gate = new SessionToolPartGate();
+  let tool_a_ready = false;
+  let tool_b_ready = false;
+  const tool_a = gate.wait_until_available("call-a").then(() => {
+    tool_a_ready = true;
+  });
+  const tool_b = gate.wait_until_available("call-b").then(() => {
+    tool_b_ready = true;
+  });
+
+  gate.mark_available("call-a");
+  await tool_a;
+  assert.equal(tool_a_ready, true);
+  assert.equal(tool_b_ready, false);
+
+  gate.mark_available("call-b");
+  await tool_b;
+  assert.equal(tool_b_ready, true);
+  await gate.wait_until_available("call-a");
+});
+
+test("reject_pending 只清理当前等待，Gate 可用于后续 step", async () => {
+  const gate = new SessionToolPartGate();
+  const aborted = assert.rejects(
+    gate.wait_until_available("call-aborted"),
+    /step aborted: call-aborted/,
+  );
+  gate.reject_pending("step aborted");
+  await aborted;
+
+  const next_step = gate.wait_until_available("call-next");
+  gate.mark_available("call-next");
+  await next_step;
+});
+
+test("close 拒绝当前及后续 Tool Part 等待", async () => {
+  const gate = new SessionToolPartGate();
+  const pending = assert.rejects(
+    gate.wait_until_available("call-pending"),
+    /writer closed: call-pending/,
+  );
+  gate.close("writer closed");
+  await pending;
+  await assert.rejects(
+    gate.wait_until_available("call-future"),
+    /writer closed/,
+  );
+});

package/src/agent/Agent.ts

@@ -159,7 +159,6 @@ export class Agent {
   setInstruction(input: string | string[]): void {
     const next_instruction = normalizeInstructionInput(input);
     this.instruction.splice(0, this.instruction.length, ...next_instruction);
-    this.sessions.broadcast_instruction(this.instruction, generateId());
   }
 
   /**

package/src/agent/AgentSessions.ts

@@ -146,23 +146,6 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return this.list_executing_session_ids().length;
   }
 
-  /**
-   * 把 Agent instruction 修改广播到已有 Session 的统一输入队列。
-   */
-  broadcast_instruction(instruction: string[], command_id: string): void {
-    const instruction_blocks = createInstructionSystemBlocks(
-      instruction,
-      this.project_root,
-    );
-    for (const session of this.sessions_by_id.values()) {
-      session.enqueue_agent_command({
-        type: "instruction",
-        command_id,
-        instruction_blocks,
-      });
-    }
-  }
-
   /**
    * 把 Agent env 修改广播到已有 Session 的统一输入队列。
    */
@@ -198,9 +181,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
    * 获取或创建一个 session runtime port。
    */
   runtime(session_id: string): SessionPort {
-    return this.get_or_create_session({
-      session_id,
-    }).getRuntimePort();
+    return this.get_or_create_session({ session_id }).getRuntimePort();
   }
 
   /**
@@ -436,7 +417,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       sessionId: resolved_session_id,
       tools: this.tools,
       logger: this.logger,
-      getInstructionSystemBlocks: () => this.load_instruction_system_blocks(),
+      instruction_system_blocks: this.load_instruction_system_blocks(),
       getAgentEnv: () => this.get_agent_env(),
       getAgentModel: () => this.get_agent_model(),
       get_agent_plugins: () => this.get_agent_plugins(),