@downcity/agent 1.1.237 → 1.1.258

package/src/agent/local/Agent.ts

@@ -1,250 +0,0 @@
-/**
- * Agent local：本地入口与 facade。
- *
- * 职责说明（中文）
- * - 对外暴露 `Agent` 这一唯一的本地实例类。
- * - facade 只保留公开 API 与 service 组合，不再直接承载装配、session 管理与生命周期细节。
- * - 单个 agent 的长期对象装配、session 管理、后台能力生命周期分别下沉到独立 service。
- */
-
-import type { Tool } from "ai";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
-import type { AgentModel } from "@/model/CityModelAdapter.js";
-import type { AgentOptions } from "@/types/agent/AgentOptions.js";
-import type { AgentSessions as AgentSessionsApi } from "@/types/agent/SessionActor.js";
-import type {
-  Shell,
-} from "@downcity/shell";
-import { Logger } from "@/utils/logger/Logger.js";
-import { normalizeInstructionInput } from "@/agent/local/AgentInstructions.js";
-import {
-  AgentAssemblyService,
-  type AgentAssemblyResult,
-} from "@/agent/local/services/AgentAssemblyService.js";
-import { AgentSessions as LocalAgentSessions } from "@/agent/local/services/AgentSessions.js";
-import { AgentBackgroundService } from "@/agent/local/services/AgentBackgroundService.js";
-import { generateId } from "@/utils/Id.js";
-import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
-
-/**
- * SDK 本地 Agent。
- */
-export class Agent {
-  readonly id: string;
-  readonly path: string;
-  readonly tools: Record<string, Tool>;
-  readonly plugins: AgentPlugins;
-  readonly sessions: AgentSessionsApi;
-
-  private readonly logger: Logger;
-  private readonly agentContext: AgentContext;
-  private readonly config: DowncityConfig;
-  private readonly env: Record<string, string>;
-  private readonly defaultModel?: AgentModel;
-  private readonly default_model_id?: string;
-  private readonly resolve_model?: AgentOptions["resolve_model"];
-  private readonly SessionClass: AgentOptions["Session"];
-  private readonly backgroundService: AgentBackgroundService;
-  private readonly shell?: AgentOptions["shell"];
-  private readonly local_sessions: LocalAgentSessions;
-
-  private instruction: string[];
-
-  constructor(options: AgentOptions) {
-    this.defaultModel = options.model;
-    this.default_model_id = String(options.model_id || "").trim() || undefined;
-    this.resolve_model = options.resolve_model;
-    this.SessionClass = options.Session;
-    let sessions_ref: LocalAgentSessions | null = null;
-    const assembly_service = new AgentAssemblyService({
-      options,
-      list_cached_sessions: () => sessions_ref?.list_cached_sessions() || [],
-      get_session_port: (session_id) => {
-        if (!sessions_ref) {
-          throw new Error("Agent sessions are not initialized");
-        }
-        return sessions_ref.get_session_port(session_id);
-      },
-      resolve_session_model: async (session_id) => {
-        if (!sessions_ref) return undefined;
-        const session = await sessions_ref.get(session_id);
-        return session.config.model;
-      },
-    });
-    const assembly = assembly_service.assemble();
-
-    this.id = assembly.id;
-    this.path = assembly.path;
-    this.tools = assembly.tools;
-    this.plugins = assembly.plugins;
-    this.logger = assembly.logger;
-    this.agentContext = assembly.agent_context;
-    this.config = assembly.config;
-    this.env = assembly.env;
-    this.instruction = assembly.instruction;
-    this.shell = assembly.shell;
-
-    // 关键点（中文）：构造完成即触发后台能力启动；调用方可 `await agent.ready()` 等待。
-    this.backgroundService = new AgentBackgroundService({
-      logger: this.logger,
-      agent_context: this.agentContext,
-      get_shell: () => this.shell,
-    });
-    const sessions = this.create_sessions(assembly);
-    this.sessions = sessions;
-    this.local_sessions = sessions;
-    sessions_ref = sessions;
-    if (this.plugins instanceof PluginRegistry) {
-      const plugin_registry = this.plugins;
-      plugin_registry.set_change_listener(({ type, plugin_name }) => {
-        const verb = type === "register" ? "registered" : "unregistered";
-        this.local_sessions.broadcast_plugins({
-          command_id: generateId(),
-          title: `Agent plugin ${plugin_name} ${verb}`,
-          plugins: plugin_registry.execution_view(),
-        });
-      });
-    }
-  }
-
-  /**
-   * 等待 Agent 后台能力启动完成。
-   *
-   * 关键点（中文）
-   * - Agent 构造完成即开始启动 plugin lifecycle 与 ActionSchedule。
-   * - 调用方在需要确认后台能力就绪时使用，例如启动后立刻读取 plugin 状态。
-   */
-  async ready(): Promise<void> {
-    await this.backgroundService.ready();
-  }
-
-  /**
-   * 释放当前 Agent 的后台能力。
-   *
-   * 关键点（中文）
-   * - 关闭 plugin lifecycle、ActionSchedule、shell 等后台资源。
-   * - 不负责任何 transport（RPC / HTTP）；transport 由 `@downcity/server` 自行管理。
-   */
-  async dispose(): Promise<void> {
-    await this.backgroundService.dispose();
-  }
-
-  /**
-   * 更新当前 SDK Agent 的静态基础指令。
-   */
-  setInstruction(input: string | string[]): void {
-    const next_instruction = normalizeInstructionInput(input);
-    this.instruction.splice(0, this.instruction.length, ...next_instruction);
-    this.local_sessions.broadcast_instruction(this.instruction, generateId());
-  }
-
-  /**
-   * 返回当前 agent env 的浅拷贝快照。
-   *
-   * 关键点（中文）
-   * - 返回的是拷贝，调用方修改它不会影响 agent 真实状态。
-   * - 想改 env 请使用 `setEnv` / `patchEnv`。
-   */
-  getEnv(): Record<string, string> {
-    return { ...this.env };
-  }
-
-  /**
-   * 整体覆盖 agent env。
-   *
-   * 关键点（中文）
-   * - 直接清空当前共享 env 对象，再写入新值，保证 plugin / runtime / shell 看到的是同一引用。
-   * - 仅写入字符串值，`null` / `undefined` 表示删除该 key。
-   */
-  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.local_sessions.broadcast_env(this.env, generateId());
-  }
-
-  /**
-   * 增量合并 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.local_sessions.broadcast_env(this.env, generateId());
-  }
-
-  /**
-   * 原地应用一次 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);
-    }
-  }
-
-  /**
-   * 返回当前项目根目录解析后的配置快照。
-   */
-  getConfig(): DowncityConfig {
-    return this.config;
-  }
-
-  /**
-   * 返回当前 agent 绑定的统一日志器。
-   */
-  getLogger(): Logger {
-    return this.logger;
-  }
-
-  /**
-   * 返回当前 agent context。
-   */
-  getContext(): AgentContext {
-    return this.agentContext;
-  }
-
-  /**
-   * 返回当前 agent 挂载的 Shell。
-   */
-  getShell(): Shell | undefined {
-    return this.shell;
-  }
-
-  private create_sessions(
-    assembly: AgentAssemblyResult,
-  ): LocalAgentSessions {
-    return new LocalAgentSessions({
-      agent_id: this.id || assembly.id,
-      project_root: this.path || assembly.path,
-      tools: this.tools || assembly.tools,
-      logger: this.logger || assembly.logger,
-      get_agent_context: () => this.agentContext ?? assembly.agent_context,
-      get_shell: () => this.shell,
-      get_instruction: () => this.instruction,
-      get_agent_env: () => this.getEnv(),
-      get_agent_plugins: () =>
-        (this.plugins as PluginRegistry).execution_view(),
-      ensure_agent_ready: async () => {
-        await this.backgroundService.ready();
-      },
-      default_model: this.defaultModel,
-      default_model_id: this.default_model_id,
-      resolve_model: this.resolve_model,
-      SessionClass: this.SessionClass,
-    });
-  }
-}

