@downcity/agent 1.1.337 → 1.1.399

package/src/agent/AgentSessions.ts

@@ -8,7 +8,7 @@
  */
 
 import { nanoid } from "nanoid";
-import type { Tool } from "ai";
+import type { RuntimeTool as Tool } from "@downcity/type";
 import type { AgentModel } from "@/agent/AgentModel.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type {
@@ -32,7 +32,9 @@ import { Session } from "@/session/Session.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
 import { create_instruction_system_blocks } from "@/agent/AgentInstructions.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
-import type { AgentStore } from "@/types/store/AgentStore.js";
+import type { SessionStore } from "@/types/store/SessionStore.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
 
 type AgentSessionsOptions = {
   /**
@@ -41,17 +43,20 @@ type AgentSessionsOptions = {
   agent_id: string;
 
   /**
-   * 当前项目根目录。
-   */
-  workspace_path: string;
-
-  /** 当前 Agent 独享的领域持久化入口。 */
-  store: AgentStore;
-
-  /**
-   * 当前 agent 默认工具集合。
+   * 按 Session 解析执行上下文。
+   *
+   * AgentSessions 是 Agent 唯一的 Session 集合；Workspace 相关能力不能
+   * 固定在集合实例上，而应在创建或恢复单个 Session 时解析。
    */
-  tools: Record<string, Tool>;
+  resolve_session_context: (workspace?: WorkspaceBase) => {
+    workspace_path: string;
+    workspace_id?: string;
+    logger: Logger;
+    tools: Record<string, Tool>;
+    get_workspace_env: () => Record<string, string>;
+    get_agent_plugins: () => AgentPluginExecutionRuntime;
+    store: SessionStore;
+  };
 
   /**
    * 当前统一日志器。
@@ -63,12 +68,6 @@ type AgentSessionsOptions = {
    */
   get_instruction: () => string[];
 
-  /** 延迟读取当前 Workspace configured env。 */
-  get_workspace_env: () => Record<string, string>;
-
-  /** 创建当前 configured Plugin registry 的 Session step 执行视图。 */
-  get_agent_plugins: () => AgentPluginExecutionRuntime;
-
   /**
    * 等待当前 Agent 持有的长期运行时启动完成。
    */
@@ -81,6 +80,9 @@ type AgentSessionsOptions = {
 
   /** 读取 Agent 当前持有的运行时模型实例。 */
   get_agent_model: () => AgentModel | undefined;
+
+  /** Session 创建或恢复后的内部路由登记回调。 */
+  on_session_routed?: (session_id: string, sessions: AgentSessions) => void;
 };
 
 /**
@@ -88,30 +90,24 @@ type AgentSessionsOptions = {
  */
 export class AgentSessions implements AgentSessionsContract<AgentSession> {
   private readonly agent_id: string;
-  private readonly workspace_path: string;
-  private readonly store: AgentStore;
-  private readonly tools: Record<string, Tool>;
+  private readonly resolve_session_context: AgentSessionsOptions["resolve_session_context"];
   private readonly logger: Logger;
   private readonly get_instruction: AgentSessionsOptions["get_instruction"];
-  private readonly get_workspace_env: AgentSessionsOptions["get_workspace_env"];
-  private readonly get_agent_plugins: AgentSessionsOptions["get_agent_plugins"];
   private readonly ensure_agent_ready: AgentSessionsOptions["ensure_agent_ready"];
   private readonly session_class: AgentSessionConstructor;
   private readonly get_agent_model: AgentSessionsOptions["get_agent_model"];
+  private readonly on_session_routed?: AgentSessionsOptions["on_session_routed"];
   private readonly sessions_by_id = new Map<string, AgentManagedSession>();
 
   constructor(options: AgentSessionsOptions) {
     this.agent_id = options.agent_id;
-    this.workspace_path = options.workspace_path;
-    this.store = options.store;
-    this.tools = options.tools;
+    this.resolve_session_context = options.resolve_session_context;
     this.logger = options.logger;
     this.get_instruction = options.get_instruction;
-    this.get_workspace_env = options.get_workspace_env;
-    this.get_agent_plugins = options.get_agent_plugins;
     this.ensure_agent_ready = options.ensure_agent_ready;
     this.session_class = options.session_class || Session;
     this.get_agent_model = options.get_agent_model;
+    this.on_session_routed = options.on_session_routed;
   }
 
   /**
@@ -121,10 +117,13 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return [...this.sessions_by_id.values()];
   }
 
-  /** 返回当前所有执行中的 Session 标识。 */
-  list_executing_session_ids(): string[] {
+  /** 返回当前所有执行中的 Session 标识；可按 Workspace 限定。 */
+  list_executing_session_ids(workspace_id?: string): string[] {
     return this.list_cached_sessions()
-      .filter((session) => session.is_executing())
+      .filter((session) =>
+        session.is_executing()
+        && (!workspace_id || session.workspace_id === workspace_id)
+      )
       .map((session) => session.id);
   }
 
@@ -133,9 +132,19 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return this.list_executing_session_ids().length;
   }
 
+  /** 停止当前集合内正在执行的 Session；可按 Workspace 限定。 */
+  async stop_executing_sessions(workspace_id?: string): Promise<void> {
+    const executing_sessions = this.list_cached_sessions().filter((session) =>
+      session.is_executing()
+      && (!workspace_id || session.workspace_id === workspace_id)
+    );
+    await Promise.all(executing_sessions.map(async (session) => await session.stop()));
+  }
+
   /** 释放全部缓存 Session 的标题后台任务。 */
-  dispose_title_generation(): void {
+  dispose_title_generation(workspace_id?: string): void {
     for (const session of this.sessions_by_id.values()) {
+      if (workspace_id && session.workspace_id !== workspace_id) continue;
       session.dispose_title_generation?.();
     }
   }
@@ -143,8 +152,9 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   /**
    * 把 Agent env 修改广播到已有 Session 的统一输入队列。
    */
-  broadcast_env(env: Record<string, string>, command_id: string): void {
+  broadcast_env(env: Record<string, string>, command_id: string, workspace_id?: string): void {
     for (const session of this.sessions_by_id.values()) {
+      if (workspace_id && session.workspace_id !== workspace_id) continue;
       session.enqueue_workspace_env({
         command_id,
         env: { ...env },
@@ -159,8 +169,10 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     command_id: string;
     title: string;
     plugins: AgentPluginExecutionRuntime;
+    workspace_id?: string;
   }): void {
     for (const session of this.sessions_by_id.values()) {
+      if (input.workspace_id && session.workspace_id !== input.workspace_id) continue;
       session.enqueue_agent_plugins({
         command_id: input.command_id,
         title: input.title,
@@ -170,30 +182,33 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   }
 
   /**
-   * 获取或创建一个 session runtime port。
+   * 获取已缓存 Session 的 runtime port。
+   *
+   * runtime 是执行层的内部投影，不负责创建 Session。需要创建时必须
+   * 通过 `create()` 获取内部生成的 ID；需要恢复时必须先调用 `get()`。
    */
   runtime(session_id: string): SessionPort {
-    return this.get_or_create_session({ session_id }).get_runtime_port();
+    const resolved_session_id = String(session_id || "").trim();
+    const session = this.sessions_by_id.get(resolved_session_id);
+    if (!session) {
+      throw new Error(
+        `Session "${resolved_session_id}" is not loaded; call sessions.get(session_id) first`,
+      );
+    }
+    return session.get_runtime_port();
   }
 
   /**
    * 新建一个 session。
    */
   async create(
-    input?: AgentCreateSessionInput,
+    input?: AgentCreateSessionInput & { workspace?: WorkspaceBase; origin?: SessionOrigin },
   ): Promise<AgentSession> {
-    const explicit_session_id =
-      String(input?.session_id || "").trim() || undefined;
-    if (
-      explicit_session_id &&
-      (this.sessions_by_id.has(explicit_session_id) ||
-        (await this.store.has_session(explicit_session_id)))
-    ) {
-      throw new Error(`Session "${explicit_session_id}" already exists`);
-    }
     const session = this.get_or_create_session({
-      session_id: explicit_session_id,
+      workspace: input?.workspace,
+      origin: input?.origin,
     });
+    this.on_session_routed?.(session.id, this);
     await session.initialize();
     return session;
   }
@@ -201,20 +216,49 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   /**
    * 获取一个已存在的 session。
    */
-  async get(session_id: string): Promise<AgentSession> {
+  async get(
+    session_id: string,
+    input?: { workspace?: WorkspaceBase; origin?: SessionOrigin },
+  ): Promise<AgentSession> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
       throw new Error("sessions.get requires a non-empty session_id");
     }
+    const store = this.resolve_session_context(input?.workspace).store;
     if (
       !this.sessions_by_id.has(resolved_session_id) &&
-      !(await this.store.has_session(resolved_session_id))
+      !(await store.has_session(resolved_session_id))
     ) {
       throw new Error(`Session "${resolved_session_id}" not found`);
     }
+    const persisted_metadata = await store
+      .session(resolved_session_id, input?.workspace?.id)
+      .read_metadata();
+    const persisted_workspace_id = String(persisted_metadata.workspace_id || "").trim() || undefined;
+    const persisted_origin = persisted_metadata.origin;
+    const cached = this.sessions_by_id.get(resolved_session_id);
+    const requested_workspace_id = String(input?.workspace?.id || "").trim() || undefined;
+    if (persisted_workspace_id !== requested_workspace_id) {
+      throw new Error(
+        persisted_workspace_id
+          ? `Session "${resolved_session_id}" requires Workspace "${persisted_workspace_id}"`
+          : `Session "${resolved_session_id}" is not bound to a Workspace`,
+      );
+    }
+    if (cached && cached.workspace_id !== requested_workspace_id) {
+      throw new Error(
+        `Session "${resolved_session_id}" is already bound to Workspace "${cached.workspace_id || ""}"`,
+      );
+    }
+    if (input?.origin && JSON.stringify(persisted_origin || { type: "user" }) !== JSON.stringify(input.origin)) {
+      throw new Error(`Session "${resolved_session_id}" has a different origin`);
+    }
     const session = this.get_or_create_session({
       session_id: resolved_session_id,
+      workspace: input?.workspace,
+      origin: input?.origin || persisted_origin,
     });
+    this.on_session_routed?.(resolved_session_id, this);
     await session.initialize();
     return session;
   }
@@ -236,7 +280,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       await cached.stop();
     }
     cached?.dispose_title_generation?.();
-    const existed = await this.store.remove_session(resolved_session_id);
+    const existed = await this.resolve_session_context().store.remove_session(resolved_session_id);
     this.sessions_by_id.delete(resolved_session_id);
     return existed;
   }
@@ -254,7 +298,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       throw new Error(`Session "${resolved_session_id}" is currently executing`);
     }
     cached?.dispose_title_generation?.();
-    const existed = await this.store.clear_session_messages(resolved_session_id);
+    const existed = await this.resolve_session_context().store.clear_session_messages(resolved_session_id);
     this.sessions_by_id.delete(resolved_session_id);
     return existed;
   }
@@ -265,7 +309,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   async list(
     input?: AgentListSessionsInput,
   ): Promise<AgentSessionSummaryPage> {
-    return await this.store.list_sessions(
+    return await this.resolve_session_context().store.list_sessions(
       input,
       new Set(this.list_executing_session_ids()),
     );
@@ -287,7 +331,7 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
       throw new Error(`Session "${session_id}" is currently executing`);
     }
 
-    const result = await this.store.archive_session(session_id);
+    const result = await this.resolve_session_context().store.archive_session(session_id);
     this.sessions_by_id.get(session_id)?.dispose_title_generation?.();
     this.sessions_by_id.delete(session_id);
     return result;
@@ -299,14 +343,14 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
   async archived(
     input?: AgentArchiveSessionsInput,
   ): Promise<AgentArchiveSessionsResult> {
-    return await this.store.list_archived_sessions(input);
+    return await this.resolve_session_context().store.list_archived_sessions(input);
   }
 
   /**
    * 永久清空已归档 session。
    */
   async clean_archive(): Promise<AgentCleanArchiveResult> {
-    return await this.store.clean_archive();
+    return await this.resolve_session_context().store.clean_archive();
   }
 
   private get_or_create_session(input?: {
@@ -314,6 +358,10 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
      * 可选指定 session id。
      */
     session_id?: string;
+    /** 当前 Session 可选使用的 Workspace。 */
+    workspace?: WorkspaceBase;
+    /** 当前 Session 的创建来源。 */
+    origin?: SessionOrigin;
   }): AgentManagedSession {
     const resolved_session_id =
       String(input?.session_id || "").trim() ||
@@ -321,19 +369,22 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     const cached = this.sessions_by_id.get(resolved_session_id);
     if (cached) return cached;
 
+    const context = this.resolve_session_context(input?.workspace);
     const created = new this.session_class({
       agent_id: this.agent_id,
-      workspace_path: this.workspace_path,
-      store: this.store.session(resolved_session_id),
-      get_session_store: (session_id) => this.store.session(session_id),
+      workspace_path: context.workspace_path,
+      ...(context.workspace_id ? { workspace_id: context.workspace_id } : {}),
+      ...(input?.origin ? { origin: input.origin } : {}),
+      store: context.store.session(resolved_session_id, context.workspace_id),
+      get_session_store: (session_id) => context.store.session(session_id, context.workspace_id),
       session_id: resolved_session_id,
-      tools: this.tools,
-      logger: this.logger,
-      instruction_system_blocks: this.load_instruction_system_blocks(),
-      get_instruction_system_blocks: () => this.load_instruction_system_blocks(),
-      get_workspace_env: () => this.get_workspace_env(),
+      tools: context.tools,
+      logger: context.logger,
+      instruction_system_blocks: this.load_instruction_system_blocks(context.workspace_path),
+      get_instruction_system_blocks: () => this.load_instruction_system_blocks(context.workspace_path),
+      get_workspace_env: () => context.get_workspace_env(),
       get_agent_model: () => this.get_agent_model(),
-      get_agent_plugins: () => this.get_agent_plugins(),
+      get_agent_plugins: () => context.get_agent_plugins(),
       get_managed_plugin_system_blocks: async () => [],
       ensure_configured: async (session) => {
         await this.ensure_agent_ready();
@@ -343,10 +394,10 @@ export class AgentSessions implements AgentSessionsContract<AgentSession> {
     return created;
   }
 
-  private load_instruction_system_blocks(): AgentSessionSystemBlock[] {
+  private load_instruction_system_blocks(workspace_path: string): AgentSessionSystemBlock[] {
     return create_instruction_system_blocks(
       this.get_instruction(),
-      this.workspace_path,
+      workspace_path,
     );
   }
 

package/src/agent/WorkspaceEntry.ts

@@ -0,0 +1,309 @@
+/**
+ * Workspace 执行上下文的内部组合对象。
+ *
+ * 关键点（中文）
+ * - Agent 仍是身份、模型、指令与 Plugin 的唯一拥有者。
+ * - 当前对象只组合 Workspace Tool、Plugin Context、日志与后台资源。
+ * - Session 的所有权属于 Agent.sessions；本对象只提供内部执行上下文。
+ * - 它不是公开领域对象，也不是 AgentWorkspace。
+ */
+
+import type { RuntimeTool as Tool } from "@downcity/type";
+import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { Hono } from "hono";
+import type { WorkspaceShell } from "@downcity/workspace";
+import { AgentSessions } from "@/agent/AgentSessions.js";
+import type { AgentSessionCollection } from "@/types/agent/AgentSessionCollection.js";
+import { create_plugin_context } from "@/plugin/core/PluginContext.js";
+import { register_plugin_http_routes } from "@/plugin/core/PluginHttpRoutes.js";
+import { list_plugin_states } from "@/plugin/core/PluginStateController.js";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
+import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
+import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
+import type { WorkspaceEntryOptions } from "@/types/agent/WorkspaceEntryOptions.js";
+import { Logger } from "@/utils/logger/Logger.js";
+import { generate_id } from "@/utils/Id.js";
+import type { AgentStorage } from "@/types/agent/AgentStorage.js";
+import {
+  resolve_session_system_messages,
+  type SystemProfile,
+} from "@/executor/composer/system/default/SystemDomain.js";
+import { agent_embassy, agent_is_in_city, get_agent_storage, plugin_storage_scope, release_workspace_entry } from "@/internal/AgentRuntime.js";
+
+const RESERVED_PLUGIN_TOOL_NAMES = new Set(["plugin_read", "plugin_call"]);
+
+/** 拒绝普通 Tool 占用 PluginRegistry 的稳定桥接名称。 */
+function assert_no_reserved_plugin_tools(
+  source: Record<string, Tool>,
+  source_name: string,
+): void {
+  for (const tool_name of Object.keys(source)) {
+    if (RESERVED_PLUGIN_TOOL_NAMES.has(tool_name)) {
+      throw new Error(`Agent tool name conflict: "${tool_name}" is reserved for PluginRegistry (${source_name})`);
+    }
+  }
+}
+
+/** 注册 Tool Set，并拒绝不同来源静默覆盖。 */
+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;
+  }
+}
+
+/** Agent 在一个 Workspace 中的内部执行上下文。 */
+export class WorkspaceEntry {
+  /** 拥有当前作用域的 Agent。 */
+  readonly agent: WorkspaceEntryOptions["agent"];
+  /** 当前 Workspace。 */
+  readonly workspace: WorkspaceEntryOptions["workspace"];
+  /** 当前 Workspace ID。 */
+  readonly workspace_id: string;
+  /** 当前 Workspace 下的 Tool 集合。 */
+  readonly tools: Record<string, Tool>;
+  /** 当前 Workspace Context 绑定的 Agent Plugin 调用面。 */
+  readonly plugins: AgentPlugins;
+  /**
+   * 当前 Workspace 的内部 Session 查询视图；实际所有权仍属于 Agent.sessions。
+   * 该视图只供 City transport 和内部测试装配使用，不是新的 Session 所有者。
+   */
+  readonly sessions: AgentSessionCollection;
+  /** 当前 Workspace 的 Session、日志和调度数据根路径。 */
+  readonly data_path: string;
+
+  private readonly context: PluginContext;
+  private readonly logger: Logger;
+  private readonly unsubscribe_env: () => void;
+  private readonly unsubscribe_plugins: () => void;
+  private readonly storage: AgentStorage;
+  private readonly plugin_contexts = new Map<string, PluginContext>();
+  private leave_promise?: Promise<void>;
+
+  constructor(options: WorkspaceEntryOptions) {
+    this.agent = options.agent;
+    this.workspace = options.workspace;
+    this.workspace_id = options.workspace.id;
+    const storage: AgentStorage = get_agent_storage(this.agent);
+    this.storage = storage;
+    this.data_path = storage.root_path;
+    if (!agent_is_in_city(this.agent)) {
+      this.workspace.shell?.bind({
+        root_path: this.workspace.path,
+        // 无 City 时内部状态仍在内存；Shell 的审批/临时文件必须落在真实项目根目录。
+        data_path: this.workspace.path,
+      });
+    }
+    this.logger = new Logger();
+    this.logger.bind_storage(storage.files, storage.root_path, {
+      agent_id: this.agent.id,
+      workspace_id: this.workspace_id,
+    });
+
+    let contextual_plugins: AgentPlugins | undefined;
+    const context_input = {
+      agent_id: this.agent.id,
+      workspace_id: this.workspace_id,
+      workspace_path: this.workspace.path,
+      data_path: this.data_path,
+      files: this.workspace.files,
+      data_files: storage.files,
+      ...(this.workspace.shell ? { shell: this.workspace.shell } : {}),
+      logger: this.logger,
+      embassy: agent_embassy(this.agent),
+      get_workspace_env: () => this.workspace.get_env(),
+      get_instructions: () => this.agent.get_instructions(),
+      get_plugins: () => {
+        if (!contextual_plugins) throw new Error("WorkspaceEntry plugins are not initialized");
+        return contextual_plugins;
+      },
+      get_sessions: () => {
+        return this.agent.sessions;
+      },
+    } satisfies Parameters<typeof create_plugin_context>[0];
+    this.context = create_plugin_context(context_input);
+    this.agent.plugin_registry.bind_workspace_context(
+      this.context,
+      (plugin_name) => this.get_plugin_context(plugin_name, context_input),
+    );
+    contextual_plugins = this.agent.plugin_registry.contextual(this.context);
+    this.plugins = contextual_plugins;
+
+    this.tools = {};
+    assert_no_reserved_plugin_tools(this.workspace.tools, "WorkspaceTools");
+    assert_no_reserved_plugin_tools(this.agent.custom_tools, "AgentOptions.tools");
+    register_tools(this.tools, this.workspace.tools, "WorkspaceTools");
+    register_tools(this.tools, this.agent.plugin_registry.tools(this.context), "PluginRegistry");
+    register_tools(this.tools, this.agent.custom_tools, "AgentOptions.tools");
+
+    this.sessions = {
+      create: async (input) => await this.agent.sessions.create({ ...(input || {}), workspace: this.workspace }),
+      get: async (session_id, input) => await this.agent.sessions.get(session_id, { ...(input || {}), workspace: this.workspace }),
+      list: async (input) => await this.agent.sessions.list({ ...(input || {}), workspace_id: this.workspace_id }),
+      archive: async (input) => {
+        await this.agent.sessions.get(input.id, { workspace: this.workspace });
+        return await this.agent.sessions.archive(input);
+      },
+      archived: async (input) => await this.agent.sessions.archived({ ...(input || {}), workspace_id: this.workspace_id }),
+      clean_archive: async () => await this.agent.sessions.clean_archive(),
+      runtime: (session_id) => this.agent.sessions.runtime(session_id),
+      list_executing_session_ids: () => (this.agent.sessions as AgentSessions).list_executing_session_ids(this.workspace_id),
+      remove: async (session_id) => {
+        await this.agent.sessions.get(session_id, { workspace: this.workspace });
+        return await this.agent.sessions.remove(session_id);
+      },
+      clear_messages: async (session_id) => {
+        await this.agent.sessions.get(session_id, { workspace: this.workspace });
+        return await this.agent.sessions.clear_messages(session_id);
+      },
+    };
+
+    this.unsubscribe_env = this.workspace.subscribe_env((env) => {
+      (this.agent.sessions as AgentSessions).broadcast_env(
+        { ...env },
+        generate_id(),
+        this.workspace_id,
+      );
+    });
+    this.unsubscribe_plugins = this.agent.plugin_registry.subscribe_change((change) => {
+      for (const tool_name of RESERVED_PLUGIN_TOOL_NAMES) delete this.tools[tool_name];
+      register_tools(
+        this.tools,
+        this.agent.plugin_registry.tools(this.context),
+        "PluginRegistry",
+      );
+      const verb = change.type === "register" ? "registered" : "unregistered";
+      (this.agent.sessions as AgentSessions).broadcast_plugins({
+        command_id: generate_id(),
+        title: `Agent plugin ${change.plugin_name} ${verb}`,
+        plugins: this.agent.plugin_registry.execution_view(this.context),
+        workspace_id: this.workspace_id,
+      });
+    });
+  }
+
+  /** 当前 Agent ID。 */
+  get id(): string {
+    return this.agent.id;
+  }
+
+  /** 返回当前 Workspace 的 Shell。 */
+  get_shell(): WorkspaceShell | undefined {
+    return this.workspace.shell;
+  }
+
+  /** 返回当前 Workspace 的日志器。 */
+  get_logger(): Logger {
+    return this.logger;
+  }
+
+  /** 列出当前 Agent 注册的 Plugin 状态。 */
+  list_plugin_states(): PluginSnapshot[] {
+    return list_plugin_states({ context: this.context });
+  }
+
+  /** 将 Plugin HTTP 路由绑定到当前 Workspace Context。 */
+  register_plugin_http_routes(app: Hono): void {
+    register_plugin_http_routes({
+      app,
+      get_context: (plugin_name) => this.agent.plugin_registry.plugin_context(this.context, plugin_name),
+      plugins: this.agent.plugin_registry.snapshots()
+        .map((snapshot) => this.agent.plugin_registry.get(snapshot.name))
+        .filter((plugin) => plugin !== null),
+    });
+  }
+
+  /** 解析指定 Session 当前可见的完整 system messages。 */
+  async resolve_system_messages(input: {
+    session_id: string;
+    profile?: SystemProfile;
+  }): Promise<SessionSystemMessage[]> {
+    return await resolve_session_system_messages({
+      project_root: this.workspace.path,
+      session_id: input.session_id,
+      profile: input.profile || "chat",
+      static_system_prompts: [...this.agent.get_instructions()],
+      context: this.context,
+    });
+  }
+
+  /** 离开当前 Workspace 并释放 Agent 独享的执行资源。 */
+  async leave(): Promise<void> {
+    this.leave_promise ??= (async () => {
+      const errors: unknown[] = [];
+      const cleanup_steps: Array<() => void | Promise<void>> = [
+        () => this.unsubscribe_env(),
+        () => this.unsubscribe_plugins(),
+        async () => await (this.agent.sessions as AgentSessions).stop_executing_sessions(this.workspace_id),
+        () => (this.agent.sessions as AgentSessions).dispose_title_generation(this.workspace_id),
+        async () => await this.logger.save_all_logs(),
+        ...(agent_is_in_city(this.agent) ? [] : [async () => await this.workspace.dispose()]),
+      ];
+      for (const cleanup of cleanup_steps) {
+        try {
+          await cleanup();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      release_workspace_entry(this.agent, this.workspace_id, this);
+      this.agent.plugin_registry.unbind_workspace_context(this.context);
+      if (errors.length > 0) {
+        throw new AggregateError(errors, `WorkspaceEntry cleanup failed: ${this.workspace_id}`);
+      }
+    })();
+    await this.leave_promise;
+  }
+
+  /** 返回当前 Workspace 的 PluginContext，供 Agent 级调度器解析执行上下文。 */
+  get_context(): PluginContext {
+    return this.context;
+  }
+
+  /** 返回单个 Session 创建所需的 Workspace 执行上下文。 */
+  get_session_context(): {
+    workspace_path: string;
+    workspace_id: string;
+    logger: Logger;
+    tools: Record<string, Tool>;
+    get_workspace_env: () => Record<string, string>;
+    get_agent_plugins: () => AgentPluginExecutionRuntime;
+    store: AgentStorage["sessions"];
+  } {
+    return {
+      workspace_path: this.workspace.path,
+      workspace_id: this.workspace_id,
+      logger: this.logger,
+      tools: this.tools,
+      get_workspace_env: () => this.workspace.get_env(),
+      get_agent_plugins: () => this.agent.plugin_registry.execution_view(this.context),
+      store: this.storage.sessions,
+    };
+  }
+
+  /** 返回指定 Plugin 的 Agent 级运行时 Context。 */
+  private get_plugin_context(
+    plugin_name: string,
+    input: Parameters<typeof create_plugin_context>[0],
+  ): PluginContext {
+    const key = String(plugin_name || "").trim();
+    const existing = this.plugin_contexts.get(key);
+    if (existing) return existing;
+    const plugin_scope = plugin_storage_scope(this.agent, key);
+    const plugin_files = plugin_scope.files;
+    const context = create_plugin_context({
+      ...input,
+      data_path: plugin_scope.root_path,
+      data_files: plugin_files,
+    });
+    this.plugin_contexts.set(key, context);
+    return context;
+  }
+}

package/src/agent/index.ts

@@ -0,0 +1,4 @@
+/**
+ * `@downcity/agent/agent` 的 Agent 主体入口。
+ */
+export { Agent } from "./Agent.js";