@downcity/agent 1.1.32 → 1.1.43

package/bin/types/common/EnvFile.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Env 文件工具相关类型定义。
+ *
+ * 职责说明（中文）
+ * - 统一描述 `.env` / `.env.example` 写入工具使用的最小数据结构。
+ * - 避免工具模块直接内联匿名对象，便于后续在其他初始化流程中复用。
+ * - 这里只描述“文件写入条目”，不承载运行时环境变量快照语义。
+ */
+/**
+ * Env 文件中的单条键值项。
+ */
+export interface EnvFileEntry {
+    /**
+     * 环境变量键名。
+     *
+     * 关键点（中文）
+     * - 调用方应传入已规范化的变量名。
+     * - 工具层不会自动把任意字符串修正成合法变量名。
+     */
+    key: string;
+    /**
+     * 环境变量值。
+     *
+     * 关键点（中文）
+     * - 会按字面量写入目标文件。
+     * - 当前工具不额外做引号包裹或 shell 转义。
+     */
+    value: string;
+}
+//# sourceMappingURL=EnvFile.d.ts.map

package/bin/types/common/EnvFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvFile.d.ts","sourceRoot":"","sources":["../../../src/types/common/EnvFile.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;CACf"}

package/bin/types/common/EnvFile.js

@@ -0,0 +1,10 @@
+/**
+ * Env 文件工具相关类型定义。
+ *
+ * 职责说明（中文）
+ * - 统一描述 `.env` / `.env.example` 写入工具使用的最小数据结构。
+ * - 避免工具模块直接内联匿名对象，便于后续在其他初始化流程中复用。
+ * - 这里只描述“文件写入条目”，不承载运行时环境变量快照语义。
+ */
+export {};
+//# sourceMappingURL=EnvFile.js.map

package/bin/types/common/EnvFile.js.map

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

package/bin/types/common/ResolvedConfigValue.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 配置值递归结构类型。
+ *
+ * 职责说明（中文）
+ * - 描述 `downcity.json` 在“读取原始 JSON -> 解析环境变量占位符”阶段可接受的值结构。
+ * - 允许对象、数组、JSON 标量与 `undefined` 递归嵌套，供配置解析工具复用。
+ * - 该类型只服务配置装配阶段，不承诺运行时最终配置的严格业务语义。
+ */
+export type ResolvedConfigValue = string | number | boolean | null | undefined | {
+    [key: string]: ResolvedConfigValue;
+} | ResolvedConfigValue[];
+//# sourceMappingURL=ResolvedConfigValue.d.ts.map

package/bin/types/common/ResolvedConfigValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResolvedConfigValue.d.ts","sourceRoot":"","sources":["../../../src/types/common/ResolvedConfigValue.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAAA;CAAE,GACtC,mBAAmB,EAAE,CAAC"}

package/bin/types/common/ResolvedConfigValue.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ResolvedConfigValue.js.map

package/bin/types/common/ResolvedConfigValue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResolvedConfigValue.js","sourceRoot":"","sources":["../../../src/types/common/ResolvedConfigValue.ts"],"names":[],"mappings":""}

