@downcity/agent 1.1.200 → 1.1.202

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({

package/src/agent/remote/RemoteAgent.ts

@@ -8,7 +8,15 @@
  */
 
 import type {
-  AgentSessionCollection,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+  AgentSessions,
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
   RemoteAgentOptions,
@@ -30,6 +38,8 @@ import { create_remote_agent_transport } from "@/agent/remote/TransportFactory.j
  * RemoteAgent：远程 Agent 客户端。
  */
 export class RemoteAgent {
+  readonly sessions: AgentSessions<RemoteAgentSession>;
+
   private readonly transport: RemoteAgentTransport;
 
   constructor(options: RemoteAgentOptions) {
@@ -38,6 +48,7 @@ export class RemoteAgent {
       throw new Error("RemoteAgent requires a non-empty url");
     }
     this.transport = create_remote_agent_transport(url, options.token);
+    this.sessions = new RemoteAgentSessions(this.transport);
   }
 
   /**
@@ -121,27 +132,51 @@ export class RemoteAgent {
     await this.transport.close?.();
   }
 
-  /**
-   * 返回当前远程 session collection 入口。
-   *
-   * 关键点（中文）
-   * - `RemoteAgentTransport` 只负责协议传输，不直接等价于 `AgentSessionCollection`。
-   * - 这里把 transport 包装为 `AgentSessionCollection`，`create_session` / `get_session` 返回 `RemoteSession` 实例。
-   */
-  session_collection(): AgentSessionCollection {
-    return {
-     create_session: async (input) => {
-       const info = await this.transport.create_session(input);
-        return new RemoteSession(this.transport, info);
-      },
-      get_session: async (session_id) => {
-        const info = await this.transport.get_info(session_id);
-        return new RemoteSession(this.transport, info);
-      },
-      list_sessions: async (input) => await this.transport.list_sessions(input),
-      archive_session: async (input) => await this.transport.archive_session(input),
-      archive_sessions: async (input) => await this.transport.archive_sessions(input),
-      clean_archive: async () => await this.transport.clean_archive(),
-    };
+}
+
+/**
+ * 远程 Agent session 集合入口。
+ *
+ * 关键点（中文）
+ * - `RemoteAgentTransport` 只负责协议传输，不直接暴露为用户 SDK API。
+ * - 这里把远程传输包装成和本地 `agent.sessions` 一致的方法命名。
+ */
+class RemoteAgentSessions implements AgentSessions<RemoteAgentSession> {
+  private readonly transport: RemoteAgentTransport;
+
+  constructor(transport: RemoteAgentTransport) {
+    this.transport = transport;
+  }
+
+  /** 新建一个远程 session。 */
+  async create(input?: AgentCreateSessionInput): Promise<RemoteAgentSession> {
+    const info = await this.transport.create_session(input);
+    return new RemoteSession(this.transport, info);
+  }
+
+  /** 获取一个远程 session。 */
+  async get(session_id: string): Promise<RemoteAgentSession> {
+    const info = await this.transport.get_info(session_id);
+    return new RemoteSession(this.transport, info);
+  }
+
+  /** 列出远程 session 摘要页。 */
+  async list(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage> {
+    return await this.transport.list_sessions(input);
+  }
+
+  /** 归档一个远程 session。 */
+  async archive(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult> {
+    return await this.transport.archive_session(input);
+  }
+
+  /** 列出远程已归档 session。 */
+  async archived(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult> {
+    return await this.transport.archive_sessions(input);
+  }
+
+  /** 永久清空远程已归档 session。 */
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    return await this.transport.clean_archive();
   }
 }