@downcity/agent 1.1.337 → 1.1.399

package/src/workspace/store/LocalSessionStore.ts

@@ -1,127 +1,243 @@
 /**
- * LocalSessionStore：Workspace 内单个 Session 的 JSONL 持久化视图。
+ * LocalSessionStore：Agent 的 Session 查询与管理视图。
  *
  * 职责说明（中文）
- * - 集中创建 Message Store，并封装 Metadata 与 Instruction 的物理路径。
- * - Session 领域只持有本对象，不再自行拼接任何存储路径。
+ * - 统一管理 Session 创建判断、删除、列表、归档与清理。
+ * - 缓存稳定的 LocalSessionDataStore，避免同一 Session 重复创建 Message Store。
+ * - 当前阶段沿用既有本地目录布局；调用方和 Session 不感知该约定。
  */
 
-import { JsonlSessionMessageStore } from "@/workspace/store/JsonlSessionMessageStore.js";
+import type {
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+} from "@/types/agent/SessionTypes.js";
+import type { SessionStore } from "@/types/store/SessionStore.js";
+import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
+import { LocalSessionDataStore } from "@/workspace/store/LocalSessionDataStore.js";
 import {
-  get_sdk_agent_session_instruction_path,
-  get_sdk_agent_session_meta_path,
-  get_sdk_agent_session_assistant_message_path,
-  get_sdk_agent_session_messages_path,
-  get_sdk_agent_session_attachments_dir_path,
+  get_workspace_archived_session_meta_path,
+  get_workspace_archived_session_path,
+  get_workspace_archived_sessions_path,
+  get_workspace_session_messages_path,
+  get_workspace_session_meta_path,
+  get_workspace_session_path,
 } from "@/workspace/store/LocalStorePaths.js";
-import { normalize_session_metadata } from "@/session/storage/Metadata.js";
-import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
-import type { SessionStore } from "@/types/store/SessionStore.js";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import {
+  list_archived_agent_session_summary_page,
+  list_agent_session_summary_page,
+} from "@/session/browse/Browse.js";
+import type { FileSystem } from "@downcity/workspace";
 import type { LocalSessionStoreOptions } from "@/types/store/LocalStore.js";