package/bin/types/config/AgentProject.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Agent 项目初始化相关类型定义。
+ *
+ * 关键点（中文）
+ * - 统一承载 CLI 与 control plane 共用的初始化输入/输出结构。
+ * - 所有字段都面向"项目骨架创建"语义，不掺杂 runtime 状态。
+ */
+import type { ExecutionBindingConfig } from "../../types/config/ExecutionBinding.js";
+import type { DowncityConfig } from "../../types/config/DowncityConfig.js";
+/**
+ * 可选的 chat channel 标识。
+ */
+export type AgentProjectChannel = "telegram" | "feishu" | "qq";
+/**
+ * 初始化 agent 项目的输入参数。
+ */
+export interface AgentProjectInitializationInput {
+    /**
+     * agent 项目根目录（绝对路径或可解析相对路径）。
+     */
+    projectRoot: string;
+    /**
+     * agent 展示名。
+     *
+     * 关键点（中文）
+     * - 为空时会自动回退到目录名推导出的默认名称。
+     */
+    agentName?: string;
+    /**
+     * 项目执行绑定配置。
+     *
+     * 说明（中文）
+     * - 绑定平台全局模型池中的模型 ID。
+     */
+    execution: ExecutionBindingConfig;
+    /**
+     * 需要一并写入项目的 plugin 配置补丁。
+     *
+     * 说明（中文）
+     * - 这里只承载初始化时的最小配置，不负责 city 级 plugin lifecycle。
+     */
+    plugins?: DowncityConfig["plugins"];
+    /**
+     * 需要启用的 chat channels。
+     *
+     * 关键点（中文）
+     * - 仅写入用户选择的渠道，未选择的渠道不会写入 `downcity.json`。
+     */
+    channels?: AgentProjectChannel[];
+    /**
+     * 是否允许覆盖已存在的 `downcity.json`。
+     */
+    forceOverwriteShipJson?: boolean;
+}
+/**
+ * 初始化完成后的摘要结果。
+ */
+export interface AgentProjectInitializationResult {
+    /**
+     * 已解析后的 agent 项目根目录（绝对路径）。
+     */
+    projectRoot: string;
+    /**
+     * 最终写入的 agent 名称。
+     */
+    agentName: string;
+    /**
+     * 最终启用的 chat channels。
+     */
+    channels: AgentProjectChannel[];
+    /**
+     * 本次实际创建/写入的文件列表。
+     */
+    createdFiles: string[];
+    /**
+     * 因已存在而跳过的文件列表。
+     */
+    skippedFiles: string[];
+}
+//# sourceMappingURL=AgentProject.d.ts.map

package/bin/types/config/AgentProject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentProject.d.ts","sourceRoot":"","sources":["../../../src/types/config/AgentProject.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,QAAQ,GAAG,IAAI,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAElC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAEjC;;OAEG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAEhC;;OAEG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;OAEG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB"}

package/bin/types/config/AgentProject.js.map

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

package/bin/types/config/DowncityConfig.d.ts

@@ -3,12 +3,138 @@
  *
  * 关键点（中文）
  * - 作为全局共享类型，不挂在 console 目录下。
- * - 供 agent、services、control plane 宿主层多处复用，避免反向类型依赖。
+ * - 供 agent、plugin、control plane 宿主层多处复用，避免反向类型依赖。
  */
 import type { LlmConfig } from "../../types/config/LlmConfig.js";
 import type { ExecutionBindingConfig } from "../../types/config/ExecutionBinding.js";
 import type { JsonObject } from "../../types/common/Json.js";
 import type { SandboxProjectConfig } from "../../runtime/sandbox/types/Sandbox.js";
