@downcity/agent 1.1.200 → 1.1.203

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,

package/src/agent/local/services/{AgentSessionManager.ts → AgentSessions.ts}

@@ -1,8 +1,8 @@
 /**
- * AgentSessionManager：本地 Agent session 管理服务。
+ * AgentSessions：本地 Agent session 集合入口。
  *
  * 关键点（中文）
- * - 统一管理 session 缓存、创建、恢复、默认配置注入与 session collection。
+ * - 统一管理 session 缓存、创建、恢复、默认配置注入与列表查询。
  * - 该服务只负责 session 生命周期与查询，不负责 plugin / RPC 启停。
  * - Session 对象创建细节集中在这里，避免 facade 和 lifecycle 重复依赖 Session 构造逻辑。
  */
@@ -22,7 +22,7 @@ import type {
   AgentManagedSession,
   AgentModel,
   AgentSession,
-  AgentSessionCollection,
+  AgentSessions as AgentSessionsApi,
   AgentSessionConstructor,
   AgentSessionSummaryPage,
   AgentSessionSystemBlock,
@@ -48,7 +48,7 @@ function decodeMaybe(input: string): string {
   }
 }
 
-type AgentSessionManagerOptions = {
+type AgentSessionsOptions = {
   /**
    * 当前 agent 稳定标识。
    */
@@ -106,22 +106,21 @@ type AgentSessionManagerOptions = {
 /**
  * 本地 Agent session 管理服务。
  */
-export class AgentSessionManager {
+export class AgentSessions implements AgentSessionsApi<AgentSession> {
   private readonly agent_id: string;
   private readonly project_root: string;
   private readonly tools: Record<string, Tool>;
   private readonly logger: Logger;
-  private readonly get_agent_context: AgentSessionManagerOptions["get_agent_context"];
-  private readonly get_instruction: AgentSessionManagerOptions["get_instruction"];
+  private readonly get_agent_context: AgentSessionsOptions["get_agent_context"];
+  private readonly get_instruction: AgentSessionsOptions["get_instruction"];
   private readonly plugin_instances: Map<string, Plugin>;
-  private readonly ensure_agent_ready: AgentSessionManagerOptions["ensure_agent_ready"];
+  private readonly ensure_agent_ready: AgentSessionsOptions["ensure_agent_ready"];
   private readonly default_model?: AgentModel;
   private readonly SessionClass: AgentSessionConstructor;
   private readonly sessions_by_id = new Map<string, AgentManagedSession>();
   private readonly configured_session_ids = new Set<string>();
-  private readonly session_collection: AgentSessionCollection;
 
-  constructor(options: AgentSessionManagerOptions) {
+  constructor(options: AgentSessionsOptions) {
     this.agent_id = options.agent_id;
     this.project_root = options.project_root;
     this.tools = options.tools;
@@ -132,14 +131,6 @@ export class AgentSessionManager {
     this.ensure_agent_ready = options.ensure_agent_ready;
     this.default_model = options.default_model;
     this.SessionClass = options.SessionClass || Session;
-    this.session_collection = {
-      create_session: async (input) => await this.create_session(input),
-      get_session: async (session_id) => await this.get_session(session_id),
-      list_sessions: async (input) => await this.list_sessions(input),
-      archive_session: async (input) => await this.archive_session(input),
-      archive_sessions: async (input) => await this.archive_sessions(input),
-      clean_archive: async () => await this.clean_archive(),
-    };
   }
 
   /**
@@ -149,13 +140,6 @@ export class AgentSessionManager {
     return [...this.sessions_by_id.values()];
   }
 
-  /**
-   * 返回对外暴露的 session collection。
-   */
-  get_session_collection(): AgentSessionCollection {
-    return this.session_collection;
-  }
-
   /**
    * 获取或创建一个 session runtime port。
    */
@@ -168,7 +152,7 @@ export class AgentSessionManager {
   /**
    * 新建一个 session。
    */
-  async create_session(
+  async create(
     input?: AgentCreateSessionInput,
   ): Promise<AgentSession> {
     const explicit_session_id =
@@ -197,10 +181,10 @@ export class AgentSessionManager {
   /**
    * 获取一个已存在的 session。
    */
-  async get_session(session_id: string): Promise<AgentSession> {
+  async get(session_id: string): Promise<AgentSession> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
-      throw new Error("get_session requires a non-empty sessionId");
+      throw new Error("sessions.get requires a non-empty sessionId");
     }
     const session_dir_path = getSdkAgentSessionDirPath(
       this.project_root,
@@ -224,7 +208,7 @@ export class AgentSessionManager {
   /**
    * 列出当前 agent 的 session 摘要页。
    */
-  async list_sessions(
+  async list(
     input?: AgentListSessionsInput,
   ): Promise<AgentSessionSummaryPage> {
     return await listAgentSessionSummaryPage({
@@ -238,12 +222,12 @@ export class AgentSessionManager {
   /**
    * 归档单个 session。
    */
-  async archive_session(
+  async archive(
     input: AgentArchiveSessionInput,
   ): Promise<AgentArchiveSessionResult> {
     const session_id = String(input?.id || "").trim();
     if (!session_id) {
-      throw new Error("archive_session requires a non-empty id");
+      throw new Error("sessions.archive requires a non-empty id");
     }
 
     const executing_session_ids = new Set(
@@ -290,7 +274,7 @@ export class AgentSessionManager {
   /**
    * 列出当前 agent 的已归档 session 摘要页。
    */
-  async archive_sessions(
+  async archived(
     input?: AgentArchiveSessionsInput,
   ): Promise<AgentArchiveSessionsResult> {
     return await listArchivedAgentSessionSummaryPage({