@downcity/agent 1.1.408 → 1.1.437

package/src/agent/Agent.ts

@@ -1,64 +1,70 @@
 /**
- * Agent：身份、模型、指令与 Plugin 的主体对象。
+ * Agent：身份、模型、指令与 Session 的主体对象。
  *
  * 职责说明（中文）
  * - Agent 不绑定 Workspace；调用方通过 `agent.sessions.create({ workspace })` 选择本次执行环境。
- * - PluginRegistry 只属于 Agent，所有 Workspace 共享同一份注册定义。
+ * - Plugin 与 Transport 由 City 持有，Agent 只通过 CityRuntime 使用最小执行能力。
  * - Session 由 AgentSessions 统一持有；Workspace 只在单个 Session 创建时提供执行资源。
  */
 
-import type { RuntimeTool as Tool } from "@downcity/type";
-import type { AgentModel } from "@/agent/AgentModel.js";
-import { normalize_instruction_input } from "@/agent/AgentInstructions.js";
-import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
+import type {
+  CityRuntime,
+  ModelClient,
+  RuntimeTool as Tool,
+  StorageProvider,
+  WorkspaceRuntime,
+} from "@downcity/type";
+import {
+  create_instruction_system_blocks,
+  normalize_instruction_input,
+} from "@/agent/AgentInstructions.js";
 import type {
   AgentOptions,
   AgentSessionConstructor,
 } from "@/types/agent/AgentOptions.js";
-import type { AgentPluginContext } from "@/types/plugin/AgentPluginContext.js";
-import type { PluginWebServices } from "@/types/plugin/PluginServices.js";
 import type {
   AgentSessionCollection,
 } from "@/types/agent/AgentSessionCollection.js";
 import { Logger } from "@/utils/logger/Logger.js";
 import { AgentSessions } from "@/agent/AgentSessions.js";
