@downcity/agent 1.1.74 → 1.1.81

package/bin/session/services/SessionViewService.js

@@ -0,0 +1,184 @@
+/**
+ * SessionViewService：本地 Session 查询与派生视图服务。
+ *
+ * 关键点（中文）
+ * - 统一管理 info/history/system/fork 这类读取型能力。
+ * - 该服务只负责拼装查询结果，不负责编排 prompt turn。
+ * - 需要写入持久化状态的地方仍委托给 SessionStateService。
+ */
+import { nanoid } from "nanoid";
+import { buildSessionHistoryPage, buildSessionInfo, ensureSessionTitle, readSessionMetadata, } from "../../session/index.js";
+import { buildSessionSystemBlocks } from "../../session/SessionSystemBuilder.js";
+/**
+ * 本地 Session 查询与派生视图服务。
+ */
+export class SessionViewService {
+    agent_id;
+    project_root;
+    session_id;
+    history_store;
+    state_service;
+    is_executing;
+    get_instruction_system_blocks;
+    get_managed_plugin_system_blocks;
+    get_plugin_system_blocks;
+    custom_system_composer;
+    create_fork_session;
+    constructor(options) {
+        this.agent_id = options.agent_id;
+        this.project_root = options.project_root;
+        this.session_id = options.session_id;
+        this.history_store = options.history_store;
+        this.state_service = options.state_service;
+        this.is_executing = options.is_executing;
+        this.get_instruction_system_blocks = options.get_instruction_system_blocks;
+        this.get_managed_plugin_system_blocks =
+            options.get_managed_plugin_system_blocks;
+        this.get_plugin_system_blocks = options.get_plugin_system_blocks;
+        this.custom_system_composer = options.custom_system_composer;
+        this.create_fork_session = options.create_fork_session;
+    }
+    /**
+     * 读取当前 session 详情。
+     */
+    async get_info() {
+        const [metadata, messages] = await Promise.all([
+            readSessionMetadata({
+                projectRoot: this.project_root,
+                agentId: this.agent_id,
+                sessionId: this.session_id,
+            }),
+            this.history_store.list(),
+        ]);
+        const metadata_with_title = metadata.title
+            ? metadata
+            : await ensureSessionTitle({
+                projectRoot: this.project_root,
+                agentId: this.agent_id,
+                sessionId: this.session_id,
+                messages,
+            });
+        return buildSessionInfo({
+            projectRoot: this.project_root,
+            agentId: this.agent_id,
+            sessionId: this.session_id,
+            metadata: metadata_with_title,
+            messages,
+            executing: this.is_executing(),
+        });
+    }
+    /**
+     * 读取当前 session 历史分页。
+     */
+    async history(input) {
+        const [session, messages] = await Promise.all([
+            this.get_info(),
+            this.history_store.list(),
+        ]);
+        return buildSessionHistoryPage({
+            session,
+            messages,
+            input,
+        });
+    }
+    /**
+     * 读取当前 session 生效的 system 快照。
+     */
+    async system() {
+        const blocks = this.custom_system_composer
+            ? await this.resolve_custom_system_blocks(this.custom_system_composer)
+            : await buildSessionSystemBlocks({
+                agentId: this.agent_id,
+                projectRoot: this.project_root,
+                sessionId: this.session_id,
+                createdAt: this.state_service.get_created_at(),
+                timezone: this.state_service.get_timezone(),
+                getInstructionSystemBlocks: this.get_instruction_system_blocks,
+                getManagedPluginSystemBlocks: this.get_managed_plugin_system_blocks,
+                getPluginSystemBlocks: this.get_plugin_system_blocks,
+            });
+        return {
+            sessionId: this.session_id,
+            session: {
+                agentId: this.agent_id,
+                sessionId: this.session_id,
+                projectRoot: this.project_root,
+                createdAt: new Date(this.state_service.get_created_at()).toISOString(),
+                timezone: this.state_service.get_timezone(),
+            },
+            blocks,
+        };
+    }
+    async resolve_custom_system_blocks(composer) {
+        const run_context = {
+            sessionId: this.session_id,
+            injectedUserMessages: [],
+            deferredPersistedUserMessages: [],
+            pendingAssistantFileParts: [],
+        };
+        const messages = await composer.resolve(run_context);
+        const blocks = [];
+        messages.forEach((message, index) => {
+            const content = this.stringify_system_content(message.content);
+            if (!content)
+                return;
+            blocks.push({
+                source: "session",
+                name: `${composer.name || "custom_system"}:${index + 1}`,
+                content,
+            });
+        });
+        return blocks;
+    }
+    /**
+     * 从当前 session 创建一个分叉会话。
+     */
+    async fork(input) {
+        const message_id = typeof input === "string"
+            ? String(input || "").trim() || undefined
+            : String(input?.messageId || "").trim() || undefined;
+        const messages = await this.history_store.list();
+        const fork_messages = !message_id
+            ? messages
+            : this.resolve_fork_messages(messages, message_id);
+        const forked_bundle = await this.create_fork_session(`fork-${Date.now()}-${nanoid(8)}`);
+        const forked = forked_bundle.session;
+        const session_config = this.state_service.get_config();
+        if (session_config.model) {
+            await forked.set({
+                model: session_config.model,
+            });
+        }
+        await this.append_fork_messages(forked_bundle, fork_messages);
+        return forked;
+    }
+    resolve_fork_messages(messages, message_id) {
+        const target_index = messages.findIndex((message) => String(message.id || "").trim() === message_id);
+        if (target_index < 0) {
+            throw new Error(`Cannot fork session "${this.session_id}": messageId "${message_id}" not found.`);
+        }
+        return messages.slice(0, target_index + 1);
+    }
+    async append_fork_messages(forked_bundle, messages) {
+        for (const message of messages) {
+            await forked_bundle.history_store.append(message);
+        }
+        await forked_bundle.state_service.ensure_title_from_history({
+            generate: true,
+        });
+        await forked_bundle.state_service.touch_metadata();
+    }
+    stringify_system_content(content) {
+        if (typeof content === "string")
+            return content.trim();
+        if (content === null || content === undefined)
+            return "";
+        try {
+            return JSON.stringify(content);
+        }
+        catch {
+            return String(content || "").trim();
+        }
+    }
+}
+//# sourceMappingURL=SessionViewService.js.map

