@downcity/agent 1.1.287 → 1.1.310

package/src/agent/Agent.ts

@@ -9,16 +9,46 @@
 
 import type { Tool } from "ai";
 import type { AgentModel } from "@/agent/AgentModel.js";
-import { AgentContext } from "@/agent/AgentContext.js";
+import { create_plugin_context } from "@/plugin/core/PluginContext.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 import type { AgentOptions } from "@/types/agent/AgentOptions.js";
 import type { Shell } from "@downcity/shell";
+import type { Workspace } from "@/workspace/Workspace.js";
 import { Logger } from "@/utils/logger/Logger.js";
-import { resolve_agent_env } from "@/config/AgentEnv.js";
-import { normalizeInstructionInput } from "@/agent/AgentInstructions.js";
+import { normalize_instruction_input } from "@/agent/AgentInstructions.js";
 import { AgentSessions } from "@/agent/AgentSessions.js";
 import { AgentState } from "@/agent/AgentState.js";
-import { generateId } from "@/utils/Id.js";
+import { generate_id } from "@/utils/Id.js";
 import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
+import type { PluginRegistryUnsubscribe } from "@/types/plugin/PluginRegistry.js";
+import type { WorkspaceEnvUnsubscribe } from "@/types/workspace/WorkspaceEnv.js";
+import type { Hono } from "hono";
+import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
+import { list_plugin_states } from "@/plugin/core/PluginStateController.js";
+import { register_plugin_http_routes } from "@/plugin/core/PluginHttpRoutes.js";
+import {
+  resolve_session_system_messages,
+  type SystemProfile,
+} from "@/executor/composer/system/default/SystemDomain.js";
+import type { SystemModelMessage } from "ai";
+
+const RESERVED_PLUGIN_TOOL_NAMES = new Set(["plugin_read", "plugin_call"]);
+
+/** 将一个来源明确的 Tool Set 注册到 Agent，并拒绝静默覆盖。 */
+function register_agent_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;
+  }
+}
 
 /**
  * SDK 本地 Agent。
@@ -27,8 +57,8 @@ export class Agent {
   /** 当前 Agent 的稳定标识，用于区分 Session 存储目录与运行时归属。 */
   readonly id: string;
 
-  /** 当前 Agent 绑定的项目根目录绝对路径。 */
-  readonly path: string;
+  /** 当前 Agent 引用的项目资源与安全边界。 */
+  readonly workspace: Workspace;
 
   /** 当前 Agent 向所有 Session 提供的工具集合。 */
   readonly tools: Record<string, Tool>;
