@downcity/agent 1.1.270 → 1.1.276

package/scripts/session-messages.test.mjs

@@ -230,6 +230,7 @@ test("Streaming Tool Provider metadata 在输入和输出状态间完整保留",
     turn_id: "turn-provider-metadata",
     segment_index: 1,
   });
+  await writer.begin_step();
   await writer.apply_chunk({
     type: "tool-input-start",
     toolCallId: "call_1",
@@ -256,7 +257,7 @@ test("Streaming Tool Provider metadata 在输入和输出状态间完整保留",
     providerExecuted: true,
     providerMetadata: { openai: { resultId: "result_1" } },
   });
-  await writer.reconcile_final_tool_part({
+  await writer.finish_step([{
     part_id: "call_1",
     sequence: 1,
     type: "tool",
@@ -267,7 +268,7 @@ test("Streaming Tool Provider metadata 在输入和输出状态间完整保留",
     output: "ok",
     provider_executed: true,
     call_provider_metadata: { openai: { itemId: "fc_final" } },
-  });
+  }]);
   await writer.complete();
 
   const assistant = (await read_jsonl(file_path))[0];
@@ -820,6 +821,7 @@ test("不同模型 step 重复使用 Text chunk ID 时仍保持真实 Part 顺
   const { recorder, file_path } = await create_recorder("reused-text-id-order-test");
   const writer = await recorder.open_assistant_message({ turn_id: "turn-1", segment_index: 1 });
 
+  await writer.begin_step();
   await writer.apply_chunk({ type: "text-start", id: "txt-0" });
   await writer.apply_chunk({ type: "text-delta", id: "txt-0", delta: "first" });
   await writer.apply_chunk({ type: "text-end", id: "txt-0" });
@@ -831,7 +833,27 @@ test("不同模型 step 重复使用 Text chunk ID 时仍保持真实 Part 顺
     input: { query: "first" },
   });
   await writer.apply_chunk({ type: "tool-output-available", toolCallId: "call-1", output: "one" });
+  await writer.finish_step([
+    {
+      part_id: "text-1",
+      sequence: 1,
+      type: "text",
+      text: "first",
+      state: "done",
+    },
+    {
+      part_id: "call-1",
+      sequence: 2,
+      type: "tool",
+      tool_call_id: "call-1",
+      tool_name: "search",
+      state: "completed",
+      input: { query: "first" },
+      output: "one",
+    },
+  ]);
 
+  await writer.begin_step();
   await writer.apply_chunk({ type: "text-start", id: "txt-0" });
   await writer.apply_chunk({ type: "text-delta", id: "txt-0", delta: "second" });
   await writer.apply_chunk({ type: "text-end", id: "txt-0" });
@@ -843,6 +865,25 @@ test("不同模型 step 重复使用 Text chunk ID 时仍保持真实 Part 顺
     input: { query: "second" },
   });
   await writer.apply_chunk({ type: "tool-output-available", toolCallId: "call-2", output: "two" });
+  await writer.finish_step([
+    {
+      part_id: "text-1",
+      sequence: 1,
+      type: "text",
+      text: "second",
+      state: "done",
+    },
+    {
+      part_id: "call-2",
+      sequence: 2,
+      type: "tool",
+      tool_call_id: "call-2",
+      tool_name: "search",
+      state: "completed",
+      input: { query: "second" },
+      output: "two",
+    },
+  ]);
   await writer.complete();
 
   const assistant = (await read_jsonl(file_path))[0];
@@ -855,10 +896,58 @@ test("不同模型 step 重复使用 Text chunk ID 时仍保持真实 Part 顺
   assert.notEqual(assistant.parts[0].part_id, assistant.parts[2].part_id);
 });
 
