@downcity/agent 1.1.408 → 1.1.437

package/README.md

@@ -1,48 +1,53 @@
 # @downcity/agent
 
-`@downcity/agent` 是 Downcity 的 Agent runtime 包。`Agent` 是主体，`City` 是承载多个 Agent、Workspace、Embassy 与 transport 的环境容器。
+`@downcity/agent` 是 Downcity 的单 Agent runtime 包。`Agent` 持有身份、模型、指令、Tool 与 Session，并可独立于 City 运行。
 
-它负责把一个 agent 项目目录装配成可执行运行时，包括：
+它负责把单个 Agent 装配成可执行运行时，包括：
 
-- 本地 SDK：`Agent`、`Group`、`Workspace`、`Session`、`RemoteAgent`
+- 本地 SDK：`Agent`、`Group`、`Session`
 - 内部执行内核：Session Composer、LLM/Tool Loop、增量输出
-- Plugin 框架：registry、action、tool runtime 与执行生命周期
-- 远程访问：`RemoteAgent`、HTTP/RPC transport
+- 中立宿主执行端口：接收 City 提供的 Tool、SessionHooks 与 Workspace 协议
 
-CLI 与 Desktop 负责读取产品配置并显式装配 `Agent`，再通过 `city.agents.add(agent)` 将 Agent 加入环境。City 不创建 Agent，也不持有 Plugin 实例；City 只提供底层资源和 Storage，Plugin 通过执行 Context 使用被允许的能力。
+CLI 与 Desktop 通过 `@downcity/city` 读取宿主配置并显式装配 `Agent`，再将 City 级 Plugin 注册到 `City`。调用 `city.agents.add(agent)` 后，City 中全部 Plugin 自动对该 Agent 可用；Agent 不保存 Plugin 实例。Plugin 的实例、配置投影、Hook scope 与生命周期均由 City 持有。
 
 ## 包定位
 
 - 面向单个 Agent 项目的执行面
 - 对外通过 `@downcity/agent` 根入口暴露公共 API
-- 负责 session SDK、executor 内核、plugin runtime、sandbox、SDK 本地 Agent
+- 负责 Session SDK、Executor 内核、中性执行端口与 SDK 本地 Agent
 - 不负责多 Agent registry、control plane daemon、console UI 聚合和平台级编排
 
 ## 与其他包的边界
 
 - `@downcity/agent`
-  - Agent 与 City runtime
-  - session SDK、executor 内核、plugin 框架、sandbox
-  - City Workspace、Embassy、HTTP/RPC transport
+  - Agent、Group、Session
+  - Session SDK、Executor 内核和中性执行端口
+- `@downcity/city`
+  - City 组合根、Workspace/Embassy 装配、RemoteAgent 与 HTTP/RPC transport
+  - Plugin Registry、Hook 调度、唯一实例和生命周期
+  - `@downcity/city/local` 提供本地数据库、配置 Repository 与 Plugin Loader
+- `@downcity/city/plugin`
+  - Plugin 作者协议、Context、Action、Hook、Lifecycle 与统一 City module
 - `downcity`
   - 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。
+`session_id`。Session 默认来源是 `{ type: "chat" }`，Group 使用 `group`，Task Plugin
+使用 `task`，其他创建方也可以在 `create({ origin })` 中声明任意非空的 `origin.type`
+及附加 JSON 元数据。恢复已有 Session 使用 `agent.sessions.get(session_id, origin_type = "chat")`；
+该调用只读取指定来源分区，不跨目录猜测。如果 Session 创建时绑定了 Workspace，恢复时还必须
+通过第三个参数传入同一个 Workspace，例如 `get(session_id, "task", { workspace })`。
 
