@downcity/agent 1.1.337 → 1.1.399

package/src/agent/Agent.ts

@@ -1,292 +1,192 @@
 /**
- * Agent：本地 Agent 核心入口与 facade。
+ * Agent：身份、模型、指令与 Plugin 的主体对象。
  *
  * 职责说明（中文）
- * - 对外暴露 `Agent` 这一唯一的本地实例类。
- * - Agent 直接持有自身状态与长期运行时对象，避免额外 Assembly 复制同一批字段。
- * - Session 集合由 `AgentSessions` 管理；长期运行状态由 `AgentState` 管理。
+ * - Agent 不绑定 Workspace；调用方通过 `agent.sessions.create({ workspace })` 选择本次执行环境。
+ * - PluginRegistry 只属于 Agent，所有 Workspace 共享同一份注册定义。
+ * - Session 由 AgentSessions 统一持有；Workspace 只在单个 Session 创建时提供执行资源。
  */
 
-import type { Tool } from "ai";
+import type { RuntimeTool as Tool } from "@downcity/type";
 import type { AgentModel } from "@/agent/AgentModel.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 { WorkspaceBase } from "@/workspace/WorkspaceBase.js";
-import { Logger } from "@/utils/logger/Logger.js";
 import { normalize_instruction_input } from "@/agent/AgentInstructions.js";