package/bin/session/services/SessionViewService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionViewService.js","sourceRoot":"","sources":["../../../src/session/services/SessionViewService.ts"],"names":[],"mappings":"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"}

package/bin/session/storage/Paths.d.ts

@@ -41,4 +41,13 @@ export declare function getSdkAgentSessionMetaPath(projectRoot: string, agentId:
  * 单个 session 的 archive 目录路径。
  */
 export declare function getSdkAgentSessionArchiveDirPath(projectRoot: string, agentId: string, sessionId: string): string;
+/**
+ * 单个 session 的 inflight assistant 路径。
+ *
+ * 关键点（中文）
+ * - 运行中的 assistant 只保留一份增量快照。
+ * - step / tool 过程会持续重写这个文件，避免中途中断后过程完全丢失。
+ * - 完成后再把最终 assistant 合并进 `messages.jsonl`，并清理该文件。
+ */
+export declare function getSdkAgentSessionInflightPath(projectRoot: string, agentId: string, sessionId: string): string;
 //# sourceMappingURL=Paths.d.ts.map

package/bin/session/storage/Paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Paths.d.ts","sourceRoot":"","sources":["../../../src/session/storage/Paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR"}
+{"version":3,"file":"Paths.d.ts","sourceRoot":"","sources":["../../../src/session/storage/Paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR"}

package/bin/session/storage/Paths.js

@@ -60,4 +60,15 @@ export function getSdkAgentSessionMetaPath(projectRoot, agentId, sessionId) {
 export function getSdkAgentSessionArchiveDirPath(projectRoot, agentId, sessionId) {
     return path.join(getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId), "archive");
 }
+/**
+ * 单个 session 的 inflight assistant 路径。
+ *
+ * 关键点（中文）
+ * - 运行中的 assistant 只保留一份增量快照。
+ * - step / tool 过程会持续重写这个文件，避免中途中断后过程完全丢失。
+ * - 完成后再把最终 assistant 合并进 `messages.jsonl`，并清理该文件。
+ */
+export function getSdkAgentSessionInflightPath(projectRoot, agentId, sessionId) {
+    return path.join(getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId), "inflight.json");
+}
 //# sourceMappingURL=Paths.js.map

package/bin/session/storage/Paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"Paths.js","sourceRoot":"","sources":["../../../src/session/storage/Paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IACzD,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,OAAe;IAEf,OAAO,IAAI,CAAC,IAAI,CACd,uBAAuB,CAAC,WAAW,CAAC,EACpC,kBAAkB,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CACjD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,WAAmB,EACnB,OAAe;IAEf,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,8BAA8B,CAAC,WAAW,EAAE,OAAO,CAAC,EACpD,kBAAkB,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CACnD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iCAAiC,CAC/C,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,yBAAyB,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAC1D,UAAU,CACX,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAClE,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAClE,WAAW,CACZ,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gCAAgC,CAC9C,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAClE,SAAS,CACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"Paths.js","sourceRoot":"","sources":["../../../src/session/storage/Paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IACzD,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,OAAe;IAEf,OAAO,IAAI,CAAC,IAAI,CACd,uBAAuB,CAAC,WAAW,CAAC,EACpC,kBAAkB,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CACjD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,WAAmB,EACnB,OAAe;IAEf,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,8BAA8B,CAAC,WAAW,EAAE,OAAO,CAAC,EACpD,kBAAkB,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CACnD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iCAAiC,CAC/C,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,yBAAyB,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAC1D,UAAU,CACX,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAClE,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAClE,WAAW,CACZ,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gCAAgC,CAC9C,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAClE,SAAS,CACV,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,8BAA8B,CAC5C,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,EAClE,eAAe,CAChB,CAAC;AACJ,CAAC"}

package/bin/types/agent/AgentOptions.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Agent 本地实例配置与生命周期类型。
+ *
+ * 关键点（中文）
+ * - 只描述本地 Agent 的构造、启动、停止与 RPC 绑定。
+ * - RemoteAgent 与 Session 数据结构拆到独立类型文件。
+ */
+import type { Tool } from "ai";
+import type { BasePlugin } from "../../plugin/core/BasePlugin.js";
+import type { AgentModel } from "../../model/CityModelAdapter.js";
+import type { RpcServerInstance } from "../../rpc/Server.js";
+import type { AgentManagedSession, SessionOptions } from "../../types/session/SessionOptions.js";
+/**
+ * Agent 可使用的 Session 类。
+ *
+ * 关键点（中文）
+ * - 传 class，而不是传实例，保证 Agent 可以按 sessionId 创建多个 session。
+ * - 自定义类可继承默认 `Session`，并在构造函数里注入自己的 Composer。
+ */
+export type AgentSessionConstructor = new (options: SessionOptions) => AgentManagedSession;
+/**
+ * 本地 Agent 构造参数。
+ */
+export interface AgentOptions {
+    /**
+     * 当前 agent 的稳定标识。
+     *
+     * 关键点（中文）
+     * - 用于 `.downcity/agents/<agentId>/...` 目录分区。
+     * - 应保持稳定、可 URL 编码、尽量不要依赖展示名称。
+     */
+    id: string;
+    /** 当前 agent 绑定的项目根目录。 */
+    path: string;
+    /**
+     * 当前 agent 默认可用的工具集合。
+     *
+     * 关键点（中文）
+     * - tools 归属于 agent 级，而不是 session 级。
+     * - session 运行时会直接复用这份工具集合。
+     */
+    tools?: Record<string, Tool>;
+    /**
+     * 调用方显式传入的静态基础指令。
+     *
+     * 关键点（中文）
+     * - `instruction` 是稳定、缓存友好的 system 前缀，不做动态变量替换。
+     * - SDK 不主动读取 `PROFILE.md` / `SOUL.md`；这类项目文件应由 city 或调用方读取后传入。
+     * - 未传入时，SDK 会使用包内最小 core instruction 作为 fallback。
+     */
+    instruction?: string | string[];
+    /**
+     * 当前 agent 为新建 session 提供的默认模型实例。
+     *
+     * 关键点（中文）
+     * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的模型实例。
+     * - 支持 AI SDK `LanguageModel`，也支持 City City 返回的 `CityModel`。
+     * - 该模型会作为 session 首次执行前的默认注入值。
+     */
+    model?: AgentModel;
+    /**
+     * 当前 agent 显式持有的插件实例集合。
+     *
+     * 关键点（中文）
+     * - 这里接收已经实例化好的 `BasePlugin` 对象，而不是 plugin class。
+     * - `Agent` 会在构造阶段按名称注册这些实例，并自动绑定到当前 runtime。
+     * - 同名 plugin 会直接报错，避免 action / hook / resolve 行为被静默覆盖。
+     * - SDK 不再自动注入任何 built-in plugin；需要的能力都应由宿主显式传入。
+     */
+    plugins?: BasePlugin[];
+    /**
+     * 当前 agent 使用的本地 Session 类。
+     *
+     * 关键点（中文）
+     * - Agent 只负责用这个类创建/恢复 session，不感知具体 Composer 策略。
+     * - 如果需要自定义 Composer，请在自定义 Session 类内部传给 `super({ composers })`。
+     * - 该能力仅适用于本地 `Agent`。
+     */
+    Session?: AgentSessionConstructor;
+    /**
+     * 当前 agent 的显式环境变量覆盖项。
+     *
+     * 关键点（中文）
+     * - 这里表示宿主显式注入给 agent 的基础 env。
+     * - `Agent` 会在这份基础 env 之上继续叠加项目 `.env`。
+     * - 覆盖后的最终 env 会参与配置解析与运行时上下文装配，但不会回写到宿主环境。
+     */
+    env?: Record<string, string>;
+}
+/**
+ * Agent 启动参数。
+ */
+export interface AgentStartOptions {
+    /**
+     * 是否启动本机 RPC 服务。
+     *
+     * 关键点（中文）
+     * - `false` 表示不启动。
+     * - 传对象时会按给定 host/port 启动。
+     * - 省略时默认不启动，避免 SDK 本地嵌入场景误开端口。
+     */
+    rpc?: false | AgentRpcStartOptions;
+    /**
+     * 是否启动当前 agent 的 plugins。
+     *
+     * 关键点（中文）
+     * - 默认 `true`。
+     * - `false` 适合只需要 session 能力、不希望启动后台能力的嵌入场景。
+     */
+    plugins?: boolean;
+}
+/**
+ * Agent 停止结果快照。
+ */
+export interface AgentStopResult {
+    /** 本次是否实际停止了本机 RPC 服务。 */
+    rpcStopped: boolean;
+    /** 本次是否实际停止了 plugins。 */
+    pluginsStopped: boolean;
+}
+/**
+ * Agent 启动后的状态快照。
+ */
+export interface AgentStartResult {
+    /** 当前 agent 是否已启动本机 RPC 服务。 */
+    rpc?: AgentRpcBinding;
+    /** 当前 agent 是否已启动 plugins。 */
+    pluginsStarted: boolean;
+}
+/**
+ * Agent RPC 启动参数。
+ */
+export interface AgentRpcStartOptions {
+    /** RPC 监听主机。 */
+    host?: string;
+    /** RPC 监听端口。 */
+    port?: number;
+}
+/**
+ * Agent RPC 绑定信息。
+ */
+export interface AgentRpcBinding {
+    /** 远程访问地址。 */
+    url: string;
+    /** 当前 host。 */
+    host: string;
+    /** 当前 port。 */
+    port: number;
+    /** RPC server 句柄。 */
+    server: RpcServerInstance;
+}
+//# sourceMappingURL=AgentOptions.d.ts.map

package/bin/types/agent/AgentOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentOptions.d.ts","sourceRoot":"","sources":["../../../src/types/agent/AgentOptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACf,MAAM,mCAAmC,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,KACpC,OAAO,EAAE,cAAc,KACpB,mBAAmB,CAAC;AAEzB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE7B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEhC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IAEvB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAElC;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,KAAK,GAAG,oBAAoB,CAAC;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,yBAAyB;IACzB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,8BAA8B;IAC9B,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,cAAc;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe;IACf,IAAI,EAAE,MAAM,CAAC;IACb,eAAe;IACf,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,MAAM,EAAE,iBAAiB,CAAC;CAC3B"}

package/bin/types/agent/AgentOptions.js

@@ -0,0 +1,9 @@
+/**
+ * Agent 本地实例配置与生命周期类型。
+ *
+ * 关键点（中文）
+ * - 只描述本地 Agent 的构造、启动、停止与 RPC 绑定。
+ * - RemoteAgent 与 Session 数据结构拆到独立类型文件。
+ */
+export {};
+//# sourceMappingURL=AgentOptions.js.map

package/bin/types/agent/AgentOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentOptions.js","sourceRoot":"","sources":["../../../src/types/agent/AgentOptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/{runtime/host/AgentHost.d.ts → agent/AgentRuntimeAssembly.d.ts}

@@ -1,12 +1,12 @@
 /**
- * Agent 宿主能力类型定义。
+ * AgentRuntimeAssembly 类型定义。
  *
  * 关键点（中文）
- * - 这里统一描述由 agent runtime 装配、再挂入 AgentRuntime 的宿主能力。
+ * - 这里统一描述由本地 agent 装配、再挂入 AgentRuntime 的能力。
  * - plugin runtime / session / plugin 作者 API 只能消费这些稳定能力，不应直接依赖具体宿主实现。
  * - 当前先收敛路径与 plugin 配置持久化两类高频能力。
  */
-import type { DowncityConfig } from "../../../types/config/DowncityConfig.js";
+import type { DowncityConfig } from "../../types/config/DowncityConfig.js";
 /**
  * Agent 路径能力集合。
  */
@@ -69,4 +69,4 @@ export interface AgentPluginConfigRuntime {
      */
     persistProjectPlugins(plugins: DowncityConfig["plugins"] | undefined): Promise<string>;
 }
-//# sourceMappingURL=AgentHost.d.ts.map
+//# sourceMappingURL=AgentRuntimeAssembly.d.ts.map

package/bin/types/agent/AgentRuntimeAssembly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRuntimeAssembly.d.ts","sourceRoot":"","sources":["../../../src/types/agent/AgentRuntimeAssembly.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,kBAAkB,IAAI,MAAM,CAAC;IAC7B;;OAEG;IACH,eAAe,IAAI,MAAM,CAAC;IAC1B;;OAEG;IACH,yBAAyB,IAAI,MAAM,CAAC;IACpC;;OAEG;IACH,0BAA0B,IAAI,MAAM,CAAC;IACrC;;OAEG;IACH,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACtD;;OAEG;IACH,6BAA6B,IAAI,MAAM,CAAC;IACxC;;OAEG;IACH,6BAA6B,IAAI,MAAM,CAAC;IACxC;;OAEG;IACH,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACjD;;OAEG;IACH,6BAA6B,IAAI,MAAM,CAAC;IACxC;;OAEG;IACH,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxF"}

package/bin/types/{runtime/host/AgentHost.js → agent/AgentRuntimeAssembly.js}

@@ -1,10 +1,10 @@
 /**
- * Agent 宿主能力类型定义。
+ * AgentRuntimeAssembly 类型定义。
  *
  * 关键点（中文）
- * - 这里统一描述由 agent runtime 装配、再挂入 AgentRuntime 的宿主能力。
+ * - 这里统一描述由本地 agent 装配、再挂入 AgentRuntime 的能力。
  * - plugin runtime / session / plugin 作者 API 只能消费这些稳定能力，不应直接依赖具体宿主实现。
  * - 当前先收敛路径与 plugin 配置持久化两类高频能力。
  */
 export {};
-//# sourceMappingURL=AgentHost.js.map
+//# sourceMappingURL=AgentRuntimeAssembly.js.map

package/bin/types/agent/AgentRuntimeAssembly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRuntimeAssembly.js","sourceRoot":"","sources":["../../../src/types/agent/AgentRuntimeAssembly.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}