-Group 是和 Agent 并列的可联系主体。Group 持有自己的模型，默认通过 AI 调度器识别消息意图、选择成员和生成当前最佳响应图；没有模型或模型调用失败时，GroupSession 会记录明确的调度失败，不会静默使用另一套规则。需要自定义行为时可显式提供 `dispatch_strategy`，异步策略应响应输入中的 `abort_signal`。普通群聊消息是否投递给一个或多个成员完全由 Group.model 决定。每个 GroupSession 拥有唯一的内部 Dispatch Session，调度 Turn 会排队并持久化；AI 调度在同一 Turn 内通过强制的 `dispatch_group` tool call 提交 `steps` 和 `next`，协议输出无效时会先要求模型纠正，再由 SDK 编译为内部执行图。
+Group 是和 Agent 并列的可联系主体。Agent 的 `name` 是可见名称，`description` 是供展示和 Group 选择成员使用的能力简介；两者不替代控制 Agent 行为的 `instruction`。Group 持有自己的模型，默认通过 AI 调度器结合 Group 目标、对话上下文和成员的 `id/name/description` 生成有限阶段计划。没有模型或模型调用失败时，GroupSession 会记录明确的调度失败，不会静默使用另一套规则。需要自定义行为时可显式提供 `dispatch_strategy`，异步策略应响应输入中的 `abort_signal`。
 
-`steps` 是二维数组：外层阶段按顺序执行，同一阶段数组内的成员并行执行；同一个成员可以出现在不同阶段，表示它在拓扑中再次参与。例如 `[["architect"], ["developer"], ["architect"], ["reviewer"]]` 表示 architect 的回复先交给 developer，再交回 architect，最后交给 reviewer。空数组配合 `next: "stop"` 表示本次不投递成员。
-并通过 `group.sessions.create()` 创建独立的群聊上下文。消息和传播属于 GroupSession；
-成员执行仍通过成员 Agent 的 `AgentSessions` 完成。`prompt()` 立即返回消息回执并异步启动 user dispatch；GroupSession 只运行一个全局 auto dispatch，在当前成员执行完成后统一决定是否扩展响应图。成员运行态可通过
+AI 调度在同一 Turn 内通过强制的 `dispatch_group` tool call 提交 `reason`、`stages` 和 `next`。`stages` 按顺序执行，每个阶段包含一个或多个成员专属 `assignment`，同一阶段内并行执行；同一个成员可以在不同阶段再次参与。`next: "continue"` 只表示下一步选择必须依赖当前阶段的真实输出；当前对话已满足用户意图时返回空 `stages` 和 `next: "stop"`，已知阶段执行后即可完成时也使用 `stop`。32 次上限与重复路径检测只用于异常熔断，不参与正常的停止判断。
+
+调用 `group.sessions.create()` 可创建独立的群聊上下文。消息和传播属于 GroupSession；
+成员执行仍通过成员 Agent 的 `AgentSessions` 完成。`prompt()` 立即返回消息回执并异步启动 user dispatch；GroupSession 只运行一个全局 auto dispatch，在当前成员执行完成后统一决定是否需要依据结果继续判断。成员运行态可通过
 `subscribe()` 统一订阅共享消息和 Group/成员运行态；Session metadata 会记录 Group 与
-GroupSession 来源。Dispatch Session 的 Turn 日志与传播检查点都会写入 City Storage；
+GroupSession 来源。GroupSession 的调度 Turn 日志与传播检查点都会写入 City Storage；
 进程中断后可以根据调度阶段重新执行尚未完成的 user dispatch 或继续 auto dispatch。
 `GroupSession.stop()` 会同时中断调度模型和成员 Session。`group.sessions.list()` 返回轻量摘要，
 `group.sessions.get(id)` 恢复完整上下文。
@@ -66,13 +71,15 @@ src/
 ├── index.ts               # 包公开入口
 ├── agent/                 # Agent facade、状态、模型、环境与执行绑定
 ├── group/                 # Group 主体、GroupSession 和消息调度策略