+/**
+ * 单个聊天渠道配置。
+ */
+export interface DowncityChatChannelConfig {
+    /**
+     * 当前渠道是否启用。
+     */
+    enabled?: boolean;
+    /**
+     * 绑定的渠道账户 ID。
+     */
+    channelAccountId?: string;
+}
+/**
+ * 聊天插件渠道配置集合。
+ */
+export interface DowncityChatPluginChannelsConfig {
+    /**
+     * Telegram 渠道配置。
+     */
+    telegram?: DowncityChatChannelConfig;
+    /**
+     * Feishu 渠道配置。
+     */
+    feishu?: DowncityChatChannelConfig;
+    /**
+     * QQ 渠道配置。
+     */
+    qq?: DowncityChatChannelConfig;
+}
+/**
+ * 聊天插件队列配置。
+ */
+export interface DowncityChatPluginQueueConfig {
+    /**
+     * 全局最大并发（不同 chatKey 之间）。
+     * 默认：2
+     */
+    maxConcurrency?: number;
+    /**
+     * 入站消息合并的防抖窗口（毫秒）。
+     *
+     * 关键点（中文）
+     * - 同一 chatKey 在该窗口内连续到达的多条消息，会在一次 run 前一起并入上下文。
+     * - 典型场景：用户先发一句话，再紧接着转发链接/卡片。
+     * - 设为 `0` 或负数可关闭该能力（立即执行首条消息）。
+     *
+     * 默认：600
+     */
+    mergeDebounceMs?: number;
+    /**
+     * 入站消息合并的最长等待时间（毫秒）。
+     *
+     * 关键点（中文）
+     * - 即使用户持续发送新消息，也不会无限延期；达到该上限后会立刻启动 run。
+     * - 用于平衡“尽量合并上下文”与“响应时延可控”。
+     * - 当 `mergeDebounceMs <= 0` 时该字段不会生效。
+     *
+     * 默认：2000
+     */
+    mergeMaxWaitMs?: number;
+}
+/**
+ * 聊天插件出站控制配置。
+ */
+export interface DowncityChatPluginEgressConfig {
+    /**
+     * 单次 agent run 内，`chat_send` 允许调用的最大次数。
+     */
+    chatSendMaxCallsPerRun?: number;
+    /**
+     * 是否启用 `chat_send` 幂等去重（基于 inbound messageId + 回复内容 hash）。
+     */
+    chatSendIdempotency?: boolean;
+}
+/**
+ * 聊天插件配置。
+ */
+export interface DowncityChatPluginConfig {
+    /**
+     * Chat 调度队列（按 chatKey 分 lane）。
+     */
+    queue?: DowncityChatPluginQueueConfig;
+    /**
+     * 出站（egress）控制：用于限制工具发送、避免重复与无限循环刷屏。
+     */
+    egress?: DowncityChatPluginEgressConfig;
+    /**
+     * 消息平台 channel 配置。
+     */
+    channels?: DowncityChatPluginChannelsConfig;
+}
+/**
+ * skill 插件配置。
+ */
+export interface DowncitySkillPluginConfig {
+    /**
+     * 当前插件是否启用。
+     */
+    enabled?: boolean;
+    /**
+     * 技能目录列表。
+     */
+    paths?: string[];
+    /**
+     * 是否允许读取项目外部技能目录。
+     */
+    allowExternalPaths?: boolean;
+}
+/**
+ * downcity.json 中的插件配置映射。
+ */
+export interface DowncityPluginConfigMap {
+    /**
+     * chat 插件配置。
+     */
+    chat?: DowncityChatPluginConfig;
+    /**
+     * skill 插件配置。
+     */
+    skill?: DowncitySkillPluginConfig;
+    /**
+     * 其他插件配置。
+     */
+    [pluginName: string]: JsonObject | DowncityChatPluginConfig | DowncitySkillPluginConfig | undefined;
+}
 export interface DowncityConfig {
     $schema?: string;
     name: string;
@@ -22,106 +148,16 @@ export interface DowncityConfig {
         port?: number;
         host?: string;
     };
-    /**
-     * services 配置。
-     *
-     * 关键点（中文）
-     * - 所有服务相关配置统一收敛到 `services` 下，避免顶层散落字段。
-     * - 例如：`services.chat.channels`、`services.chat.queue`。
-     */
-    services?: {
-        /**
-         * Chat service 配置。
-         */
-        chat?: {
-            /**
-             * Chat 调度队列（按 chatKey 分 lane）。
-             */
-            queue?: {
-                /**
-                 * 全局最大并发（不同 chatKey 之间）。
-                 * 默认：2
-                 */
-                maxConcurrency?: number;
-                /**
-                 * 入站消息合并的防抖窗口（毫秒）。
-                 *
-                 * 关键点（中文）
-                 * - 同一 chatKey 在该窗口内连续到达的多条消息，会在一次 run 前一起并入上下文。
-                 * - 典型场景：用户先发一句话，再紧接着转发链接/卡片。
-                 * - 设为 `0` 或负数可关闭该能力（立即执行首条消息）。
-                 *
-                 * 默认：600
-                 */
-                mergeDebounceMs?: number;
-                /**
-                 * 入站消息合并的最长等待时间（毫秒）。
-                 *
-                 * 关键点（中文）
-                 * - 即使用户持续发送新消息，也不会无限延期；达到该上限后会立刻启动 run。
-                 * - 用于平衡“尽量合并上下文”与“响应时延可控”。
-                 * - 当 `mergeDebounceMs <= 0` 时该字段不会生效。
-                 *
-                 * 默认：2000
-                 */
-                mergeMaxWaitMs?: number;
-            };
-            /**
-             * 出站（egress）控制：用于限制工具发送、避免重复与无限循环刷屏。
-             */
-            egress?: {
-                /**
-                 * 单次 agent run 内，`chat_send` 允许调用的最大次数。
-                 */
-                chatSendMaxCallsPerRun?: number;
-                /**
-                 * 是否启用 `chat_send` 幂等去重（基于 inbound messageId + 回复内容 hash）。
-                 */
-                chatSendIdempotency?: boolean;
-            };
-            /**
-             * 消息平台 channel 配置。
-             */
-            channels?: {
-                telegram?: {
-                    enabled: boolean;
-                    /**
-                     * 绑定的 channel account id（来源：平台全局 `~/.downcity/downcity.db`）。
-                     */
-                    channelAccountId?: string;
-                };
-                feishu?: {
-                    enabled: boolean;
-                    /**
-                     * 绑定的 channel account id（来源：平台全局 `~/.downcity/downcity.db`）。
-                     */
-                    channelAccountId?: string;
-                };
-                qq?: {
-                    enabled: boolean;
-                    /**
-                     * 绑定的 channel account id（来源：平台全局 `~/.downcity/downcity.db`）。
-                     */
-                    channelAccountId?: string;
-                };
-            };
-        };
-    };
     /**
      * plugins 配置。
      *
      * 关键点（中文）
-     * - 新插件体系的行为配置统一收敛到该字段。
-     * - plugin 私有配置（例如 `plugins.skill.paths`）也放在这里。
+     * - 所有可配置能力统一收敛到 `plugins`，不再保留独立 `services` 域。
+     * - plugin 私有配置（例如 `plugins.skill.paths`、`plugins.chat.channels`）也放在这里。
      * - key 为 plugin 名称，value 为对应插件的结构化配置对象。
      * - 当前阶段允许各 plugin 自定义字段，但必须保持 JSON 可序列化。
      */
-    plugins?: {
-        /**
-         * 插件配置对象映射。
-         */
-        [pluginName: string]: JsonObject;
-    };
+    plugins?: DowncityPluginConfigMap;
     /**
      * 项目执行绑定配置。
      *
@@ -134,7 +170,7 @@ export interface DowncityConfig {
      * shell / CLI 执行 sandbox 配置。
      *
      * 关键点（中文）
-     * - 当前只作用于 shell service 这条命令执行链。
+     * - 当前只作用于 shell plugin 这条命令执行链。
      * - 这里不表达审批、用户授权与复杂策略系统，只表达最小边界。
      */
     sandbox?: SandboxProjectConfig;
@@ -206,7 +242,7 @@ export interface DowncityConfig {
          */
         memory?: {
             /**
-             * 是否启用 memory service。
+             * 是否启用 memory plugin。
              */
             enabled?: boolean;
         };

package/bin/types/config/DowncityConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DowncityConfig.d.ts","sourceRoot":"","sources":["../../../src/types/config/DowncityConfig.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAE/E,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE;QACT;;WAEG;QACH,IAAI,CAAC,EAAE;YACL;;eAEG;YACH,KAAK,CAAC,EAAE;gBACN;;;mBAGG;gBACH,cAAc,CAAC,EAAE,MAAM,CAAC;gBACxB;;;;;;;;;mBASG;gBACH,eAAe,CAAC,EAAE,MAAM,CAAC;gBACzB;;;;;;;;;mBASG;gBACH,cAAc,CAAC,EAAE,MAAM,CAAC;aACzB,CAAC;YACF;;eAEG;YACH,MAAM,CAAC,EAAE;gBACP;;mBAEG;gBACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;gBAChC;;mBAEG;gBACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;aAC/B,CAAC;YACF;;eAEG;YACH,QAAQ,CAAC,EAAE;gBACT,QAAQ,CAAC,EAAE;oBACT,OAAO,EAAE,OAAO,CAAC;oBACjB;;uBAEG;oBACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;iBAC3B,CAAC;gBACF,MAAM,CAAC,EAAE;oBACP,OAAO,EAAE,OAAO,CAAC;oBACjB;;uBAEG;oBACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;iBAC3B,CAAC;gBACF,EAAE,CAAC,EAAE;oBACH,OAAO,EAAE,OAAO,CAAC;oBACjB;;uBAEG;oBACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;iBAC3B,CAAC;aACH,CAAC;SACH,CAAC;KACH,CAAC;IACF;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE;QACR;;WAEG;QACH,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAC;KAClC,CAAC;IACF;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE;QACR;;WAEG;QACH,QAAQ,CAAC,EAAE;YACT;;;;;;;;eAQG;YACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;YAC1B;;;;;;;;eAQG;YACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;YAC9B;;;eAGG;YACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;YAE3B;;;;;;;;;eASG;YACH,YAAY,CAAC,EAAE,MAAM,CAAC;SACvB,CAAC;QACF;;;;;;WAMG;QACH,MAAM,CAAC,EAAE;YACP;;eAEG;YACH,OAAO,CAAC,EAAE,OAAO,CAAC;SACnB,CAAC;KACH,CAAC;CACH"}
+{"version":3,"file":"DowncityConfig.d.ts","sourceRoot":"","sources":["../../../src/types/config/DowncityConfig.ts"],"names":[],"mappings":"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"}

package/bin/types/runtime/agent/AgentContext.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Agent 执行上下文类型定义。
+ *
+ * 职责说明（中文）
+ * - 这里定义 plugin runtime、plugin、prompt system 共用的统一执行上下文。
+ * - `AgentContext` 表达的是“当前一次执行可见的能力面”，不是宿主状态本体。
+ *
+ * 边界说明（中文）
+ * - `AgentRuntime` 负责保存长期状态；`AgentContext` 负责把这些状态暴露成执行接口。
+ * - 这里只定义协议，不负责任何上下文装配逻辑。
+ */
+import type { LanguageModel } from "ai";
+import type { Logger } from "../../../utils/logger/Logger.js";
+import type { AgentRuntime } from "../../../types/runtime/agent/AgentRuntime.js";
+import type { AgentPathRuntime, AgentPluginConfigRuntime } from "../../../types/runtime/host/AgentHost.js";
+import type { DowncityConfig } from "../../../types/config/DowncityConfig.js";
+import type { JsonValue } from "../../../types/common/Json.js";
+import type { PluginPort } from "../../../plugin/types/Plugin.js";
+import type { SessionMetadataV1, SessionMessageV1 } from "../../../executor/types/SessionMessages.js";
+import type { SessionRunInput, SessionRunResult } from "../../../executor/types/SessionRun.js";
+import type { SessionHistoryStore } from "../../../executor/store/history/SessionHistoryStore.js";
+import type { AgentSessionPromptInput } from "../../../types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionSubscriber, AgentSessionUnsubscribe } from "../../../types/sdk/AgentSessionEvent.js";
+import type { AgentSessionTurnHandle } from "../../../types/sdk/AgentSessionTurn.js";
+/**
+ * 跨 plugin runtime 调用参数。
+ */
+export interface InvokePluginParams {
+    /**
+     * 目标 plugin 名称。
+     */
+    plugin: string;
+    /**
+     * 目标 action 名称。
+     */
+    action: string;
+    /**
+     * 调用时附带的结构化 payload。
+     */
+    payload?: JsonValue;
+}
+/**
+ * 跨 plugin runtime 调用结果。
+ */
+export interface InvokePluginResult {
+    /**
+     * 调用是否成功。
+     */
+    success: boolean;
+    /**
+     * 成功时返回的数据载荷。
+     */
+    data?: JsonValue;
+    /**
+     * 失败时的错误信息。
+     */
+    error?: string;
+}
+/**
+ * 跨 plugin runtime 调用端口。
+ */
+export interface InvokePluginPort {
+    /**
+     * 调用指定 plugin action。
+     */
+    invoke(params: InvokePluginParams): Promise<InvokePluginResult>;
+}
+/**
+ * 单个 Session 执行端口。
+ */
+export interface SessionExecutorPort {
+    /**
+     * 执行一次 session run。
+     */
+    run(params: SessionRunInput): Promise<SessionRunResult>;
+}
+/**
+ * 单个 Session 实例端口。
+ */
+export interface SessionPort {
+    /**
+     * 当前 session 标识。
+     */
+    readonly sessionId: string;
+    /**
+     * 获取当前 session 的执行端口。
+     */
+    getExecutor(): SessionExecutorPort;
+    /**
+     * 获取当前 session 的持久化端口。
+     */
+    getHistoryStore(): SessionHistoryStore;
+    /**
+     * 向当前 session actor 追加一条新的 prompt。
+     *
+     * 关键点（中文）
+     * - 这是面向 SDK / transport 的统一交互输入入口。
+     * - 返回值只有在当前输入被绑定到某个 turn 后才会兑现。
+     */
+    prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
+    /**
+     * 订阅当前 session 后续产生的 future 事件。
+     *
+     * 关键点（中文）
+     * - 只广播订阅之后产生的事件。
+     * - 历史消息仍通过 `getHistoryStore()` / SDK `history()` 读取。
+     */
+    subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
+    /**
+     * 清理当前 session 的 executor 缓存。
+     */
+    clearExecutor(): void;
+    /**
+     * 当前 session 更新后的异步通知钩子。
+     */
+    afterSessionUpdatedAsync(): Promise<void>;
+    /**
+     * 追加一条 user 消息。
+     */
+    appendUserMessage(params: {
+        /**
+         * 已构造好的完整消息。
+         */
+        message?: SessionMessageV1 | null;
+        /**
+         * 兜底文本内容。
+         */
+        text?: string;
+        /**
+         * 附加元数据。
+         */
+        extra?: SessionMetadataV1["extra"];
+    }): Promise<void>;
+    /**
+     * 追加一条 assistant 消息。
+     */
+    appendAssistantMessage(params: {
+        /**
+         * 已构造好的完整消息。
+         */
+        message?: SessionMessageV1 | null;
+        /**
+         * 兜底文本内容。
+         */
+        fallbackText?: string;
+        /**
+         * 附加元数据。
+         */
+        extra?: SessionMetadataV1["extra"];
+    }): Promise<void>;
+    /**
+     * 返回当前 session 是否正在执行。
+     */
+    isExecuting(): boolean;
+}
+/**
+ * Session 集合入口。
+ */
+export interface SessionCollectionPort {
+    /**
+     * 获取指定 sessionId 对应的 Session 实例。
+     */
+    get(sessionId: string): SessionPort;
+    /**
+     * 返回当前所有执行中的 sessionId。
+     */
+    listExecutingSessionIds(): string[];
+    /**
+     * 返回当前执行中的 session 数量。
+     */
+    getExecutingSessionCount(): number;
+    /**
+     * 解析指定 session 当前绑定的模型实例。
+     *
+     * 关键点（中文）
+     * - 模型归属于 session，而不是 agent 全局运行时。
+     * - 这里会触发 session 初始化/宿主配置，适合 task 等后台链路按 session 读取模型。
+     */
+    resolveModel(sessionId: string): Promise<LanguageModel | undefined>;
+}
+/**
+ * 统一执行上下文。
+ */
+export interface AgentContext {
+    /**
+     * 当前执行上下文对应的 agent 状态。
+     */
+    agent: AgentRuntime;
+    /**
+     * 当前命令工作目录。
+     */
+    cwd: string;
+    /**
+     * 当前项目根目录。
+     */
+    rootPath: string;
+    /**
+     * 统一日志器。
+     */
+    logger: Logger;
+    /**
+     * 当前运行时已解析配置。
+     */
+    config: DowncityConfig;
+    /**
+     * 当前项目环境变量快照。
+     */
+    env: Record<string, string>;
+    /**
+     * 当前生效的 system 文本集合。
+     */
+    systems: string[];
+    /**
+     * 当前可见的路径能力集合。
+     */
+    paths: AgentPathRuntime;
+    /**
+     * 当前可见的 plugin 配置持久化能力集合。
+     */
+    pluginConfig: AgentPluginConfigRuntime;
+    /**
+     * Session 能力入口。
+     *
+     * 关键点（中文）
+     * - plugin runtime 与 plugin 都通过这里访问 session 执行与持久化能力。
+     * - 内外统一使用 `sessionId` 语义。
+     */
+    session: SessionCollectionPort;
+    /**
+     * 跨 plugin runtime 调用主入口。
+     */
+    invoke: InvokePluginPort;
+    /**
+     * Plugin 调用入口。
+     */
+    plugins: PluginPort;
+}
+/**
+ * 允许 optional 字段的结构化配置对象。
+ */
+export type StructuredConfig = {
+    [key: string]: JsonValue | undefined;
+};
+//# sourceMappingURL=AgentContext.d.ts.map