@downcity/agent 1.1.337 → 1.1.399

package/README.md

@@ -1,15 +1,15 @@
 # @downcity/agent
 
-`@downcity/agent` 是 Downcity 的单 Agent 运行时包。
+`@downcity/agent` 是 Downcity 的 Agent runtime 包。`Agent` 是主体，`City` 是承载多个 Agent、Workspace、Embassy 与 transport 的环境容器。
 
 它负责把一个 agent 项目目录装配成可执行运行时，包括：
 
-- 本地 SDK：`Agent`、`Session`、`RemoteAgent`
+- 本地 SDK：`Agent`、`Group`、`Workspace`、`Session`、`RemoteAgent`
 - 内部执行内核：Session Composer、LLM/Tool Loop、增量输出
 - Plugin 框架：registry、action、tool runtime 与执行生命周期
 - 远程访问：`RemoteAgent`、HTTP/RPC transport
 
-`downcity` 负责多 Agent 管理、控制面网关、平台 CLI、共享模型目录接入与 daemon 进程管理；`@downcity/agent` 只负责单 Agent 的执行面。
+CLI 与 Desktop 负责读取产品配置并显式装配 `Agent`，再通过 `city.agents.add(agent)` 将 Agent 加入环境。City 不创建 Agent，也不持有 Plugin 实例；City 只提供底层资源和 Storage，Plugin 通过执行 Context 使用被允许的能力。
 
 ## 包定位
 
@@ -21,17 +21,31 @@
 ## 与其他包的边界
 
 - `@downcity/agent`
-  - 单 Agent runtime
+  - Agent 与 City runtime
   - session SDK、executor 内核、plugin 框架、sandbox
-  - 本地 SDK facade
+  - City Workspace、Embassy、HTTP/RPC transport
 - `downcity`
-  - 多 Agent registry
-  - control plane / gateway
-  - 平台 CLI、共享模型目录接入、模型运行时绑定、全局 env、Plugin Resource Store
-  - agent daemon 进程管理
+  - CLI City daemon 与平台控制面
+- `@downcity/local`
+  - CLI 与 Desktop 共用的本地数据库 Adapter、配置 Repository 与 Plugin Loader
+  - 不创建 Agent、Workspace、Model 或 City
 - `@downcity/ui`
   - React UI 组件与展示层
 