-├── executor/              # LLM/Tool Loop、执行恢复与内存上下文折叠
-├── plugin/                # Plugin registry、执行视图、工具桥接与生命周期
-├── remote/                # RemoteAgent、RemoteSession 与 HTTP/RPC transport
-├── session/               # Session facade、State、Turn、Queue、Messages 与 Composer
-├── types/                 # agent / executor / session / plugin 等共享协议类型
-├── utils/                 # 日志、资源和通用辅助能力
-└── workspace/             # 项目文件、工具、初始化、路径与结构化存储
+├── executor/              # LLM/Tool Loop、usage 观测与执行恢复
+├── host/                  # Agent 宿主端口
+├── internal/              # Agent 与 Group 的内部运行时装配
+├── plugin/                # Agent 使用的 Plugin 执行协议辅助
+├── remote/                # 远程 Agent 与 Session 客户端协议
+├── session/               # Session facade、执行编排、消息与持久化
+├── tools/                 # Agent 内置 Tool
+├── types/                 # agent / executor / session 等包内类型
+└── utils/                 # 日志、资源和通用辅助能力
 ```
 
 ## 顶层目录职责
@@ -83,38 +90,39 @@ src/
   - `AgentSessions.ts` 负责 Session 集合生命周期
   - `ExecutionBinding.ts` 负责 Agent 执行目标绑定
 
-- `src/workspace/`
-  - 统一承载项目根目录、文件系统、模型工具、初始化和结构化存储
-  - `store/` 负责 AgentStorage、Session 和 JSONL Message 的本地持久化
-  - `WorkspaceEnv.ts` 负责 Workspace 环境变量装配
-  - `tool/WorkspaceTools.ts` 组合文件、搜索与可选 Shell 工具
-  - `WorkspacePaths.ts` 负责 AgentStorage 私有数据路径布局
-
 - `src/session/`
   - `Session.ts` 是公开 facade 与 Session 对象装配入口
   - `SessionState.ts` 管理配置与 metadata
-  - `SessionLoop.ts` 管理输入队列和 Turn 生命周期
-  - `SessionMessages.ts` 是 canonical Message 唯一事实源
-  - `DefaultSessionComposer.ts` 负责 system/history/tools 与压缩计划定制
-  - `messages/` 放 Assistant writer、Message codec 与 compaction；JSONL Store 位于 `workspace/store/`
-  - Session 由 `AgentSessions` 统一持有；Workspace 只作为 `agent.sessions.create/get({ workspace })` 的单次执行输入
+  - `SessionLoop.ts` 是 Command Queue 的唯一消费者，并管理 Turn 生命周期
+  - Prompt Command 创建或加入 Turn；配置与压缩等 Maintenance Command 在空闲期独立执行
+  - `SessionComposition.ts` 管理 system snapshot、检查点 env/hook 与 Composer 输入
+  - `session.db` 是 canonical Message 唯一事实源，`SessionMessages.ts` 负责领域写入、恢复和有界运行态投影
+  - `DefaultSessionComposer.ts` 负责 system/history/tools，并默认使用 Part 级上下文策略
+  - `SessionTurnContext.effects` 只负责按发生顺序收集当前 Turn 的 Tool 副作用，不解释具体业务
+  - `messages/` 放 Assistant 状态转换与 writer、Message codec、Tool effect 投影与结构化文件编辑 Diff
+  - `composer/policies/` 放只读 canonical Message 并管理自有派生表的上下文策略
+  - `storage/` 负责 Session SQLite、附件和事务；只使用 AgentStorage，不访问项目 Workspace
+  - Session 由 `AgentSessions` 统一持有；Workspace 只作为 `agent.sessions.create({ workspace })` 或 `agent.sessions.get(session_id, origin_type, { workspace })` 的单次执行输入
+
+- `src/group/`
+  - `storage/` 负责 GroupSession 的 metadata、共享消息和调度记录持久化
 
 - `src/executor/`
   - 内部执行内核
   - `Executor` 只负责单轮 LLM/Tool Loop、Step 状态和上下文恢复
   - 不持有 History Store，不负责 Message 或 metadata 持久化
+  - 默认 system block 只由 `session/SessionSystem.ts` 组装，不维护第二套 system composer
 
 - `src/plugin/`
-  - Agent 侧 Plugin registry、执行视图、生命周期与工具桥接
-  - 具体内建 Plugin 实现位于 `@downcity/plugins`
+  - 只保留 Agent 公开的 Action schedule 与 Plugin 协议辅助
+  - Plugin Registry、Hook 调度与生命周期属于 `@downcity/city`
 
 - `src/remote/transports/` 放 HTTP、RPC transport 及其内部客户端；RPC Server 与 HTTP gateway 由上游宿主管理
-- Agent 与 Session 都持有宿主传入的 `AgentModel` 实例；`AgentModel` 可以是 AI SDK `LanguageModel` 或 City 返回的 `CityModel`
-- Session 可通过 `session.set({ model })` 覆盖，执行时固定按 Session 模型、Agent 模型的顺序解析，并在 LLM 调用边界转换为 `LanguageModel`
+- Agent、Session 与 Group 统一持有宿主传入的 `ModelClient`；City 返回的 `CityModel` 在该协议上额外提供目录与展示元数据
+- Session 可通过 `session.set({ model })` 覆盖，执行时固定按 Session 模型、Agent 模型的顺序解析，并直接通过统一的 `ModelClient` 协议调用
 
 - `src/types/`
   - 跨模块、跨包共享协议类型
-  - `common/` 放 JSON、模板等无领域依赖的基础类型
   - `config/` 放 LLM、execution binding、plugin 配置、start options 等宿主配置契约
   - `runtime/` 放 auth、agent、host、platform 等运行时与控制面共享协议
   - 领域内部类型仍保留在对应领域目录，例如 `plugin/types/`、`executor/types/`
@@ -132,15 +140,19 @@ src/
 
 其中：
 
-- `agent` 承载本地 Agent 核心运行时，`remote` 承载独立的远程 SDK 客户端
-- `workspace` 承载项目资源、初始化和持久化能力，`platform` 只处理系统级路径
-- `Agent` facade 是实例级装配中心，持有 instruction、model、tools、plugins 与 sessions；env 由 Workspace 持有
-- `PluginContext` 只在 Agent 内部向 Plugin 投影稳定能力，不向宿主暴露
-- `session / executor / plugin` 是三大核心分层
+- `agent` 承载本地 Agent 核心运行时
+- Workspace、Shell 与 Plugin 实现由 City 持有，Agent 只消费 `@downcity/type` 中的中立协议
+- `Agent` facade 是实例级装配中心，持有 instruction、model、tools 与 sessions；env 由 Workspace 持有，Plugin 由 City 持有
+- `PluginContext` 由 City 为 Agent/Workspace 执行范围创建，只向 Plugin 投影稳定的受限能力
+- `session / executor` 是 Agent 的核心执行分层，Plugin 通过 `SessionHooks` 进入 Session
 - `SessionMessages` 是 Message 唯一事实源，Executor 不持有 Store
 - `types / utils` 提供横向公共支撑
 
-持久化规则：加入 City 后，AgentSession 使用 `agents/<agent_id>/sessions/<session_id>/`，
+持久化规则：加入 City 后，AgentSession 使用 `agents/<agent_id>/sessions/<origin_type>/<session_id>/`，
+归档后使用 `agents/<agent_id>/archived-sessions/<origin_type>/<session_id>/`；每个 Session 目录包含
+`session.db` 与 `attachments/`，`origin_type` 会被安全编码为单个目录段。普通聊天默认位于 `sessions/chat/`。
 GroupSession 使用 `groups/<group_id>/sessions/<group_session_id>/`；未加入 City 时两者均使用
 当前主体实例的内存 Storage。只有传入 Workspace 的 AgentSession 或 GroupSession 才会在
-`meta.json` 写入 `workspace_id`。
+`session_state` 写入 `workspace_id`。GroupSession 使用 `Group.model` 根据首条用户消息异步生成并持久化
+`title`，`preview_text` 仍只保存最后一条消息摘要；`rename(title)` 可提交手动标题。AgentSession 的
+状态均由 `session_state` 保存，并始终保留完整且不可变的 `origin`。

package/bin/agent/Agent.d.ts

@@ -1,46 +1,51 @@
 /**
- * Agent：身份、模型、指令与 Plugin 的主体对象。
+ * Agent：身份、模型、指令与 Session 的主体对象。
  *
  * 职责说明（中文）
  * - Agent 不绑定 Workspace；调用方通过 `agent.sessions.create({ workspace })` 选择本次执行环境。
- * - PluginRegistry 只属于 Agent，所有 Workspace 共享同一份注册定义。
+ * - Plugin 与 Transport 由 City 持有，Agent 只通过 CityRuntime 使用最小执行能力。
  * - Session 由 AgentSessions 统一持有；Workspace 只在单个 Session 创建时提供执行资源。
  */
-import type { RuntimeTool as Tool } from "@downcity/type";
-import type { AgentModel } from "./AgentModel.js";
-import { PluginRegistry } from "../plugin/core/PluginRegistry.js";
+import type { CityRuntime, ModelClient, RuntimeTool as Tool, WorkspaceRuntime } from "@downcity/type";
 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";
+import type { SessionSystemMessage } from "../executor/types/SessionPrompts.js";
+import type { SessionComposer } from "../types/session/SessionComposer.js";
 /** SDK Agent 主体。 */
 export declare class Agent {
     /** Agent 的全局稳定标识。 */
     readonly id: string;
+    /** Agent 的用户可见名称。 */
+    readonly name: string;
+    /** Agent 的一句话能力描述，供展示与 Group 调度使用。 */
+    readonly description: string;
     /** Agent 默认模型；Session 可以显式覆盖。 */
-    readonly model?: AgentModel;
+    readonly model?: ModelClient;
     /** 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;
+    /** 为每个 Session 创建独立 Composer 的工厂。 */
+    readonly session_composer?: () => SessionComposer;
     /** Agent 级日志器，不绑定任何 Workspace。 */
     private readonly logger;
     /** 当前 Agent configured instruction。 */
     private readonly instruction;
     /** Agent 释放状态。 */
     private dispose_promise?;
-    /** Agent 级 Plugin lifecycle 启动流程。 */
-    private readonly plugin_ready;
     /** Agent 唯一的 Session 集合。 */
     private readonly session_manager;
+    /** 未加入宿主时使用的隔离进程内存储。 */
+    private storage_provider;
+    /** Agent 当前所属的唯一 City；独立运行时为空。 */
+    private city?;
+    /** 延迟创建的 Agent 私有持久化视图。 */
+    private agent_storage?;
+    /** 是否已经在无宿主存储中创建或恢复过 Session。 */
+    private memory_session_started;
     constructor(options: AgentOptions);
     /** 更新 Agent 的静态基础指令。 */
     set_instruction(input: string | string[]): void;
@@ -48,9 +53,26 @@ export declare class Agent {
     get_instructions(): readonly string[];
     /** 返回 Agent 级日志器。 */
     get_logger(): Logger;
-    /** 释放 Agent 进入的全部 Workspace 与 Agent Plugin。 */
+    /** 将 Agent 加入 City；必须在创建或恢复 Session 前完成。 */
+    attach(city: CityRuntime): void;
+    /** 解除指定 City 关系；其他 City 不能解除当前绑定。 */
+    detach(city: CityRuntime): void;
+    /** 停止绑定到指定 Workspace 的运行中 Session，并释放后台标题任务。 */
+    release_workspace(workspace_id: string): Promise<void>;
+    /** 解析指定 Workspace 下一个 Session 当前可见的 system messages。 */
+    resolve_system_messages(workspace: WorkspaceRuntime, input: {
+        /** 目标 Session 稳定标识。 */
+        session_id: string;
+    }): Promise<SessionSystemMessage[]>;
+    /** 释放 Agent 的 Session 后台任务、存储与宿主引用。 */
     dispose(): Promise<void>;
-    /** 等待 Agent 级 Plugin 完成启动，供内部运行时使用。 */
+    /** 等待 Agent 自身运行时 ready，供内部运行时使用。 */
     ensure_ready(): Promise<void>;
+    /** 获取或创建 Agent 唯一的 Session 存储。 */
+    private resolve_storage;
+    /** 校验宿主模式下使用的 Workspace 来自当前宿主事实源。 */
+    private assert_workspace;
+    /** 在明确检查点合并 Workspace、宿主扩展和 Agent Tool。 */
+    private resolve_tools;
 }
 //# 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,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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,WAAW,IAAI,IAAI,EAEnB,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAKxB,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACxB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,sBAAsB,EACvB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAMlD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAQ1E,oBAAoB;AACpB,qBAAa,KAAK;IAChB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAE7B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAE1C,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5C,2BAA2B;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,uBAAuB,CAAC;IAEjD,qCAAqC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,eAAe,CAAC;IAElD,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,4BAA4B;IAC5B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgB;IAEhD,wBAAwB;IACxB,OAAO,CAAC,gBAAgB,CAAqD;IAE7E,kCAAkC;IAClC,OAAO,CAAC,IAAI,CAAC,CAAc;IAE3B,2BAA2B;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAe;IAErC,iCAAiC;IACjC,OAAO,CAAC,sBAAsB,CAAS;gBAE3B,OAAO,EAAE,YAAY;IAoDjC,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,4CAA4C;IAC5C,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAe/B,qCAAqC;IACrC,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAI/B,gDAAgD;IAC1C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D,wDAAwD;IAClD,uBAAuB,CAC3B,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE;QACL,uBAAuB;QACvB,UAAU,EAAE,MAAM,CAAC;KACpB,GACA,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAqClC,uCAAuC;IACjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB9B,qCAAqC;IAC/B,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC,kCAAkC;IAClC,OAAO,CAAC,eAAe;IAkBvB,sCAAsC;IACtC,OAAO,CAAC,gBAAgB;IAQxB,2CAA2C;IAC3C,OAAO,CAAC,aAAa;CAYtB"}

package/bin/agent/Agent.js

@@ -1,114 +1,104 @@
 /**
- * Agent：身份、模型、指令与 Plugin 的主体对象。
+ * Agent：身份、模型、指令与 Session 的主体对象。
  *
  * 职责说明（中文）
  * - Agent 不绑定 Workspace；调用方通过 `agent.sessions.create({ workspace })` 选择本次执行环境。
- * - PluginRegistry 只属于 Agent，所有 Workspace 共享同一份注册定义。
+ * - Plugin 与 Transport 由 City 持有，Agent 只通过 CityRuntime 使用最小执行能力。
  * - Session 由 AgentSessions 统一持有；Workspace 只在单个 Session 创建时提供执行资源。
  */
-import { normalize_instruction_input } from "./AgentInstructions.js";
-import { PluginRegistry } from "../plugin/core/PluginRegistry.js";
+import { create_instruction_system_blocks, normalize_instruction_input, } from "../agent/AgentInstructions.js";
 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";
+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 { build_session_system_blocks, resolve_session_plugin_system_blocks, } from "../session/SessionSystem.js";
+import { create_session_hook_context } from "../session/runtime/SessionTurnContext.js";
+import { resolve_system_timezone } from "../session/storage/Metadata.js";
 /** SDK Agent 主体。 */
 export class Agent {
     /** Agent 的全局稳定标识。 */
     id;
+    /** Agent 的用户可见名称。 */
+    name;
+    /** Agent 的一句话能力描述，供展示与 Group 调度使用。 */
+    description;
     /** Agent 默认模型；Session 可以显式覆盖。 */
     model;
     /** Agent 面向用户的 Session 创建入口。 */
     sessions;
-    /** 当前 Agent 持有的 Web 搜索与文档能力。 */
-    web;
-    /** Agent 注册的唯一 PluginRegistry。 */
-    plugins;
     /** Agent 自定义 Tool；进入每个 Workspace 时与项目 Tool 合并。 */
     custom_tools;
     /** Agent 使用的 Session 类。 */
     session_class;
-    /** AgentPlugin 的内部访问名，仍指向 Agent 唯一 Registry。 */
-    plugin_registry;
+    /** 为每个 Session 创建独立 Composer 的工厂。 */
+    session_composer;
     /** Agent 级日志器，不绑定任何 Workspace。 */
     logger = new Logger();
     /** 当前 Agent configured instruction。 */
     instruction;
     /** Agent 释放状态。 */
     dispose_promise;
-    /** Agent 级 Plugin lifecycle 启动流程。 */
-    plugin_ready;
     /** Agent 唯一的 Session 集合。 */
     session_manager;
+    /** 未加入宿主时使用的隔离进程内存储。 */
+    storage_provider = new AgentMemoryStorageProvider();
+    /** Agent 当前所属的唯一 City；独立运行时为空。 */
+    city;
+    /** 延迟创建的 Agent 私有持久化视图。 */
+    agent_storage;
+    /** 是否已经在无宿主存储中创建或恢复过 Session。 */
+    memory_session_started = false;
     constructor(options) {
         this.id = String(options.id || "").trim();
         if (!this.id)
             throw new Error("Agent requires a non-empty id");
-        initialize_agent_runtime(this);
+        this.name = String(options.name || "").trim() || this.id;
+        this.description = String(options.description || "").trim();
         this.model = options.model;
-        this.web = options.web;
         this.instruction = normalize_instruction_input(options.instruction);
-        const agent = this;
-        const agent_plugin_context = Object.freeze({
-            agent_id: this.id,
-            logger: this.logger,
-            web: this.web,
-            get embassy() {
-                return agent_embassy(agent);
-            },
-            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.session_composer = options.session_composer;
         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,
             logger: this.logger,
             get_instruction: () => [...this.get_instructions()],
-            ensure_agent_ready: async () => { await this.plugin_ready; },
+            ensure_agent_ready: async () => await this.ensure_ready(),
             get_agent_model: () => this.model,
             session_class: this.session_class,
-            on_session_routed: () => mark_agent_session_started(agent),
+            create_session_composer: this.session_composer,
+            on_session_routed: () => {
+                if (!this.city)
+                    this.memory_session_started = true;
+            },
             resolve_session_context: (workspace) => {
+                const storage = this.resolve_storage();
                 if (!workspace)
                     return {
                         workspace_path: ".",
                         logger: this.logger,
-                        tools: this.custom_tools,
+                        get_tools: () => ({ ...this.custom_tools }),
                         get_workspace_env: () => ({}),
-                        get_agent_plugins: no_workspace_plugins,
-                        store: session_store,
+                        get_hooks: () => EMPTY_SESSION_HOOKS,
+                        store: storage.sessions,
                     };
-                return create_workspace_entry(this, workspace).get_session_context();
+                this.assert_workspace(workspace);
+                // 静态 Workspace Tool 与 Agent Tool 的命名冲突属于 Session 创建不变量，
+                // 在装配时立即失败；执行时仍通过 getter 读取最新宿主扩展。
+                this.resolve_tools(workspace);
+                return {
+                    workspace_path: workspace.path,
+                    workspace_id: workspace.id,
+                    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,
+                    store: storage.sessions,
+                };
             },
         });
         this.sessions = this.session_manager;
@@ -126,26 +116,134 @@ export class Agent {
     get_logger() {
         return this.logger;
     }
-    /** 释放 Agent 进入的全部 Workspace 与 Agent Plugin。 */
+    /** 将 Agent 加入 City；必须在创建或恢复 Session 前完成。 */
+    attach(city) {
+        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`);
+        }
+        if (this.memory_session_started || this.agent_storage) {
+            throw new Error(`Agent "${this.id}" already used standalone storage; attach it before using Sessions`);
+        }
+        this.city = city;
+        this.storage_provider = city.storage;
+    }
+    /** 解除指定 City 关系；其他 City 不能解除当前绑定。 */
+    detach(city) {
+        if (this.city === city)
+            this.city = undefined;
+    }
+    /** 停止绑定到指定 Workspace 的运行中 Session，并释放后台标题任务。 */
+    async release_workspace(workspace_id) {
+        await this.session_manager.stop_executing_sessions(workspace_id);
+        this.session_manager.dispose_title_generation(workspace_id);
+    }
+    /** 解析指定 Workspace 下一个 Session 当前可见的 system messages。 */
+    async resolve_system_messages(workspace, input) {
+        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({
+            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),
+        });
+        const plugin_system_blocks = await resolve_session_plugin_system_blocks({
+            session_id,
+            hooks,
+            context: hook_context,
+        });
+        const blocks = await build_session_system_blocks({
+            agent_id: this.id,
+            project_root: workspace.path,
+            session_id,
+            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,
+        });
+        return blocks.map((block) => ({ role: "system", content: block.content }));
+    }
+    /** 释放 Agent 的 Session 后台任务、存储与宿主引用。 */
     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();