@@ -52,83 +82,105 @@ export class Agent {
   private readonly logger: Logger;
 
   /** 提供给 Plugin、Session 与宿主集成层共享的 Agent 执行上下文。 */
-  private readonly context: AgentContext;
-
-  /** 当前 Agent configured env 的可变共享对象。 */
-  private readonly env: Record<string, string>;
+  private readonly plugin_context: PluginContext;
 
   /** 调用方提供的自定义 Session 类；省略时使用 SDK 默认实现。 */
-  private readonly SessionClass: AgentOptions["Session"];
+  private readonly session_class: AgentOptions["session_class"];
 
   /** 当前 Agent 的长期运行状态与生命周期。 */
   private readonly state: AgentState;
 
-  /** 当前 Agent 可选的内建 Shell 实例。 */
-  private readonly shell?: AgentOptions["shell"];
-
   /** 当前 Agent configured instruction 的可变有序集合。 */
   private instruction: string[];
 
+  /** 取消 Workspace env 变化订阅的函数。 */
+  private readonly unsubscribe_workspace_env: WorkspaceEnvUnsubscribe;
+
+  /** 取消 PluginRegistry 变化订阅的函数。 */
+  private readonly unsubscribe_plugin_change: PluginRegistryUnsubscribe;
+
+  /** 当前由 PluginRegistry 注册到 Agent 的 Tool 名称。 */
+  private readonly plugin_tool_names = new Set<string>();
+
   constructor(options: AgentOptions) {
     this.id = String(options.id || "").trim();
-    this.path = String(options.path || "").trim();
     if (!this.id) throw new Error("Agent requires a non-empty id");
-    if (!this.path) throw new Error("Agent requires a non-empty path");
+    if (!options.workspace) throw new Error("Agent requires a Workspace");
+    this.workspace = options.workspace;
 
-    this.SessionClass = options.Session;
+    this.session_class = options.session_class;
     this.model = options.model;
-    this.tools = options.tools && typeof options.tools === "object"
-      ? { ...options.tools }
-      : {};
-    this.logger = new Logger();
-    this.logger.bindProjectRoot(this.path);
-    this.env = resolve_agent_env(this.path, options.env);
-    this.instruction = normalizeInstructionInput(options.instruction);
-    this.shell = options.shell;
-
     this.plugins = new PluginRegistry(options.plugins || []);
-    if (this.shell) {
-      this.shell.configure({
-        root_path: this.path,
-        env: this.env,
-        agent_id: this.id,
-        logger: this.logger,
-      });
-      Object.assign(this.tools, this.shell.tools);
+    this.tools = {};
+    for (const tool_name of Object.keys(this.workspace.tools)) {
+      if (RESERVED_PLUGIN_TOOL_NAMES.has(tool_name)) {
+        throw new Error(
+          `Agent tool name conflict: "${tool_name}" is reserved for PluginRegistry`,
+        );
+      }
+    }
+    register_agent_tools(this.tools, this.workspace.tools, "WorkspaceTools");
+    this.sync_plugin_tools();
+    const custom_tools = options.tools && typeof options.tools === "object"
+      ? options.tools
+      : {};
+    for (const tool_name of Object.keys(custom_tools)) {
+      if (RESERVED_PLUGIN_TOOL_NAMES.has(tool_name)) {
+        throw new Error(
+          `Agent tool name conflict: "${tool_name}" is reserved for PluginRegistry`,
+        );
+      }
     }
+    register_agent_tools(this.tools, custom_tools, "AgentOptions.tools");
+    this.logger = new Logger();
+    this.logger.bind_workspace(this.workspace.files);
+    this.instruction = normalize_instruction_input(options.instruction);
+    const store = this.workspace.bind_agent(this.id);
 
     this.sessions = new AgentSessions({
       agent_id: this.id,
-      project_root: this.path,
+      workspace_path: this.workspace.path,
+      store,
       tools: this.tools,
       logger: this.logger,
       get_instruction: () => this.instruction,
-      get_agent_env: () => this.getEnv(),
+      get_workspace_env: () => this.workspace.get_env(),
       get_agent_plugins: () => this.plugins.execution_view(),
       ensure_agent_ready: async () => {
         await this.ready();
       },
       get_agent_model: () => this.model,
-      SessionClass: this.SessionClass,
+      session_class: this.session_class,
     });
-    this.context = new AgentContext({
-      ...(this.shell ? { shell: this.shell } : {}),
+    this.plugin_context = create_plugin_context({
+      ...(this.workspace.shell ? { shell: this.workspace.shell } : {}),
       agent_id: this.id,
-      rootPath: this.path,
+      workspace_path: this.workspace.path,
+      files: this.workspace.files,
       logger: this.logger,
-      get_env: () => this.env,
-      get_systems: () => this.instruction,
+      get_workspace_env: () => this.workspace.get_env(),
+      get_instructions: () => this.instruction,
       sessions: this.sessions,
       plugins: this.plugins,
     });
 
+    this.unsubscribe_workspace_env = this.workspace.subscribe_env((env) => {
+      this.sessions.broadcast_env({ ...env }, generate_id());
+    });
+    this.unsubscribe_plugin_change = this.plugins.subscribe_change((change) => {
+      this.sync_plugin_tools();
+      const verb = change.type === "register" ? "registered" : "unregistered";
+      this.sessions.broadcast_plugins({
+        command_id: generate_id(),
+        title: `Agent plugin ${change.plugin_name} ${verb}`,
+        plugins: this.plugins.execution_view(),
+      });
+    });
+
     // 关键点（中文）：装配完成后创建唯一状态对象，并立即启动长期运行时。
     this.state = new AgentState({
-      context: this.context,
+      context: this.plugin_context,
       plugins: this.plugins,
-      sessions: this.sessions,
-      tools: this.tools,
-      shell: this.shell,
     });
   }
 
@@ -147,95 +199,93 @@ export class Agent {
    * 释放当前 Agent 持有的长期运行时对象。
    *
    * 关键点（中文）
-   * - 关闭 plugin lifecycle、ActionSchedule、shell 等 Agent 自有资源。
+   * - 关闭 plugin lifecycle 与 ActionSchedule 等 Agent 自有资源。
+   * - Workspace 与 Agent 一对一绑定，因此这里同时关闭 Shell 与 Sandbox。
    * - 不负责任何 transport（RPC / HTTP）；transport 由 `@downcity/server` 自行管理。
    */
   async dispose(): Promise<void> {
-    await this.state.dispose();
+    this.unsubscribe_workspace_env();
+    this.unsubscribe_plugin_change();
+    try {
+      await this.state.dispose();
+    } finally {
+      try {
+        await this.logger.save_all_logs();
+      } finally {
+        await this.workspace.dispose();
+      }
+    }
   }
 
   /**
    * 更新当前 SDK Agent 的静态基础指令。
    */
-  setInstruction(input: string | string[]): void {
-    const next_instruction = normalizeInstructionInput(input);
+  set_instruction(input: string | string[]): void {
+    const next_instruction = normalize_instruction_input(input);
     this.instruction.splice(0, this.instruction.length, ...next_instruction);
   }
 
   /**
-   * 返回当前 agent env 的浅拷贝快照。
-   *
-   * 关键点（中文）
-   * - 返回的是拷贝，调用方修改它不会影响 agent 真实状态。
-   * - 想改 env 请使用 `setEnv` / `patchEnv`。
+   * 返回当前 agent 绑定的统一日志器。
    */
-  getEnv(): Record<string, string> {
-    return { ...this.env };
+  get_logger(): Logger {
+    return this.logger;
   }
 
   /**
-   * 整体覆盖 agent env。
-   *
-   * 关键点（中文）
-   * - 直接清空当前共享 env 对象，再写入新值，保证 plugin / runtime / shell 看到的是同一引用。
-   * - 仅写入字符串值，`null` / `undefined` 表示删除该 key。
+   * 返回当前 agent 挂载的 Shell。
    */
-  setEnv(next: Record<string, string | null | undefined>): void {
-    for (const key of Object.keys(this.env)) {
-      delete this.env[key];
-    }
-    this.apply_env_patch(next);
-    this.sessions.broadcast_env(this.env, generateId());
+  get_shell(): Shell | undefined {
+    return this.workspace.shell;
   }
 
-  /**
-   * 增量合并 agent env。
-   *
-   * 关键点（中文）
-   * - `null` / `undefined` 表示删除该 key；其他值会强制转字符串后写入。
-   * - configured env 原地更新；已有 Session 在下一 step 检查点提交 effective env。
-   */
-  patchEnv(patch: Record<string, string | null | undefined>): void {
-    this.apply_env_patch(patch);
-    this.sessions.broadcast_env(this.env, generateId());
+  /** 返回当前 Agent 已配置的静态指令快照。 */
+  get_instructions(): readonly string[] {
+    return [...this.instruction];
   }
 
-  /**
-   * 原地应用一次 env patch，不触发重复广播。
-   */
-  private apply_env_patch(
-    patch: Record<string, string | null | undefined>,
-  ): void {
-    if (!patch || typeof patch !== "object") return;
-    for (const [raw_key, raw_value] of Object.entries(patch)) {
-      const key = String(raw_key || "").trim();
-      if (!key) continue;
-      if (raw_value === null || raw_value === undefined) {
-        delete this.env[key];
-        continue;
-      }
-      this.env[key] = String(raw_value);
-    }
+  /** 列出当前 Agent 已注册的 Plugin 状态。 */
+  list_plugin_states(): PluginSnapshot[] {
+    return list_plugin_states({ context: this.plugin_context });
   }
 
-  /**
-   * 返回当前 agent 绑定的统一日志器。
-   */
-  getLogger(): Logger {
-    return this.logger;
+  /** 把当前 Agent 已注册 Plugin 的 HTTP 路由装配到宿主应用。 */
+  register_plugin_http_routes(app: Hono): void {
+    register_plugin_http_routes({
+      app,
+      get_context: () => this.plugin_context,
+      plugins: this.plugins.snapshots()
+        .map((snapshot) => this.plugins.get(snapshot.name))
+        .filter((plugin) => plugin !== null),
+    });
   }
 
-  /**
-   * 返回当前 agent context。
-   */
-  getContext(): AgentContext {
-    return this.context;
+  /** 解析指定 Session 当前可见的完整 system messages。 */
+  async resolve_system_messages(input: {
+    /** 需要解析 system 的 Session 标识。 */
+    session_id: string;
+    /** system 组合档位；省略时使用 chat。 */
+    profile?: SystemProfile;
+  }): Promise<SystemModelMessage[]> {
+    return await resolve_session_system_messages({
+      project_root: this.workspace.path,
+      session_id: input.session_id,
+      profile: input.profile || "chat",
+      static_system_prompts: [...this.instruction],
+      context: this.plugin_context,
+    });
   }
 
-  /**
-   * 返回当前 agent 挂载的 Shell。
-   */
-  getShell(): Shell | undefined {
-    return this.shell;
+  /** 将 PluginRegistry 当前 Tool Set 同步到 Agent 持有的工具集合。 */
+  private sync_plugin_tools(): void {
+    for (const tool_name of this.plugin_tool_names) {
+      delete this.tools[tool_name];
+    }
+    this.plugin_tool_names.clear();
+    const plugin_tools = this.plugins.tools();
+    register_agent_tools(this.tools, plugin_tools, "PluginRegistry");
+    for (const tool_name of Object.keys(plugin_tools)) {
+      this.plugin_tool_names.add(tool_name);
+    }
   }
 }

package/src/agent/AgentInstructions.ts

@@ -13,7 +13,7 @@ import { DEFAULT_SHIP_PROMPTS } from "@executor/composer/system/default/SystemDo
 /**
  * 归一化调用方传入的静态 instruction。
  */
-export function normalizeInstructionInput(
+export function normalize_instruction_input(
   input: string | string[] | undefined,
 ): string[] {
   const items = Array.isArray(input)
@@ -37,7 +37,7 @@ function createCoreInstructionContent(project_root: string): string {
 /**
  * 构造进入 session system prompt 的 instruction block。
  */
-export function createInstructionSystemBlocks(
+export function create_instruction_system_blocks(
   instruction: string[],
   project_root: string,
 ): AgentSessionSystemBlock[] {

package/src/agent/AgentModel.ts

@@ -20,7 +20,7 @@ export type AgentModel = LanguageModel;
 /**
  * 将 Agent 可接受的模型输入归一为 AI SDK LanguageModel。
  */
-export function normalizeAgentModel(model: AgentModel): LanguageModel {
+export function normalize_agent_model(model: AgentModel): LanguageModel {
   return model;
 }
 
@@ -42,7 +42,7 @@ export function read_agent_model_context_window(
 /**
  * 从 Agent 模型输入推导展示标签。
  */
-export function inferAgentModelLabel(model: AgentModel | undefined): string | undefined {
+export function infer_agent_model_label(model: AgentModel | undefined): string | undefined {
   if (!model) return undefined;
   if (isCityModel(model)) return model.name || model.id;
   if (typeof model !== "object") return undefined;