package/src/agent/local/AgentPluginFactory.ts

@@ -1,51 +0,0 @@
-/**
- * Agent plugin 装配工厂。
- *
- * 关键点（中文）
- * - 这里只负责把 plugin 实例装配成 registry。
- * - Agent 仍然持有长期状态；这里不创建新的运行时层级。
- */
-
-import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import { HookRegistry } from "@/plugin/core/HookRegistry.js";
-import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
-
-/**
- * 创建 plugin registry 的参数。
- */
-export interface CreateAgentPluginRegistryOptions {
-  /** 当前 agent 显式注册的 plugin 实例。 */
-  plugins: Plugin[];
-  /** 当前 agent plugin 实例集合。 */
-  plugin_instances: Map<string, Plugin>;
-  /** 延迟读取当前 AgentContext。 */
-  get_context: () => AgentContext;
-}
-
-/**
- * 创建 plugin 注册表。
- */
-export function createAgentPluginRegistry(
-  options: CreateAgentPluginRegistryOptions,
-): PluginRegistry {
-  let plugin_registry_ref: PluginRegistry | null = null;
-  const hook_registry = new HookRegistry({
-    contextResolver: options.get_context,
-    pluginEnabledChecker: (plugin_name) => {
-      void options;
-      return plugin_registry_ref?.isReady(plugin_name) || false;
-    },
-  });
-  const registry = new PluginRegistry({
-    contextResolver: options.get_context,
-    hookRegistry: hook_registry,
-    pluginInstances: options.plugin_instances,
-  });
-  plugin_registry_ref = registry;
-
-  for (const plugin of options.plugins) {
-    registry.mount(plugin);
-  }
-  return registry;
-}

