@downcity/agent 1.1.276 → 1.1.277

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/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/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;
+}