+import { AgentMemoryStorageProvider } from "@/agent/AgentMemoryStorage.js";
+import { LocalSessionStore } from "@/session/storage/LocalSessionStore.js";
+import { EMPTY_SESSION_HOOKS } from "@/session/SessionHooks.js";
+import type { AgentStorage } from "@/types/agent/AgentStorage.js";
+import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import {
-  agent_embassy,
-  clear_agent_runtime,
-  create_workspace_entry,
-  dispose_agent_runtime,
-  get_agent_storage,
-  initialize_agent_runtime,
-  list_workspace_entries,
-  mark_agent_session_started,
-  release_agent_from_city,
-} from "@/internal/AgentRuntime.js";
+  build_session_system_blocks,
+  resolve_session_plugin_system_blocks,
+} from "@/session/SessionSystem.js";
+import { create_session_hook_context } from "@/session/runtime/SessionTurnContext.js";
+import { resolve_system_timezone } from "@/session/storage/Metadata.js";
 
 /** SDK Agent 主体。 */
 export class Agent {
   /** Agent 的全局稳定标识。 */
   readonly id: string;
 
+  /** Agent 的用户可见名称。 */
+  readonly name: string;
+
+  /** Agent 的一句话能力描述，供展示与 Group 调度使用。 */
+  readonly description: string;
+
   /** Agent 默认模型；Session 可以显式覆盖。 */
-  readonly model?: AgentModel;
+  readonly model?: ModelClient;
 
   /** Agent 面向用户的 Session 创建入口。 */
   readonly sessions: AgentSessionCollection;
 
-  /** 当前 Agent 持有的 Web 搜索与文档能力。 */
-  readonly web?: PluginWebServices;
-
-  /** Agent 注册的唯一 PluginRegistry。 */
-  readonly plugins: PluginRegistry;
-
   /** Agent 自定义 Tool；进入每个 Workspace 时与项目 Tool 合并。 */
   readonly custom_tools: Record<string, Tool>;
 
   /** Agent 使用的 Session 类。 */
   readonly session_class?: AgentSessionConstructor;
 
-  /** AgentPlugin 的内部访问名，仍指向 Agent 唯一 Registry。 */
-  readonly plugin_registry: PluginRegistry;
+  /** 为每个 Session 创建独立 Composer 的工厂。 */
+  readonly session_composer?: () => SessionComposer;
 
   /** Agent 级日志器，不绑定任何 Workspace。 */
   private readonly logger = new Logger();
@@ -69,81 +75,68 @@ export class Agent {
   /** Agent 释放状态。 */
   private dispose_promise?: Promise<void>;
 
-  /** Agent 级 Plugin lifecycle 启动流程。 */
-  private readonly plugin_ready: Promise<unknown>;
-
   /** Agent 唯一的 Session 集合。 */
   private readonly session_manager: AgentSessions;
 
+  /** 未加入宿主时使用的隔离进程内存储。 */
+  private storage_provider: StorageProvider = new AgentMemoryStorageProvider();
+
+  /** Agent 当前所属的唯一 City；独立运行时为空。 */
+  private city?: CityRuntime;
+
+  /** 延迟创建的 Agent 私有持久化视图。 */
+  private agent_storage?: AgentStorage;
+
+  /** 是否已经在无宿主存储中创建或恢复过 Session。 */
+  private memory_session_started = false;
+
   constructor(options: AgentOptions) {
     this.id = String(options.id || "").trim();
     if (!this.id) throw new Error("Agent requires a non-empty id");
-    initialize_agent_runtime(this);
+    this.name = String(options.name || "").trim() || this.id;
+    this.description = String(options.description || "").trim();
     this.model = options.model;
-    this.web = options.web;
     this.instruction = normalize_instruction_input(options.instruction);
-    const agent = this;
-    const agent_plugin_context: AgentPluginContext = Object.freeze({
-      agent_id: this.id,
-      logger: this.logger,
-      web: this.web,
-      get embassy() {
-        return agent_embassy(agent);
-      },
-      get instructions() {
-        return agent.get_instructions();
-      },
-    });
     this.session_class = options.session_class;
-    this.plugins = new PluginRegistry(agent_plugin_context, options.plugins || []);
-    this.plugin_registry = this.plugins;
-    this.plugin_ready = this.plugins.start_all();
+    this.session_composer = options.session_composer;
     this.custom_tools = options.tools && typeof options.tools === "object"
       ? { ...options.tools }
       : {};
-    const no_workspace_plugins = () => ({
-      plugins: [],
-      read: () => ({ plugins: [] }),
-      run_action: async () => ({ success: false, error: "Workspace is required" }),
-      system_blocks: async () => [],
-      acquire: () => ({
-        read: () => ({ plugins: [] }),
-        run_action: async () => ({ success: false, error: "Workspace is required" }),
-        system_blocks: async () => [],
-        release: async () => {},
-      }),
-    });
-    const get_store = (): import("@/types/store/SessionStore.js").SessionStore =>
-      get_agent_storage(this).sessions;
-    const session_store = {
-      session: (session_id: string, workspace_id?: string) => get_store().session(session_id, workspace_id),
-      has_session: async (session_id: string) => await get_store().has_session(session_id),
-      remove_session: async (session_id: string) => await get_store().remove_session(session_id),
-      clear_session_messages: async (session_id: string) => await get_store().clear_session_messages(session_id),
-      list_sessions: async (input: Parameters<import("@/types/store/SessionStore.js").SessionStore["list_sessions"]>[0], executing: ReadonlySet<string>) => await get_store().list_sessions(input, executing),
-      archive_session: async (session_id: string) => await get_store().archive_session(session_id),
-      list_archived_sessions: async (input?: Parameters<import("@/types/store/SessionStore.js").SessionStore["list_archived_sessions"]>[0]) => await get_store().list_archived_sessions(input),
-      clean_archive: async () => await get_store().clean_archive(),
-      dispose: async () => {},
-    } satisfies import("@/types/store/SessionStore.js").SessionStore;
     this.session_manager = new AgentSessions({
       agent_id: this.id,
       logger: this.logger,
       get_instruction: () => [...this.get_instructions()],
-      ensure_agent_ready: async () => { await this.plugin_ready; },
+      ensure_agent_ready: async () => await this.ensure_ready(),
       get_agent_model: () => this.model,
       session_class: this.session_class,
-      on_session_routed: () => mark_agent_session_started(agent),
+      create_session_composer: this.session_composer,
+      on_session_routed: () => {
+        if (!this.city) this.memory_session_started = true;
+      },
       resolve_session_context: (workspace) => {
+        const storage = this.resolve_storage();
         if (!workspace) return {
           workspace_path: ".",
           logger: this.logger,
-          tools: this.custom_tools,
+          get_tools: () => ({ ...this.custom_tools }),
           get_workspace_env: () => ({}),
-          get_agent_plugins: no_workspace_plugins,
-          store: session_store,
+          get_hooks: () => EMPTY_SESSION_HOOKS,
+          store: storage.sessions,
+        };
+        this.assert_workspace(workspace);
+        // 静态 Workspace Tool 与 Agent Tool 的命名冲突属于 Session 创建不变量，
+        // 在装配时立即失败；执行时仍通过 getter 读取最新宿主扩展。
+        this.resolve_tools(workspace);
+        return {
+          workspace_path: workspace.path,
+          workspace_id: workspace.id,
+          logger: this.logger,
+          get_tools: () => this.resolve_tools(workspace),
+          get_workspace_env: () => workspace.get_env(),
+          get_hooks: () => this.city?.get_session_hooks(this.id, workspace)
+            ?? EMPTY_SESSION_HOOKS,
+          store: storage.sessions,
         };
-        return create_workspace_entry(this, workspace).get_session_context();
       },
     });
     this.sessions = this.session_manager;
@@ -165,28 +158,156 @@ export class Agent {
     return this.logger;
   }
 
-  /** 释放 Agent 进入的全部 Workspace 与 Agent Plugin。 */
+  /** 将 Agent 加入 City；必须在创建或恢复 Session 前完成。 */
+  attach(city: CityRuntime): void {
+    if (this.dispose_promise) throw new Error(`Agent "${this.id}" is disposing`);
+    if (this.city) {
+      if (this.city === city) return;
+      throw new Error(`Agent "${this.id}" already belongs to another City`);
+    }
+    if (this.memory_session_started || this.agent_storage) {
+      throw new Error(
+        `Agent "${this.id}" already used standalone storage; attach it before using Sessions`,
+      );
+    }
+    this.city = city;
+    this.storage_provider = city.storage;
+  }
+
+  /** 解除指定 City 关系；其他 City 不能解除当前绑定。 */
+  detach(city: CityRuntime): void {
+    if (this.city === city) this.city = undefined;
+  }
+
+  /** 停止绑定到指定 Workspace 的运行中 Session，并释放后台标题任务。 */
+  async release_workspace(workspace_id: string): Promise<void> {
+    await this.session_manager.stop_executing_sessions(workspace_id);
+    this.session_manager.dispose_title_generation(workspace_id);
+  }
+
+  /** 解析指定 Workspace 下一个 Session 当前可见的 system messages。 */
+  async resolve_system_messages(
+    workspace: WorkspaceRuntime,
+    input: {
+      /** 目标 Session 稳定标识。 */
+      session_id: string;
+    },
+  ): Promise<SessionSystemMessage[]> {
+    this.assert_workspace(workspace);
+    const session_id = String(input.session_id || "").trim();
+    if (!session_id) {
+      throw new Error("resolve_system_messages requires a non-empty session_id");
+    }
+    const instruction_system_blocks = create_instruction_system_blocks(
+      [...this.get_instructions()],
+      workspace.path,
+    );
+    const hooks = this.city?.get_session_hooks(this.id, workspace)
+      ?? EMPTY_SESSION_HOOKS;
+    const hook_context = create_session_hook_context({
+      session_id,
+      session_origin: { type: "chat" },
+      project_root: workspace.path,
+      workspace_env: Object.freeze({ ...workspace.get_env() }),
+      agent_systems: instruction_system_blocks.map((block) => block.content),
+    });
+    const plugin_system_blocks = await resolve_session_plugin_system_blocks({
+      session_id,
+      hooks,
+      context: hook_context,
+    });
+    const blocks = await build_session_system_blocks({
+      agent_id: this.id,
+      project_root: workspace.path,
+      session_id,
+      created_at: Date.now(),
+      timezone: resolve_system_timezone(),
+      get_instruction_system_blocks: () => instruction_system_blocks,
+      get_managed_plugin_system_blocks: async () => [],
+      get_plugin_system_blocks: async () => plugin_system_blocks,
+    });
+    return blocks.map((block) => ({ role: "system", content: block.content }));
+  }
+
+  /** 释放 Agent 的 Session 后台任务、存储与宿主引用。 */
   async dispose(): Promise<void> {
     this.dispose_promise ??= (async () => {
-      await this.plugin_ready.catch(() => undefined);
-      const entries = [...list_workspace_entries(this)];
-      const results = await Promise.allSettled(entries.map(async (entry) => await entry.leave()));
-      await this.plugins.unregister_all();
+      const results = await Promise.allSettled([
+        this.session_manager.stop_executing_sessions(),
+      ]);
       this.session_manager.dispose_title_generation();
-      await dispose_agent_runtime(this);
-      const errors = results.flatMap((result) =>
-        result.status === "rejected" ? [result.reason] : []
-      );
-      release_agent_from_city(this);
-      clear_agent_runtime(this);
+      const city = this.city;
+      results.push(...await Promise.allSettled([
+        city?.release_agent(this) ?? Promise.resolve(),
+        this.agent_storage?.sessions.dispose() ?? Promise.resolve(),
+        this.logger.save_all_logs(),
+      ]));
+      const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+      this.city = undefined;
+      this.agent_storage = undefined;
       if (errors.length > 0) throw new AggregateError(errors, "Agent dispose failed");
     })();
     await this.dispose_promise;
   }
 
-  /** 等待 Agent 级 Plugin 完成启动，供内部运行时使用。 */
+  /** 等待 Agent 自身运行时 ready，供内部运行时使用。 */
   async ensure_ready(): Promise<void> {
-    await this.plugin_ready;
+    await this.city?.ensure_ready();
+  }
+
+  /** 获取或创建 Agent 唯一的 Session 存储。 */
+  private resolve_storage(): AgentStorage {
+    if (this.agent_storage) return this.agent_storage;
+    const scope = this.storage_provider.open_scope(["agents", this.id]);
+    this.logger.bind_storage(scope.files, scope.root_path, { agent_id: this.id });
+    this.agent_storage = {
+      root_path: scope.root_path,
+      files: scope.files,
+      database_location: scope.database_location,
+      sessions: new LocalSessionStore({
+        files: scope.files,
+        storage_root_path: scope.root_path,
+        agent_id: this.id,
+        database_location: scope.database_location,
+      }),
+    };
+    return this.agent_storage;
+  }
+
+  /** 校验宿主模式下使用的 Workspace 来自当前宿主事实源。 */
+  private assert_workspace(workspace: WorkspaceRuntime): void {
+    const workspace_id = String(workspace?.id || "").trim();
+    if (!workspace_id) throw new Error("Agent sessions require a Workspace with a stable id");
+    if (this.city && this.city.workspaces.get(workspace_id) !== workspace) {
+      throw new Error(`Workspace "${workspace_id}" does not belong to the Agent City`);
+    }
   }
 
+  /** 在明确检查点合并 Workspace、宿主扩展和 Agent Tool。 */
+  private resolve_tools(workspace: WorkspaceRuntime): Record<string, Tool> {
+    const tools: Record<string, Tool> = {};
+    register_tools(tools, workspace.tools, "WorkspaceTools");
+    register_tools(
+      tools,
+      this.city?.get_session_tools(this.id, workspace) ?? {},
+      "City",
+    );
+    register_tools(tools, this.custom_tools, "AgentOptions.tools");
+    return tools;
+  }
+
+}
+
+/** 注册 Tool 集合，并拒绝不同来源静默覆盖。 */
+function register_tools(
+  target: Record<string, Tool>,
+  source: Record<string, Tool>,
+  source_name: string,
+): void {
+  for (const [tool_name, tool_definition] of Object.entries(source)) {
+    if (Object.prototype.hasOwnProperty.call(target, tool_name)) {
+      throw new Error(`Agent tool name conflict: "${tool_name}" from ${source_name}`);
+    }
+    target[tool_name] = tool_definition;
+  }
 }

package/src/agent/AgentInstructions.ts

@@ -4,11 +4,11 @@
  * 关键点（中文）
  * - 这里只处理静态 instruction 与默认 core prompt。
  * - instruction 永远在 core 前面；core 不会被调用方 instruction 替代。
- * - 不读取 session、plugin 或 runtime 状态，保持为纯函数。
+ * - 不读取 Session、Plugin 或 runtime 状态，保持为纯函数。
  */
 
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import { DEFAULT_SHIP_PROMPTS } from "@executor/composer/system/default/SystemDomain.js";
+import { CORE_SYSTEM_PROMPT } from "@executor/composer/system/default/SystemPromptAssets.js";
 
 /**
  * 归一化调用方传入的静态 instruction。
@@ -28,7 +28,7 @@ export function normalize_instruction_input(
 
 function createCoreInstructionContent(project_root: string): string {
   const current_year = String(new Date().getFullYear());
-  return DEFAULT_SHIP_PROMPTS
+  return CORE_SYSTEM_PROMPT
     .replaceAll("{{project_path}}", project_root)
     .replaceAll("{{project_root}}", project_root)
     .replaceAll("{{current_year}}", current_year);

package/src/agent/AgentMemoryStorage.ts

@@ -0,0 +1,208 @@
+/**
+ * Agent 与 Group 无宿主模式使用的私有进程内存储。
+ *
+ * 该实现只保证 Agent/Group Store 所需的文件原语，不作为 SDK 资源公开。正式 City
+ * 运行时会在创建 Session 前注入 City 持有的 StorageProvider。
+ */
+
+import type {
+  FileSystem,
+  FileToolActionRequest,
+  FileToolActionResult,
+  SearchToolActionRequest,
+  SearchToolActionResult,
+  StorageProvider,
+  StorageScope,
+  WorkspaceDirectoryEntry,
+} from "@downcity/type/workspace";
+
+/** 单一内存作用域内的最小文件系统。 */
+class AgentMemoryFileSystem implements FileSystem {
+  /** 当前作用域的稳定逻辑根路径。 */
+  readonly root_path: string;
+
+  /** 按规范化路径保存的文件字节。 */
+  private readonly files_by_path = new Map<string, Buffer>();
+
+  /** 当前作用域中已经创建的目录。 */
+  private readonly directories = new Set<string>();
+
+  constructor(root_path: string) {
+    this.root_path = root_path;
+    this.directories.add(root_path);
+  }
+
+  /** 将输入路径约束到当前逻辑根目录。 */
+  resolve_path(...segments: string[]): string {
+    return this.normalize(segments.join("/"));
+  }
+
+  /** 判断文件或目录是否存在。 */
+  async path_exists(file_path: string): Promise<boolean> {
+    const target_path = this.normalize(file_path);
+    return this.files_by_path.has(target_path) || this.directories.has(target_path);
+  }
+
+  /** 返回文件字节的独立副本。 */
+  async read_file(file_path: string): Promise<Buffer> {
+    const content = this.files_by_path.get(this.normalize(file_path));
+    if (!content) throw Object.assign(new Error("File not found"), { code: "ENOENT" });
+    return Buffer.from(content);
+  }
+
+  /** 返回文件字节大小。 */
+  async file_size(file_path: string): Promise<number> {
+    return (await this.read_file(file_path)).byteLength;
+  }
+
+  /** 创建目录和缺失的父目录。 */
+  async ensure_directory(directory_path: string): Promise<void> {
+    const target_path = this.normalize(directory_path);
+    const parts = target_path.slice(this.root_path.length).split("/").filter(Boolean);
+    let current_path = this.root_path;
+    for (const part of parts) {
+      current_path = `${current_path}/${part}`;
+      this.directories.add(current_path);
+    }
+  }
+
+  /** 幂等删除目标路径及其子内容。 */
+  async remove_path(target_path: string): Promise<void> {
+    const normalized_path = this.normalize(target_path);
+    for (const file_path of [...this.files_by_path.keys()]) {
+      if (file_path === normalized_path || file_path.startsWith(`${normalized_path}/`)) {
+        this.files_by_path.delete(file_path);
+      }
+    }
+    for (const directory_path of [...this.directories]) {
+      if (directory_path === normalized_path || directory_path.startsWith(`${normalized_path}/`)) {
+        this.directories.delete(directory_path);
+      }
+    }
+  }
+
+  /** 原子移动一个文件或目录树。 */
+  async move_path(source_path: string, target_path: string): Promise<void> {
+    const source = this.normalize(source_path);
+    const target = this.normalize(target_path);
+    if (await this.path_exists(target)) throw new Error(`Target already exists: ${target}`);
+    for (const [file_path, content] of [...this.files_by_path.entries()]) {
+      if (file_path === source || file_path.startsWith(`${source}/`)) {
+        this.files_by_path.set(`${target}${file_path.slice(source.length)}`, content);
+        this.files_by_path.delete(file_path);
+      }
+    }
+    for (const directory_path of [...this.directories]) {
+      if (directory_path === source || directory_path.startsWith(`${source}/`)) {
+        this.directories.add(`${target}${directory_path.slice(source.length)}`);
+        this.directories.delete(directory_path);
+      }
+    }
+  }
+
+  /** 列出目标目录的直接子条目。 */
+  async read_directory(directory_path: string): Promise<WorkspaceDirectoryEntry[]> {
+    const parent_path = this.normalize(directory_path);
+    const entries = new Map<string, WorkspaceDirectoryEntry>();
+    for (const directory of this.directories) this.add_entry(parent_path, directory, true, entries);
+    for (const file_path of this.files_by_path.keys()) this.add_entry(parent_path, file_path, false, entries);
+    return [...entries.values()];
+  }
+
+  /** 原子写入完整文件内容。 */
+  async write_file_atomically(file_path: string, content: string | Buffer): Promise<void> {
+    const target_path = this.normalize(file_path);
+    await this.ensure_directory(target_path.slice(0, target_path.lastIndexOf("/")));
+    this.files_by_path.set(target_path, Buffer.from(content));
+  }
+
+  /** 向目标文件追加内容。 */
+  async append_file(file_path: string, content: string | Buffer): Promise<void> {
+    const current = this.files_by_path.get(this.normalize(file_path)) ?? Buffer.alloc(0);
+    await this.write_file_atomically(file_path, Buffer.concat([current, Buffer.from(content)]));
+  }
+
+  /** 内存作用域在单线程事件循环中直接执行文件事务。 */
+  async with_file_lock<T>(_lock_path: string, action: () => Promise<T>): Promise<T> {
+    return await action();
+  }
+
+  /** Agent 私有存储不提供项目文件工具。 */
+  async run_file_action(_request: FileToolActionRequest): Promise<FileToolActionResult> {
+    throw new Error("Agent memory storage does not provide project file tools");
+  }
+
+  /** Agent 私有存储不提供项目搜索工具。 */
+  async run_search_action(_request: SearchToolActionRequest): Promise<SearchToolActionResult> {
+    throw new Error("Agent memory storage does not provide project search tools");
+  }
+
+  /** 规范化并校验当前作用域内的逻辑路径。 */
+  private normalize(file_path: string): string {
+    const normalized_path = String(file_path || "").replace(/\/+/g, "/");
+    const relative_path = normalized_path.startsWith(this.root_path)
+      ? normalized_path.slice(this.root_path.length)
+      : normalized_path;
+    const parts = relative_path.split("/").filter(Boolean);
+    if (parts.some((part) => part === "." || part === "..")) {
+      throw new Error(`Path escapes Agent memory storage: ${file_path}`);
+    }
+    return [this.root_path, ...parts].join("/");
+  }
+
+  /** 将候选路径归并为一个直接子条目。 */
+  private add_entry(
+    parent_path: string,
+    candidate_path: string,
+    is_directory: boolean,
+    entries: Map<string, WorkspaceDirectoryEntry>,
+  ): void {
+    if (!candidate_path.startsWith(`${parent_path}/`) || candidate_path === parent_path) return;
+    const remainder = candidate_path.slice(parent_path.length + 1);
+    const name = remainder.split("/")[0];
+    if (!name || entries.has(name)) return;
+    entries.set(name, {
+      name,
+      is_directory: is_directory || remainder.includes("/"),
+      is_file: !is_directory && !remainder.includes("/"),
+    });
+  }
+}
+
+/** 为无宿主 Agent/Group 创建隔离的进程内 StorageProvider。 */
+export class AgentMemoryStorageProvider implements StorageProvider {
+  /** 按完整 scope key 缓存稳定作用域。 */
+  private readonly scopes_by_key = new Map<string, StorageScope>();
+
+  /** 当前 Provider 的逻辑根目录。 */
+  private readonly root_path: string;
+
+  constructor(root_path = "/agent-memory") {
+    this.root_path = root_path;
+  }
+
+  /** 打开或复用一个受路径片段约束的内存作用域。 */
+  open_scope(segments: readonly string[]): StorageScope {
+    const normalized_segments = segments.map((segment) => normalize_scope_segment(segment));
+    const scope_key = normalized_segments.join("/");
+    const existing = this.scopes_by_key.get(scope_key);
+    if (existing) return existing;
+    const root_path = [this.root_path, ...normalized_segments].join("/");
+    const scope = Object.freeze({
+      root_path,
+      files: new AgentMemoryFileSystem(root_path),
+      database_location: { type: "memory" as const },
+    });
+    this.scopes_by_key.set(scope_key, scope);
+    return scope;
+  }
+}
+
+/** 校验 Storage scope 的单个稳定路径片段。 */
+function normalize_scope_segment(value: string): string {
+  const segment = String(value || "").trim();
+  if (!segment || segment === "." || segment === ".." || segment.includes("/") || segment.includes("\\")) {
+    throw new Error("Storage scope contains an invalid segment");
+  }
+  return segment;
+}