-import { AgentSessions } from "@/agent/AgentSessions.js";
-import { AgentState } from "@/agent/AgentState.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 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 {
-  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。
- */
+  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";
+
+/** SDK Agent 主体。 */
 export class Agent {
-  /** 当前 Agent 的稳定标识，用于区分 Session 存储目录与运行时归属。 */
+  /** Agent 的全局稳定标识。 */
   readonly id: string;
 
-  /** 当前 Agent 引用的项目资源与安全边界。 */
-  readonly workspace: WorkspaceBase;
+  /** Agent 默认模型；Session 可以显式覆盖。 */
+  readonly model?: AgentModel;
 
-  /** 当前 Agent 向所有 Session 提供的工具集合。 */
-  readonly tools: Record<string, Tool>;
+  /** Agent 面向用户的 Session 创建入口。 */
+  readonly sessions: AgentSessionCollection;
 
-  /** 当前 Agent 已装配的 Plugin 调用与注册入口。 */
-  readonly plugins: PluginRegistry;
+  /** 当前 Agent 持有的 Web 搜索与文档能力。 */
+  readonly web?: PluginWebServices;
 
-  /** 当前 Agent 的本地 Session 创建、恢复、查询与归档入口。 */
-  readonly sessions: AgentSessions;
-
-  /**
-   * 当前 Agent 持有的默认运行时模型实例。
-   *
-   * 关键点（中文）
-   * - Agent 只持有调用方传入的实例，不负责模型选择、持久化或恢复。
-   * - Session 未设置自己的模型时，执行会回退使用该实例。
-   */
-  readonly model?: AgentModel;
+  /** Agent 注册的唯一 PluginRegistry。 */
+  readonly plugins: PluginRegistry;
 
-  /** 当前 Agent 独享的运行日志器。 */
-  private readonly logger: Logger;
+  /** Agent 自定义 Tool；进入每个 Workspace 时与项目 Tool 合并。 */
+  readonly custom_tools: Record<string, Tool>;
 
-  /** 提供给 Plugin、Session 与宿主集成层共享的 Agent 执行上下文。 */
-  private readonly plugin_context: PluginContext;
+  /** Agent 使用的 Session 类。 */
+  readonly session_class?: AgentSessionConstructor;
 
-  /** 调用方提供的自定义 Session 类；省略时使用 SDK 默认实现。 */
-  private readonly session_class: AgentOptions["session_class"];
+  /** AgentPlugin 的内部访问名，仍指向 Agent 唯一 Registry。 */
+  readonly plugin_registry: PluginRegistry;
 
-  /** 当前 Agent 的长期运行状态与生命周期。 */
-  private readonly state: AgentState;
+  /** Agent 级日志器，不绑定任何 Workspace。 */
+  private readonly logger = new Logger();
 
-  /** 当前 Agent configured instruction 的可变有序集合。 */
-  private instruction: string[];
+  /** 当前 Agent configured instruction。 */
+  private readonly instruction: string[];
 
-  /** 取消 Workspace env 变化订阅的函数。 */
-  private readonly unsubscribe_workspace_env: WorkspaceEnvUnsubscribe;
+  /** Agent 释放状态。 */
+  private dispose_promise?: Promise<void>;
 
-  /** 取消 PluginRegistry 变化订阅的函数。 */
-  private readonly unsubscribe_plugin_change: PluginRegistryUnsubscribe;
+  /** Agent 级 Plugin lifecycle 启动流程。 */
+  private readonly plugin_ready: Promise<unknown>;
 
-  /** 当前由 PluginRegistry 注册到 Agent 的 Tool 名称。 */
-  private readonly plugin_tool_names = new Set<string>();
+  /** Agent 唯一的 Session 集合。 */
+  private readonly session_manager: AgentSessions;
 
   constructor(options: AgentOptions) {
     this.id = String(options.id || "").trim();
     if (!this.id) throw new Error("Agent requires a non-empty id");
-    if (!options.workspace) throw new Error("Agent requires a Workspace");
-    this.workspace = options.workspace;
-
-    this.session_class = options.session_class;
+    initialize_agent_runtime(this);
     this.model = options.model;
-    this.plugins = new PluginRegistry(options.plugins || []);
-    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.web = options.web;
     this.instruction = normalize_instruction_input(options.instruction);
-    const store = this.workspace.bind_agent(this.id);
-
-    this.sessions = new AgentSessions({
+    const agent = this;
+    const agent_plugin_context: AgentPluginContext = Object.freeze({
       agent_id: this.id,
-      workspace_path: this.workspace.path,
-      store,
-      tools: this.tools,
       logger: this.logger,
-      get_instruction: () => this.instruction,
-      get_workspace_env: () => this.workspace.get_env(),
-      get_agent_plugins: () => this.plugins.execution_view(),
-      ensure_agent_ready: async () => {
-        await this.ready();
+      web: this.web,
+      get embassy() {
+        return agent_embassy(agent);
       },
-      get_agent_model: () => this.model,
-      session_class: this.session_class,
+      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.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 () => {},
+      }),
     });
-    this.plugin_context = create_plugin_context({
-      ...(this.workspace.shell ? { shell: this.workspace.shell } : {}),
+    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,
-      workspace_path: this.workspace.path,
-      files: this.workspace.files,
       logger: this.logger,
-      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.plugin_context,
-      plugins: this.plugins,
+      get_instruction: () => [...this.get_instructions()],
+      ensure_agent_ready: async () => { await this.plugin_ready; },
+      get_agent_model: () => this.model,
+      session_class: this.session_class,
+      on_session_routed: () => mark_agent_session_started(agent),
+      resolve_session_context: (workspace) => {
+        if (!workspace) return {
+          workspace_path: ".",
+          logger: this.logger,
+          tools: this.custom_tools,
+          get_workspace_env: () => ({}),
+          get_agent_plugins: no_workspace_plugins,
+          store: session_store,
+        };
+        return create_workspace_entry(this, workspace).get_session_context();
+      },
     });
+    this.sessions = this.session_manager;
   }
 
-  /**
-   * 等待 Agent 持有的长期运行时启动完成。
-   *
-   * 关键点（中文）
-   * - Agent 构造完成即开始启动 plugin lifecycle 与 ActionSchedule。
-   * - 调用方在需要确认运行时就绪时使用，例如启动后立刻读取 plugin 状态。
-   */
-  async ready(): Promise<void> {
-    await this.state.ready();
-  }
-
-  /**
-   * 释放当前 Agent 持有的长期运行时对象。
-   *
-   * 关键点（中文）
-   * - 关闭 plugin lifecycle 与 ActionSchedule 等 Agent 自有资源。
-   * - Workspace 与 Agent 一对一绑定，因此这里同时关闭 Shell 与 Sandbox。
-   * - 不负责任何 transport（RPC / HTTP）；transport 由 `@downcity/server` 自行管理。
-   */
-  async dispose(): Promise<void> {
-    this.unsubscribe_workspace_env();
-    this.unsubscribe_plugin_change();
-    this.sessions.dispose_title_generation();
-    try {
-      await this.state.dispose();
-    } finally {
-      try {
-        await this.logger.save_all_logs();
-      } finally {
-        await this.workspace.dispose();
-      }
-    }
-  }
-
-  /**
-   * 更新当前 SDK Agent 的静态基础指令。
-   */
+  /** 更新 Agent 的静态基础指令。 */
   set_instruction(input: string | string[]): void {
     const next_instruction = normalize_instruction_input(input);
     this.instruction.splice(0, this.instruction.length, ...next_instruction);
   }
 
-  /**
-   * 返回当前 agent 绑定的统一日志器。
-   */
-  get_logger(): Logger {
-    return this.logger;
-  }
-
-  /**
-   * 返回当前 agent 挂载的 Shell。
-   */
-  get_shell(): Shell | undefined {
-    return this.workspace.shell;
-  }
-
-  /** 返回当前 Agent 已配置的静态指令快照。 */
+  /** 返回 Agent 指令快照。 */
   get_instructions(): readonly string[] {
     return [...this.instruction];
   }
 
-  /** 列出当前 Agent 已注册的 Plugin 状态。 */
-  list_plugin_states(): PluginSnapshot[] {
-    return list_plugin_states({ context: this.plugin_context });
+  /** 返回 Agent 级日志器。 */
+  get_logger(): 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 进入的全部 Workspace 与 Agent Plugin。 */
+  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();
+      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);
+      if (errors.length > 0) throw new AggregateError(errors, "Agent dispose failed");
+    })();
+    await this.dispose_promise;
   }
 
