@downcity/agent 1.1.267 → 1.1.269

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.267",
+  "version": "1.1.269",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",
@@ -12,8 +12,8 @@
     }
   },
   "dependencies": {
-    "@downcity/shell": "^0.1.123",
-    "@downcity/type": "0.1.153",
+    "@downcity/shell": "^0.1.125",
+    "@downcity/type": "0.1.155",
     "ai": "^6.0.193",
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",

package/scripts/executor-failure-result.test.mjs

@@ -0,0 +1,81 @@
+/**
+ * @file 验证执行器失败结果不会伪造 Assistant 正文。
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { MockLanguageModelV3 } from "ai/test";
+
+import { CoreEngineRunner } from "../bin/executor/core-engine/CoreEngineRunner.js";
+import { ExecutorRecoveryPolicy } from "../bin/executor/services/ExecutorRecoveryPolicy.js";
+
+function create_run_context() {
+  return {
+    sessionId: "executor-failure-test",
+    injectedUserMessages: [],
+    deferredPersistedUserMessages: [],
+    pendingAssistantFileParts: [],
+  };
+}
+
+test("CoreEngine Provider 失败时只返回结构化错误", async () => {
+  const model = new MockLanguageModelV3({
+    modelId: "failing-model",
+    doStream: async () => {
+      throw new Error("quota exceeded");
+    },
+  });
+  const runner = new CoreEngineRunner({
+    session_id: "executor-failure-test",
+    logger: { log: async () => {} },
+    should_compact_on_error: () => false,
+  });
+  const messages = [{
+    id: "user-1",
+    role: "user",
+    metadata: {
+      v: 1,
+      ts: 1,
+      sessionId: "executor-failure-test",
+      source: "ingress",
+      kind: "normal",
+    },
+    parts: [{ type: "text", text: "hello" }],
+  }];
+
+  const result = await runner.run({
+    execute_input: { query: "hello", system: [], messages, tools: {} },
+    model,
+    run_context: create_run_context(),
+    resolve_step_inputs: async () => ({ model, system: [], tools: {} }),
+    reload_history: async () => messages,
+  });
+
+  assert.equal(result.success, false);
+  assert.match(result.error, /quota exceeded/);
+  assert.equal(result.assistantMessage, undefined);
+});
+
+test("恢复策略捕获普通异常后只返回结构化错误", async () => {
+  const policy = new ExecutorRecoveryPolicy({
+    session_id: "executor-failure-test",
+    logger: { log: async () => {} },
+    should_compact: () => false,
+  });
+  const run_context = create_run_context();
+  const result = await policy.run_with_retry({
+    query: "hello",
+    model: {},
+    run_context,
+    prepare_execute_input: async () => {
+      throw new Error("configuration failed");
+    },
+    execute_prepared_run: async () => {
+      throw new Error("unexpected execution");
+    },
+  });
+
+  assert.equal(result.success, false);
+  assert.match(result.error, /configuration failed/);
+  assert.equal(result.assistantMessage, undefined);
+});

package/scripts/openai-responses-continuation.test.mjs

@@ -1,5 +1,5 @@
 /**
- * @file 验证 AI SDK OpenAI Responses 使用持久化 itemId 生成 HTTP item_reference。
+ * @file 验证 Session 使用完整工具事务续接 OpenAI Responses。
  */
 
 import test from "node:test";
@@ -7,7 +7,8 @@ import assert from "node:assert/strict";
 import { createOpenAI } from "@ai-sdk/openai";
 import { convertToModelMessages } from "ai";
 
-test("OpenAI Responses 默认 store 策略使用 item_reference continuation", async () => {
+/** 捕获 AI SDK 在指定 store 策略下生成的 Responses 请求体。 */
+async function capture_request_body(store) {
   let request_body;
   const openai = createOpenAI({
     apiKey: "test-api-key",
@@ -30,11 +31,25 @@ test("OpenAI Responses 默认 store 策略使用 item_reference continuation", a
   }]);
 
   await assert.rejects(
-    openai.responses("gpt-5").doGenerate({ prompt: messages }),
+    openai.responses("gpt-5").doGenerate({
+      prompt: messages,
+      providerOptions: { openai: { store } },
+    }),
     /request captured/,
   );
+  return request_body;
+}
+
+test("Responses store=false 发送完整 function_call", async () => {
+  const request_body = await capture_request_body(false);
   assert.deepEqual(request_body.input, [
-    { type: "item_reference", id: "fc_1" },
+    {
+      type: "function_call",
+      call_id: "call_1",
+      name: "lookup",
+      arguments: "{\"q\":\"x\"}",
+      id: "fc_1",
+    },
     {
       type: "function_call_output",
       call_id: "call_1",
@@ -42,7 +57,22 @@ test("OpenAI Responses 默认 store 策略使用 item_reference continuation", a
     },
   ]);
   assert.equal(
-    request_body.input.some((item) => item.type === "function_call"),
+    request_body.input.some((item) => item.type === "item_reference"),
     false,
   );
 });
+
+test("Responses store=true 使用已存储 item_reference", async () => {
+  const request_body = await capture_request_body(true);
+  assert.deepEqual(request_body.input, [
+    {
+      type: "item_reference",
+      id: "fc_1",
+    },
+    {
+      type: "function_call_output",
+      call_id: "call_1",
+      output: "ok",
+    },
+  ]);
+});

package/scripts/session-messages.test.mjs

@@ -14,6 +14,7 @@ import { SessionApprovalBroker } from "../bin/session/approval/SessionApprovalBr
 import { compose_session_compaction } from "../bin/session/messages/SessionMessageCompaction.js";
 import {
   from_ui_assistant_parts,
+  from_ui_user_parts,
   to_executor_history,
   to_executor_ui_message,
 } from "../bin/session/messages/SessionMessageCodec.js";
@@ -281,6 +282,126 @@ test("Streaming Tool Provider metadata 在输入和输出状态间完整保留",
   assert.equal(tool_part.state, "completed");
 });
 
+test("AI SDK 流式 metadata、source、data、step 和审批状态完整持久化", async () => {
+  const { recorder, file_path } = await create_recorder("ui-chunk-semantics-test");
+  const writer = await recorder.open_assistant_message({
+    turn_id: "turn-ui-chunks",
+    segment_index: 1,
+  });
+  await writer.apply_chunk({
+    type: "text-start",
+    id: "text_1",
+    providerMetadata: { openai: { itemId: "text_start" } },
+  });
+  await writer.apply_chunk({ type: "text-delta", id: "text_1", delta: "hello" });
+  await writer.apply_chunk({
+    type: "text-end",
+    id: "text_1",
+    providerMetadata: { openai: { itemId: "text_end" } },
+  });
+  await writer.apply_chunk({ type: "reasoning-start", id: "reasoning_1" });
+  await writer.apply_chunk({
+    type: "reasoning-delta",
+    id: "reasoning_1",
+    delta: "think",
+    providerMetadata: { openai: { itemId: "reasoning_delta" } },
+  });
+  await writer.apply_chunk({ type: "reasoning-end", id: "reasoning_1" });
+  await writer.apply_chunk({
+    type: "source-url",
+    sourceId: "source_1",
+    url: "https://example.com/old",
+  });
+  await writer.apply_chunk({
+    type: "source-url",
+    sourceId: "source_1",
+    url: "https://example.com/new",
+    title: "Updated source",
+    providerMetadata: { openai: { itemId: "source_item" } },
+  });
+  await writer.apply_chunk({
+    type: "data-progress",
+    id: "progress_1",
+    data: { percent: 10 },
+  });
+  await writer.apply_chunk({
+    type: "data-progress",
+    id: "progress_1",
+    data: { percent: 90 },
+  });
+  await writer.apply_chunk({
+    type: "data-progress",
+    id: "transient_1",
+    data: { percent: 100 },
+    transient: true,
+  });
+  await writer.apply_chunk({
+    type: "tool-input-start",
+    toolCallId: "call_approval",
+    toolName: "lookup",
+    title: "Lookup",
+    dynamic: true,
+    providerMetadata: { openai: { itemId: "fc_approval" } },
+  });
+  await writer.apply_chunk({
+    type: "tool-input-available",
+    toolCallId: "call_approval",
+    toolName: "lookup",
+    input: { q: "downcity" },
+    toolMetadata: { category: "search" },
+  });
+  await writer.apply_chunk({
+    type: "tool-approval-request",
+    approvalId: "approval_stream_1",
+    toolCallId: "call_approval",
+  });
+  await writer.apply_chunk({
+    type: "tool-output-denied",
+    toolCallId: "call_approval",
+  });
+  await writer.apply_chunk({
+    type: "file",
+    mediaType: "image/png",
+    url: "https://example.com/output.png",
+    providerMetadata: { openai: { fileId: "output_file" } },
+  });
+  await writer.apply_chunk({ type: "start-step" });
+  await writer.complete();
+
+  const assistant = (await read_jsonl(file_path))[0];
+  assert.deepEqual(assistant.parts.map((part) => part.type), [
+    "text",
+    "reasoning",
+    "source",
+    "data",
+    "tool",
+    "file",
+    "step-start",
+  ]);
+  assert.deepEqual(assistant.parts[0].provider_metadata, {
+    openai: { itemId: "text_end" },
+  });
+  assert.deepEqual(assistant.parts[1].provider_metadata, {
+    openai: { itemId: "reasoning_delta" },
+  });
+  assert.equal(assistant.parts[2].url, "https://example.com/new");
+  assert.equal(assistant.parts[2].title, "Updated source");
+  assert.deepEqual(assistant.parts[3].data, { percent: 90 });
+  const tool_part = assistant.parts[4];
+  assert.equal(tool_part.state, "failed");
+  assert.equal(tool_part.title, "Lookup");
+  assert.equal(tool_part.dynamic, true);
+  assert.deepEqual(tool_part.tool_metadata, { category: "search" });
+  assert.deepEqual(tool_part.approval, {
+    approval_id: "approval_stream_1",
+    approved: false,
+  });
+  assert.equal(
+    assistant.parts.some((part) => part.type === "data" && part.data_id === "transient_1"),
+    false,
+  );
+});
+
 test("UI Tool Provider metadata 经 Session roundtrip 后恢复为 ModelMessage providerOptions", async () => {
   const parts = from_ui_assistant_parts([{
     type: "dynamic-tool",
@@ -388,6 +509,171 @@ test("UI Tool Provider metadata 经 Session roundtrip 后恢复为 ModelMessage
   });
 });
 
+test("SessionMessage 无损恢复 AI SDK UIMessage 的完整 Part 语义", () => {
+  const user_parts = [
+    {
+      type: "text",
+      text: "分析附件",
+      state: "done",
+      providerMetadata: { openai: { itemId: "user_text_1" } },
+    },
+    {
+      type: "file",
+      mediaType: "image/png",
+      url: "https://example.com/input.png",
+      filename: "input.png",
+      providerMetadata: { openai: { fileId: "file_1" } },
+    },
+    {
+      type: "data-preferences",
+      id: "preferences_1",
+      data: { locale: "zh-CN" },
+    },
+  ];
+  const restored_user = to_executor_ui_message({
+    message_id: "user_roundtrip",
+    session_id: "session_roundtrip",
+    turn_id: "turn_roundtrip",
+    sequence: 1,
+    revision: 1,
+    visibility: "visible",
+    created_at: 1,
+    updated_at: 1,
+    type: "user",
+    input_type: "prompt",
+    parts: from_ui_user_parts(user_parts),
+  });
+  assert.deepEqual(restored_user.parts, user_parts);
+
+  const assistant_parts = [
+    {
+      type: "text",
+      text: "正在处理",
+      state: "streaming",
+      providerMetadata: { openai: { itemId: "msg_1" } },
+    },
+    {
+      type: "reasoning",
+      text: "先读取来源",
+      state: "done",
+      providerMetadata: { openai: { itemId: "reasoning_1" } },
+    },
+    {
+      type: "file",
+      mediaType: "application/pdf",
+      url: "https://example.com/report.pdf",
+      filename: "report.pdf",
+      providerMetadata: { openai: { fileId: "file_2" } },
+    },
+    {
+      type: "source-url",
+      sourceId: "source_url_1",
+      url: "https://example.com/source",
+      title: "Example source",
+      providerMetadata: { openai: { itemId: "source_1" } },
+    },
+    {
+      type: "source-document",
+      sourceId: "source_document_1",
+      mediaType: "application/pdf",
+      title: "Source document",
+      filename: "source.pdf",
+      providerMetadata: { openai: { itemId: "source_2" } },
+    },
+    { type: "step-start" },
+    {
+      type: "data-progress",
+      id: "progress_1",
+      data: { percent: 80 },
+    },
+    {
+      type: "dynamic-tool",
+      toolName: "lookup",
+      toolCallId: "call_streaming",
+      state: "input-streaming",
+      title: "Lookup",
+      toolMetadata: { category: "search" },
+      providerExecuted: false,
+      callProviderMetadata: { openai: { itemId: "fc_streaming" } },
+    },
+    {
+      type: "tool-fetch",
+      toolCallId: "call_ready",
+      state: "input-available",
+      input: { url: "https://example.com" },
+      title: "Fetch",
+      toolMetadata: { category: "network" },
+      providerExecuted: true,
+      callProviderMetadata: { openai: { itemId: "fc_ready" } },
+    },
+    {
+      type: "dynamic-tool",
+      toolName: "shell_exec",
+      toolCallId: "call_approval",
+      state: "approval-requested",
+      input: { cmd: "pwd" },
+      approval: { id: "approval_1" },
+    },
+    {
+      type: "tool-shell_exec",
+      toolCallId: "call_responded",
+      state: "approval-responded",
+      input: { cmd: "ls" },
+      approval: { id: "approval_2", approved: true, reason: "Allowed" },
+    },
+    {
+      type: "dynamic-tool",
+      toolName: "lookup",
+      toolCallId: "call_completed",
+      state: "output-available",
+      input: { q: "downcity" },
+      output: { count: 1 },
+      preliminary: true,
+      approval: { id: "approval_3", approved: true, reason: "Allowed" },
+      callProviderMetadata: { openai: { itemId: "fc_completed" } },
+      resultProviderMetadata: { openai: { itemId: "result_completed" } },
+    },
+    {
+      type: "dynamic-tool",
+      toolName: "parse",
+      toolCallId: "call_error",
+      state: "output-error",
+      input: undefined,
+      rawInput: "{invalid",
+      errorText: "Invalid input",
+      approval: { id: "approval_4", approved: true },
+      resultProviderMetadata: { openai: { itemId: "result_error" } },
+    },
+    {
+      type: "dynamic-tool",
+      toolName: "delete",
+      toolCallId: "call_denied",
+      state: "output-denied",
+      input: { path: "/tmp/a" },
+      approval: { id: "approval_5", approved: false, reason: "Denied" },
+    },
+  ];
+  const canonical_parts = from_ui_assistant_parts(assistant_parts);
+  const restored_assistant = to_executor_ui_message({
+    message_id: "assistant_roundtrip",
+    session_id: "session_roundtrip",
+    turn_id: "turn_roundtrip",
+    sequence: 2,
+    revision: 1,
+    visibility: "visible",
+    created_at: 2,
+    updated_at: 2,
+    type: "assistant",
+    kind: "normal",
+    segment_index: 1,
+    status: "streaming",
+    parts: canonical_parts,
+  });
+  assert.deepEqual(restored_assistant.parts, assistant_parts);
+  assert.equal(canonical_parts.find((part) => part.tool_call_id === "call_ready").dynamic, false);
+  assert.equal(canonical_parts.find((part) => part.tool_call_id === "call_completed").dynamic, true);
+});
+
 test("Approval Broker 只接受已经准备完整输入的 Tool", async () => {
   const { recorder, events } = await create_recorder("tool-ready-barrier-test");
   const approval_broker = new SessionApprovalBroker({
@@ -430,7 +716,7 @@ test("Approval Broker 只接受已经准备完整输入的 Tool", async () => {
   const tool = recorder.get_message(writer.message_id).parts[0];
   assert.equal(tool.state, "approval-required");
   assert.equal(tool.approval.approval_id, approval_handle.approval_id);
-  assert.equal(tool.approval.command, approval_input.command);
+  assert.equal(tool.approval.request.command, approval_input.command);
   assert.equal(tool.input.cmd, "ls -la /Users/example/Desktop");
   await approval_broker.resolve({
     approval_id: approval_handle.approval_id,

package/scripts/session-shell-approval.test.mjs

@@ -154,9 +154,9 @@ test("unrestricted Shell 审批保留当前 Turn 并等待用户决定", async (
       .flatMap((message) => message.type === "assistant" ? message.parts : [])
       .find((part) => part.type === "tool" && part.tool_call_id === "call_unrestricted");
     assert.ok(approval_snapshot, JSON.stringify(messages.items));
-    assert.equal(approval_snapshot.session_id, session.id);
-    assert.equal(approval_snapshot.turn_id, turn.id);
-    assert.equal(approval_snapshot.tool_call_id, "call_unrestricted");
+    assert.equal(approval_snapshot.request.session_id, session.id);
+    assert.equal(approval_snapshot.request.turn_id, turn.id);
+    assert.equal(approval_snapshot.request.tool_call_id, "call_unrestricted");
     assert.deepEqual(await approval_result, {
       success: true,
       approval_id: approval_snapshot.approval_id,

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

@@ -0,0 +1,101 @@
+/**
+ * @file 验证 Turn 失败只写入一次结构化错误，并保留已经生成的 Assistant 内容。
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { SessionApprovalBroker } from "../bin/session/approval/SessionApprovalBroker.js";
+import { JsonlSessionMessageStore } from "../bin/session/messages/JsonlSessionMessageStore.js";
+import { SessionMessages } from "../bin/session/SessionMessages.js";
+import { SessionEventHub } from "../bin/session/runtime/SessionEventHub.js";
+import { SessionTurn } from "../bin/session/SessionTurn.js";
+
+async function create_turn_harness(execute_run) {
+  const session_id = "session-turn-failure-test";
+  const root_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-turn-failure-"));
+  const messages = new SessionMessages({
+    session_id,
+    store: new JsonlSessionMessageStore({
+      session_id,
+      file_path: path.join(root_path, "active.jsonl"),
+    }),
+    publish: () => {},
+  });
+  await messages.initialize();
+
+  const turn = new SessionTurn({
+    session_id,
+    project_root: root_path,
+    executor: {
+      run: async ({ runContext }) => await execute_run(runContext),
+      stop: () => false,
+      compact_history: async () => ({ compacted: false, reason: "nothing_to_compact" }),
+    },
+    state: {
+      ensure_runnable: async () => {},
+      ensure_title_from_history: async () => {},
+      touch_metadata: async () => {},
+    },
+    messages,
+    events: new SessionEventHub(),
+    approvals: new SessionApprovalBroker({ session_id, messages }),
+    apply_command: async () => {},
+  });
+
+  return { messages, turn };
+}
+
+test("Provider 在输出前失败时只持久化 Error Message", async () => {
+  const { messages, turn } = await create_turn_harness(async () => ({
+    success: false,
+    error: "quota exceeded",
+    deferredPersistedUserMessages: [],
+  }));
+
+  const handle = await turn.prompt({ query: "hello" });
+  const result = await handle.finished;
+  const page = await messages.list_messages();
+
+  assert.equal(result.success, false);
+  assert.equal(result.error, "quota exceeded");
+  assert.equal(result.assistantMessage, undefined);
+  assert.deepEqual(page.items.map((message) => message.type), ["user", "error"]);
+  assert.equal(page.items[1].code, "turn_execution_failed");
+  assert.equal(page.items[1].message, "quota exceeded");
+});
+
+test("Provider 在部分输出后失败时保留 failed Assistant 并追加 Error Message", async () => {
+  const { messages, turn } = await create_turn_harness(async (run_context) => {
+    await run_context.onUiMessageChunkCallback({ type: "text-start", id: "text-1" });
+    await run_context.onUiMessageChunkCallback({
+      type: "text-delta",
+      id: "text-1",
+      delta: "partial response",
+    });
+    await run_context.onUiMessageChunkCallback({ type: "text-end", id: "text-1" });
+    return {
+      success: false,
+      error: "stream interrupted",
+      deferredPersistedUserMessages: [],
+    };
+  });
+
+  const handle = await turn.prompt({ query: "hello" });
+  const result = await handle.finished;
+  const page = await messages.list_messages();
+
+  assert.equal(result.success, false);
+  assert.equal(result.assistantMessage, undefined);
+  assert.deepEqual(page.items.map((message) => message.type), [
+    "user",
+    "assistant",
+    "error",
+  ]);
+  assert.equal(page.items[1].status, "failed");
+  assert.equal(page.items[1].parts[0].text, "partial response");
+  assert.equal(page.items[2].message, "stream interrupted");
+});

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

@@ -601,10 +601,6 @@ export class CoreEngineRunner {
       return {
         success: false,
         error: error_text,
-        assistantMessage: build_fallback_assistant_message(
-          session_id,
-          `Execution failed: ${error_text}`,
-        ),
         ...(compact_required ? { compact_required: true } : {}),
         deferredPersistedUserMessages: [
           ...input.run_context.deferredPersistedUserMessages,
@@ -635,7 +631,7 @@ function build_internal_user_message(input: {
   };
 }
 
-/** 构造 Executor 失败或空结果使用的临时 Assistant Message。 */
+/** 构造成功执行但缺少最终消息时使用的临时 Assistant Message。 */
 function build_fallback_assistant_message(
   session_id: string,
   text: string,

package/src/executor/services/ExecutorRecoveryPolicy.ts

@@ -107,16 +107,15 @@ interface ExecutorRecoveryRunInput {
  * 执行恢复与重试策略服务。
  */
 export class ExecutorRecoveryPolicy {
-  private readonly session_id: string;
   private readonly should_compact: ExecutorRecoveryPolicyOptions["should_compact"];
   private readonly logger: Logger;
   private retry_count = 0;
 
   constructor(options: ExecutorRecoveryPolicyOptions) {
-    this.session_id = String(options.session_id || "").trim();
+    const session_id = String(options.session_id || "").trim();
     this.should_compact = options.should_compact;
     this.logger = options.logger;
-    if (!this.session_id) {
+    if (!session_id) {
       throw new Error("ExecutorRecoveryPolicy requires a non-empty session_id");
     }
   }
@@ -161,8 +160,6 @@ export class ExecutorRecoveryPolicy {
         return this.build_failure_result({
           error_text:
             "Context length exceeded and retries failed. Please resend your question.",
-          fallback_text:
-            "Context length exceeded and retries failed. Please resend your question.",
           run_context: input.run_context,
         });
       }
@@ -173,7 +170,6 @@ export class ExecutorRecoveryPolicy {
       });
       return this.build_failure_result({
         error_text,
-        fallback_text: `Execution failed: ${error_text}`,
         run_context: input.run_context,
       });
     }
@@ -185,11 +181,6 @@ export class ExecutorRecoveryPolicy {
      */
     error_text: string;
 
-    /**
-     * fallback assistant 消息文本。
-     */
-    fallback_text: string;
-
     /**
      * 当前显式运行上下文。
      */
@@ -198,18 +189,6 @@ export class ExecutorRecoveryPolicy {
     return {
       success: false,
       error: input.error_text,
-      assistantMessage: {
-        id: `a:${this.session_id}:${Date.now()}`,
-        role: "assistant",
-        metadata: {
-          v: 1,
-          ts: Date.now(),
-          sessionId: this.session_id,
-          source: "egress",
-          kind: "normal",
-        },
-        parts: [{ type: "text", text: input.fallback_text }],
-      },
       deferredPersistedUserMessages: [
         ...input.run_context.deferredPersistedUserMessages,
       ],