+Session ID 由 `agent.sessions.create()` 内部生成；创建接口不接受调用方指定的
+`session_id`。恢复已有 Session 时使用 `agent.sessions.get(session_id)`，如果该
+Session 创建时绑定了 Workspace，恢复时必须传入同一个 Workspace。
+
+Group 是和 Agent 并列的可联系主体。Group 持有自己的模型，默认通过 AI 调度器识别消息意图、选择成员和生成当前最佳响应图；没有模型或模型调用失败时，GroupSession 会记录明确的调度失败，不会静默使用另一套规则。需要自定义行为时可显式提供 `dispatch_strategy`。普通群聊消息是否投递给一个或多个成员完全由 Group.model 决定。AI 调度使用一次强制的内部 `dispatch_group` tool call，不依赖 `generateObject`；tool call 只提交 `steps` 和 `next`，SDK 再编译为内部执行图。
+
+`steps` 是二维数组：外层阶段按顺序执行，同一阶段数组内的成员并行执行；同一个成员可以出现在不同阶段，表示它在拓扑中再次参与。例如 `[["architect"], ["developer"], ["architect"], ["reviewer"]]` 表示 architect 的回复先交给 developer，再交回 architect，最后交给 reviewer。空数组配合 `next: "stop"` 表示本次不投递成员。
+并通过 `group.sessions.create()` 创建独立的群聊上下文。消息和传播属于 GroupSession；
+成员执行仍通过成员 Agent 的 `AgentSessions` 完成。`prompt()` 立即返回消息回执并异步启动 user dispatch；GroupSession 只运行一个全局 auto dispatch，在当前成员执行完成后统一决定是否扩展响应图。成员运行态可通过
+`subscribe()` 统一订阅共享消息和 Group/成员运行态；Session metadata 会记录 Group 与
+GroupSession 来源。调度检查点也会写入 City Storage；进程中断后只依据已落盘消息继续
+auto dispatch，不会重复提交已经接受的 Agent Turn。`group.sessions.list()` 返回轻量摘要，
+`group.sessions.get(id)` 恢复完整上下文。
+
 ## 根目录结构
 
 ```text
@@ -50,6 +64,7 @@ packages/agent
 src/
 ├── index.ts               # 包公开入口
 ├── agent/                 # Agent facade、状态、模型、环境与执行绑定
+├── group/                 # Group 主体、GroupSession 和消息调度策略
 ├── executor/              # LLM/Tool Loop、执行恢复与内存上下文折叠
 ├── plugin/                # Plugin registry、执行视图、工具桥接与生命周期
 ├── remote/                # RemoteAgent、RemoteSession 与 HTTP/RPC transport
@@ -69,11 +84,10 @@ src/
 
 - `src/workspace/`
   - 统一承载项目根目录、文件系统、模型工具、初始化和结构化存储
-  - `setup/` 负责项目 `.env`、`.gitignore` 与 `.downcity` 初始化
-  - `store/` 负责 Agent、Session 和 JSONL Message 的本地持久化
+  - `store/` 负责 AgentStorage、Session 和 JSONL Message 的本地持久化
   - `WorkspaceEnv.ts` 负责 Workspace 环境变量装配
   - `tool/WorkspaceTools.ts` 组合文件、搜索与可选 Shell 工具
-  - `WorkspacePaths.ts` 负责 Workspace 内部路径布局
+  - `WorkspacePaths.ts` 负责 AgentStorage 私有数据路径布局
 
 - `src/session/`
   - `Session.ts` 是公开 facade 与 Session 对象装配入口
@@ -82,7 +96,7 @@ src/
   - `SessionMessages.ts` 是 canonical Message 唯一事实源
   - `DefaultSessionComposer.ts` 负责 system/history/tools 与压缩计划定制
   - `messages/` 放 Assistant writer、Message codec 与 compaction；JSONL Store 位于 `workspace/store/`
-  - 完整设计见 [`docs/session-runtime-architecture.md`](../../docs/session-runtime-architecture.md)
+  - Session 由 `AgentSessions` 统一持有；Workspace 只作为 `agent.sessions.create/get({ workspace })` 的单次执行输入
 
 - `src/executor/`
   - 内部执行内核
@@ -125,5 +139,7 @@ src/
 - `SessionMessages` 是 Message 唯一事实源，Executor 不持有 Store
 - `types / utils` 提供横向公共支撑
 
-完整架构、执行链、持久化、Plugin、Shell 与跨平台设计见
-[`docs/agent-sdk-architecture.md`](../../docs/agent-sdk-architecture.md)。
+持久化规则：加入 City 后，AgentSession 使用 `agents/<agent_id>/sessions/<session_id>/`，
+GroupSession 使用 `groups/<group_id>/sessions/<group_session_id>/`；未加入 City 时两者均使用
+当前主体实例的内存 Storage。只有传入 Workspace 的 AgentSession 或 GroupSession 才会在
+`meta.json` 写入 `workspace_id`。

package/bin/agent/Agent.d.ts

@@ -1,105 +1,56 @@
 /**
- * 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 { AgentModel } from "../agent/AgentModel.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 { AgentSessions } from "../agent/AgentSessions.js";
+import type { RuntimeTool as Tool } from "@downcity/type";
+import type { AgentModel } from "./AgentModel.js";
 import { PluginRegistry } from "../plugin/core/PluginRegistry.js";
-import type { Hono } from "hono";
-import type { PluginSnapshot } from "../types/plugin/PluginState.js";
-import { type SystemProfile } from "../executor/composer/system/default/SystemDomain.js";
-import type { SystemModelMessage } from "ai";
-/**
- * SDK 本地 Agent。
- */
+import type { AgentOptions, AgentSessionConstructor } from "../types/agent/AgentOptions.js";
+import type { PluginWebServices } from "../types/plugin/PluginServices.js";
+import type { AgentSessionCollection } from "../types/agent/AgentSessionCollection.js";
+import { Logger } from "../utils/logger/Logger.js";
+/** SDK Agent 主体。 */
 export declare class Agent {
-    /** 当前 Agent 的稳定标识，用于区分 Session 存储目录与运行时归属。 */
+    /** Agent 的全局稳定标识。 */
     readonly id: string;
-    /** 当前 Agent 引用的项目资源与安全边界。 */
-    readonly workspace: WorkspaceBase;
-    /** 当前 Agent 向所有 Session 提供的工具集合。 */
-    readonly tools: Record<string, Tool>;
-    /** 当前 Agent 已装配的 Plugin 调用与注册入口。 */
-    readonly plugins: PluginRegistry;
-    /** 当前 Agent 的本地 Session 创建、恢复、查询与归档入口。 */
-    readonly sessions: AgentSessions;
-    /**
-     * 当前 Agent 持有的默认运行时模型实例。
-     *
-     * 关键点（中文）
-     * - Agent 只持有调用方传入的实例，不负责模型选择、持久化或恢复。
-     * - Session 未设置自己的模型时，执行会回退使用该实例。
-     */
+    /** Agent 默认模型；Session 可以显式覆盖。 */
     readonly model?: AgentModel;
-    /** 当前 Agent 独享的运行日志器。 */
+    /** Agent 面向用户的 Session 创建入口。 */
+    readonly sessions: AgentSessionCollection;
+    /** 当前 Agent 持有的 Web 搜索与文档能力。 */
+    readonly web?: PluginWebServices;
+    /** Agent 注册的唯一 PluginRegistry。 */
+    readonly plugins: PluginRegistry;
+    /** Agent 自定义 Tool；进入每个 Workspace 时与项目 Tool 合并。 */
+    readonly custom_tools: Record<string, Tool>;
+    /** Agent 使用的 Session 类。 */
+    readonly session_class?: AgentSessionConstructor;
+    /** AgentPlugin 的内部访问名，仍指向 Agent 唯一 Registry。 */
+    readonly plugin_registry: PluginRegistry;
+    /** Agent 级日志器，不绑定任何 Workspace。 */
     private readonly logger;
-    /** 提供给 Plugin、Session 与宿主集成层共享的 Agent 执行上下文。 */
-    private readonly plugin_context;
-    /** 调用方提供的自定义 Session 类；省略时使用 SDK 默认实现。 */
-    private readonly session_class;
-    /** 当前 Agent 的长期运行状态与生命周期。 */
-    private readonly state;
-    /** 当前 Agent configured instruction 的可变有序集合。 */
-    private instruction;
-    /** 取消 Workspace env 变化订阅的函数。 */
-    private readonly unsubscribe_workspace_env;
-    /** 取消 PluginRegistry 变化订阅的函数。 */
-    private readonly unsubscribe_plugin_change;
-    /** 当前由 PluginRegistry 注册到 Agent 的 Tool 名称。 */
-    private readonly plugin_tool_names;
+    /** 当前 Agent configured instruction。 */
+    private readonly instruction;
+    /** Agent 释放状态。 */
+    private dispose_promise?;
+    /** Agent 级 Plugin lifecycle 启动流程。 */
+    private readonly plugin_ready;
+    /** Agent 唯一的 Session 集合。 */
+    private readonly session_manager;
     constructor(options: AgentOptions);
-    /**
-     * 等待 Agent 持有的长期运行时启动完成。
-     *
-     * 关键点（中文）
-     * - Agent 构造完成即开始启动 plugin lifecycle 与 ActionSchedule。
-     * - 调用方在需要确认运行时就绪时使用，例如启动后立刻读取 plugin 状态。
-     */
-    ready(): Promise<void>;
-    /**
-     * 释放当前 Agent 持有的长期运行时对象。
-     *
-     * 关键点（中文）
-     * - 关闭 plugin lifecycle 与 ActionSchedule 等 Agent 自有资源。
-     * - Workspace 与 Agent 一对一绑定，因此这里同时关闭 Shell 与 Sandbox。
-     * - 不负责任何 transport（RPC / HTTP）；transport 由 `@downcity/server` 自行管理。
-     */
-    dispose(): Promise<void>;
-    /**
-     * 更新当前 SDK Agent 的静态基础指令。
-     */
+    /** 更新 Agent 的静态基础指令。 */
     set_instruction(input: string | string[]): void;
-    /**
-     * 返回当前 agent 绑定的统一日志器。
-     */
-    get_logger(): Logger;
-    /**
-     * 返回当前 agent 挂载的 Shell。
-     */
-    get_shell(): Shell | undefined;
-    /** 返回当前 Agent 已配置的静态指令快照。 */
+    /** 返回 Agent 指令快照。 */
     get_instructions(): readonly string[];
-    /** 列出当前 Agent 已注册的 Plugin 状态。 */
-    list_plugin_states(): PluginSnapshot[];
-    /** 把当前 Agent 已注册 Plugin 的 HTTP 路由装配到宿主应用。 */
-    register_plugin_http_routes(app: Hono): void;
-    /** 解析指定 Session 当前可见的完整 system messages。 */
-    resolve_system_messages(input: {
-        /** 需要解析 system 的 Session 标识。 */
-        session_id: string;
-        /** system 组合档位；省略时使用 chat。 */
-        profile?: SystemProfile;
-    }): Promise<SystemModelMessage[]>;
-    /** 将 PluginRegistry 当前 Tool Set 同步到 Agent 持有的工具集合。 */
-    private sync_plugin_tools;
+    /** 返回 Agent 级日志器。 */
+    get_logger(): Logger;
+    /** 释放 Agent 进入的全部 Workspace 与 Agent Plugin。 */
+    dispose(): Promise<void>;
+    /** 等待 Agent 级 Plugin 完成启动，供内部运行时使用。 */
+    ensure_ready(): Promise<void>;
 }
 //# sourceMappingURL=Agent.d.ts.map

package/bin/agent/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAGpE,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,IAAI,CAAC;AAoB7C;;GAEG;AACH,qBAAa,KAAK;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAElC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAErC,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IAEjC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAE5B,yBAAyB;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAE/C,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgC;IAE9D,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC,+CAA+C;IAC/C,OAAO,CAAC,WAAW,CAAW;IAE9B,gCAAgC;IAChC,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAA0B;IAEpE,iCAAiC;IACjC,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAA4B;IAEtE,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;gBAE3C,OAAO,EAAE,YAAY;IAkFjC;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAe9B;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAK/C;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,SAAS,IAAI,KAAK,GAAG,SAAS;IAI9B,6BAA6B;IAC7B,gBAAgB,IAAI,SAAS,MAAM,EAAE;IAIrC,iCAAiC;IACjC,kBAAkB,IAAI,cAAc,EAAE;IAItC,6CAA6C;IAC7C,2BAA2B,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI;IAU5C,4CAA4C;IACtC,uBAAuB,CAAC,KAAK,EAAE;QACnC,gCAAgC;QAChC,UAAU,EAAE,MAAM,CAAC;QACnB,8BAA8B;QAC9B,OAAO,CAAC,EAAE,aAAa,CAAC;KACzB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAUjC,sDAAsD;IACtD,OAAO,CAAC,iBAAiB;CAW1B"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,IAAI,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACxB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EACV,sBAAsB,EACvB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAclD,oBAAoB;AACpB,qBAAa,KAAK;IAChB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAE5B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAE1C,gCAAgC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,iBAAiB,CAAC;IAEjC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5C,2BAA2B;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,uBAAuB,CAAC;IAEjD,gDAAgD;IAChD,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC;IAEzC,kCAAkC;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC,uCAAuC;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IAEvC,kBAAkB;IAClB,OAAO,CAAC,eAAe,CAAC,CAAgB;IAExC,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAEhD,4BAA4B;IAC5B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgB;gBAEpC,OAAO,EAAE,YAAY;IA0EjC,wBAAwB;IACxB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAK/C,qBAAqB;IACrB,gBAAgB,IAAI,SAAS,MAAM,EAAE;IAIrC,qBAAqB;IACrB,UAAU,IAAI,MAAM;IAIpB,+CAA+C;IACzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB9B,uCAAuC;IACjC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAIpC"}

package/bin/agent/Agent.js

@@ -1,236 +1,151 @@
 /**
- * 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 { create_plugin_context } from "../plugin/core/PluginContext.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 { normalize_instruction_input } from "./AgentInstructions.js";
 import { PluginRegistry } from "../plugin/core/PluginRegistry.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, } from "../executor/composer/system/default/SystemDomain.js";
-const RESERVED_PLUGIN_TOOL_NAMES = new Set(["plugin_read", "plugin_call"]);
-/** 将一个来源明确的 Tool Set 注册到 Agent，并拒绝静默覆盖。 */
-function register_agent_tools(target, source, source_name) {
-    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。
- */
+import { Logger } from "../utils/logger/Logger.js";
+import { AgentSessions } from "./AgentSessions.js";
+import { 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 的全局稳定标识。 */
     id;
-    /** 当前 Agent 引用的项目资源与安全边界。 */
-    workspace;
-    /** 当前 Agent 向所有 Session 提供的工具集合。 */
-    tools;
-    /** 当前 Agent 已装配的 Plugin 调用与注册入口。 */
-    plugins;
-    /** 当前 Agent 的本地 Session 创建、恢复、查询与归档入口。 */
-    sessions;
-    /**
-     * 当前 Agent 持有的默认运行时模型实例。
-     *
-     * 关键点（中文）
-     * - Agent 只持有调用方传入的实例，不负责模型选择、持久化或恢复。
-     * - Session 未设置自己的模型时，执行会回退使用该实例。
-     */
+    /** Agent 默认模型；Session 可以显式覆盖。 */
     model;
-    /** 当前 Agent 独享的运行日志器。 */
-    logger;
-    /** 提供给 Plugin、Session 与宿主集成层共享的 Agent 执行上下文。 */
-    plugin_context;
-    /** 调用方提供的自定义 Session 类；省略时使用 SDK 默认实现。 */
+    /** Agent 面向用户的 Session 创建入口。 */
+    sessions;
+    /** 当前 Agent 持有的 Web 搜索与文档能力。 */
+    web;
+    /** Agent 注册的唯一 PluginRegistry。 */
+    plugins;
+    /** Agent 自定义 Tool；进入每个 Workspace 时与项目 Tool 合并。 */
+    custom_tools;
+    /** Agent 使用的 Session 类。 */
     session_class;
-    /** 当前 Agent 的长期运行状态与生命周期。 */
-    state;
-    /** 当前 Agent configured instruction 的可变有序集合。 */
+    /** AgentPlugin 的内部访问名，仍指向 Agent 唯一 Registry。 */
+    plugin_registry;
+    /** Agent 级日志器，不绑定任何 Workspace。 */
+    logger = new Logger();
+    /** 当前 Agent configured instruction。 */
     instruction;
-    /** 取消 Workspace env 变化订阅的函数。 */
-    unsubscribe_workspace_env;
-    /** 取消 PluginRegistry 变化订阅的函数。 */
-    unsubscribe_plugin_change;
-    /** 当前由 PluginRegistry 注册到 Agent 的 Tool 名称。 */
-    plugin_tool_names = new Set();
+    /** Agent 释放状态。 */
+    dispose_promise;
+    /** Agent 级 Plugin lifecycle 启动流程。 */
+    plugin_ready;
+    /** Agent 唯一的 Session 集合。 */
+    session_manager;
     constructor(options) {
         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 = 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 instructions() {
+                return agent.get_instructions();
             },
-            get_agent_model: () => this.model,
-            session_class: this.session_class,
         });
-        this.plugin_context = create_plugin_context({
-            ...(this.workspace.shell ? { shell: this.workspace.shell } : {}),
+        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 () => { },
+            }),
+        });
+        const get_store = () => get_agent_storage(this).sessions;
+        const session_store = {
+            session: (session_id, workspace_id) => get_store().session(session_id, workspace_id),
+            has_session: async (session_id) => await get_store().has_session(session_id),
+            remove_session: async (session_id) => await get_store().remove_session(session_id),
+            clear_session_messages: async (session_id) => await get_store().clear_session_messages(session_id),
+            list_sessions: async (input, executing) => await get_store().list_sessions(input, executing),
+            archive_session: async (session_id) => await get_store().archive_session(session_id),
+            list_archived_sessions: async (input) => await get_store().list_archived_sessions(input),
+            clean_archive: async () => await get_store().clean_archive(),
+            dispose: async () => { },
+        };
+        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() {
-        await this.state.ready();
-    }
-    /**
-     * 释放当前 Agent 持有的长期运行时对象。
-     *
-     * 关键点（中文）
-     * - 关闭 plugin lifecycle 与 ActionSchedule 等 Agent 自有资源。
-     * - Workspace 与 Agent 一对一绑定，因此这里同时关闭 Shell 与 Sandbox。
-     * - 不负责任何 transport（RPC / HTTP）；transport 由 `@downcity/server` 自行管理。
-     */
-    async dispose() {
-        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) {
         const next_instruction = normalize_instruction_input(input);
         this.instruction.splice(0, this.instruction.length, ...next_instruction);
     }
-    /**
-     * 返回当前 agent 绑定的统一日志器。
-     */
-    get_logger() {
-        return this.logger;
-    }
-    /**
-     * 返回当前 agent 挂载的 Shell。
-     */
-    get_shell() {
-        return this.workspace.shell;
-    }
-    /** 返回当前 Agent 已配置的静态指令快照。 */
+    /** 返回 Agent 指令快照。 */
     get_instructions() {
         return [...this.instruction];
     }
-    /** 列出当前 Agent 已注册的 Plugin 状态。 */
-    list_plugin_states() {
-        return list_plugin_states({ context: this.plugin_context });
-    }
-    /** 把当前 Agent 已注册 Plugin 的 HTTP 路由装配到宿主应用。 */
-    register_plugin_http_routes(app) {
-        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 级日志器。 */
+    get_logger() {
+        return this.logger;
     }
-    /** 解析指定 Session 当前可见的完整 system messages。 */
-    async resolve_system_messages(input) {
-        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 进入的全部 Workspace 与 Agent Plugin。 */
+    async dispose() {
+        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;
     }
-    /** 将 PluginRegistry 当前 Tool Set 同步到 Agent 持有的工具集合。 */
-    sync_plugin_tools() {
-        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);
-        }
+    /** 等待 Agent 级 Plugin 完成启动，供内部运行时使用。 */
+    async ensure_ready() {
+        await this.plugin_ready;
     }
 }
 //# sourceMappingURL=Agent.js.map