-import { LocalSessionAttachmentStore } from "@/workspace/store/LocalSessionAttachmentStore.js";
-
-/** 本地 Session Store。 */
-export class LocalSessionStore implements SessionStore {
-  /** 当前 Session 的稳定标识。 */
-  readonly session_id: string;
 
-  /** 当前 Session 的 JSONL Message Store。 */
-  readonly messages: JsonlSessionMessageStore;
-
-  /** 当前 Session 的附件持久化能力。 */
-  readonly attachments: LocalSessionAttachmentStore;
+/** 解码目录中经过 URL 编码的 Session 标识。 */
+function decode_session_id(input: string): string {
+  try {
+    return decodeURIComponent(input);
+  } catch {
+    return input;
+  }
+}
 
-  /** 当前 Store 与 WorkspaceTools 共用的 Workspace 文件能力。 */
+/** 默认本地 Agent Store。 */
+export class LocalSessionStore implements SessionStore {
+  /** 当前 Agent 内部数据文件能力。 */
   private readonly files: FileSystem;
 
   /** 当前 Agent 的稳定标识。 */
   private readonly agent_id: string;
 
+  /** 当前 Workspace 的稳定标识。 */
+  private readonly workspace_id?: string;
+
+  /** 当前 Agent 内部数据根路径。 */
+  private readonly storage_root_path: string;
+
+  /** 已创建的 Session Store 缓存。 */
+  private readonly sessions = new Map<string, LocalSessionDataStore>();
+
   constructor(options: LocalSessionStoreOptions) {
     this.files = options.files;
     this.agent_id = options.agent_id;
-    this.session_id = options.session_id;
-    this.messages = new JsonlSessionMessageStore({
-      files: this.files,
-      session_id: this.session_id,
-      file_path: get_sdk_agent_session_messages_path(
-        this.files.root_path,
-        this.agent_id,
-        this.session_id,
-      ),
-      assistant_message_file_path: get_sdk_agent_session_assistant_message_path(
-        this.files.root_path,
-        this.agent_id,
-        this.session_id,
-      ),
-    });
-    this.attachments = new LocalSessionAttachmentStore({
+    this.workspace_id = options.workspace_id;
+    this.storage_root_path = options.storage_root_path;
+  }
+
+  /** 返回指定 Session 的稳定持久化视图。 */
+  session(session_id: string, workspace_id = this.workspace_id): SessionDataStore {
+    const resolved_session_id = String(session_id || "").trim();
+    if (!resolved_session_id) {
+      throw new Error("SessionStore.session requires a non-empty session_id");
+    }
+    const cached = this.sessions.get(resolved_session_id);
+    if (cached) return cached;
+    const created = new LocalSessionDataStore({
       files: this.files,
-      attachments_dir_path: get_sdk_agent_session_attachments_dir_path(
-        this.files.root_path,
-        this.agent_id,
-        this.session_id,
-      ),
+      storage_root_path: this.storage_root_path,
+      agent_id: this.agent_id,
+      workspace_id: workspace_id,
+      session_id: resolved_session_id,
     });
+    this.sessions.set(resolved_session_id, created);
+    return created;
   }
 
-  /** 读取规范化 Session Metadata。 */
-  async read_metadata(): Promise<SessionHistoryMetaV1> {
-    try {
-      const raw = JSON.parse(
-        (await this.files.read_file(this.metadata_path())).toString("utf8"),
-      ) as Partial<SessionHistoryMetaV1>;
-      return normalize_session_metadata(raw, this.session_id, this.agent_id);
-    } catch {
-      return normalize_session_metadata({}, this.session_id, this.agent_id);
+  /** 判断活动 Session 是否存在。 */
+  async has_session(session_id: string): Promise<boolean> {
+    const session_path = this.session_path(session_id);
+    if (!(await this.files.path_exists(session_path))) return false;
+    await this.assert_session_owner(session_id, false);
+    return true;
+  }
+
+  /** 永久删除活动 Session。 */
+  async remove_session(session_id: string): Promise<boolean> {
+    const session_path = this.session_path(session_id);
+    const existed = await this.files.path_exists(session_path);
+    if (existed) {
+      await this.assert_session_owner(session_id, false);
+      await this.files.remove_path(session_path);
     }
+    this.sessions.delete(session_id);
+    return existed;
   }
 
-  /** 写入完整 Session Metadata。 */
-  async write_metadata(metadata: SessionHistoryMetaV1): Promise<void> {
-    await this.files.write_file_atomically(
-      this.metadata_path(),
-      `${JSON.stringify(metadata, null, 2)}\n`,
+  /** 清空活动 Session Message 数据。 */
+  async clear_session_messages(session_id: string): Promise<boolean> {
+    const messages_path = get_workspace_session_messages_path(
+      this.storage_root_path,
+      session_id,
     );
+    const existed = await this.files.path_exists(messages_path);
+    if (existed) {
+      await this.assert_session_owner(session_id, false);
+      await this.files.remove_path(messages_path);
+    }
+    this.sessions.delete(session_id);
+    return existed;
   }
 
-  /** 判断显式 system 快照是否存在。 */
-  async has_instruction(): Promise<boolean> {
-    return await this.files.path_exists(this.instruction_path());
+  /** 返回活动 Session 摘要页。 */
+  async list_sessions(
+    input: AgentListSessionsInput | undefined,
+    executing_session_ids: ReadonlySet<string>,
+  ): Promise<AgentSessionSummaryPage> {
+    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),
+      files: this.files,
+    });
   }
 
-  /** 读取显式 system 快照。 */
-  async read_instruction(): Promise<string | null> {
-    if (!(await this.has_instruction())) return null;
-    return (await this.files.read_file(this.instruction_path())).toString("utf8");
+  /** 将活动 Session 迁入归档区。 */
+  async archive_session(session_id: string): Promise<AgentArchiveSessionResult> {
+    const source_path = this.session_path(session_id);
+    if (!(await this.files.path_exists(source_path))) {
+      throw new Error(`Session "${session_id}" not found`);
+    }
+    await this.assert_session_owner(session_id, false);
+    const target_path = get_workspace_archived_session_path(
+      this.storage_root_path,
+      session_id,
+    );
+    if (await this.files.path_exists(target_path)) {
+      throw new Error(`Archived session "${session_id}" already exists`);
+    }
+    await this.files.ensure_directory(get_workspace_archived_sessions_path(
+      this.storage_root_path,
+    ));
+    await this.files.move_path(source_path, target_path);
+    this.sessions.delete(session_id);
+    return {
+      session_id: session_id,
+      archived_at: Date.now(),
+    };
   }
 
-  /** 写入显式 system 快照。 */
-  async write_instruction(instruction: string): Promise<void> {
-    const instruction_path = get_sdk_agent_session_instruction_path(
-      this.files.root_path,
-      this.agent_id,
-      this.session_id,
+  /** 返回归档 Session 摘要页。 */
+  async list_archived_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult> {
+    return await list_archived_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,
+      files: this.files,
+    });
+  }
+
+  /** 永久删除全部归档 Session。 */
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    const archive_path = get_workspace_archived_sessions_path(
+      this.storage_root_path,
     );
-    await this.files.write_file_atomically(instruction_path, instruction);
+    if (!(await this.files.path_exists(archive_path))) {
+      return { removed_session_ids: [] };
+    }
+    const entries = await this.files.read_directory(archive_path);
+    const removed_session_ids: string[] = [];
+    for (const entry of entries) {
+      if (!entry.is_directory) continue;
+      const session_id = decode_session_id(entry.name);
+      if (!session_id) continue;
+      if (!(await this.is_session_owner(session_id, true))) continue;
+      await this.files.remove_path(get_workspace_archived_session_path(
+        this.storage_root_path,
+        session_id,
+      ));
+      removed_session_ids.push(session_id);
+    }
+    return { removed_session_ids: removed_session_ids };
   }
 
-  /** 返回当前 Session instruction.md 的 Workspace 路径。 */
-  private instruction_path(): string {
-    return get_sdk_agent_session_instruction_path(
-      this.files.root_path,
-      this.agent_id,
-      this.session_id,
+  /** 本地 JSONL Store 当前没有常驻句柄。 */
+  async dispose(): Promise<void> {}
+
+  /** 返回活动 Session 物理目录，仅供本地实现内部使用。 */
+  private session_path(session_id: string): string {
+    return get_workspace_session_path(
+      this.storage_root_path,
+      session_id,
     );
   }
 
-  /** 返回当前 Session meta.json 的 Workspace 路径。 */
-  private metadata_path(): string {
-    return get_sdk_agent_session_meta_path(
-      this.files.root_path,
-      this.agent_id,
-      this.session_id,
+  /** 校验目标 Session 确实属于当前 Agent 与 Workspace。 */
+  private async assert_session_owner(
+    session_id: string,
+    archived: boolean,
+  ): Promise<void> {
+    if (await this.is_session_owner(session_id, archived)) return;
+    throw new Error(
+      `Session "${session_id}" belongs to another Agent`,
     );
   }
+
+  /** 判断 Session metadata 是否匹配当前查询视图。 */
+  private async is_session_owner(
+    session_id: string,
+    archived: boolean,
+  ): Promise<boolean> {
+    const file_path = archived
+      ? get_workspace_archived_session_meta_path(
+        this.storage_root_path,
+        session_id,
+      )
+      : get_workspace_session_meta_path(this.storage_root_path, 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; workspace_id?: unknown };
+      return metadata.agent_id === this.agent_id;
+    } catch {
+      return false;
+    }
+  }
 }

package/src/workspace/store/LocalStorePaths.ts

@@ -1,225 +1,143 @@
 /**
- * Workspace LocalAgentStore 的 Session 路径规则。
+ * Workspace 本地运行数据与 Session 路径规则。
  *
  * 关键点（中文）
- * - 所有 agent session 统一落盘到 `.downcity/agents/<agent_id>/sessions/<session_id>/...`。
- * - `agent_id` 是唯一隔离维度，不再保留第二套旧 session 根目录。
+ * - 调用方已经把文件能力限制在当前 Agent 的私有数据根。
+ * - Session 在 Agent 内使用稳定且唯一的 session_id 定位。
+ * - 本模块只拼接作用域内的相对领域路径，不解析用户级数据根。
  */
 
 import path from "node:path";
 
-/**
- * `.downcity` 根目录路径。
- */
-export function get_sdk_downcity_dir_path(workspace_path: string): string {
-  return path.join(workspace_path, ".downcity");
-}
-
-/**
- * SDK agents 根目录路径。
- */
-export function get_sdk_agents_root_dir_path(workspace_path: string): string {
-  return path.join(get_sdk_downcity_dir_path(workspace_path), "agents");
-}
-
-/**
- * 单个 agent 根目录路径。
- */
-export function get_sdk_agent_dir_path(
-  workspace_path: string,
-  agent_id: string,
-): string {
-  return path.join(
-    get_sdk_agents_root_dir_path(workspace_path),
-    encodeURIComponent(String(agent_id || "").trim()),
-  );
+/** 返回活动 Session 集合目录。 */
+export function get_workspace_sessions_path(storage_root_path: string): string {
+  return path.join(path.resolve(storage_root_path), "sessions");
 }
 
-/**
- * 单个 agent 的 sessions 根目录路径。
- */
-export function get_sdk_agent_sessions_root_dir_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回归档 Session 集合目录。 */
+export function get_workspace_archived_sessions_path(
+  storage_root_path: string,
 ): string {
-  return path.join(get_sdk_agent_dir_path(workspace_path, agent_id), "sessions");
+  return path.join(path.resolve(storage_root_path), "archived-sessions");
 }
 
-/**
- * 单个 agent 的已归档 sessions 根目录路径。
- *
- * 关键点（中文）
- * - `archive_session` 会把整个 session 目录从 `sessions/<session_id>` 移动到此处。
- * - `clean_archive` 会永久删除该目录下的全部内容。
- */
-export function get_sdk_agent_archived_sessions_dir_path(
-  workspace_path: string,
-  agent_id: string,
-): string {
-  return path.join(get_sdk_agent_dir_path(workspace_path, agent_id), "archived-sessions");
-}
-
-/**
- * 单个已归档 session 的根目录路径。
- */
-export function get_sdk_agent_archived_session_dir_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个活动 Session 目录。 */
+export function get_workspace_session_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_archived_sessions_dir_path(workspace_path, agent_id),
+    get_workspace_sessions_path(storage_root_path),
     encodeURIComponent(String(session_id || "").trim()),
   );
 }
 
-/**
- * 单个已归档 session 的消息目录路径。
- */
-export function get_sdk_agent_archived_session_messages_dir_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个归档 Session 目录。 */
+export function get_workspace_archived_session_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_archived_session_dir_path(workspace_path, agent_id, session_id),
-    "messages",
+    get_workspace_archived_sessions_path(storage_root_path),
+    encodeURIComponent(String(session_id || "").trim()),
   );
 }
 
-/**
- * 单个已归档 session 的 Active JSONL 文件路径。
- */
-export function get_sdk_agent_archived_session_messages_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个 Session 的 instruction.md 路径。 */
+export function get_workspace_session_instruction_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_archived_session_messages_dir_path(workspace_path, agent_id, session_id),
-    "active.jsonl",
+    get_workspace_session_path(storage_root_path, session_id),
+    "instruction.md",
   );
 }
 
-/**
- * 单个已归档 session 的 meta.json 路径。
- */
-export function get_sdk_agent_archived_session_meta_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个 Session 的附件目录。 */
+export function get_workspace_session_attachments_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_archived_session_messages_dir_path(workspace_path, agent_id, session_id),
-    "meta.json",
+    get_workspace_session_path(storage_root_path, session_id),
+    "attachments",
   );
 }
 
-/**
- * 单个 session 根目录路径。
- */
-export function get_sdk_agent_session_dir_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个 Session 的消息目录。 */
+export function get_workspace_session_messages_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_sessions_root_dir_path(workspace_path, agent_id),
-    encodeURIComponent(String(session_id || "").trim()),
+    get_workspace_session_path(storage_root_path, session_id),
+    "messages",
   );
 }
 
