@downcity/agent 1.1.430 → 1.1.438

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

package/scripts/session-queue.test.mjs

@@ -1,19 +1,19 @@
 /**
- * @file 验证 SessionQueue 只保存具体 Command 对象并维护确定的 FIFO 顺序。
+ * @file 验证 SessionQueue 只保存最小 Command 数据并维护确定的 FIFO 顺序。
  */
 
 import assert from "node:assert/strict";
 import test from "node:test";
 import { SessionQueue } from "../bin/session/SessionQueue.js";
-import { SessionCommand } from "../bin/session/SessionCommand.js";
 
 function create_command(name, executed, cancel) {
-  return new SessionCommand({
+  return {
+    kind: cancel ? "prompt" : "maintenance",
     execute: async () => {
       executed.push(name);
     },
     ...(cancel ? { cancel } : {}),
-  });
+  };
 }
 
 test("SessionQueue 按 FIFO 返回具体 Command 对象", async () => {
@@ -79,21 +79,22 @@ test("SessionQueue 可以把未处理 Command 恢复到队列头部", async () =
   assert.deepEqual(executed, ["head", "middle", "tail"]);
 });
 
-test("SessionCommand 成功执行后返回可选的持久化完成信息", async () => {
+test("SessionQueue 保留 Command 的类别与完成信息", async () => {
+  const queue = new SessionQueue();
   const completion = {
     type: "action",
     id: "config-completed",
     title: "Configuration updated",
     description: "The next step uses the new configuration.",
   };
-  const command = new SessionCommand({
+  const command = {
+    kind: "maintenance",
     execute: async () => {},
     completion,
-  });
-  const silent_command = new SessionCommand({
-    execute: async () => {},
-  });
+  };
+  queue.enqueue_command(command);
 
-  assert.deepEqual(await command.execute(), completion);
-  assert.equal(await silent_command.execute(), undefined);
+  assert.equal(queue.take_next(), command);
+  assert.equal(command.kind, "maintenance");
+  assert.deepEqual(command.completion, completion);
 });

package/scripts/session-storage-sqlite.test.mjs

@@ -0,0 +1,209 @@
+/** @file 验证 SessionStorage 的 SQLite 事务、投影、恢复与 Policy 隔离边界。 */
+
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { SqliteSessionStorage } from "../bin/session/storage/SqliteSessionStorage.js";
+
+/** 创建测试用文件系统协议。 */
+function create_files() {
+  return {
+    ensure_directory: async (directory_path) => await fs.mkdir(directory_path, { recursive: true }),
+    file_size: async (file_path) => (await fs.stat(file_path)).size,
+  };
+}
+
+/** 创建一个文件型 SessionStorage。 */
+async function create_storage(directory_path, options = {}) {
+  const storage = new SqliteSessionStorage({
+    session_id: options.session_id || "session-1",
+    agent_id: options.agent_id || "agent-1",
+    workspace_id: "workspace-1",
+    origin: { type: "chat" },
+    database_path: path.join(directory_path, "session.db"),
+    database_location: { type: "file" },
+    files: create_files(),
+    attachments: {},
+  });
+  await storage.initialize();
+  return storage;
+}
+
+/** 创建一条 User Message。 */
+function create_user_message(state) {
+  return {
+    message_id: "user-1",
+    session_id: "session-1",
+    turn_id: "turn-1",
+    sequence: state.message_sequence,
+    revision: 1,
+    role: "user",
+    visibility: "visible",
+    created_at: 10,
+    updated_at: 10,
+    parts: [{ part_id: "part-user-1", sequence: 1, type: "text", text: "你好" }],
+  };
+}
+
+test("Message 与 Part 分表原子保存并刷新列表投影", async () => {
+  const directory_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-session-storage-"));
+  const storage = await create_storage(directory_path);
+  const created = await storage.create_message(create_user_message);
+  assert.equal(created.role, "user");
+  const metadata = await storage.read_metadata();
+  assert.equal(metadata.message_count, 1);
+  assert.equal(metadata.preview_text, "你好");
+
+  const database = new DatabaseSync(path.join(directory_path, "session.db"), { readOnly: true });
+  try {
+    const message = database.prepare("SELECT role, state FROM messages").get();
+    assert.deepEqual({ ...message }, { role: "user", state: null });
+    const part = database.prepare("SELECT type, content FROM message_parts").get();
+    assert.equal(part.type, "text");
+    assert.deepEqual(Object.keys(JSON.parse(part.content)).sort(), ["text"]);
+  } finally {
+    database.close();
+  }
+
+  await assert.rejects(storage.update_message({
+    message: { ...created, revision: 3 },
+    expected_revision: 2,
+    changed_parts: [],
+  }), /revision conflict/);
+  const updated = {
+    ...created,
+    revision: 2,
+    updated_at: 20,
+    parts: [{ ...created.parts[0], text: "你好，SQLite" }],
+  };
+  await storage.update_message({
+    message: updated,
+    expected_revision: 1,
+    changed_parts: updated.parts,
+  });
+  assert.equal(updated.parts[0].text, "你好，SQLite");
+  assert.equal((await storage.read_metadata()).preview_text, "你好，SQLite");
+  await storage.dispose();
+});
+
+test("Storage 只查询中断状态，不擅自解释领域恢复语义", async () => {
+  const directory_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-session-storage-"));
+  const storage = await create_storage(directory_path);
+  await storage.create_message((state) => ({
+    message_id: "agent-1",
+    session_id: "session-1",
+    turn_id: "turn-1",
+    sequence: state.message_sequence,
+    revision: 1,
+    role: "agent",
+    state: "streaming",
+    visibility: "visible",
+    created_at: 10,
+    updated_at: 10,
+    parts: [
+      { part_id: "text-1", sequence: 1, step_id: "step-1", type: "text", text: "部分输出", state: "streaming" },
+      { part_id: "tool-1", sequence: 2, step_id: "step-1", type: "tool", tool_call_id: "call-1", tool_name: "read", state: "running" },
+      { part_id: "action-1", sequence: 3, type: "action", action_id: "action-1", action_type: "test", state: "running", title: "测试" },
+    ],
+  }));
+  await storage.dispose();
+
+  const reopened = await create_storage(directory_path);
+  const [message] = await reopened.list_recoverable_agent_messages();
+  assert.equal(message.state, "streaming");
+  assert.equal(message.parts[0].state, "streaming");
+  assert.equal(message.parts[1].state, "running");
+  assert.equal(message.parts[2].state, "running");
+  assert.equal((await reopened.read_metadata()).preview_text, "部分输出");
+  await reopened.dispose();
+});
+
+test("Composer Policy 只能写自己的派生 namespace，clear 触发 FK 清理", async () => {
+  const directory_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-session-storage-"));
+  const storage = await create_storage(directory_path);
+  await storage.create_message(create_user_message);
+  const policy = storage.composer_storage("sequence");
+  await policy.transaction((transaction) => {
+    transaction.execute("CREATE TABLE composer_sequence_test (message_id TEXT REFERENCES messages(message_id) ON DELETE CASCADE)");
+    transaction.execute("INSERT INTO composer_sequence_test (message_id) VALUES (?)", ["user-1"]);
+  });
+  await assert.rejects(policy.transaction((transaction) => transaction.execute("UPDATE messages SET visibility = 'internal'")), /can only mutate/);
+  await assert.rejects(policy.transaction((transaction) => transaction.execute("ALTER TABLE messages ADD COLUMN invalid TEXT")), /cannot execute database control/);
+  await assert.rejects(
+    policy.transaction((transaction) => transaction.execute(
+      "CREATE INDEX composer_sequence_messages_index ON messages(sequence)",
+    )),
+    /cannot execute database control/,
+  );
+  await storage.clear_messages();
+  assert.equal(await policy.transaction((transaction) => transaction.get("SELECT COUNT(*) AS count FROM composer_sequence_test")).then((row) => row.count), 0);
+  assert.equal((await storage.read_metadata()).preview_text, undefined);
+  await storage.dispose();
+});
+
+test("初始化失败会关闭连接并允许同一实例重试", async () => {
+  const directory_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-session-storage-"));
+  const database_path = path.join(directory_path, "session.db");
+  const database = new DatabaseSync(database_path);
+  database.exec("PRAGMA user_version = 99");
+  database.close();
+  const storage = new SqliteSessionStorage({
+    session_id: "session-1",
+    agent_id: "agent-1",
+    origin: { type: "chat" },
+    database_path,
+    database_location: { type: "file" },
+    files: create_files(),
+    attachments: {},
+  });
+  await assert.rejects(storage.initialize(), /Unsupported Session schema version/);
+  const repair = new DatabaseSync(database_path);
+  repair.exec("PRAGMA user_version = 0");
+  repair.close();
+  await storage.initialize();
+  assert.equal((await storage.read_metadata()).session_id, "session-1");
+  await storage.dispose();
+});
+
+test("旧 SQLite schema 必须由外部脚本迁移", async () => {
+  const directory_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-session-storage-"));
+  const database_path = path.join(directory_path, "session.db");
+  const database = new DatabaseSync(database_path);
+  database.exec("PRAGMA user_version = 1");
+  database.close();
+  const storage = new SqliteSessionStorage({
+    session_id: "session-1",
+    agent_id: "agent-1",
+    origin: { type: "chat" },
+    database_path,
+    database_location: { type: "file" },
+    files: create_files(),
+    attachments: {},
+  });
+  await assert.rejects(storage.initialize(), /requires the external migration script/);
+  await storage.dispose();
+});
+
+test("Codec 在损坏的 Part 内容进入领域层前失败", async () => {
+  const directory_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-session-storage-"));
+  const database_path = path.join(directory_path, "session.db");
+  const storage = await create_storage(directory_path);
+  await storage.create_message(create_user_message);
+  await storage.dispose();
+
+  const database = new DatabaseSync(database_path);
+  database.prepare(
+    "UPDATE message_parts SET content = ? WHERE part_id = ?",
+  ).run(JSON.stringify({ text: 42 }), "part-user-1");
+  database.close();
+
+  const reopened = await create_storage(directory_path);
+  await assert.rejects(
+    reopened.list_messages(),
+    /Invalid persisted Session Part part-user-1.*text must be a string/,
+  );
+  await reopened.dispose();
+});