@downcity/agent 1.1.437 → 1.1.445

package/src/agent/Agent.ts

@@ -3,15 +3,17 @@
  *
  * 职责说明（中文）
  * - Agent 不绑定 Workspace；调用方通过 `agent.sessions.create({ workspace })` 选择本次执行环境。
- * - Plugin 与 Transport 由 City 持有，Agent 只通过 CityRuntime 使用最小执行能力。
+ * - 能力与 Transport 由容器持有，Agent 只收下容器在绑定时推送的能力，不持有容器引用。
  * - Session 由 AgentSessions 统一持有；Workspace 只在单个 Session 创建时提供执行资源。
  */
 
 import type {
   CityRuntime,
   ModelClient,
-  RuntimeTool as Tool,
+  AgentTool as Tool,
   StorageProvider,
+  ToolCallContext,
+  ToolHookSet,
   WorkspaceRuntime,
 } from "@downcity/type";
 import {
@@ -29,15 +31,15 @@ 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 { EMPTY_TOOL_HOOK_SET } from "@downcity/type";
 import type { AgentStorage } from "@/types/agent/AgentStorage.js";
-import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { SessionSystemMessage } from "@downcity/type";
 import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import {
   build_session_system_blocks,
-  resolve_session_plugin_system_blocks,
-} from "@/session/SessionSystem.js";
-import { create_session_hook_context } from "@/session/runtime/SessionTurnContext.js";
+  resolve_session_power_system_blocks,
+} from "@/session/input/SessionSystem.js";
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import { resolve_system_timezone } from "@/session/storage/Metadata.js";
 
 /** SDK Agent 主体。 */
