@downcity/agent 1.1.199 → 1.1.202

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

@@ -0,0 +1,199 @@
+/**
+ * @file 验证 action record 的持久化、模型输入过滤与 timeline 投影。
+ *
+ * 关键点（中文）
+ * - action record 会作为 `type=action` item 写入 JSONL。
+ * - 同一个 action id 会被更新为一条历史记录，不拆成 running/completed 多条。
+ * - history composer 组装 LLM 输入时必须过滤 action record。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+import { JsonlSessionHistoryStore } from "../bin/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import { JsonlSessionHistoryComposer } from "../bin/executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
+import { toSessionTimelineEvents } from "../bin/session/browse/Browse.js";
+import { Agent } from "../bin/index.js";
+
+test("action record is upserted but filtered from LLM history", async () => {
+  const root_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-action-message-"),
+  );
+  const session_id = "action_session";
+  const store = new JsonlSessionHistoryStore({
+    rootPath: root_path,
+    agentId: "action_agent",
+    sessionId: session_id,
+  });
+  const composer = new JsonlSessionHistoryComposer({ store });
+
+  await store.write_record(
+    store.userText({
+      text: "hello",
+      metadata: { sessionId: session_id },
+      id: "u:1",
+    }),
+  );
+  await store.write_record(
+    store.action({
+      action: {
+        id: "action:1",
+        title: "Compacting session records",
+        state: "running",
+        turnId: "turn-1",
+      },
+      metadata: { sessionId: session_id },
+    }),
+  );
+  await store.write_record(
+    store.action({
+      action: {
+        id: "action:1",
+        title: "Session records compacted",
+        description: "Compacted earlier messages.",
+        state: "completed",
+        turnId: "turn-1",
+      },
+      metadata: { sessionId: session_id },
+    }),
+  );
+  await store.write_record(
+    store.assistantText({
+      text: "world",
+      metadata: { sessionId: session_id },
+      id: "a:1",
+    }),
+  );
+
+  const persisted_messages = await store.list_records();
+  assert.equal(persisted_messages.length, 3);
+  assert.equal(persisted_messages[1].type, "action");
+  assert.equal(persisted_messages[1].title, "Session records compacted");
+  assert.equal(persisted_messages[1].description, "Compacted earlier messages.");
+  assert.equal(persisted_messages[1].state, "completed");
+
+  const model_messages = await composer.prepare({
+    query: "",
+    tools: {},
+    system: [],
+    model: {},
+    retryCount: 0,
+  });
+  assert.deepEqual(
+    model_messages.map((message) => message.id),
+    ["u:1", "a:1"],
+  );
+
+  const timeline_events = toSessionTimelineEvents(persisted_messages[1]);
+  assert.equal(timeline_events.length, 1);
+  assert.equal(timeline_events[0].role, "action");
+  assert.equal(timeline_events[0].actionTitle, "Session records compacted");
+  assert.equal(timeline_events[0].actionDescription, "Compacted earlier messages.");
+  assert.equal(timeline_events[0].actionState, "completed");
+  assert.equal(
+    timeline_events[0].text,
+    "Session records compacted\nCompacted earlier messages.",
+  );
+});
+
+test("session.set persists and publishes model-switching actions", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-model-switching-"),
+  );
+  const agent = new Agent({
+    id: "model_switching_agent",
+    path: agent_path,
+  });
+  try {
+    const session = await agent.sessions.create({
+      sessionId: "model_switching_session",
+    });
+    const events = [];
+    const unsubscribe = session.subscribe((event) => {
+      if (event.type === "action") events.push(event);
+    });
+
+    await session.set({
+      model: {
+        modelId: "test-model",
+        provider: "test",
+      },
+    });
+    unsubscribe();
+
+    assert.deepEqual(
+      events.map((event) => `${event.title}:${event.state}`),
+      ["Switching session model:running", "Session model switched:completed"],
+    );
+    assert.equal(new Set(events.map((event) => event.id)).size, 1);
+
+    const records = await session.records({ view: "timeline" });
+    const action_events = records.items.filter(
+      (item) => item.role === "action",
+    );
+    assert.deepEqual(
+      action_events.map((event) => `${event.actionTitle}:${event.actionState}`),
+      ["Session model switched:completed"],
+    );
+  } finally {
+    await agent.dispose();
+  }
+});
+
+test("session.fork persists and publishes history-forking actions on source session", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-history-forking-"),
+  );
+  const agent = new Agent({
+    id: "history_forking_agent",
+    path: agent_path,
+  });
+  try {
+    const session = await agent.sessions.create({
+      sessionId: "history_forking_session",
+    });
+    await session.set({
+      model: {
+        modelId: "fork-test-model",
+        provider: "test",
+      },
+    });
+    await session.append_user_message({ text: "source message" });
+
+    const events = [];
+    const unsubscribe = session.subscribe((event) => {
+      if (event.type === "action") {
+        events.push(event);
+      }
+    });
+    const forked = await session.fork();
+    unsubscribe();
+
+    assert.deepEqual(
+      events.map((event) => `${event.title}:${event.state}`),
+      ["Forking session records:running", "Session records forked:completed"],
+    );
+    assert.equal(new Set(events.map((event) => event.id)).size, 1);
+    assert.notEqual(forked.id, session.id);
+
+    const source_records = await session.records({ view: "timeline" });
+    const source_fork_actions = source_records.items.filter(
+      (item) => item.role === "action" && item.actionTitle === "Session records forked",
+    );
+    assert.deepEqual(
+      source_fork_actions.map((event) => event.actionState),
+      ["completed"],
+    );
+
+    const forked_records = await forked.records({ view: "timeline" });
+    const forked_model_actions = forked_records.items.filter(
+      (item) => item.role === "action" && item.actionTitle === "Session model switched",
+    );
+    assert.equal(forked_model_actions.length, 1);
+  } finally {
+    await agent.dispose();
+  }
+});

package/scripts/session-compaction-prompts.test.mjs

@@ -0,0 +1,97 @@
+/**
+ * @file 验证 session compact prompt 与文件操作 XML 记录。
+ *
+ * 关键点（中文）
+ * - compact prompt 必须保持结构化摘要格式稳定。
+ * - 迭代更新 prompt 需要携带 previous-summary 标签。
+ * - 文件操作 XML 由本地解析追加，不依赖模型复述工具日志。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  SESSION_COMPACTION_SYSTEM_PROMPT,
+  append_session_compaction_file_operations,
+  build_initial_session_compaction_prompt,
+  build_turn_prefix_session_compaction_prompt,
+  build_update_session_compaction_prompt,
+} from "../bin/executor/composer/compaction/jsonl/JsonlSessionCompactionPrompts.js";
+import {
+  collect_session_compaction_file_operations,
+  format_session_compaction_file_operations,
+} from "../bin/executor/composer/compaction/jsonl/JsonlSessionCompactionFileOperations.js";
+
+test("session compaction prompts preserve structured formats", () => {
+  assert.match(
+    SESSION_COMPACTION_SYSTEM_PROMPT,
+    /Do NOT continue the conversation/,
+  );
+
+  const initial_prompt = build_initial_session_compaction_prompt({
+    conversation_text: "user: 请修改 packages/agent/src/foo.ts",
+  });
+  assert.match(initial_prompt, /## Goal/);
+  assert.match(initial_prompt, /## Constraints & Preferences/);
+  assert.match(initial_prompt, /## Critical Context/);
+  assert.match(
+    initial_prompt,
+    /Keep each section concise\. Preserve exact file paths/,
+  );
+
+  const update_prompt = build_update_session_compaction_prompt({
+    previous_summary: "## Goal\n旧目标",
+    new_conversation_text: "assistant: 已完成一部分",
+  });
+  assert.match(update_prompt, /<previous-summary>\n## Goal\n旧目标\n<\/previous-summary>/);
+  assert.match(update_prompt, /PRESERVE all existing information/);
+  assert.match(update_prompt, /## Next Steps/);
+
+  const prefix_prompt = build_turn_prefix_session_compaction_prompt({
+    prefix_text: "user: 这个 turn 太长",
+  });
+  assert.match(prefix_prompt, /## Original Request/);
+  assert.match(prefix_prompt, /## Context for Suffix/);
+});
+
+test("session compaction file operations are appended as xml", () => {
+  const messages = [
+    {
+      id: "a:1",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-exec_command",
+          input: {
+            cmd: "sed -n '1,40p' packages/agent/src/foo.ts && rg -n compact packages/agent/src",
+          },
+          output: [
+            "*** Update File: packages/agent/src/bar.ts",
+            " M packages/agent/src/baz.ts",
+          ].join("\n"),
+        },
+      ],
+    },
+  ];
+
+  const operations = collect_session_compaction_file_operations(messages);
+  assert.deepEqual(operations.read_files, [
+    "packages/agent/src",
+    "packages/agent/src/foo.ts",
+  ]);
+  assert.deepEqual(operations.modified_files, [
+    "packages/agent/src/bar.ts",
+    "packages/agent/src/baz.ts",
+  ]);
+
+  const xml = format_session_compaction_file_operations(messages);
+  assert.match(xml, /<read-files>\npackages\/agent\/src/);
+  assert.match(xml, /<modified-files>\npackages\/agent\/src\/bar\.ts/);
+
+  const summary = append_session_compaction_file_operations({
+    summary: "## Goal\n完成 compact",
+    file_operations_xml: xml,
+  });
+  assert.match(summary, /## Goal\n完成 compact\n\n<read-files>/);
+  assert.match(summary, /<\/modified-files>$/);
+});

package/scripts/session-history-archive.test.mjs

@@ -1,5 +1,5 @@
 /**
- * @file 验证 session.history 的 compact archive 分层读取语义。
+ * @file 验证 session.records 的 compact archive 分层读取语义。
  *
  * 关键点（中文）
  * - compact summary 是模型上下文消息，但不应作为用户可见 history item 返回。
@@ -91,7 +91,7 @@ async function write_archive(file_path, session_id, messages) {
   );
 }
 
-test("session.history hides compact summary and reads archive layers by archive_id", async () => {
+test("session.records hides compact summary and reads archive layers by archive_id", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-history-archive-"),
   );
@@ -99,7 +99,7 @@ test("session.history hides compact summary and reads archive layers by archive_
     id: "history_archive_agent",
     path: agent_path,
   });
-  const session = await agent.session_collection().create_session({
+  const session = await agent.sessions.create({
     sessionId: "history_archive_session",
   });
 
@@ -131,7 +131,7 @@ test("session.history hides compact summary and reads archive layers by archive_
       assistant_message(session.id, 2),
     ]);
 
-    const current_page = await session.history({
+    const current_page = await session.records({
       limit: 1,
     });
     assert.equal(current_page.total, 2);
@@ -144,7 +144,7 @@ test("session.history hides compact summary and reads archive layers by archive_
       ["u:31"],
     );
 
-    const next_current_page = await session.history({
+    const next_current_page = await session.records({
       cursor: current_page.next_cursor,
     });
     assert.equal(next_current_page.has_more, false);
@@ -153,7 +153,7 @@ test("session.history hides compact summary and reads archive layers by archive_
       ["a:32"],
     );
 
-    const previous_page = await session.history({
+    const previous_page = await session.records({
       archive_id: current_page.previous_archive_id,
     });
     assert.equal(previous_page.archive_id, "compact-B");
@@ -164,7 +164,7 @@ test("session.history hides compact summary and reads archive layers by archive_
       ["u:16", "a:17"],
     );
 
-    const oldest_page = await session.history({
+    const oldest_page = await session.records({
       archive_id: previous_page.previous_archive_id,
     });
     assert.equal(oldest_page.archive_id, "compact-A");
@@ -174,7 +174,7 @@ test("session.history hides compact summary and reads archive layers by archive_
       ["u:1", "a:2"],
     );
 
-    const timeline_page = await session.history({
+    const timeline_page = await session.records({
       view: "timeline",
       archive_id: "compact-B",
     });

package/scripts/session-history-inflight.test.mjs

@@ -1,5 +1,5 @@
 /**
- * @file 验证 session history 会把运行中的 assistant 收敛到 inflight 快照，并在完成后写回正式历史。
+ * @file 验证 session records 会把运行中的 assistant 收敛到 inflight 快照，并在完成后写回正式历史。
  *
  * 关键点（中文）
  * - 直接覆盖 JSONL history store 的落盘语义，确保运行中不中断丢失过程。
@@ -41,7 +41,7 @@ test("JsonlSessionHistoryStore exposes inflight assistant during execution and f
     sessionId: "session_test",
   });
 
-  await store.append(
+  await store.write_record(
     store.userText({
       text: "write to document",
       metadata: {
@@ -50,7 +50,7 @@ test("JsonlSessionHistoryStore exposes inflight assistant during execution and f
     }),
   );
 
-  await store.writeInflight(
+  await store.write_inflight(
     create_assistant_message([
       { type: "step-start" },
       { type: "text", text: "Let me inspect the document.", state: "done" },
@@ -64,7 +64,7 @@ test("JsonlSessionHistoryStore exposes inflight assistant during execution and f
     ]),
   );
 
-  const during_run = await store.list();
+  const during_run = await store.list_records();
   assert.equal(during_run.length, 2);
   assert.equal(during_run[1]?.role, "assistant");
   assert.deepEqual(
@@ -72,13 +72,13 @@ test("JsonlSessionHistoryStore exposes inflight assistant during execution and f
     ["step-start", "text", "tool-exec_command"],
   );
 
-  await store.finalizeInflight(
+  await store.finalize_inflight(
     create_assistant_message([
       { type: "text", text: "Done writing.", state: "done" },
     ]),
   );
 
-  const after_finish = await store.list();
+  const after_finish = await store.list_records();
   assert.equal(after_finish.length, 2);
   assert.deepEqual(
     after_finish[1]?.parts.map((part) => part.type),
@@ -113,7 +113,7 @@ test("Appending a new user message flushes stale inflight assistant before the n
     sessionId: "session_flush_test",
   });
 
-  await store.append(
+  await store.write_record(
     store.userText({
       text: "first",
       metadata: {
@@ -122,14 +122,14 @@ test("Appending a new user message flushes stale inflight assistant before the n
     }),
   );
 
-  await store.writeInflight(
+  await store.write_inflight(
     create_assistant_message([
       { type: "step-start" },
       { type: "text", text: "partial assistant", state: "done" },
     ]),
   );
 
-  await store.append(
+  await store.write_record(
     store.userText({
       text: "second",
       metadata: {
@@ -138,7 +138,7 @@ test("Appending a new user message flushes stale inflight assistant before the n
     }),
   );
 
-  const messages = await store.list();
+  const messages = await store.list_records();
   assert.equal(messages.length, 3);
   assert.equal(messages[0]?.role, "user");
   assert.equal(messages[1]?.role, "assistant");

package/scripts/session-list-title.test.mjs

@@ -54,12 +54,12 @@ async function create_agent_with_titled_session(input) {
     path: agent_path,
     model: create_mock_title_model(input.title),
   });
-  const collection = agent.session_collection();
-  const session = await collection.create_session({
+  const collection = agent.sessions;
+  const session = await collection.create({
     sessionId: input.session_id,
   });
 
-  await session.appendUserMessage({
+  await session.append_user_message({
     text: input.first_user_text,
   });
 
@@ -80,7 +80,7 @@ test("list_sessions returns persisted title from active session metadata", async
   });
 
   try {
-    const page = await collection.list_sessions();
+    const page = await collection.list();
 
     assert.equal(page.total, 1);
     assert.deepEqual(
@@ -93,7 +93,7 @@ test("list_sessions returns persisted title from active session metadata", async
         {
           sessionId: session.id,
           title: "列表标题",
-          messageCount: 1,
+          messageCount: 2,
         },
       ],
     );
@@ -112,12 +112,12 @@ test("archive_sessions returns title from archived session metadata", async () =
   });
 
   try {
-    await collection.archive_session({
+    await collection.archive({
       id: session.id,
     });
 
-    const active_page = await collection.list_sessions();
-    const archived_page = await collection.archive_sessions();
+    const active_page = await collection.list();
+    const archived_page = await collection.archived();
 
     assert.equal(active_page.total, 0);
     assert.equal(archived_page.total, 1);
@@ -131,7 +131,7 @@ test("archive_sessions returns title from archived session metadata", async () =
         {
           sessionId: session.id,
           title: "归档标题",
-          messageCount: 1,
+          messageCount: 2,
         },
       ],
     );

package/scripts/session-title-event.test.mjs

@@ -53,24 +53,25 @@ test("Session keeps title empty when no model is available", async () => {
     id: "title_agent",
     path: agent_path,
   });
-  const session = await agent.createSession();
+  const session = await agent.sessions.create();
   const events = [];
   const unsubscribe = session.subscribe((event) => {
     events.push(event);
   });
 
   try {
-    await session.appendUserMessage({
+    await session.append_user_message({
       text: "Use shell tools to inspect the current workspace",
     });
 
     const title_event = events.find((event) => event.type === "session-title");
     assert.equal(title_event, undefined);
 
-    const history = await session.history();
-    assert.equal(history.session.title, undefined);
+    const records = await session.records();
+    assert.equal(records.session.title, undefined);
   } finally {
     unsubscribe();
+    await agent.dispose();
   }
 });
 
@@ -82,24 +83,24 @@ test("Session retries title generation after model becomes available", async ()
     id: "title_retry_agent",
     path: agent_path,
   });
-  const session = await agent.createSession();
+  const session = await agent.sessions.create();
   const events = [];
   const unsubscribe = session.subscribe((event) => {
     events.push(event);
   });
 
   try {
-    await session.appendUserMessage({
+    await session.append_user_message({
       text: "Investigate flaky session title generation in the SDK",
     });
 
-    const history_before_model = await session.history();
+    const history_before_model = await session.records();
     assert.equal(history_before_model.session.title, undefined);
 
     await session.set({
       model: create_mock_title_model("排查 session 标题"),
     });
-    await session.appendUserMessage({
+    await session.append_user_message({
       text: "Need another prompt to trigger the retry path",
     });
 
@@ -110,9 +111,10 @@ test("Session retries title generation after model becomes available", async ()
       title: "排查 session 标题",
     });
 
-    const history = await session.history();
-    assert.equal(history.session.title, "排查 session 标题");
+    const records = await session.records();
+    assert.equal(records.session.title, "排查 session 标题");
   } finally {
     unsubscribe();
+    await agent.dispose();
   }
 });

package/src/agent/local/Agent.ts

@@ -14,7 +14,7 @@ import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type {
   AgentModel,
   AgentOptions,
-  AgentSessionCollection,
+  AgentSessions as AgentSessionsApi,
 } from "@/types/agent/AgentTypes.js";
 import type {
   ShellApprovalMode,
@@ -32,7 +32,7 @@ import {
   AgentAssemblyService,
   type AgentAssemblyResult,
 } from "@/agent/local/services/AgentAssemblyService.js";
-import { AgentSessionManager } from "@/agent/local/services/AgentSessionManager.js";
+import { AgentSessions as LocalAgentSessions } from "@/agent/local/services/AgentSessions.js";
 import { AgentBackgroundService } from "@/agent/local/services/AgentBackgroundService.js";
 
 /**
@@ -43,6 +43,7 @@ export class Agent {
   readonly path: string;
   readonly tools: Record<string, Tool>;
   readonly plugins: AgentPlugins;
+  readonly sessions: AgentSessionsApi;
 
   private readonly logger: Logger;
   private readonly agentContext: AgentContext;
@@ -51,7 +52,6 @@ export class Agent {
   private readonly env: Record<string, string>;
   private readonly defaultModel?: AgentModel;
   private readonly SessionClass: AgentOptions["Session"];
-  private readonly sessionManager: AgentSessionManager;
   private readonly backgroundService: AgentBackgroundService;
   private readonly shell?: AgentOptions["shell"];
 
@@ -60,19 +60,19 @@ export class Agent {
   constructor(options: AgentOptions) {
     this.defaultModel = options.model;
     this.SessionClass = options.Session;
-    let session_manager_ref: AgentSessionManager | null = null;
+    let sessions_ref: LocalAgentSessions | null = null;
     const assembly_service = new AgentAssemblyService({
       options,
-      list_cached_sessions: () => session_manager_ref?.list_cached_sessions() || [],
+      list_cached_sessions: () => sessions_ref?.list_cached_sessions() || [],
       get_session_port: (session_id) => {
-        if (!session_manager_ref) {
-          throw new Error("Agent session manager is not initialized");
+        if (!sessions_ref) {
+          throw new Error("Agent sessions are not initialized");
         }
-        return session_manager_ref.get_session_port(session_id);
+        return sessions_ref.get_session_port(session_id);
       },
       resolve_session_model: async (session_id) => {
-        if (!session_manager_ref) return undefined;
-        const session = await session_manager_ref.get_session(session_id);
+        if (!sessions_ref) return undefined;
+        const session = await sessions_ref.get(session_id);
         return session.config.model;
       },
     });
@@ -96,8 +96,9 @@ export class Agent {
       agent_context: this.agentContext,
       get_shell: () => this.shell,
     });
-    this.sessionManager = this.create_session_manager(assembly);
-    session_manager_ref = this.sessionManager;
+    const sessions = this.create_sessions(assembly);
+    this.sessions = sessions;
+    sessions_ref = sessions;
   }
 
   /**
@@ -244,13 +245,6 @@ export class Agent {
     return this.agentContext;
   }
 
-  /**
-   * 返回当前 session collection 入口。
-   */
-  session_collection(): AgentSessionCollection {
-    return this.sessionManager.get_session_collection();
-  }
-
   /**
    * 返回当前 agent 挂载的 Shell。
    */
@@ -258,10 +252,10 @@ export class Agent {
     return this.shell;
   }
 
-  private create_session_manager(
+  private create_sessions(
     assembly: AgentAssemblyResult,
-  ): AgentSessionManager {
-    return new AgentSessionManager({
+  ): LocalAgentSessions {
+    return new LocalAgentSessions({
       agent_id: this.id || assembly.id,
       project_root: this.path || assembly.path,
       tools: this.tools || assembly.tools,