@downcity/agent 1.1.430 → 1.1.438

package/src/session/storage/LocalSessionStore.ts

@@ -3,7 +3,7 @@
  *
  * 职责说明（中文）
  * - 统一管理 Session 创建判断、删除、列表、归档与清理。
- * - 缓存稳定的 LocalSessionDataStore，避免同一 Session 重复创建 Message Store。
+ * - 缓存稳定的 LocalSessionDataStore，避免同一 Session 重复创建 SQLite Storage。
  * - 使用来源类型建立确定性一级分区，避免跨来源扫描。
  */
 
@@ -14,23 +14,25 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentListSessionsInput,
+  AgentSessionSummary,
   AgentSessionSummaryPage,
 } from "@/types/agent/SessionTypes.js";
 import type { SessionStore } from "@/types/store/SessionStore.js";
-import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
 import { LocalSessionDataStore } from "@/session/storage/LocalSessionDataStore.js";
 import {
-  get_agent_archived_session_meta_path,
+  get_agent_archived_session_database_path,
   get_agent_archived_session_origins_path,
   get_agent_archived_session_path,
   get_agent_archived_sessions_path,
-  get_agent_session_messages_path,
-  get_agent_session_meta_path,
+  get_agent_session_database_path,
   get_agent_session_path,
 } from "@/session/storage/LocalStorePaths.js";
 import {
+  build_session_info,
   list_archived_agent_session_summary_page,
   list_agent_session_summary_page,
+  read_session_metadata_from_database,
 } from "@/session/browse/Browse.js";
 import type { FileSystem } from "@downcity/type";
 import type { LocalSessionStoreOptions } from "@/types/store/LocalStore.js";
