@downcity/agent 1.1.408 → 1.1.437

package/scripts/logger-isolation.test.mjs

@@ -34,8 +34,23 @@ test("get_logger keeps concurrent workspace logs isolated", async () => {
   const root_b = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-logger-isolation-b-"),
   );
-  const logger_a = get_logger(root_a);
-  const logger_b = get_logger(root_b);
+  const create_files = (root_path) => ({
+    resolve_path: (...segments) => path.resolve(root_path, ...segments),
+    append_file: async (file_path, content) => {
+      await fs.mkdir(path.dirname(file_path), { recursive: true });
+      await fs.appendFile(file_path, content);
+    },
+  });
+  const logger_a = get_logger();
+  const logger_b = get_logger();
+  logger_a.bind_storage(create_files(root_a), root_a, {
+    agent_id: "logger-a",
+    workspace_id: "workspace-a",
+  });
+  logger_b.bind_storage(create_files(root_b), root_b, {
+    agent_id: "logger-b",
+    workspace_id: "workspace-b",
+  });
 
   assert.notEqual(logger_a, logger_b);
   await Promise.all([

package/scripts/public-api-naming.test.mjs

@@ -21,28 +21,15 @@ const package_root = path.resolve(
 const public_declaration_files = [
   "agent/Agent.d.ts",
   "agent/AgentSessions.d.ts",
-  "remote/RemoteAgent.d.ts",
-  "remote/RemoteSession.d.ts",
   "session/Session.d.ts",
-  "plugin/core/PluginRegistry.d.ts",
   "types/agent/AgentOptions.d.ts",
   "types/agent/SessionActor.d.ts",
   "types/agent/SessionTypes.d.ts",
-  "types/agent/RemoteAgentOptions.d.ts",
-  "types/agent/RemoteAgentPluginAction.d.ts",
   "types/sdk/AgentSessionPrompt.d.ts",
   "types/sdk/AgentSessionStop.d.ts",
   "types/sdk/AgentSessionTurn.d.ts",
   "types/session/SessionOptions.d.ts",
   "types/session/SessionPort.d.ts",
-  "types/plugin/PluginContext.d.ts",
-  "types/plugin/PluginRuntime.d.ts",
-  "types/plugin/PluginAction.d.ts",
-  "types/plugin/PluginCommand.d.ts",
-  "types/plugin/PluginHttp.d.ts",
-  "types/plugin/PluginExecutionContext.d.ts",
-  "plugin/types/ActionSchedule.d.ts",
-  "types/rpc/RpcProtocol.d.ts",
 ];
 
 /** 删除声明文件注释，避免示例文本参与标识符检查。 */
@@ -80,13 +67,20 @@ test("Agent SDK root exports do not expose camelCase functions", () => {
   assert.deepEqual([...new Set(camel_function_exports)], []);
 });
 
-test("Agent internal module exports use snake_case function names", () => {
+test("Agent SDK does not expose a separate attachment concept", () => {
+  const file_path = path.join(package_root, "bin", "index.d.ts");
+  const content = strip_comments(fs.readFileSync(file_path, "utf8"));
+
+  assert.doesNotMatch(content, /AgentAttachment/u);
+});
+
+test("Agent non-root module exports use snake_case function names", () => {
   const source_root = path.join(package_root, "src");
   const failures = [];
   const camel_export_pattern =
     /^export\s+(?:async\s+)?function\s+([a-z][A-Za-z0-9_]*[A-Z][A-Za-z0-9_]*)\b/gm;
 
-  /** 递归扫描 Agent 源码，覆盖未从根入口暴露的内部模块 API。 */
+  /** 递归扫描 Agent 源码，覆盖未从根入口暴露的模块 API。 */
   function visit(directory) {
     for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
       const absolute_path = path.join(directory, entry.name);

package/scripts/session-agent-message-part-order.test.mjs

@@ -0,0 +1,63 @@
+/**
+ * @file 验证 Agent Message 的终态 Error 与 Turn 结果 Part 使用同一 canonical sequence。
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { SessionAgentMessageWriter } from "../bin/session/SessionMessages.js";
+
+/** 使用最小内存 Recorder 验证 Writer 的 Part 顺序能力。 */
+test("Error Part 在后续 Turn 结果 Data Part 之前写入", async () => {
+  let message = {
+    message_id: "agent:session-1:message-1",
+    session_id: "session-1",
+    turn_id: "turn-1",
+    sequence: 2,
+    revision: 1,
+    visibility: "visible",
+    created_at: 1,
+    updated_at: 1,
+    role: "agent",
+    state: "streaming",
+    parts: [],
+  };
+  const recorder = {
+    get_message: () => message,
+    project_agent_part: (_message_id, part) => {
+      const index = message.parts.findIndex((candidate) => candidate.part_id === part.part_id);
+      const parts = [...message.parts];
+      if (index < 0) parts.push(part);
+      else parts[index] = part;
+      message = { ...message, parts };
+    },
+    commit_agent_parts: async (_message_id, new_parts) => {
+      message = {
+        ...message,
+        revision: message.revision + 1,
+        parts: [...message.parts, ...new_parts],
+      };
+    },
+    complete_agent_message: async (_message_id, status) => {
+      message = { ...message, state: "done", revision: message.revision + 1 };
+    },
+  };
+  const writer = new SessionAgentMessageWriter(recorder, message.message_id);
+
+  await writer.append_result_parts([{ type: "text", text: "处理中" }]);
+  await writer.append_error({
+    scope: "turn",
+    code: "turn_execution_failed",
+    message: "执行失败",
+    recoverable: true,
+  });
+  await writer.append_result_parts([{
+    type: "data",
+    data_type: "data-session-turn-file-diff",
+    data: { files: [], additions: 0, deletions: 0 },
+  }]);
+  await writer.fail("执行失败");
+
+  assert.deepEqual(message.parts.map((part) => part.type), ["text", "error", "data"]);
+  assert.deepEqual(message.parts.map((part) => part.sequence), [1, 2, 3]);
+  assert.equal(message.state, "done");
+});

package/scripts/session-initialization.test.mjs

@@ -0,0 +1,141 @@
+/**
+ * @file 验证 Session 初始化图并发复用成功任务，并在临时存储失败后允许重试。
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Session } from "../bin/session/Session.js";
+
+/** 创建可以精确观测初始化调用次数的最小 Session。 */
+function create_session(overrides = {}) {
+  const calls = {
+    initialize_messages: 0,
+    read_instruction: 0,
+    read_metadata: 0,
+    write_metadata: 0,
+  };
+  let initialize_promise;
+  const store = {
+    session_id: "initialization-session",
+    origin: { type: "chat" },
+    attachments: {},
+    initialize: async () => {
+      if (!initialize_promise) initialize_promise = (async () => {
+        calls.initialize_messages += 1;
+        await overrides.initialize_messages?.(calls.initialize_messages);
+      })();
+      await initialize_promise;
+    },
+    list_messages: async () => [],
+    list_recoverable_agent_messages: async () => [],
+    message_stats: async () => ({ message_count: 0, storage_bytes: 0, latest_message: null }),
+    composer_storage: () => ({
+      list_messages: async () => [],
+      transaction: async (operation) => operation({
+        execute: () => {},
+        get: () => null,
+        all: () => [],
+      }),
+    }),
+    read_instruction: async () => {
+      calls.read_instruction += 1;
+      return await overrides.read_instruction?.(calls.read_instruction) ?? null;
+    },
+    read_metadata: async () => {
+      calls.read_metadata += 1;
+      return await overrides.read_metadata?.(calls.read_metadata) ?? {};
+    },
+    write_metadata: async () => {
+      calls.write_metadata += 1;
+    },
+    has_instruction: async () => false,
+    write_instruction: async () => {},
+  };
+  const session = new Session({
+    agent_id: "initialization-agent",
+    workspace_path: "/tmp/downcity-session-initialization",
+    origin: store.origin,
+    store,
+    create_session_store: () => store,
+    register_forked_session: () => {},
+    session_id: store.session_id,
+    get_tools: () => ({}),
+    logger: { log: async () => {} },
+    instruction_system_blocks: [],
+    get_instruction_system_blocks: () => [],
+    get_workspace_env: () => ({}),
+    get_hooks: () => ({}),
+    get_managed_plugin_system_blocks: async () => [],
+    get_agent_model: () => undefined,
+  });
+  return { calls, session };
+}
+
+/** 创建由测试显式释放的异步门。 */
+function create_gate() {
+  let release;
+  const promise = new Promise((resolve) => {
+    release = resolve;
+  });
+  return { promise, release };
+}
+
+test("Session 并发初始化共享完整初始化图", async () => {
+  const gate = create_gate();
+  const { calls, session } = create_session({
+    read_instruction: async () => {
+      await gate.promise;
+      return null;
+    },
+  });
+
+  const first = session.initialize();
+  const second = session.initialize();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(calls.initialize_messages, 1);
+  assert.equal(calls.read_instruction, 1);
+  assert.equal(calls.read_metadata, 1);
+  assert.ok(calls.write_metadata <= 1);
+
+  gate.release();
+  assert.equal(await first, session);
+  assert.equal(await second, session);
+  assert.equal(await session.initialize(), session);
+  assert.deepEqual(calls, {
+    initialize_messages: 1,
+    read_instruction: 1,
+    read_metadata: 1,
+    write_metadata: 1,
+  });
+});
+
+test("SessionComposition 恢复失败后允许 Session 重试", async () => {
+  const { calls, session } = create_session({
+    read_instruction: async (attempt) => {
+      if (attempt === 1) throw new Error("instruction unavailable");
+      return null;
+    },
+  });
+
+  await assert.rejects(session.initialize(), /instruction unavailable/);
+  await session.initialize();
+  assert.equal(calls.read_instruction, 2);
+  assert.equal(calls.initialize_messages, 1);
+  assert.equal(calls.read_metadata, 1);
+});
+
+test("SessionState 恢复失败后允许 Session 重试", async () => {
+  const { calls, session } = create_session({
+    read_metadata: async (attempt) => {
+      if (attempt === 1) throw new Error("metadata unavailable");
+      return {};
+    },
+  });
+
+  await assert.rejects(session.initialize(), /metadata unavailable/);
+  await session.initialize();
+  assert.equal(calls.read_metadata, 2);
+  assert.equal(calls.write_metadata, 1);
+  assert.equal(calls.read_instruction, 1);
+  assert.equal(calls.initialize_messages, 1);
+});

package/scripts/session-message-timeline.test.mjs

@@ -6,7 +6,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { to_session_message_timeline_events } from "../bin/index.js";
 
-test("Session timeline preserves assistant text and tool order", () => {
+test("Session timeline preserves Agent text and tool order", () => {
   const message = {
     message_id: "assistant-1",
     session_id: "session-1",
@@ -16,9 +16,8 @@ test("Session timeline preserves assistant text and tool order", () => {
     visibility: "visible",
     created_at: 10,
     updated_at: 20,
-    type: "assistant",
-    kind: "normal",
-    status: "completed",
+    role: "agent",
+    state: "done",
     parts: [
       {
         part_id: "text-1",
@@ -49,10 +48,10 @@ test("Session timeline preserves assistant text and tool order", () => {
 
   const events = to_session_message_timeline_events(message);
   assert.deepEqual(events.map((event) => event.role), [
-    "assistant",
+    "agent",
     "tool-call",
     "tool-result",
-    "assistant",
+    "agent",
   ]);
   assert.deepEqual(events.map((event) => event.id), [
     "assistant-1:0",

package/scripts/session-messages-error-part.test.mjs

@@ -0,0 +1,175 @@
+/**
+ * @file 验证 SessionMessages 将 Error 归入当前 Turn 的 Agent Message，而非无条件新建消息。
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { SessionMessages } from "../bin/session/SessionMessages.js";
+
+/** 创建支持聚合创建和 expected revision 更新的最小内存 SessionStorage。 */
+function create_fixture(initial_messages = []) {
+  let stored_messages = structuredClone(initial_messages);
+  let update_count = 0;
+  const publications = [];
+  const store = {
+    initialize: async () => {},
+    list_messages: async () => structuredClone(stored_messages),
+    list_recoverable_agent_messages: async () => structuredClone(
+      stored_messages.filter((message) =>
+        message.role === "agent" && message.state === "streaming"
+      ),
+    ),
+    read_message: async (message_id) => structuredClone(
+      stored_messages.find((message) => message.message_id === message_id) ?? null,
+    ),
+    read_latest_agent_message: async (turn_id) => structuredClone(
+      stored_messages
+        .filter((message) =>
+          message.role === "agent" && (!turn_id || message.turn_id === turn_id)
+        )
+        .sort((left, right) => right.sequence - left.sequence)[0] ?? null,
+    ),
+    message_stats: async () => ({ message_count: stored_messages.length, storage_bytes: 0, latest_message: structuredClone(stored_messages.at(-1) ?? null) }),
+    create_message: async (build_message) => {
+      const message = build_message({
+        message_sequence: next_message_sequence(stored_messages),
+      });
+      stored_messages.push(structuredClone(message));
+      return structuredClone(message);
+    },
+    update_message: async ({ message, expected_revision }) => {
+      update_count += 1;
+      const index = stored_messages.findIndex(
+        (candidate) => candidate.message_id === message.message_id,
+      );
+      const current = stored_messages[index];
+      if (!current || current.revision !== expected_revision) throw new Error("revision conflict");
+      stored_messages[index] = structuredClone(message);
+    },
+  };
+  const messages = new SessionMessages({
+    session_id: "session-1",
+    store,
+    publish: (mutation) => publications.push(mutation),
+  });
+  return {
+    messages,
+    publications,
+    read_active: () => structuredClone(stored_messages.filter((message) => message.role !== "agent" || message.state !== "streaming")),
+    read_draft: () => structuredClone(stored_messages.find((message) => message.role === "agent" && message.state === "streaming") ?? null),
+    get_update_count: () => update_count,
+  };
+}
+
+test("Model delta 只更新运行投影，Step 完成时才持久化一次", async () => {
+  const fixture = create_fixture();
+  await fixture.messages.initialize();
+  const writer = await fixture.messages.open_agent_message({ turn_id: "turn-1" });
+  await writer.begin_step();
+  await writer.apply_model_event({ type: "text_start", content_id: "text-1" });
+  await writer.apply_model_event({ type: "text_delta", content_id: "text-1", delta: "你" });
+  await writer.apply_model_event({ type: "text_delta", content_id: "text-1", delta: "好" });
+  await writer.apply_model_event({ type: "text_finish", content_id: "text-1" });
+
+  assert.equal(fixture.get_update_count(), 0);
+  assert.equal(fixture.read_draft().parts.length, 0);
+  assert.equal(fixture.messages.get_message(writer.message_id).parts[0].text, "你好");
+
+  await writer.finish_step([{
+    part_id: "collector-text-1",
+    sequence: 1,
+    type: "text",
+    text: "你好",
+    state: "done",
+  }]);
+
+  assert.equal(fixture.get_update_count(), 1);
+  assert.equal(fixture.read_draft().parts[0].text, "你好");
+});
+
+/** 返回下一条顶层 Message sequence。 */
+function next_message_sequence(messages) {
+  return messages
+    .reduce((maximum, message) => Math.max(maximum, message.sequence), 0) + 1;
+}
+
+/** 创建一条已完成的 canonical Agent Message。 */
+function create_completed_agent_message() {
+  return {
+    message_id: "agent-1",
+    session_id: "session-1",
+    turn_id: "turn-1",
+    sequence: 1,
+    revision: 1,
+    visibility: "visible",
+    created_at: 1,
+    updated_at: 1,
+    role: "agent",
+    state: "done",
+    parts: [{ part_id: "text-1", sequence: 1, type: "text", text: "处理中", state: "done" }],
+  };
+}
+
+/** 创建标准 Turn Error 输入。 */
+function create_error_input() {
+  return {
+    scope: "turn",
+    turn_id: "turn-1",
+    code: "turn_execution_failed",
+    message: "执行失败",
+    recoverable: true,
+  };
+}
+
+test("已有流式 Agent Message 时 Error 追加到同一草稿", async () => {
+  const fixture = create_fixture();
+  await fixture.messages.initialize();
+  const writer = await fixture.messages.open_agent_message({ turn_id: "turn-1" });
+  await writer.append_result_parts([{ type: "text", text: "处理中" }]);
+  const message_id = writer.message_id;
+
+  const result = await fixture.messages.append_error_part(create_error_input());
+
+  assert.equal(result.message_id, message_id);
+  assert.equal(fixture.read_active().length, 0);
+  assert.deepEqual(fixture.read_draft().parts.map((part) => part.type), ["text", "error"]);
+  assert.deepEqual(fixture.read_draft().parts.map((part) => part.sequence), [1, 2]);
+});
+
+test("已有已完成 Agent Message 时 Error 作为同 Message 的新 revision 追加", async () => {
+  const original = create_completed_agent_message();
+  const fixture = create_fixture([original]);
+  await fixture.messages.initialize();
+
+  const result = await fixture.messages.append_error_part(create_error_input());
+
+  assert.equal(result.message_id, original.message_id);
+  assert.equal(fixture.read_active().length, 1);
+  assert.deepEqual(result.parts.map((part) => part.type), ["text", "error"]);
+  assert.deepEqual(result.parts.map((part) => part.sequence), [1, 2]);
+  assert.equal(result.revision, 2);
+  assert.equal(result.state, "done");
+});
+
+test("同 Turn 同错误码重复追加保持幂等", async () => {
+  const fixture = create_fixture([create_completed_agent_message()]);
+  await fixture.messages.initialize();
+  const first = await fixture.messages.append_error_part(create_error_input());
+  const second = await fixture.messages.append_error_part(create_error_input());
+
+  assert.equal(second.message_id, first.message_id);
+  assert.equal(second.revision, first.revision);
+  assert.equal(second.parts.filter((part) => part.type === "error").length, 1);
+});
+
+test("Turn 尚无 Agent Message 时才创建仅含 Error 的 Agent Message", async () => {
+  const fixture = create_fixture();
+  await fixture.messages.initialize();
+
+  const result = await fixture.messages.append_error_part(create_error_input());
+
+  assert.equal(result.role, "agent");
+  assert.equal(result.state, "done");
+  assert.deepEqual(result.parts.map((part) => part.type), ["error"]);
+  assert.equal(fixture.read_active().length, 1);
+});

package/scripts/session-messages-error.test.mjs

@@ -12,6 +12,7 @@ function create_messages(store) {
     store: {
       initialize: async () => {},
       list_messages: async () => [],
+      list_recoverable_agent_messages: async () => [],
       ...store,
     },
     publish: () => {},
@@ -20,7 +21,7 @@ function create_messages(store) {
 
 test("append_user_message 透传 Store 写入失败", async () => {
   const messages = create_messages({
-    append_message: async () => {
+    create_message: async () => {
       throw new Error("disk full");
     },
   });
@@ -28,29 +29,69 @@ test("append_user_message 透传 Store 写入失败", async () => {
   await assert.rejects(
     messages.append_user_message({
       turn_id: "turn-1",
-      input_type: "prompt",
       parts: [{
         part_id: "text-1",
         type: "text",
         text: "hello",
-        state: "done",
       }],
     }),
     /disk full/,
   );
 });
 
-test("open_assistant_message 透传草稿写入失败", async () => {
+test("open_agent_message 透传草稿写入失败", async () => {
   const messages = create_messages({
-    create_assistant_message: async () => {
+    create_message: async () => {
       throw new Error("disk full");
     },
   });
   await messages.initialize();
   await assert.rejects(
-    messages.open_assistant_message({
+    messages.open_agent_message({
       turn_id: "turn-1",
     }),
     /disk full/,
   );
 });
+
+test("SessionMessages 并发初始化只执行一次 Store 恢复", async () => {
+  let initialize_count = 0;
+  let list_count = 0;
+  let release_initialize;
+  const initialize_gate = new Promise((resolve) => {
+    release_initialize = resolve;
+  });
+  const messages = create_messages({
+    initialize: async () => {
+      initialize_count += 1;
+      await initialize_gate;
+    },
+    list_recoverable_agent_messages: async () => {
+      list_count += 1;
+      return [];
+    },
+  });
+
+  const first = messages.initialize();
+  const second = messages.initialize();
+  await Promise.resolve();
+  assert.equal(initialize_count, 1);
+
+  release_initialize();
+  await Promise.all([first, second]);
+  assert.equal(list_count, 1);
+});
+
+test("SessionMessages 初始化失败后允许重试", async () => {
+  let initialize_count = 0;
+  const messages = create_messages({
+    initialize: async () => {
+      initialize_count += 1;
+      if (initialize_count === 1) throw new Error("restore failed");
+    },
+  });
+
+  await assert.rejects(messages.initialize(), /restore failed/);
+  await messages.initialize();
+  assert.equal(initialize_count, 2);
+});

package/scripts/session-prompt-idempotency.test.mjs

@@ -0,0 +1,91 @@
+/**
+ * @file 验证 Session Prompt 可以从 canonical Message 恢复同一业务请求的完成结果。
+ */
+
+import { createHash } from "node:crypto";
+import assert from "node:assert/strict";
+import test from "node:test";
+import { SessionLoop } from "../bin/session/SessionLoop.js";
+import { SessionQueue } from "../bin/session/SessionQueue.js";
+
+/** 创建只覆盖已完成幂等请求读取路径的最小 SessionLoop。 */
+function create_loop(request_id) {
+  const session_id = "idempotent-session";
+  const digest = createHash("sha256")
+    .update(session_id)
+    .update("\u0000")
+    .update(request_id)
+    .digest("hex");
+  const turn_id = `turn-request:${digest}`;
+  const user_message = {
+    message_id: `user-request:${digest}`,
+    session_id,
+    turn_id,
+    sequence: 1,
+    revision: 1,
+    visibility: "visible",
+    created_at: 1,
+    updated_at: 1,
+    role: "user",
+    parts: [{ part_id: "user-part", sequence: 1, type: "text", text: "hello" }],
+  };
+  const agent_message = {
+    message_id: "agent-result",
+    session_id,
+    turn_id,
+    sequence: 2,
+    revision: 1,
+    visibility: "visible",
+    created_at: 2,
+    updated_at: 2,
+    role: "agent",
+    state: "done",
+    parts: [{ part_id: "agent-part", sequence: 1, type: "text", text: "world", state: "done" }],
+  };
+  let execute_count = 0;
+  const loop = new SessionLoop({
+    session_id,
+    session_origin: { type: "chat" },
+    workspace_path: "/tmp/downcity-idempotent-prompt",
+    executor: {
+      execute: async () => {
+        execute_count += 1;
+        return { text: "unexpected", success: true };
+      },
+    },
+    maintain_context: async () => {},
+    state: { ensure_runnable: async () => {} },
+    messages: {
+      get_message: (message_id) => message_id === user_message.message_id
+        ? user_message
+        : undefined,
+      read_latest_agent_message: async (requested_turn_id) => requested_turn_id === turn_id
+        ? agent_message
+        : null,
+    },
+    events: { publish: () => {} },
+    logger: { log: async () => {} },
+    queue: new SessionQueue(),
+    interactions: { cancel_all: async () => {} },
+    shell_approval_gateway: {},
+  });
+  return { loop, turn_id, get_execute_count: () => execute_count };
+}
+
+test("相同 request_id 直接恢复原 Turn 结果且不重复执行", async () => {
+  const request_id = "inbound_123";
+  const { loop, turn_id, get_execute_count } = create_loop(request_id);
+
+  const first = await loop.prompt({ query: "hello", request_id });
+  const second = await loop.prompt({ query: "hello", request_id });
+
+  assert.equal(first.id, turn_id);
+  assert.equal(second.id, turn_id);
+  assert.deepEqual(await first.finished, {
+    turn_id,
+    text: "world",
+    success: true,
+  });
+  assert.deepEqual(await second.finished, await first.finished);
+  assert.equal(get_execute_count(), 0);
+});