-/**
- * 单个 session 显式固化完整 system 的 instruction.md 路径。
- *
- * 关键点（中文）
- * - 文件不存在表示 Session 恢复时继续采用 Agent 当前 instruction。
- * - 空文件表示调用方显式固化了空 system。
- */
-export function get_sdk_agent_session_instruction_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个 Session 的 Active JSONL 路径。 */
+export function get_workspace_session_active_messages_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_session_dir_path(workspace_path, agent_id, session_id),
-    "instruction.md",
+    get_workspace_session_messages_path(storage_root_path, session_id),
+    "active.jsonl",
   );
 }
 
-/**
- * 单个 session 的消息目录路径。
- */
-export function get_sdk_agent_session_messages_dir_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个 Session 的运行中 Assistant 快照路径。 */
+export function get_workspace_session_assistant_message_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_session_dir_path(workspace_path, agent_id, session_id),
-    "messages",
+    get_workspace_session_messages_path(storage_root_path, session_id),
+    "assistant_message.json",
   );
 }
 
-/**
- * 单个 Session 的附件目录路径。
- *
- * 附件与 Session 目录同生命周期，归档或删除 Session 时随目录一起迁移或清理。
- */
-export function get_sdk_agent_session_attachments_dir_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个 Session 的 meta.json 路径。 */
+export function get_workspace_session_meta_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_session_dir_path(workspace_path, agent_id, session_id),
-    "attachments",
+    get_workspace_session_path(storage_root_path, session_id),
+    "meta.json",
   );
 }
 