@@ -63,8 +65,8 @@ export class Agent {
   /** Agent 使用的 Session 类。 */
   readonly session_class?: AgentSessionConstructor;
 
-  /** 为每个 Session 创建独立 Composer 的工厂。 */
-  readonly session_composer?: () => SessionComposer;
+  /** 当前 Agent 使用的 Session Composer；其所有 Session 共享该实例。 */
+  readonly session_composer?: SessionComposer;
 
   /** Agent 级日志器，不绑定任何 Workspace。 */
   private readonly logger = new Logger();
@@ -72,24 +74,24 @@ export class Agent {
   /** 当前 Agent configured instruction。 */
   private readonly instruction: string[];
 
+  /** Agent 自有检查点处理器；与容器提供的 Power hooks 合并使用。 */
+  private readonly custom_hooks: ToolHookSet;
+
   /** Agent 释放状态。 */
   private dispose_promise?: Promise<void>;
 
   /** Agent 唯一的 Session 集合。 */
   private readonly session_manager: AgentSessions;
 
-  /** 未加入宿主时使用的隔离进程内存储。 */
+  /** 未加入容器时使用的隔离进程内存储。 */
   private storage_provider: StorageProvider = new AgentMemoryStorageProvider();
 
-  /** Agent 当前所属的唯一 City；独立运行时为空。 */
-  private city?: CityRuntime;
+  /** 当前绑定的容器运行环境；独立运行时为空。 */
+  private host?: 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");
@@ -102,28 +104,27 @@ export class Agent {
     this.custom_tools = options.tools && typeof options.tools === "object"
       ? { ...options.tools }
       : {};
+    this.custom_hooks = options.hooks ?? EMPTY_TOOL_HOOK_SET;
     this.session_manager = new AgentSessions({
       agent_id: this.id,
+      agent_name: this.name,
+      agent_description: this.description,
       logger: this.logger,
       get_instruction: () => [...this.get_instructions()],
-      ensure_agent_ready: async () => await this.ensure_ready(),
       get_agent_model: () => this.model,
       session_class: this.session_class,
-      create_session_composer: this.session_composer,
-      on_session_routed: () => {
-        if (!this.city) this.memory_session_started = true;
-      },
+      session_composer: this.session_composer,
       resolve_session_context: (workspace) => {
         const storage = this.resolve_storage();
         if (!workspace) return {
           workspace_path: ".",
           logger: this.logger,
-          get_tools: () => ({ ...this.custom_tools }),
+          get_tools: () => this.resolve_tools(),
           get_workspace_env: () => ({}),
-          get_hooks: () => EMPTY_SESSION_HOOKS,
+          get_workspace: () => undefined,
+          get_hooks: () => this.resolve_hooks(),
           store: storage.sessions,
         };
-        this.assert_workspace(workspace);
         // 静态 Workspace Tool 与 Agent Tool 的命名冲突属于 Session 创建不变量，
         // 在装配时立即失败；执行时仍通过 getter 读取最新宿主扩展。
         this.resolve_tools(workspace);
@@ -133,8 +134,8 @@ export class Agent {
           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,
+          get_workspace: () => workspace,
+          get_hooks: () => this.resolve_hooks(),
           store: storage.sessions,
         };
       },
@@ -158,25 +159,38 @@ export class Agent {
     return this.logger;
   }
 
-  /** 将 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`);
+  /**
+   * 绑定容器运行环境；必须在创建或恢复 Session 前完成。
+   *
+   * 关键点（中文）
+   * - 主体只收下容器推送的存储能力，不持有容器引用。
+   * - 存储一旦在独立模式下被使用就不能再切换，否则已有 Session 会写入两个事实源。
+   */
+  bind(host: CityRuntime): void {
+    if (this.host) {
+      if (this.host === host) return;
+      throw new Error(`Agent "${this.id}" is already bound to another container`);
     }
-    if (this.memory_session_started || this.agent_storage) {
+    if (this.agent_storage) {
       throw new Error(
-        `Agent "${this.id}" already used standalone storage; attach it before using Sessions`,
+        `Agent "${this.id}" already used standalone storage; bind it before using Sessions`,
       );
     }
-    this.city = city;
-    this.storage_provider = city.storage;
+    this.host = host;
+    this.storage_provider = host.storage;
   }
 
-  /** 解除指定 City 关系；其他 City 不能解除当前绑定。 */
-  detach(city: CityRuntime): void {
-    if (this.city === city) this.city = undefined;
+  /**
+   * 解除容器绑定，主体回到独立运行状态。
+   *
+   * 关键点（中文）
+   * - 由容器在放下引用后调用；主体不反向通知容器。
+   * - 已解析的存储视图同时丢弃，避免解绑后继续写旧容器存储。
+   */
+  unbind(): void {
+    this.host = undefined;
+    this.storage_provider = new AgentMemoryStorageProvider();
+    this.agent_storage = undefined;
   }
 
   /** 停止绑定到指定 Workspace 的运行中 Session，并释放后台标题任务。 */
@@ -193,28 +207,25 @@ export class Agent {
       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({
+    const instruction_system_blocks = create_instruction_system_blocks({
+      agent_id: this.id,
+      agent_name: this.name,
+      instruction: [...this.get_instructions()],
+    });
+    const hooks = this.resolve_hooks();
+    const context = this.create_session_call_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),
+      workspace,
+      instruction_system_blocks,
     });
-    const plugin_system_blocks = await resolve_session_plugin_system_blocks({
+    const power_system_blocks = await resolve_session_power_system_blocks({
       session_id,
       hooks,
-      context: hook_context,
+      context,
     });
     const blocks = await build_session_system_blocks({
       agent_id: this.id,
@@ -223,38 +234,64 @@ export class Agent {
       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,
+      get_power_system_blocks: async () => power_system_blocks,
     });
     return blocks.map((block) => ({ role: "system", content: block.content }));
   }
 
-  /** 释放 Agent 的 Session 后台任务、存储与宿主引用。 */
+  /** 构造不属任何 Turn 的调用环境；用于 system 查询。 */
+  private create_session_call_context(input: {
+    /** 目标 Session 稳定标识。 */
+    readonly session_id: string;
+    /** 当前使用的 Workspace 实例。 */
+    readonly workspace: WorkspaceRuntime;
+    /** 当前 Agent 指令快照。 */
+    readonly instruction_system_blocks: readonly AgentSessionSystemBlock[];
+  }): ToolCallContext {
+    return Object.freeze({
+      agent_id: this.id,
+      agent_name: this.name,
+      agent_description: this.description,
+      agent_instructions: Object.freeze(
+        input.instruction_system_blocks.map((block) => block.content),
+      ),
+      session_id: input.session_id,
+      session_origin: { type: "chat" },
+      workspace: input.workspace,
+      messages: Object.freeze([]),
+      workspace_env: Object.freeze({ ...input.workspace.get_env() }),
+    });
+  }
+
+  /**
+   * 释放 Agent 的 Session 后台任务、存储与运行环境。
+   *
+   * 关键点（中文）
+   * - 已绑定的 Agent 不能自行释放：容器仍持有引用，必须走 `city.agents.remove(id)`。
+   * - 这把「已注册主体不能自行释放」变成可检查的不变量，而不是靠时序掩盖。
+   */
   async dispose(): Promise<void> {
+    if (this.host) {
+      throw new Error(
+        `Agent "${this.id}" is bound to a container; release it with city.agents.remove(id)`,
+      );
+    }
     this.dispose_promise ??= (async () => {
       const results = await Promise.allSettled([
         this.session_manager.stop_executing_sessions(),
       ]);
       this.session_manager.dispose_title_generation();
-      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 自身运行时 ready，供内部运行时使用。 */
-  async ensure_ready(): Promise<void> {
-    await this.city?.ensure_ready();
-  }
-
   /** 获取或创建 Agent 唯一的 Session 存储。 */
   private resolve_storage(): AgentStorage {
     if (this.agent_storage) return this.agent_storage;
@@ -274,28 +311,48 @@ export class Agent {
     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> {
+  /**
+   * 返回当前生效的工具集合：Workspace 工具 + 容器 Power 工具 + Agent 自有工具。
+   *
+   * 关键点（中文）
+   * - 容器 Power 工具从环境句柄实时读取，不缓存；容器增删 Power 后下一次求值即生效。
+   * - 静态 Workspace Tool 与 Agent Tool 的命名冲突属于 Session 创建不变量，装配时立即失败。
+   */
+  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",
-    );
+    if (workspace) register_tools(tools, workspace.tools, "WorkspaceTools");
+    register_tools(tools, this.host?.power_tools ?? {}, "Power");
     register_tools(tools, this.custom_tools, "AgentOptions.tools");
     return tools;
   }
 
+  /** 合并容器 Power hooks 与 Agent 自有 hooks。 */
+  private resolve_hooks(): ToolHookSet {
+    const power_hooks = this.host?.power_hooks;
+    if (!power_hooks) return this.custom_hooks;
+    if (this.custom_hooks === EMPTY_TOOL_HOOK_SET) return power_hooks;
+    return merge_tool_hook_sets(power_hooks, this.custom_hooks);
+  }
+
+}
+
+/** 按检查点合并两组 hooks；同名检查点按容器在前、自有在后的顺序拼接。 */
+function merge_tool_hook_sets(base: ToolHookSet, extra: ToolHookSet): ToolHookSet {
+  const merge_points = <THandler>(
+    left: Readonly<Record<string, readonly THandler[]>>,
+    right: Readonly<Record<string, readonly THandler[]>>,
+  ): Readonly<Record<string, readonly THandler[]>> => {
+    const merged: Record<string, readonly THandler[]> = { ...left };
+    for (const [point_name, handlers] of Object.entries(right)) {
+      merged[point_name] = [...(merged[point_name] ?? []), ...handlers];
+    }
+    return merged;
+  };
+  return {
+    pipeline: merge_points(base.pipeline, extra.pipeline),
+    guard: merge_points(base.guard, extra.guard),
+    effect: merge_points(base.effect, extra.effect),
+  };
 }
 
 /** 注册 Tool 集合，并拒绝不同来源静默覆盖。 */

package/src/agent/AgentInstructions.ts

@@ -2,13 +2,24 @@
  * Agent instruction 组装工具。
  *
  * 关键点（中文）
- * - 这里只处理静态 instruction 与默认 core prompt。
- * - instruction 永远在 core 前面；core 不会被调用方 instruction 替代。
- * - 不读取 Session、Plugin 或 runtime 状态，保持为纯函数。
+ * - 这里只处理 Agent 身份、静态 instruction 与默认 core prompt。
+ * - 顺序固定为 identity → instruction → core；core 不会被调用方 instruction 替代。
+ * - identity 与 core 都由 SDK 注入，调用方 instruction 只决定中间一段。
+ * - 不读取 Session、Power 或 runtime 状态，保持为纯函数。
  */
 
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import { CORE_SYSTEM_PROMPT } from "@executor/composer/system/default/SystemPromptAssets.js";
+import { CORE_SYSTEM_PROMPT } from "@/model/prompts/SystemPromptAssets.js";
+
+/** 构造 instruction system block 所需的 Agent 身份与调用方指令。 */
+export interface CreateInstructionSystemBlocksInput {
+  /** 当前 Agent 的稳定标识。 */
+  agent_id: string;
+  /** 当前 Agent 的用户可见名称；为空时回退到 agent_id。 */
+  agent_name: string;
+  /** 调用方传入的静态 instruction，应已由 `normalize_instruction_input` 归一化。 */
+  instruction: readonly string[];
+}
 
 /**
  * 归一化调用方传入的静态 instruction。
@@ -26,32 +37,54 @@ export function normalize_instruction_input(
     .filter((item) => item.length > 0);
 }
 
-function createCoreInstructionContent(project_root: string): string {
-  const current_year = String(new Date().getFullYear());
-  return CORE_SYSTEM_PROMPT
-    .replaceAll("{{project_path}}", project_root)
-    .replaceAll("{{project_root}}", project_root)
-    .replaceAll("{{current_year}}", current_year);
+/**
+ * 渲染 Agent 身份说明。
+ *
+ * 关键点（中文）
+ * - name 与 id 始终同时给出：name 是模型理解的角色名，id 是宿主可对账的稳定标识。
+ * - name 缺省回退到 id，此时两者一致，仍然保持同一输出形状。
+ */
+function create_identity_content(input: {
+  /** 当前 Agent 的稳定标识。 */
+  agent_id: string;
+  /** 当前 Agent 的用户可见名称。 */
+  agent_name: string;
+}): string {
+  const agent_id = String(input.agent_id || "").trim();
+  const agent_name = String(input.agent_name || "").trim() || agent_id;
+  return [
+    "# Agent Identity",
+    "",
+    `You are "${agent_name}" (agent id: ${agent_id}).`,
+  ].join("\n");
 }
 
 /**
  * 构造进入 session system prompt 的 instruction block。
+ *
+ * 关键点（中文）
+ * - 顺序为 identity → instruction → core。
+ * - identity 复用 `instruction` 来源，但块名独立为 `identity`，便于消费端区分。
  */
 export function create_instruction_system_blocks(
-  instruction: string[],
-  project_root: string,
+  input: CreateInstructionSystemBlocksInput,
 ): AgentSessionSystemBlock[] {
-  const instruction_blocks = instruction.map((content, index) => ({
+  const instruction_blocks = input.instruction.map((content, index) => ({
     source: "instruction" as const,
-    name: instruction.length === 1 ? "agent" : `agent:${index + 1}`,
+    name: input.instruction.length === 1 ? "agent" : `agent:${index + 1}`,
     content,
   }));
   return [
+    {
+      source: "instruction",
+      name: "identity",
+      content: create_identity_content(input),
+    },
     ...instruction_blocks,
     {
       source: "core",
       name: "default",
-      content: createCoreInstructionContent(project_root),
+      content: CORE_SYSTEM_PROMPT,
     },
   ];
 }

package/src/agent/AgentMemoryStorage.ts

@@ -175,7 +175,7 @@ export class AgentMemoryStorageProvider implements StorageProvider {
   private readonly scopes_by_key = new Map<string, StorageScope>();
 
   /** 当前 Provider 的逻辑根目录。 */
-  private readonly root_path: string;
+  readonly root_path: string;
 
   constructor(root_path = "/agent-memory") {
     this.root_path = root_path;