package/src/agent/local/AgentRuntimeAssembly.ts

@@ -1,65 +0,0 @@
-/**
- * AgentRuntimeAssembly：装配本地 AgentRuntime 能力。
- *
- * 关键点（中文）
- * - agent runtime 负责创建这些宿主能力对象，再注入到 AgentRuntime。
- * - plugin runtime / session / plugin 作者 API 只消费这些对象，不直接依赖具体宿主实现。
- * - 当前先收敛路径与 plugin 配置持久化两类宿主能力。
- * - SDK 默认不提供 plugin 配置存储；宿主必须显式注入持久化能力。
- */
-import {
-  getCacheDirPath,
-  getDowncityChannelDirPath,
-  getDowncityChannelMetaPath,
-  getDowncityChatHistoryPath,
-  getDowncityDirPath,
-  getDowncityMemoryDailyDirPath,
-  getDowncityMemoryDailyPath,
-  getDowncityMemoryLongTermPath,
-  getDowncitySessionDirPath,
-  getDowncitySessionRootDirPath,
-} from "@/config/Paths.js";
-import type {
-  AgentPathRuntime,
-  AgentPluginConfigRuntime,
-} from "@/types/agent/AgentRuntimeAssembly.js";
-
-/**
- * 创建当前项目的路径能力集合。
- */
-export function createAgentPathRuntime(
-  projectRoot: string,
-  agentIdInput: string,
-): AgentPathRuntime {
-  const rootPath = String(projectRoot || "").trim();
-  const agentId = String(agentIdInput || "").trim();
-  return {
-    projectRoot: rootPath,
-    agentId,
-    getDowncityDirPath: () => getDowncityDirPath(rootPath),
-    getCacheDirPath: () => getCacheDirPath(rootPath),
-    getDowncityChannelDirPath: () => getDowncityChannelDirPath(rootPath),
-    getDowncityChannelMetaPath: () => getDowncityChannelMetaPath(rootPath),
-    getDowncityChatHistoryPath: (sessionId) => getDowncityChatHistoryPath(rootPath, sessionId),
-    getDowncityMemoryLongTermPath: () => getDowncityMemoryLongTermPath(rootPath),
-    getDowncityMemoryDailyDirPath: () => getDowncityMemoryDailyDirPath(rootPath),
-    getDowncityMemoryDailyPath: (date) => getDowncityMemoryDailyPath(rootPath, date),
-    getDowncitySessionRootDirPath: () => getDowncitySessionRootDirPath(rootPath, agentId),
-    getDowncitySessionDirPath: (sessionId) =>
-      getDowncitySessionDirPath(rootPath, agentId, sessionId),
-  };
-}
-
-/**
- * 创建 plugin 配置持久化能力集合。
- */
-export function createAgentPluginConfigRuntime(projectRoot: string): AgentPluginConfigRuntime {
-  const rootPath = String(projectRoot || "").trim();
-  return {
-    async persistProjectPlugins(): Promise<string> {
-      throw new Error(
-        "Plugin config persistence is not configured. Pass AgentOptions.plugin_config from the host.",
-      );
-    },
-  };
-}

package/src/agent/local/services/AgentAssemblyService.ts