-/**
- * 单个 session 的 Active JSONL 文件路径。
- */
-export function get_sdk_agent_session_messages_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个归档 Session 的消息目录。 */
+export function get_workspace_archived_session_messages_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_session_messages_dir_path(workspace_path, agent_id, session_id),
-    "active.jsonl",
+    get_workspace_archived_session_path(storage_root_path, session_id),
+    "messages",
   );
 }
 
-/**
- * 单个 session 的 meta.json 路径。
- */
-export function get_sdk_agent_session_meta_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个归档 Session 的 Active JSONL 路径。 */
+export function get_workspace_archived_session_active_messages_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_session_messages_dir_path(workspace_path, agent_id, session_id),
-    "meta.json",
+    get_workspace_archived_session_messages_path(storage_root_path, session_id),
+    "active.jsonl",
   );
 }
 
-/**
- * 单个 session 的 inflight assistant 路径。
- *
- * 关键点（中文）
- * - 运行中的 assistant 只保留一份增量快照。
- * - step / tool 过程会持续重写这个文件，避免中途中断后过程完全丢失。
- * - 完成后再把最终 assistant 合并进 `active.jsonl`，并清理该文件。
- */
-export function get_sdk_agent_session_assistant_message_path(
-  workspace_path: string,
-  agent_id: string,
+/** 返回单个归档 Session 的 meta.json 路径。 */
+export function get_workspace_archived_session_meta_path(
+  storage_root_path: string,
   session_id: string,
 ): string {
   return path.join(
-    get_sdk_agent_session_messages_dir_path(workspace_path, agent_id, session_id),
-    "assistant_message.json",
+    get_workspace_archived_session_path(storage_root_path, session_id),
+    "meta.json",
   );
 }

package/src/workspace/store/SessionMessageStoreFactory.ts

@@ -8,7 +8,7 @@
 
 import { JsonlSessionMessageStore } from "@/workspace/store/JsonlSessionMessageStore.js";
 import type { JsonlSessionMessageStoreOptions } from "@/types/store/LocalStore.js";
-import type { SessionMessageStore } from "@/types/store/SessionStore.js";
+import type { SessionMessageStore } from "@/types/store/SessionDataStore.js";
 
 /** 创建当前默认的本地 Session Message Store。 */
 export function create_session_message_store(

package/tsconfig.json

@@ -9,7 +9,8 @@
     "rootDir": "src",
     "paths": {
       "@/*": ["./src/*"],
-      "@executor/*": ["./src/executor/*"]
+      "@executor/*": ["./src/executor/*"],
+      "@downcity/federation": ["../federation/bin/index.d.ts"]
     },
     "strict": true,
     "noImplicitAny": false,