+test("不同模型 step 重复 Source 与 Data ID 时创建独立 canonical Parts", async () => {
+  const { recorder, file_path } = await create_recorder("reused-structured-id-order-test");
+  const writer = await recorder.open_assistant_message({ turn_id: "turn-1", segment_index: 1 });
+
+  for (const step of [1, 2]) {
+    await writer.begin_step();
+    await writer.apply_chunk({
+      type: "source-url",
+      sourceId: "source-1",
+      url: `https://example.com/${step}`,
+    });
+    await writer.apply_chunk({
+      type: "data-status",
+      id: "status-1",
+      data: { step },
+    });
+    await writer.finish_step([
+      {
+        part_id: "source-1",
+        sequence: 1,
+        type: "source",
+        source_type: "url",
+        source_id: "source-1",
+        url: `https://example.com/${step}`,
+      },
+      {
+        part_id: "data-1",
+        sequence: 2,
+        type: "data",
+        data_type: "data-status",
+        data: { step },
+        data_id: "status-1",
+      },
+    ]);
+  }
+  await writer.complete();
+
+  const assistant = (await read_jsonl(file_path))[0];
+  assert.deepEqual(
+    assistant.parts.map((part) => part.type),
+    ["source", "data", "source", "data"],
+  );
+  assert.deepEqual(assistant.parts.map((part) => part.sequence), [1, 2, 3, 4]);
+  assert.notEqual(assistant.parts[0].part_id, assistant.parts[2].part_id);
+  assert.notEqual(assistant.parts[1].part_id, assistant.parts[3].part_id);
+});
+
 test("空 Text Start 不会抢占后续 Tool 的真实顺序", async () => {
   const { recorder, events, file_path } = await create_recorder("deferred-text-order-test");
   const writer = await recorder.open_assistant_message({ turn_id: "turn-1", segment_index: 1 });
 
+  await writer.begin_step();
   await writer.apply_chunk({ type: "reasoning-start", id: "reasoning-0" });
   await writer.apply_chunk({ type: "reasoning-delta", id: "reasoning-0", delta: "先执行命令" });
   await writer.apply_chunk({ type: "reasoning-end", id: "reasoning-0" });
@@ -881,6 +970,32 @@ test("空 Text Start 不会抢占后续 Tool 的真实顺序", async () => {
   });
   await writer.apply_chunk({ type: "text-delta", id: "text-0", delta: "命令执行完成" });
   await writer.apply_chunk({ type: "text-end", id: "text-0" });
+  await writer.finish_step([
+    {
+      part_id: "reasoning-1",
+      sequence: 1,
+      type: "reasoning",
+      text: "先执行命令",
+      state: "done",
+    },
+    {
+      part_id: "call-1",
+      sequence: 2,
+      type: "tool",
+      tool_call_id: "call-1",
+      tool_name: "shell_exec",
+      state: "completed",
+      input: { cmd: "pwd" },
+      output: { success: true },
+    },
+    {
+      part_id: "text-1",
+      sequence: 3,
+      type: "text",
+      text: "命令执行完成",
+      state: "done",
+    },
+  ]);
   await writer.complete();
 
   const assistant = (await read_jsonl(file_path))[0];
@@ -902,6 +1017,50 @@ test("空 Text Start 不会抢占后续 Tool 的真实顺序", async () => {
   );
 });
 
+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 });
+
+  await writer.begin_step();
+  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" });
+  const streamed_text_part_id = events.find(
+    (event) => event.variant === "part" && event.type === "text",
+  ).part.part_id;
+
+  await assert.rejects(
+    writer.finish_step([
+      {
+        part_id: "call-1",
+        sequence: 1,
+        type: "tool",
+        tool_call_id: "call-1",
+        tool_name: "shell_exec",
+        state: "completed",
+        input: { cmd: "pwd" },
+        output: { success: true },
+      },
+      {
+        part_id: "text-1",
+        sequence: 2,
+        type: "text",
+        text: "最终结论",
+        state: "done",
+      },
+    ]),
+    /snapshot mismatch: part count 1 != 2/,
+  );
+  await writer.abort_step();
+  await writer.fail("canonical snapshot mismatch");
+
+  const assistant = (await read_jsonl(file_path))[0];
+  assert.equal(assistant.status, "failed");
+  assert.deepEqual(assistant.parts.map((part) => part.type), ["text"]);
+  assert.deepEqual(assistant.parts.map((part) => part.sequence), [1]);
+  assert.equal(assistant.parts[0].part_id, streamed_text_part_id);
+});
+
 test("重启时将 Assistant 草稿收口为 stopped，并将运行中 Action 标记失败", async () => {
   const { recorder, file_path, assistant_message_file_path } = await create_recorder("recovery-test");
   await recorder.append_user_message({

package/scripts/session-turn-failure.test.mjs

@@ -1,5 +1,5 @@
 /**
- * @file 验证 Turn 失败只写入一次结构化错误，并保留已经生成的 Assistant 内容。
+ * @file 验证 Turn 失败收口与最终 Assistant 快照顺序。
  */
 
 import assert from "node:assert/strict";
@@ -99,3 +99,110 @@ test("Provider 在部分输出后失败时保留 failed Assistant 并追加 Erro
   assert.equal(page.items[1].parts[0].text, "partial response");
   assert.equal(page.items[2].message, "stream interrupted");
 });
+
+test("Turn 使用 step canonical chunks 保持 Tool 与最终正文顺序", async () => {
+  const { messages, turn } = await create_turn_harness(async (run_context) => {
+    await run_context.on_ui_message_step_start();
+    await run_context.onUiMessageChunkCallback({
+      type: "tool-input-start",
+      toolCallId: "call-1",
+      toolName: "shell_exec",
+    });
+    await run_context.onUiMessageChunkCallback({
+      type: "tool-input-available",
+      toolCallId: "call-1",
+      toolName: "shell_exec",
+      input: { cmd: "pwd" },
+    });
+    await run_context.onUiMessageChunkCallback({
+      type: "tool-output-available",
+      toolCallId: "call-1",
+      output: { success: true },
+    });
+    await run_context.onUiMessageChunkCallback({ type: "text-start", id: "text-1" });
+    await run_context.onUiMessageChunkCallback({
+      type: "text-delta",
+      id: "text-1",
+      delta: "最终结论",
+    });
+    await run_context.onUiMessageChunkCallback({ type: "text-end", id: "text-1" });
+    const assistant_message = {
+      id: "assistant-1",
+      role: "assistant",
+      parts: [
+        {
+          type: "dynamic-tool",
+          toolCallId: "call-1",
+          toolName: "shell_exec",
+          state: "output-available",
+          input: { cmd: "pwd" },
+          output: { success: true },
+        },
+        { type: "text", text: "最终结论", state: "done" },
+      ],
+    };
+    await run_context.on_ui_message_step_finish(assistant_message);
+    return {
+      success: true,
+      assistantMessage: assistant_message,
+      deferredPersistedUserMessages: [],
+    };
+  });
+
+  const handle = await turn.prompt({ query: "diagnose" });
+  const result = await handle.finished;
+  const page = await messages.list_messages();
+  const assistant = page.items.find((message) => message.type === "assistant");
+
+  assert.equal(result.success, true);
+  assert.deepEqual(assistant.parts.map((part) => part.type), ["tool", "text"]);
+  assert.deepEqual(assistant.parts.map((part) => part.sequence), [1, 2]);
+});
+
+test("Turn 在 step 最终快照出现未流式写入的 Tool 时失败", async () => {
+  const { messages, turn } = await create_turn_harness(async (run_context) => {
+    await run_context.on_ui_message_step_start();
+    await run_context.onUiMessageChunkCallback({ type: "text-start", id: "text-1" });
+    await run_context.onUiMessageChunkCallback({
+      type: "text-delta",
+      id: "text-1",
+      delta: "最终结论",
+    });
+    await run_context.onUiMessageChunkCallback({ type: "text-end", id: "text-1" });
+    try {
+      await run_context.on_ui_message_step_finish({
+        id: "assistant-1",
+        role: "assistant",
+        parts: [
+          {
+            type: "dynamic-tool",
+            toolCallId: "call-1",
+            toolName: "shell_exec",
+            state: "output-available",
+            input: { cmd: "pwd" },
+            output: { success: true },
+          },
+          { type: "text", text: "最终结论", state: "done" },
+        ],
+      });
+    } catch (error) {
+      await run_context.on_ui_message_step_abort();
+      return {
+        success: false,
+        error: error.message,
+        deferredPersistedUserMessages: [],
+      };
+    }
+  });
+
+  const handle = await turn.prompt({ query: "diagnose" });
+  const result = await handle.finished;
+  const page = await messages.list_messages();
+  const assistant = page.items.find((message) => message.type === "assistant");
+
+  assert.equal(result.success, false);
+  assert.match(result.error, /snapshot mismatch/);
+  assert.equal(assistant.status, "failed");
+  assert.deepEqual(assistant.parts.map((part) => part.type), ["text"]);
+  assert.equal(page.items.at(-1).type, "error");
+});

package/src/executor/core-engine/CoreEngineRunner.ts

@@ -298,7 +298,13 @@ export class CoreEngineRunner {
         last_observed_stream_error = undefined;
         let step_assistant_ui_message: SessionMessageRecordV1;
         let executed_steps: StepResult<Record<string, Tool>>[];
+        let canonical_step_started = false;
+        let canonical_step_finished = false;
         try {
+          if (input.run_context.on_ui_message_step_start) {
+            await input.run_context.on_ui_message_step_start();
+            canonical_step_started = true;
+          }
           const result = streamText({
             model: step_inputs.model,
             system,
@@ -326,6 +332,13 @@ export class CoreEngineRunner {
               abortSignal: input.run_context.abortSignal,
             });
 
+          if (input.run_context.on_ui_message_step_finish) {
+            await input.run_context.on_ui_message_step_finish(
+              step_assistant_ui_message,
+            );
+          }
+          canonical_step_finished = true;
+
           final_assistant_ui_message = mergeAssistantUiMessages(
             final_assistant_ui_message,
             step_assistant_ui_message,
@@ -336,6 +349,13 @@ export class CoreEngineRunner {
           message_state.appendRuntimeSessionMessage(step_assistant_ui_message);
           executed_steps = await result.steps;
         } catch (error) {
+          if (
+            canonical_step_started &&
+            !canonical_step_finished &&
+            input.run_context.on_ui_message_step_abort
+          ) {
+            await input.run_context.on_ui_message_step_abort();
+          }
           const compact_error = this.should_compact_on_error(error)
             ? error
             : last_observed_stream_error;
@@ -557,6 +577,7 @@ export class CoreEngineRunner {
       return {
         success: true,
         assistantMessage: final_message,
+        assistant_file_parts: [...input.run_context.pendingAssistantFileParts],
         ...(compact_required ? { compact_required: true } : {}),
         deferredPersistedUserMessages: [
           ...input.run_context.deferredPersistedUserMessages,
@@ -578,6 +599,7 @@ export class CoreEngineRunner {
           success: false,
           error: error_text,
           ...(stopped_message ? { assistantMessage: stopped_message } : {}),
+          assistant_file_parts: [...input.run_context.pendingAssistantFileParts],
           ...(compact_required ? { compact_required: true } : {}),
           deferredPersistedUserMessages: [
             ...input.run_context.deferredPersistedUserMessages,
@@ -601,6 +623,7 @@ export class CoreEngineRunner {
       return {
         success: false,
         error: error_text,
+        assistant_file_parts: [...input.run_context.pendingAssistantFileParts],
         ...(compact_required ? { compact_required: true } : {}),
         deferredPersistedUserMessages: [
           ...input.run_context.deferredPersistedUserMessages,

package/src/executor/core-engine/CoreEngineUiStreamCollector.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 必须完整消费 AI SDK UI stream，才能稳定触发 `onFinish`。
  * - 优先使用结构化 `responseMessage`；缺失时才回退到纯文本。
- * - UI chunk 回调是展示层副作用，失败不应阻断 session 执行。
+ * - UI chunk 回调负责上层 canonical message 写入，失败必须终止本轮收敛。
  */
 
 import type { streamText } from "ai";
@@ -54,6 +54,7 @@ export async function collectFinalAssistantMessageFromUiStream(params: {
   let streamedAssistantMessage: SessionMessageRecordV1 | null = null;
   let uiFinishSummary: JsonObject | null = null;
   let streamed_text = "";
+  let callback_failed = false;
 
   const uiStream = params.result.toUIMessageStream<SessionMessageRecordV1>({
     // 关键点（中文）：SDK stream 需要 reasoning 旁路事件时可直接消费；最终落盘仍由 responseMessage 收敛。
@@ -91,12 +92,13 @@ export async function collectFinalAssistantMessageFromUiStream(params: {
       if (typeof params.onUiMessageChunkCallback !== "function") continue;
       try {
         await params.onUiMessageChunkCallback(chunk);
-      } catch {
-        // ignore UI stream callback failures
+      } catch (error) {
+        callback_failed = true;
+        throw error;
       }
     }
   } catch (error) {
-    if (!params.abortSignal?.aborted) {
+    if (callback_failed || !params.abortSignal?.aborted) {
       throw error;
     }
   }

package/src/executor/types/SessionRun.ts

@@ -7,7 +7,7 @@
  * - 输出暴露可选 assistantMessage（UIMessage）。
  */
 
-import type { Tool, UIMessageChunk } from "ai";
+import type { FileUIPart, Tool, UIMessageChunk } from "ai";
 import type {
   SessionRecordV1,
   SessionMessageRecordV1,
@@ -81,6 +81,17 @@ export type SessionUiMessageChunkCallback = (
   chunk: SessionUiMessageChunk,
 ) => Promise<void>;
 
+/** 单个模型 UI stream 开始前的 canonical step 回调。 */
+export type SessionUiMessageStepStartCallback = () => Promise<void>;
+
+/** 单个模型 UI stream 完成后的 canonical step 快照回调。 */
+export type SessionUiMessageStepFinishCallback = (
+  message: SessionMessageRecordV1,
+) => Promise<void>;
+
+/** 单个模型 UI stream 未完成时的 canonical step 清理回调。 */
+export type SessionUiMessageStepAbortCallback = () => Promise<void>;
+
 /**
  * Session 执行结果。
  */
@@ -104,6 +115,14 @@ export interface SessionRunResult {
    */
   assistantMessage?: SessionMessageRecordV1 | null;
 
+  /**
+   * 工具运行期显式生成、并在 Assistant 末尾持久化的文件 Parts。
+   *
+   * 关键点（中文）：该字段与聚合 `assistantMessage` 分离，Session 不需要从最终
+   * UIMessage 反推哪些文件来自工具通道。
+   */
+  assistant_file_parts?: FileUIPart[];
+
   /**
    * 本轮执行结束后待写入长期历史的 user 消息。
    *

package/src/session/SessionMessages.ts

@@ -610,6 +610,37 @@ export class SessionMessages {
     } as SessionMutation, message);
   }
 
+  /** @internal 原子提交当前 Assistant step 的 metadata 快照。 */
+  async commit_assistant_step(
+    message_id: string,
+    parts: SessionAssistantMessagePart[],
+  ): Promise<void> {
+    await this.enqueue_assistant_write(message_id, async () => {
+      const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
+      require_streaming_assistant(current);
+      if (
+        parts.length !== current.parts.length ||
+        parts.some((part, index) =>
+          part.part_id !== current.parts[index]?.part_id ||
+          part.sequence !== current.parts[index]?.sequence
+        )
+      ) {
+        throw new Error(
+          `Assistant step changed canonical Part identity: ${message_id}`,
+        );
+      }
+      const created_at = Date.now();
+      const message: SessionAssistantMessage = {
+        ...current,
+        revision: current.revision + 1,
+        updated_at: created_at,
+        parts: structuredClone(parts),
+      };
+      await this.store.write_assistant_message(message);
+      this.accept_message(message);
+    });
+  }
+
   /** @internal 收口 Assistant Message。 */
   async complete_assistant_message(
     message_id: string,

package/src/session/SessionTurn.ts

@@ -471,6 +471,18 @@ export class SessionTurn {
         const writer = await ensure_assistant_writer();
         await writer.apply_chunk(chunk);
       },
+      on_ui_message_step_start: async () => {
+        const writer = await ensure_assistant_writer();
+        await writer.begin_step();
+      },
+      on_ui_message_step_finish: async (message) => {
+        const writer = await ensure_assistant_writer();
+        await writer.finish_step(from_ui_assistant_parts(message.parts));
+      },
+      on_ui_message_step_abort: async () => {
+        const writer = assistant_writer_ref.current;
+        if (writer) await writer.abort_step();
+      },
       on_tool_input_ready: async (tool_input) => {
         const writer = await ensure_assistant_writer();
         await writer.prepare_tool_input(tool_input);
@@ -511,12 +523,8 @@ export class SessionTurn {
       : [];
     const final_assistant_writer = assistant_writer_ref.current;
     if (final_assistant_writer) {
-      for (const part of final_assistant_parts) {
-        if (part.type === "file") {
-          await final_assistant_writer.append_file_part(part);
-        } else if (part.type === "tool") {
-          await final_assistant_writer.reconcile_final_tool_part(part);
-        }
+      for (const part of from_ui_assistant_parts(result.assistant_file_parts)) {
+        if (part.type === "file") await final_assistant_writer.append_file_part(part);
       }
       if (input.abort_signal?.aborted) {
         await final_assistant_writer.stop();
@@ -618,7 +626,11 @@ function is_assistant_content_chunk(type: string): boolean {
     type === "reasoning-delta" ||
     type === "reasoning-end" ||
     type.startsWith("tool-") ||
-    type === "file"
+    type === "file" ||
+    type === "source-url" ||
+    type === "source-document" ||
+    type === "start-step" ||
+    type.startsWith("data-")
   );
 }