@@ -1,307 +0,0 @@
-/**
- * AgentAssemblyService：本地 Agent 装配服务。
- *
- * 关键点（中文）
- * - 统一装配 logger、config、env、context 与 plugin registry。
- * - 该服务只负责一次性长期对象装配，不负责 session 缓存和生命周期启动。
- * - session/lifecycle service 通过它暴露的长期对象协作，避免在 facade 中重复拼装。
- */
-
-import type { LanguageModel, Tool } from "ai";
-import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
-import type { AgentOptions } from "@/types/agent/AgentOptions.js";
-import { Logger } from "@/utils/logger/Logger.js";
-import { resolve_agent_env } from "@/config/AgentEnv.js";
-import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
-import {
-  createFallbackSdkConfig,
-  normalizeInstructionInput,
-} from "@/agent/local/AgentInstructions.js";
-import {
-  createAgentPluginRegistry,
-} from "@/agent/local/AgentPluginFactory.js";
-import {
-  createAgentPathRuntime,
-  createAgentPluginConfigRuntime,
-} from "@/agent/local/AgentRuntimeAssembly.js";
-import {
-  createPluginTools,
-} from "@executor/tools/plugin/PluginToolDefinition.js";
-import type { AgentManagedSession } from "@/types/session/SessionOptions.js";
-import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
-import type { SessionApprovalRuntimeEvent } from "@/types/session/SessionApproval.js";
-
-type AgentAssemblyServiceOptions = {
-  /**
-   * 当前 agent 构造参数。
-   */
-  options: AgentOptions;
-
-  /**
-   * 读取当前已缓存的 session 实例。
-   */
-  list_cached_sessions: () => AgentManagedSession[];
-
-  /**
-   * 获取或创建 session runtime port。
-   */
-  get_session_port: (session_id: string) => SessionPort;
-
-  /**
-   * 解析指定 session 当前绑定的模型实例。
-   */
-  resolve_session_model: (
-    session_id: string,
-  ) => Promise<LanguageModel | undefined>;
-};
-
-/**
- * 本地 Agent 装配结果。
- */
-export interface AgentAssemblyResult {
-  /**
-   * 当前 agent 稳定标识。
-   */
-  id: string;
-
-  /**
-   * 当前项目根目录。
-   */
-  path: string;
-
-  /**
-   * 当前 agent 默认工具集合。
-   */
-  tools: Record<string, Tool>;
-
-  /**
-   * 当前 agent 统一日志器。
-   */
-  logger: Logger;
-
-  /**
-   * 当前 agent 环境变量快照。
-   */
-  env: Record<string, string>;
-
-  /**
-   * 当前 agent 静态 instruction。
-   */
-  instruction: string[];
-
-  /**
-   * 当前解析后的项目配置。
-   */
-  config: DowncityConfig;
-
-  /**
-   * 当前 plugin 实例集合。
-   */
-  plugin_instances: Map<string, Plugin>;
-
-  /**
-   * 当前 agent plugin 调用面。
-   */
-  plugins: AgentPlugins;
-
-  /**
-   * 当前 agent context。
-   */
-  agent_context: AgentContext;
-
-  /**
-   * 当前 agent 挂载的内建 shell。
-   */
-  shell?: AgentOptions["shell"];
-}
-
-/**
- * 本地 Agent 装配服务。
- */
-export class AgentAssemblyService {
-  private readonly options: AgentOptions;
-  private readonly list_cached_sessions: AgentAssemblyServiceOptions["list_cached_sessions"];
-  private readonly get_session_port: AgentAssemblyServiceOptions["get_session_port"];
-  private readonly resolve_session_model: AgentAssemblyServiceOptions["resolve_session_model"];
-
-  constructor(options: AgentAssemblyServiceOptions) {
-    this.options = options.options;
-    this.list_cached_sessions = options.list_cached_sessions;
-    this.get_session_port = options.get_session_port;
-    this.resolve_session_model = options.resolve_session_model;
-  }
-
-  /**
-   * 执行一次性长期对象装配。
-   */
-  assemble(): AgentAssemblyResult {
-    const id = String(this.options.id || "").trim();
-    const path = String(this.options.path || "").trim();
-    const tools =
-      this.options.tools && typeof this.options.tools === "object"
-        ? { ...this.options.tools }
-        : {};
-    if (!id) {
-      throw new Error("Agent requires a non-empty id");
-    }
-    if (!path) {
-      throw new Error("Agent requires a non-empty path");
-    }
-
-    const logger = new Logger();
-    logger.bindProjectRoot(path);
-    // 关键点（中文）
-    // - 这里产出的 env 是 agent 全生命周期共享的 mutable 对象引用。
-    // - context / shell 都持有同一引用；后续 `agent.setEnv()` 会原地修改它。
-    const env = resolve_agent_env(path, this.options.env);
-    const instruction = normalizeInstructionInput(this.options.instruction);
-    const config = this.load_config(id);
-    const plugin_instances = new Map<string, Plugin>();
-
-    // 关键点（中文）
-    // - plugin_registry 仍然延迟读取 agent_context（避免循环依赖）。
-    // - context 一构造完就赋值，registry 第一次读 get_context 时已经是非空。
-    let agent_context: AgentContext | undefined;
-    const plugin_registry = createAgentPluginRegistry({
-      plugins: this.options.plugins || [],
-      plugin_instances,
-      get_context: () => {
-        if (!agent_context) {
-          throw new Error("AgentContext is not assembled yet");
-        }
-        return agent_context;
-      },
-    });
-    const plugins = plugin_registry;
-    if (this.should_register_plugin_call_tool(plugin_instances)) {
-      const plugin_tools = createPluginTools({ plugins });
-      tools.plugin_read = tools.plugin_read || plugin_tools.plugin_read;
-      tools.plugin_call = tools.plugin_call || plugin_tools.plugin_call;
-    }
-    const resolve_session_model = this.resolve_session_model;
-    const paths = createAgentPathRuntime(path, id);
-    const pluginConfig = this.options.plugin_config || createAgentPluginConfigRuntime(path);
-    agent_context = new AgentContext({
-      cwd: path,
-      rootPath: path,
-      logger,
-      config,
-      env,
-      systems: instruction,
-      paths,
-      pluginConfig,
-      pluginInstances: plugin_instances,
-      session: {
-        get: (session_id) => this.get_session_port(session_id),
-        listExecutingSessionIds: () =>
-          this.list_cached_sessions()
-            .filter((session) => session.isExecuting())
-            .map((session) => session.id),
-        getExecutingSessionCount: () =>
-          this.list_cached_sessions()
-            .filter((session) => session.isExecuting()).length,
-        resolveModel: async (session_id) =>
-          await resolve_session_model(session_id),
-      },
-      plugins,
-    });
-    const shell = this.options.shell;
-    if (shell) {
-      shell.configure({
-        root_path: path,
-        env,
-        agent_id: id,
-        logger,
-        emit_event: async (event) => {
-          const session_id = String(event.session_id || "").trim();
-          if (!session_id) return;
-          const approval_event = normalize_approval_runtime_event(event);
-          if (!approval_event) return;
-          await agent_context!.session.get(session_id).publishEvent(approval_event);
-        },
-      });
-      Object.assign(tools, shell.tools);
-    }
-
-    return {
-      id,
-      path,
-      tools,
-      logger,
-      env,
-      instruction,
-      config,
-      plugin_instances,
-      plugins,
-      agent_context: agent_context!,
-      ...(shell ? { shell } : {}),
-    };
-  }
-
-  private load_config(agent_id: string): DowncityConfig {
-    if (this.options.config) {
-      return {
-        ...this.options.config,
-        id: String(this.options.config.id || "").trim() || agent_id,
-        version: String(this.options.config.version || "").trim() || "1.0.0",
-      };
-    }
-    return createFallbackSdkConfig(agent_id);
-  }
-
-  /**
-   * 判断是否需要自动注册 plugin_call tool。
-   */
-  private should_register_plugin_call_tool(
-    plugin_instances: Map<string, Plugin>,
-  ): boolean {
-    for (const plugin of plugin_instances.values()) {
-      if (
-        plugin.actions &&
-        Object.keys(plugin.actions).some((action_name) =>
-          Boolean(String(action_name || "").trim()),
-        )
-      ) {
-        return true;
-      }
-    }
-    return false;
-  }
-}
-
-function normalize_approval_runtime_event(
-  event: Record<string, unknown>,
-): SessionApprovalRuntimeEvent | null {
-  if (event.type === "tool-approval-request") {
-    return {
-      type: "tool-approval-request",
-      turn_id: String(event.turnId || ""),
-      tool_call_id: String(event.toolCallId || ""),
-      tool_name: String(event.toolName || "unknown"),
-      approval_id: String(event.approvalId || ""),
-      command: String(event.cmd || ""),
-      cwd: String(event.cwd || ""),
-      reason: String(event.reason || ""),
-      operation:
-        event.operation === "start" || event.operation === "write"
-          ? event.operation
-          : "exec",
-    };
-  }
-  if (event.type === "tool-approval-result") {
-    const decision = event.decision === "approved" || event.decision === "denied"
-      ? event.decision
-      : "expired";
-    return {
-      type: "tool-approval-result",
-      turn_id: String(event.turnId || ""),
-      tool_call_id: String(event.toolCallId || ""),
-      approval_id: String(event.approvalId || ""),
-      decision,
-    };
-  }
-  return null;
-}