@@ -60,25 +62,32 @@ export class LocalSessionStore implements SessionStore {
   /** 当前 Agent 内部数据根路径。 */
   private readonly storage_root_path: string;
 
+  /** Session 数据库使用本地文件还是进程内存。 */
+  private readonly database_location: LocalSessionStoreOptions["database_location"];
+
   /** 已创建的 Session Store 缓存。 */
   private readonly sessions = new Map<string, LocalSessionDataStore>();
 
+  /** 内存模式中已归档但仍由 Store 持有的 Session。 */
+  private readonly archived_sessions = new Map<string, LocalSessionDataStore>();
+
   constructor(options: LocalSessionStoreOptions) {
     this.files = options.files;
     this.agent_id = options.agent_id;
     this.workspace_id = options.workspace_id;
     this.storage_root_path = options.storage_root_path;
+    this.database_location = options.database_location;
   }
 
-  /** 返回指定 Session 的稳定持久化视图。 */
-  session(
+  /** 为新 Session 创建稳定持久化视图。 */
+  create_session(
     session_id: string,
     origin: SessionOrigin,
     workspace_id = this.workspace_id,
-  ): SessionDataStore {
+  ): SessionStorage {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
-      throw new Error("SessionStore.session requires a non-empty session_id");
+      throw new Error("SessionStore.create_session requires a non-empty session_id");
     }
     const resolved_origin = normalize_session_origin(origin);
     const cache_key = this.session_cache_key(resolved_session_id, resolved_origin.type);
@@ -94,6 +103,7 @@ export class LocalSessionStore implements SessionStore {
       files: this.files,
       storage_root_path: this.storage_root_path,
       agent_id: this.agent_id,
+      database_location: this.database_location,
       workspace_id: workspace_id,
       session_id: resolved_session_id,
       origin: resolved_origin,
@@ -102,11 +112,55 @@ export class LocalSessionStore implements SessionStore {
     return created;
   }
 
+  /** 打开已有 Session，并以数据库中的完整 origin 作为唯一事实。 */
+  async open_session(session_id: string, origin_type = "chat"): Promise<SessionStorage> {
+    const resolved_session_id = String(session_id || "").trim();
+    if (!resolved_session_id) {
+      throw new Error("SessionStore.open_session requires a non-empty session_id");
+    }
+    const resolved_origin_type = normalize_session_origin_type(origin_type);
+    const cache_key = this.session_cache_key(resolved_session_id, resolved_origin_type);
+    const cached = this.sessions.get(cache_key);
+    if (cached) return cached;
+    if (this.database_location.type === "memory") {
+      throw new Error(`Session "${resolved_session_id}" not found`);
+    }
+    const database_path = get_agent_session_database_path(
+      this.storage_root_path,
+      resolved_origin_type,
+      resolved_session_id,
+    );
+    if (!(await this.files.path_exists(database_path))) {
+      throw new Error(`Session "${resolved_session_id}" not found`);
+    }
+    const metadata = read_session_metadata_from_database(database_path, resolved_origin_type);
+    if (!metadata || metadata.agent_id !== this.agent_id) {
+      throw new Error(`Session "${resolved_session_id}" belongs to another Agent`);
+    }
+    const opened = new LocalSessionDataStore({
+      files: this.files,
+      storage_root_path: this.storage_root_path,
+      agent_id: this.agent_id,
+      database_location: this.database_location,
+      ...(metadata.workspace_id ? { workspace_id: metadata.workspace_id } : {}),
+      session_id: resolved_session_id,
+      origin: metadata.origin,
+    });
+    this.sessions.set(cache_key, opened);
+    return opened;
+  }
+
   /** 判断活动 Session 是否存在。 */
   async has_session(session_id: string, origin_type = "chat"): Promise<boolean> {
     const resolved_origin_type = normalize_session_origin_type(origin_type);
-    const session_path = this.session_path(session_id, resolved_origin_type);
-    if (!(await this.files.path_exists(session_path))) return false;
+    const cache_key = this.session_cache_key(session_id, resolved_origin_type);
+    if (this.database_location.type === "memory") return this.sessions.has(cache_key);
+    const database_path = get_agent_session_database_path(
+      this.storage_root_path,
+      resolved_origin_type,
+      session_id,
+    );
+    if (!(await this.files.path_exists(database_path))) return false;
     await this.assert_session_owner(session_id, resolved_origin_type, false);
     return true;
   }
@@ -115,30 +169,31 @@ export class LocalSessionStore implements SessionStore {
   async remove_session(session_id: string, origin_type = "chat"): Promise<boolean> {
     const resolved_origin_type = normalize_session_origin_type(origin_type);
     const session_path = this.session_path(session_id, resolved_origin_type);
-    const existed = await this.files.path_exists(session_path);
+    const cache_key = this.session_cache_key(session_id, resolved_origin_type);
+    const cached = this.sessions.get(cache_key);
+    const existed = this.database_location.type === "memory"
+      ? Boolean(cached)
+      : await this.files.path_exists(get_agent_session_database_path(
+          this.storage_root_path,
+          resolved_origin_type,
+          session_id,
+        ));
     if (existed) {
       await this.assert_session_owner(session_id, resolved_origin_type, false);
+      await cached?.dispose();
       await this.files.remove_path(session_path);
     }
-    this.sessions.delete(this.session_cache_key(session_id, resolved_origin_type));
+    this.sessions.delete(cache_key);
     return existed;
   }
 
   /** 清空活动 Session Message 数据。 */
   async clear_session_messages(session_id: string, origin_type = "chat"): Promise<boolean> {
     const resolved_origin_type = normalize_session_origin_type(origin_type);
-    const messages_path = get_agent_session_messages_path(
-      this.storage_root_path,
-      resolved_origin_type,
-      session_id,
-    );
-    const existed = await this.files.path_exists(messages_path);
-    if (existed) {
-      await this.assert_session_owner(session_id, resolved_origin_type, false);
-      await this.files.remove_path(messages_path);
-    }
-    this.sessions.delete(this.session_cache_key(session_id, resolved_origin_type));
-    return existed;
+    if (!(await this.has_session(session_id, resolved_origin_type))) return false;
+    const storage = await this.open_session(session_id, resolved_origin_type);
+    await storage.clear_messages();
+    return true;
   }
 
   /** 返回活动 Session 摘要页。 */
@@ -146,12 +201,15 @@ export class LocalSessionStore implements SessionStore {
     input: AgentListSessionsInput | undefined,
     executing_session_ids: ReadonlySet<string>,
   ): Promise<AgentSessionSummaryPage> {
+    if (this.database_location.type === "memory") {
+      return await this.list_cached_sessions(input, executing_session_ids);
+    }
     return await list_agent_session_summary_page({
       project_root: this.storage_root_path,
       agent_id: this.agent_id,
       ...(this.workspace_id || input?.workspace_id ? { workspace_id: this.workspace_id || input?.workspace_id } : {}),
       input,
-      executingSessionIds: new Set(executing_session_ids),
+      executing_session_ids,
       files: this.files,
     });
   }
@@ -159,11 +217,23 @@ export class LocalSessionStore implements SessionStore {
   /** 将活动 Session 迁入归档区。 */
   async archive_session(session_id: string, origin_type = "chat"): Promise<AgentArchiveSessionResult> {
     const resolved_origin_type = normalize_session_origin_type(origin_type);
+    const cache_key = this.session_cache_key(session_id, resolved_origin_type);
+    if (this.database_location.type === "memory") {
+      const storage = this.sessions.get(cache_key);
+      if (!storage) throw new Error(`Session "${session_id}" not found`);
+      if (this.archived_sessions.has(cache_key)) {
+        throw new Error(`Archived session "${session_id}" already exists`);
+      }
+      this.sessions.delete(cache_key);
+      this.archived_sessions.set(cache_key, storage);
+      return { session_id, archived_at: Date.now() };
+    }
     const source_path = this.session_path(session_id, resolved_origin_type);
     if (!(await this.files.path_exists(source_path))) {
       throw new Error(`Session "${session_id}" not found`);
     }
     await this.assert_session_owner(session_id, resolved_origin_type, false);
+    await this.sessions.get(cache_key)?.dispose();
     const target_path = get_agent_archived_session_path(
       this.storage_root_path,
       resolved_origin_type,
@@ -177,7 +247,7 @@ export class LocalSessionStore implements SessionStore {
       resolved_origin_type,
     ));
     await this.files.move_path(source_path, target_path);
-    this.sessions.delete(this.session_cache_key(session_id, resolved_origin_type));
+    this.sessions.delete(cache_key);
     return {
       session_id: session_id,
       archived_at: Date.now(),
@@ -188,6 +258,9 @@ export class LocalSessionStore implements SessionStore {
   async list_archived_sessions(
     input?: AgentArchiveSessionsInput,
   ): Promise<AgentArchiveSessionsResult> {
+    if (this.database_location.type === "memory") {
+      return await this.list_cached_sessions(input, new Set(), this.archived_sessions);
+    }
     return await list_archived_agent_session_summary_page({
       project_root: this.storage_root_path,
       agent_id: this.agent_id,
@@ -199,6 +272,12 @@ export class LocalSessionStore implements SessionStore {
 
   /** 永久删除全部归档 Session。 */
   async clean_archive(): Promise<AgentCleanArchiveResult> {
+    if (this.database_location.type === "memory") {
+      const archived = [...this.archived_sessions.values()];
+      this.archived_sessions.clear();
+      await Promise.all(archived.map(async (storage) => await storage.dispose()));
+      return { removed_session_ids: archived.map((storage) => storage.session_id) };
+    }
     const archive_root_path = get_agent_archived_session_origins_path(this.storage_root_path);
     if (!(await this.files.path_exists(archive_root_path))) {
       return { removed_session_ids: [] };
@@ -227,8 +306,13 @@ export class LocalSessionStore implements SessionStore {
     return { removed_session_ids: removed_session_ids };
   }
 
-  /** 本地 JSONL Store 当前没有常驻句柄。 */
-  async dispose(): Promise<void> {}
+  /** 关闭全部 Session SQLite 连接并清空缓存。 */
+  async dispose(): Promise<void> {
+    const storages = [...this.sessions.values(), ...this.archived_sessions.values()];
+    this.sessions.clear();
+    this.archived_sessions.clear();
+    await Promise.all(storages.map(async (storage) => await storage.dispose()));
+  }
 
   /** 返回活动 Session 物理目录，仅供本地实现内部使用。 */
   private session_path(session_id: string, origin_type: string): string {
@@ -257,22 +341,70 @@ export class LocalSessionStore implements SessionStore {
     origin_type: string,
     archived: boolean,
   ): Promise<boolean> {
+    const cache_key = this.session_cache_key(session_id, origin_type);
+    if (this.database_location.type === "memory") {
+      const cached = (archived ? this.archived_sessions : this.sessions).get(cache_key);
+      if (cached) {
+        try {
+          const metadata = await cached.read_metadata();
+          return metadata.agent_id === this.agent_id && metadata.origin.type === origin_type;
+        } catch {
+          return false;
+        }
+      }
+      return false;
+    }
     const file_path = archived
-      ? get_agent_archived_session_meta_path(
+      ? get_agent_archived_session_database_path(
         this.storage_root_path,
         origin_type,
         session_id,
       )
-      : get_agent_session_meta_path(this.storage_root_path, origin_type, session_id);
+      : get_agent_session_database_path(this.storage_root_path, origin_type, session_id);
     if (!(await this.files.path_exists(file_path))) return false;
-    try {
-      const metadata = JSON.parse(
-        (await this.files.read_file(file_path)).toString("utf8"),
-      ) as { agent_id?: unknown; origin?: { type?: unknown } };
-      return metadata.agent_id === this.agent_id && metadata.origin?.type === origin_type;
-    } catch {
-      return false;
+    const metadata = read_session_metadata_from_database(file_path, origin_type);
+    return metadata?.agent_id === this.agent_id && metadata.origin.type === origin_type;
+  }
+
+  /** 从内存数据库缓存投影 Session 列表。 */
+  private async list_cached_sessions(
+    input: AgentListSessionsInput | AgentArchiveSessionsInput | undefined,
+    executing_session_ids: ReadonlySet<string>,
+    storages = this.sessions,
+  ): Promise<AgentSessionSummaryPage> {
+    const origin_type = normalize_session_origin_type(input?.origin_type ?? "chat");
+    const query = String(input?.query || "").trim().toLowerCase();
+    const summaries: AgentSessionSummary[] = [];
+    for (const storage of storages.values()) {
+      if (storage.origin.type !== origin_type) continue;
+      const metadata = await storage.read_metadata();
+      if ((this.workspace_id || input?.workspace_id) &&
+          metadata.workspace_id !== (this.workspace_id || input?.workspace_id)) continue;
+      const summary = build_session_info({
+        project_root: this.storage_root_path,
+        agent_id: this.agent_id,
+        session_id: storage.session_id,
+        metadata,
+        executing: executing_session_ids.has(storage.session_id),
+      });
+      if (query && ![
+        summary.session_id,
+        summary.title || "",
+        summary.preview_text || "",
+      ].join("\n").toLowerCase().includes(query)) continue;
+      summaries.push(summary);
     }
+    summaries.sort((left, right) => (right.updated_at || 0) - (left.updated_at || 0));
+    const cursor = Math.max(0, Number(input?.cursor) || 0);
+    const limit = Math.min(Math.max(input?.limit ?? 50, 1), 500);
+    const items = summaries.slice(cursor, cursor + limit);
+    const next_cursor = cursor + items.length;
+    return {
+      items,
+      total: summaries.length,
+      ...(next_cursor < summaries.length ? { next_cursor: String(next_cursor) } : {}),
+      has_more: next_cursor < summaries.length,
+    };
   }
 
   /** 返回来源分区内唯一的 Session Store 缓存键。 */

package/src/session/storage/LocalStorePaths.ts

@@ -74,122 +74,50 @@ export function get_agent_session_path(
   );
 }
 
-/** 返回单个归档 Session 目录。 */
-export function get_agent_archived_session_path(
-  storage_root_path: string,
-  origin_type: string,
-  session_id: string,
-): string {
-  return path.join(
-    get_agent_archived_sessions_path(storage_root_path, origin_type),
-    encode_path_segment(String(session_id || "").trim()),
-  );
-}
-
-/** 返回单个 Session 的 instruction.md 路径。 */
-export function get_agent_session_instruction_path(
-  storage_root_path: string,
-  origin_type: string,
-  session_id: string,
-): string {
-  return path.join(
-    get_agent_session_path(storage_root_path, origin_type, session_id),
-    "instruction.md",
-  );
-}
-
-/** 返回单个 Session 的附件目录。 */
-export function get_agent_session_attachments_path(
+/** 返回单个活动 Session 的 SQLite 数据库路径。 */
+export function get_agent_session_database_path(
   storage_root_path: string,
   origin_type: string,
   session_id: string,
 ): string {
   return path.join(
     get_agent_session_path(storage_root_path, origin_type, session_id),
-    "attachments",
+    "session.db",
   );
 }
 
-/** 返回单个 Session 的消息目录。 */
-export function get_agent_session_messages_path(
-  storage_root_path: string,
-  origin_type: string,
-  session_id: string,
-): string {
-  return path.join(
-    get_agent_session_path(storage_root_path, origin_type, session_id),
-    "messages",
-  );
-}
-
-/** 返回单个 Session 的 Active JSONL 路径。 */
-export function get_agent_session_active_messages_path(
-  storage_root_path: string,
-  origin_type: string,
-  session_id: string,
-): string {
-  return path.join(
-    get_agent_session_messages_path(storage_root_path, origin_type, session_id),
-    "active.jsonl",
-  );
-}
-
-/** 返回单个 Session 的运行中 Assistant 快照路径。 */
-export function get_agent_session_assistant_message_path(
-  storage_root_path: string,
-  origin_type: string,
-  session_id: string,
-): string {
-  return path.join(
-    get_agent_session_messages_path(storage_root_path, origin_type, session_id),
-    "assistant_message.json",
-  );
-}
-
-/** 返回单个 Session 的 meta.json 路径。 */
-export function get_agent_session_meta_path(
+/** 返回单个归档 Session 目录。 */
+export function get_agent_archived_session_path(
   storage_root_path: string,
   origin_type: string,
   session_id: string,
 ): string {
   return path.join(
-    get_agent_session_path(storage_root_path, origin_type, session_id),
-    "meta.json",
+    get_agent_archived_sessions_path(storage_root_path, origin_type),
+    encode_path_segment(String(session_id || "").trim()),
   );
 }
 
-/** 返回单个归档 Session 的消息目录。 */
-export function get_agent_archived_session_messages_path(
+/** 返回单个归档 Session 的 SQLite 数据库路径。 */
+export function get_agent_archived_session_database_path(
   storage_root_path: string,
   origin_type: string,
   session_id: string,
 ): string {
   return path.join(
     get_agent_archived_session_path(storage_root_path, origin_type, session_id),
-    "messages",
-  );
-}
-
-/** 返回单个归档 Session 的 Active JSONL 路径。 */
-export function get_agent_archived_session_active_messages_path(
-  storage_root_path: string,
-  origin_type: string,
-  session_id: string,
-): string {
-  return path.join(
-    get_agent_archived_session_messages_path(storage_root_path, origin_type, session_id),
-    "active.jsonl",
+    "session.db",
   );
 }
 
-/** 返回单个归档 Session 的 meta.json 路径。 */
-export function get_agent_archived_session_meta_path(
+/** 返回单个 Session 的附件目录。 */
+export function get_agent_session_attachments_path(
   storage_root_path: string,
   origin_type: string,
   session_id: string,
 ): string {
   return path.join(
-    get_agent_archived_session_path(storage_root_path, origin_type, session_id),
-    "meta.json",
+    get_agent_session_path(storage_root_path, origin_type, session_id),
+    "attachments",
   );
 }

package/src/session/storage/Metadata.ts

@@ -2,8 +2,8 @@
  * SDK Session 元数据辅助。
  *
  * 关键点（中文）
- * - 统一负责 Agent Storage 内 `sessions/<origin_type>/<session_id>/meta.json` 的规范化读取。
- * - 仅处理轻量配置摘要与索引信息，不负责消息 JSONL 的读写。
+ * - 统一负责 Session SQLite 中轻量配置摘要与索引字段的规范化。
+ * - 不负责数据库连接、消息聚合或附件读写。
  */
 
 import type { SessionHistoryMeta } from "@/executor/types/SessionHistoryMeta.js";
@@ -57,21 +57,15 @@ function normalize_preview_text(input: unknown): string | undefined {
   return preview_text || undefined;
 }
 
-function normalize_history_bytes(input: unknown): number | undefined {
-  return typeof input === "number" && Number.isInteger(input) && input >= 0
-    ? input
-    : undefined;
-}
-
 /**
- * 从指定路径读取 session meta.json。
+ * 从指定路径读取旧版 Session metadata。
  *
  * 关键点（中文）
  * - 供归档 session 等需要脱离默认 `sessions/` 目录的场景复用。
  * - 路径本身不做校验，调用方需保证可访问。
  */
 export async function read_session_metadata_from_path(input: {
-  /** meta.json 文件路径。 */
+  /** 旧版 metadata 文件路径。 */
   filePath: string;
   /** 当前 session_id。 */
   session_id: string;
@@ -143,8 +137,5 @@ export function normalize_session_metadata(
     ...(normalize_preview_text(raw.preview_text)
       ? { preview_text: normalize_preview_text(raw.preview_text) }
       : {}),
-    ...(normalize_history_bytes(raw.historyBytes) !== undefined
-      ? { historyBytes: normalize_history_bytes(raw.historyBytes) }
-      : {}),
   };
 }

package/src/session/storage/RuntimeSessionPort.ts

@@ -29,6 +29,8 @@ export interface CreateRuntimeSessionPortParams {
    * 读取当前 session 底层执行端口。
    */
   get_executor: SessionPort["get_executor"];
+  /** 读取全部 canonical Session Message。 */
+  messages: SessionPort["messages"];
   /**
    * 追加一条新的 session prompt。
    */
@@ -48,15 +50,13 @@ export interface CreateRuntimeSessionPortParams {
    */
   append_user_message: SessionPort["append_user_message"];
   /**
-   * 追加 assistant 消息到底层历史。
+   * 追加 Agent 消息到底层历史。
    */
-  append_assistant_message: SessionPort["append_assistant_message"];
+  append_agent_message: SessionPort["append_agent_message"];
   /**
    * 返回当前 session 是否正在执行。
    */
   is_executing: () => boolean;
-  /** 读取当前 Session 的只读上下文快照。 */
-  context: SessionPort["context"];
   /**
    * 在执行前确保当前 session 已完成初始化与宿主级配置。
    */
@@ -73,7 +73,7 @@ export function create_runtime_session_port(
     session_id: params.session_id,
     get_model: () => params.get_model(),
     get_executor: () => params.get_executor(),
-    context: async () => await params.context(),
+    messages: async () => await params.messages(),
     prompt: async (input) => {
       await params.ensure_ready_for_execution();
       return await params.prompt(input);
@@ -88,8 +88,8 @@ export function create_runtime_session_port(
     append_user_message: async (messageParams) => {
       await params.append_user_message(messageParams);
     },
-    append_assistant_message: async (messageParams) => {
-      await params.append_assistant_message(messageParams);
+    append_agent_message: async (message_params) => {
+      await params.append_agent_message(message_params);
     },
     is_executing: () => params.is_executing(),
   };