-  /** 解析指定 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 级 Plugin 完成启动，供内部运行时使用。 */
+  async ensure_ready(): Promise<void> {
+    await this.plugin_ready;
   }
 
-  /** 将 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/AgentModel.ts

@@ -2,32 +2,32 @@
  * AgentModel：Agent 与 Session 统一使用的运行时模型协议。
  *
  * 关键点（中文）
- * - Agent 与 Session 对外统一接收 AgentModel，executor 内部只处理 AI SDK LanguageModel。
- * - CityModel 自身实现 LanguageModelV3，executor 可以直接调用。
- * - 这里不依赖 @downcity/city，只依赖 @downcity/type 的共享协议。
+ * - Agent 与 Session 对外统一接收 Downcity ModelClient。
+ * - CityModel 自身实现 ModelClient，executor 可以直接调用。
+ * - 这里不依赖 @downcity/agent，只依赖 @downcity/type 的共享协议。
  */
 
 import {
   isCityModel,
+  type ModelClient,
 } from "@downcity/type";
-import type { LanguageModel } from "ai";
 
 /**
  * Agent SDK 可接受的模型输入。
  */
-export type AgentModel = LanguageModel;
+export type AgentModel = ModelClient;
 
 /**
- * 将 Agent 可接受的模型输入归一为 AI SDK LanguageModel。
+ * 将 Agent 可接受的模型输入归一为 Downcity ModelClient。
  */
-export function normalize_agent_model(model: AgentModel): LanguageModel {
+export function normalize_agent_model(model: AgentModel): ModelClient {
   return model;
 }
 
 /**
  * 从 Agent 模型输入读取已声明的上下文窗口。
  *
- * 只有 CityModel 携带可信的模型目录元数据；普通 AI SDK LanguageModel 未声明时返回空。
+ * 只有 CityModel 携带可信的模型目录元数据；其它 ModelClient 未声明时返回空。
  */
 export function read_agent_model_context_window(
   model: AgentModel | undefined,
@@ -46,7 +46,7 @@ export function infer_agent_model_label(model: AgentModel | undefined): string |
   if (!model) return undefined;
   if (isCityModel(model)) return model.name || model.id;
   if (typeof model !== "object") return undefined;
-  const record = model as Record<string, unknown>;
+  const record = model as unknown as Record<string, unknown>;
   const candidates = [
     record.modelId,
     record.model,