+            const results = await Promise.allSettled([
+                this.session_manager.stop_executing_sessions(),
+            ]);
             this.session_manager.dispose_title_generation();
-            await dispose_agent_runtime(this);
+            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] : []);
-            release_agent_from_city(this);
-            clear_agent_runtime(this);
+            this.city = undefined;
+            this.agent_storage = undefined;
             if (errors.length > 0)
                 throw new AggregateError(errors, "Agent dispose failed");
         })();
         await this.dispose_promise;
     }
-    /** 等待 Agent 级 Plugin 完成启动，供内部运行时使用。 */
+    /** 等待 Agent 自身运行时 ready，供内部运行时使用。 */
     async ensure_ready() {
-        await this.plugin_ready;
+        await this.city?.ensure_ready();
+    }
+    /** 获取或创建 Agent 唯一的 Session 存储。 */
+    resolve_storage() {
+        if (this.agent_storage)
+            return this.agent_storage;
+        const scope = this.storage_provider.open_scope(["agents", this.id]);
+        this.logger.bind_storage(scope.files, scope.root_path, { agent_id: this.id });
+        this.agent_storage = {
+            root_path: scope.root_path,
+            files: scope.files,
+            database_location: scope.database_location,
+            sessions: new LocalSessionStore({
+                files: scope.files,
+                storage_root_path: scope.root_path,
+                agent_id: this.id,
+                database_location: scope.database_location,
+            }),
+        };
+        return this.agent_storage;
+    }
+    /** 校验宿主模式下使用的 Workspace 来自当前宿主事实源。 */
+    assert_workspace(workspace) {
+        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。 */
+    resolve_tools(workspace) {
+        const tools = {};
+        register_tools(tools, workspace.tools, "WorkspaceTools");
+        register_tools(tools, this.city?.get_session_tools(this.id, workspace) ?? {}, "City");
+        register_tools(tools, this.custom_tools, "AgentOptions.tools");
+        return tools;
+    }
+}
+/** 注册 Tool 集合，并拒绝不同来源静默覆盖。 */
+function register_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;
     }
 }
 //# sourceMappingURL=Agent.js.map