@tencent-ai/agent-harness 0.2.0-beta.7 → 0.2.0-beta.8

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/host/plugin-store.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `$.store` 的后端：**一个 plugin 一份**，按 plugin 名分文件。
+ *
+ * 隔离是刚需而不是洁癖：`$.store` 的键由 mod 自己命名，两个 mod 撞上同名键（`state`
+ * / `seen` 这类几乎必然撞）就会互相覆盖，而这种串台在运行时看起来像「我写进去的值
+ * 莫名变了」，极难查。所以 core 拿到 `origin.plugin` 后各写各的文件。
+ *
+ * 落盘用 temp-then-rename：写一半被 kill 不会留下半个 JSON 让下次启动读崩。
+ */
+export declare class PluginStore {
+    private readonly dir?;
+    private readonly cache;
+    /** @param dir 落盘目录；缺省表示只在进程内存活。 */
+    constructor(dir?: string | undefined);
+    private fileOf;
+    private load;
+    private flush;
+    get(plugin: string, key: string): Promise<unknown>;
+    set(plugin: string, key: string, value: unknown): Promise<void>;
+    delete(plugin: string, key: string): Promise<void>;
+    keys(plugin: string): Promise<string[]>;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/host/render-component.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Per-component `ui.render` fold 的类型契约 —— 对齐 Anthropic `claude-code`
+ * 官方 `RenderComponent` 语义（`mods/types/claude-code.d.ts`）。
+ *
+ * ## 语义模型
+ *
+ * `on('ui.render', { component: 'ToolUse' }, ($, e, next) => {
+ *     const beneath = await next(e)                 // core 返回的 SENTINEL 树
+ *     return { ...beneath, tree: <Box>{beneath.tree}<Badge/></Box> }
+ * })`
+ *
+ * 三种典型行为都走同一分派链：
+ *
+ * | Mod 写法                              | Slot 侧行为                               |
+ * |---------------------------------------|-------------------------------------------|
+ * | `return next(e)`                      | SENTINEL 原样返回 → 走真实 React JSX      |
+ * | `return { tree: <Own/> }`             | 完全覆盖 → paint(Own) 到面上              |
+ * | `return { tree: <Box>{beneath}</Box>}`| 装饰 → paint 的子树里 SENTINEL 回落 React |
+ *
+ * ## 为什么 Slot 组件不预先 serialize
+ *
+ * 15 个 slot 里有 streaming（`AssistantMessage`）、xterm widget（`CommandOutput`）、
+ * word-level diff（`ToolResult`）等**无法用闭合标签集完整表达**的能力。若强行 serialize
+ * 会丢失体验。走 SENTINEL 的关键在于：**默认路径永远是 React JSX**，只有 mod 主动
+ * 改写才走 paint —— 未装 mod / mod 未干预时零成本、零行为差。
+ *
+ * ## 与 `Pane` 通路的关系
+ *
+ * `Pane` 也在联合类型里，因此 `on('ui.render', { component: 'Pane' }, ...)` 会匹配
+ * `component: 'Pane'` 的 dispatch。**但**当前旧 `mods-render-panel` 通路走的是"无
+ * `component` 字段的通用 `ui.render`"（core-handler 缺 `component` 时返回 `{}`），
+ * 二者共存 —— 迁移期后再收敛到单一 slot 分派。
+ */
+import type { SerializedElement } from './render-registry.js';
+/**
+ * 受 mod 侧 `on('ui.render', { component: 'X' }, ...)` 分派的所有内置 slot。
+ *
+ * 每个字面量都对应 TUI + Web UI 上一个具体 React 组件位置，见 plan file 的对照表。
+ * 新增 slot 前先在 15 个之外补一行、并在**两个** surface 上同步落地 wrap，避免
+ * mod 作者以为可以 `on('ui.render', { component: 'X' }, ...)` 而实际 X 只在一面 wrap 了。
+ */
+export type RenderComponent = 'AskUserQuestion' | 'UserMessage' | 'AssistantMessage' | 'ToolUse' | 'ToolResult' | 'ToolGroup' | 'ToolProgress' | 'CommandOutput' | 'Spinner' | 'TurnDuration' | 'InfoNotice' | 'SessionMode' | 'PromptHint' | 'AbovePrompt' | 'Pane';
+/** `ui.render` 事件的输入 payload —— slot 组件 dispatch 时构造。 */
+export interface UiRenderInput {
+    /**
+     * 内置 slot 分派 discriminant。**不传** = 通用 `ui.render`（旧 Pane 通路 /
+     * `mods-render-panel` 走这条），mod 侧 `on('ui.render', hook)` 无 matcher 时
+     * 通配匹配。
+     */
+    readonly component?: RenderComponent;
+    /**
+     * 当前渲染面。**必填**：mod 通过 `$.ui.resolve(e)` 拿 surface 特定的 element table
+     * （官方 `Elements[E['surface']]`），据此对同一逻辑树做面差异化产物。
+     */
+    readonly surface: RenderSurfaceLoose;
+    /**
+     * slot 具体 props —— TypeScript index signature 兼容任意读法，避免 mod 作者
+     * 对 slot 的实际 props 形状做假设时被编译器挡住；运行时按 host 实际注入为准。
+     */
+    readonly [key: string]: unknown;
+}
+/**
+ * `ui.render` 事件的返回值形状 —— mod hook 返回、slot 组件消费。
+ *
+ * `tree` 是**唯一被 slot 消费的字段**；其它字段允许 mod 之间约定，走 index signature。
+ */
+export interface UiRenderResult {
+    readonly tree?: SerializedElement;
+    readonly [key: string]: unknown;
+}
+/**
+ * SENTINEL 元素类型名。
+ *
+ * Core-handler 处理 `ui.render` 且 `input.component` 有值时，返回：
+ *
+ * ```
+ * { tree: { type: 'Default', props: { component: 'ToolUse' }, children: [] } }
+ * ```
+ *
+ * 面上的 paint helper 遇到 `type === 'Default'` 时，**回落到 slot 传入的
+ * `defaults[props.component]()`** —— 也就是真实的默认 React 组件。这一步是"允许
+ * 完整覆盖 + 保留 streaming/动画"两个目标的接合点。
+ */
+export declare const SENTINEL_ELEMENT_TYPE: 'Default';
+/**
+ * 构造一个 SENTINEL 元素 —— 只有 core-handler 应当调用。
+ *
+ * @param component 该 slot 的类型（用于 paint 回落时按 component 查真实组件）
+ */
+export declare function makeSentinelElement(component: RenderComponent): SerializedElement;
+/**
+ * 判断一颗树是不是 core 返回的原始 SENTINEL —— slot 组件据此走"真实 React JSX"路径。
+ *
+ * @param tree 待检查的树；`undefined` 视为 SENTINEL 等价（mod 完全没干预）
+ * @param component 可选：只有当 `tree.props.component` 匹配时才判 true。
+ *   不传即接受任意 SENTINEL —— 对通配 hook 有意义
+ */
+export declare function isSentinelTree(tree: SerializedElement | undefined, component?: RenderComponent): boolean;
+/**
+ * 判断一个元素**节点**（非整棵树）是不是 SENTINEL —— paint helper 在递归时用它
+ * 决定是否回落到 `defaults[component]()`。
+ */
+export declare function isSentinelElement(node: SerializedElement): node is SerializedElement & {
+    props: {
+        component: RenderComponent;
+    };
+};
+/**
+ * `RenderSurface` 的宽松版本 —— 供 `UiRenderInput.surface` 使用。
+ *
+ * 这里刻意不 import `host-bindings.ts:RenderSurface`：那份类型是**宿主的能力面
+ * 契约**（`session.start` 里的 surface enum），演进节奏与 mod API 不完全同步
+ * （host 支持 `mobile` 但当前 UI 尚未落地）。此处允许字符串扩展，保持前向兼容。
+ */
+export type RenderSurfaceLoose = string;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/host/render-registry.d.ts

@@ -0,0 +1,99 @@
+import type { Origin } from '../types/index.js';
+/**
+ * 渲染树的跨面传输：**树序列化出去，交互按 key 回来**。
+ *
+ * ## 为什么必须这样做
+ *
+ * `$.ui.*` 不是终端专用 —— 官方 `RenderSurface` 就是
+ * `'terminal' | 'desktop' | 'mobile' | 'vscode'`，`$.session.surfaces()` 还返回
+ * 复数。终端在本进程里画，而 desktop / web / vscode 在**另一个进程**里画，中间
+ * 只有一条可序列化的通道（cbc 这边是 ACP 的 `extNotification` / `extMethod`）。
+ *
+ * 于是产生一个看似矛盾的约束：`Button` 的 props 里有 `onPress: () => void`，
+ * 闭包不可能过线。官方的解法不是禁掉闭包，而是**让闭包留在 agent 侧**：
+ *
+ * 1. hook 在 agent 进程里渲染出树；
+ * 2. 序列化时把函数型 prop 摘下来，按元素的 `key` 存进一张表，树上只留 `key`；
+ * 3. 纯数据的树送到 surface；
+ * 4. surface 上按下按钮，回传 `{ plugin, element: key, surface }`；
+ * 5. 引擎按 `plugin + key` 找回闭包，**在它自己的 plugin 环境里**执行。
+ *
+ * 所以 JSX 完全可用 —— 它只是写法，编译后是数据树，闭包从不离开本进程。
+ *
+ * ## 为什么按 `plugin` 分表
+ *
+ * `key` 是 mod 自己起的名字（`ButtonProps.key` 默认取 label），两个 mod 同时画
+ * 一个 `确定` 按钮几乎必然撞。不按 plugin 隔离的话，一次点击会跑到别人的闭包
+ * 上 —— 而且这种串台在界面上看起来「按钮没反应」或「按错了」，极难归因。
+ */
+/**
+ * 官方元素表的全部 tag —— 这是一个**闭集**。
+ *
+ * 校验它而不是放行任意字符串：一个写错 tag 的 mod（JSX 里手滑写成 `<div>`）
+ * 若被放行，垃圾会一路送到 surface，而 surface 只能默默丢弃或者崩 —— 报错点离
+ * 错误源隔着一个进程边界，极难归因。在序列化这一层挡住，错误就停在写错的那个
+ * mod 身上。
+ *
+ * `Client` / `Raster` / `Image` 并非每个面都支持（官方
+ * `ClientElements = Omit<Elements['terminal'], 'Client' | 'Raster' | 'Image'>`），
+ * 但那是**面能力**的判断，属于宿主 paint 出口该做的事；这里只管 tag 是否存在。
+ */
+export declare const RENDER_TAGS: ReadonlySet<string>;
+/** 一棵序列化后的渲染树：纯数据，可安全跨进程。 */
+export interface SerializedElement {
+    readonly type: string;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly children: readonly SerializedElement[];
+}
+/**
+ * 渲染树的交互闭包表 —— 一个 plugin 一张。
+ *
+ * 每次重绘**整表替换**该 plugin 的条目：旧树上的按钮已经不在界面上了，留着它的
+ * 闭包只会让一次迟到的点击跑到上一帧的逻辑上。
+ */
+export declare class RenderRegistry {
+    private readonly handlers;
+    private readonly hotkeys;
+    /**
+     * 序列化一棵树，同时登记它的交互闭包。
+     *
+     * @param plugin 画这棵树的 mod
+     * @param tree hook 返回的渲染树（JSX 编译结果即是此形状）
+     * @returns 纯数据的树，可直接过线
+     */
+    serialize(plugin: string, tree: unknown): SerializedElement | undefined;
+    private walk;
+    /**
+     * 跑回某个元素的交互闭包。
+     *
+     * @param event op 事件名（`ui.press` / `ui.input`）
+     * @param plugin 该元素属于哪个 mod
+     * @param element 元素 key
+     * @param args 传给闭包的实参（`onInput` 会带值）
+     * @returns 闭包的返回值；没有登记过则 `undefined`
+     */
+    invoke(event: string, plugin: string, element: string, ...args: readonly unknown[]): Promise<{
+        ran: boolean;
+        value?: unknown;
+    }>;
+    /**
+     * 按 hotkey 找当前树上的元素 key。
+     *
+     * 供**面**用（终端的 keypress、Web 的键盘转 press）：拿到用户按的键 →
+     * 找到匹配的 Button → dispatch `ui.press`。找不到返回 undefined（那就是
+     * 一个和当前界面无关的按键，安静地忽略）。
+     *
+     * @param plugin 画这棵树的 mod
+     * @param hotkey 按下的键（原样，如 `'a'` / `'\r'`）
+     */
+    findHotkey(plugin: string, hotkey: string): string | undefined;
+    /** 丢弃某个 mod 的全部闭包（它被卸载时）。 */
+    forget(plugin: string): void;
+    /** 当前登记了多少个可交互元素（诊断用）。 */
+    countOf(plugin: string): number;
+}
+/** 从 `ui.press` / `ui.input` 的入参里取出寻址信息。 */
+export declare function addressOf(input: Record<string, unknown>, origin: Origin): {
+    plugin: string;
+    element: string;
+};

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/host/terminal-play.d.ts

@@ -0,0 +1,56 @@
+import type { HookFailureReporter } from '../engine/hooks-registry.js';
+import type { ModsRuntime } from '../engine/mods-runtime.js';
+import type { HostBindings } from './host-bindings.js';
+/**
+ * 终端里让 UI mod **真的能看见并交互**。
+ *
+ * ## 为什么是独立入口，不接进主 TUI
+ *
+ * 主 TUI 是 Ink 组件树，接进去要动 App 架构、focus 管理、样式主题。给 mod 单开
+ * 一个入口能最短路径把 Phase 4 剩下的两块 —— 宿主 paint 出口 + 键盘回流 —— 落
+ * 实到位，且不会误伤既有 chat UI。这一层刻意只做**面**的活：拿到序列化树 →
+ * 画到屏上；抓到按键 → 转成 `ui.press`。游戏逻辑与画树都在 mod 里。
+ *
+ * ## 为什么不 await 每一次画
+ *
+ * 一拍的重力（`clock.every`）里既要推状态又要请求重绘，画得多慢是**面**的事
+ * —— 慢面不该拖慢游戏节奏。因此 `paint` 出口是 fire-and-forget，重绘请求
+ * (`invalidate`) 也只是把一次待处理标记起来，多次请求聚合成一次画。
+ *
+ * ## Ctrl+C / q 退出，也告诉 mod 会话要结束
+ *
+ * 退出前 dispatch `session.end`，让 mod 有机会 flush（内置 `telemetry` mod 就靠
+ * 它落盘计数）。否则最后一局的埋点全丢，且用户看不到「保存了」这类反馈。
+ */
+/** 一次终端 paint 会话的可选项。 */
+export interface TerminalPlayOptions {
+    /** 输出流；默认 `process.stdout`。 */
+    readonly stdout?: NodeJS.WriteStream;
+    /** 输入流；默认 `process.stdin`。 */
+    readonly stdin?: NodeJS.ReadStream;
+    /**
+     * 宿主自己想附加的绑定（`cwd` / `root` / `storeDir` / `settings` …）。
+     * `paint` / `invalidate` / `log` / `status` / `toast` 会被本模块覆盖 ——
+     * 那几项才是让 mod 在终端上「亮起来」的具体实现。
+     */
+    readonly extraBindings?: HostBindings;
+    /** hook 运行期失败上报（默认写 stderr）。 */
+    readonly onHookFailure?: HookFailureReporter;
+}
+/** 终端 paint 会话的门面，供调用方停止。 */
+export interface TerminalPlaySession {
+    /** 停止并回收（还原 stdin 模式、清屏、卸载 SIGINT）。 */
+    stop(): Promise<void>;
+    /** 显式发一次重绘请求（外部逻辑改了状态时用）。 */
+    invalidate(): void;
+}
+/**
+ * 用**运行时对象**建一个终端 paint 会话。
+ *
+ * 与 `bootstrapModsFromPluginDirs` 是配套的：先启动 runtime、再传进来。
+ *
+ * @param runtime 已 `start()` 完成的运行时
+ * @param options 输出/输入流 / 附加绑定
+ * @returns 会话门面；调用 `stop()` 收尾
+ */
+export declare function playModsInTerminal(runtime: ModsRuntime, options?: TerminalPlayOptions): TerminalPlaySession;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types/index.js';
+export * from './builtin/index.js';
+export * from './engine/index.js';
+export * from './host/index.js';
+export * from './loader/index.js';
+export * from './legacy-adapter/index.js';
+export * from './testing/index.js';
+export type { RenderComponent, RenderSurface } from './host/index.js';
+export type { MockClock } from './testing/index.js';

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/legacy-adapter/fan-out.d.ts

@@ -0,0 +1,23 @@
+import { HookEvent } from '../../../../../cbc-shared/lib/node/index.js';
+import type { HooksRegistry } from '../engine/index.js';
+import type { EventResult } from '../types/index.js';
+import { toEventResult } from './hook-result-mapper.js';
+/**
+ * 广播 `classic.<Event>` 并返回 middleware 侧的决策。
+ *
+ * cbc 老 shell hooks 由 `SessionHookManager` 执行；本函数把同一次触发也分发成
+ * `classic.<Event>` middleware 事件，让新架构的 mod（如 `sec-default` 的
+ * `on('classic.*', ($, e, next) => next.to(e, 'append'))`）观察并参与决策。
+ *
+ * `core` 层结果取老 shell hook 的归一化结果（若提供），否则空对象 —— 这样
+ * `next.to(e, 'append')` 这类 hook 才有「下游」可跳。
+ *
+ * caller 应在 `isFunctionHooksEnabled()` 为 true 时才调用，否则整包旁路。
+ */
+export declare function dispatchLegacyEvent(registry: Pick<HooksRegistry, 'dispatch'>, event: HookEvent, input: Readonly<Record<string, unknown>>, legacyResult?: Parameters<typeof toEventResult>[0]): Promise<EventResult>;
+/**
+ * 只广播、不取决策的形态：老 shell hook 的执行流完全不受 middleware 返回影响。
+ *
+ * 适合「先让 mod 观察，再逐步把决策权交给 middleware」的灰度阶段。
+ */
+export declare function fanOutLegacyEvent(registry: Pick<HooksRegistry, 'dispatch'>, event: HookEvent, input: Readonly<Record<string, unknown>>): Promise<void>;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/legacy-adapter/hook-result-mapper.d.ts

@@ -0,0 +1,27 @@
+import { HookEvent, type HookExecutionResult, type HookOutput } from '../../../../../cbc-shared/lib/node/index.js';
+import type { ClassicEventName, EventResult } from '../types/index.js';
+/**
+ * 把 cbc 老 `HookEvent` 枚举值映射为 claude-code 风格的 `classic.<Event>` 事件名。
+ *
+ * 用于 legacy adapter：当 `SessionHookManager` 执行完一次 shell hook，
+ * 用这个 mapping 把结果广播到 cbc-mods middleware 引擎。
+ */
+export declare function classicEventNameOf(event: HookEvent): ClassicEventName;
+/**
+ * 老 shell hook 的 `HookExecutionResult` 或 `HookOutput` 映射为 middleware `EventResult`。
+ *
+ * 映射规则（对齐 cbc 原有阻断语义）：
+ * - `allowed === false` 或 `blocking === true` → `{ deny }`，`reason` 从下列字段按优先级取：
+ *   `permissionDecisionReason` > `blockingDetails[0].reason` > `message` > 兜底 'blocked'
+ * - `preventContinuation === true`（continue: false / Stop 停止链）→ `{ deny }`
+ * - 否则 → `{ result: hookSpecificOutput 或 undefined, context: hookSpecificOutput }`
+ *
+ * 注意：这个函数只做**决策形态映射**；不会改动 cbc 原有的 exit-2 / json 阻断行为，
+ * 后者继续由 `SessionHookManager` 依循老代码路径处理。
+ */
+export declare function toEventResult(execResult: HookExecutionResult): EventResult;
+/**
+ * `HookOutput`（shell 脚本 stdout JSON）到 `EventResult` 的直接映射（用于 hook 直接产出 JSON、
+ * 且尚未走 `HookExecutionResult` 归一化的场景）。
+ */
+export declare function hookOutputToEventResult(output: HookOutput): EventResult;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/legacy-adapter/index.d.ts

@@ -0,0 +1,2 @@
+export * from './hook-result-mapper.js';
+export * from './fan-out.js';

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/loader/bootstrap.d.ts

@@ -0,0 +1,104 @@
+import type { CoreHandler, HookFailureReporter } from '../engine/hooks-registry.js';
+import { ModsRuntime, type ModStartupFailure } from '../engine/mods-runtime.js';
+import type { HostBindings } from '../host/host-bindings.js';
+import { type LoadedMod, type LoadOptions } from './load-mod.js';
+/**
+ * 从 `--plugin-dir` 发布的环境变量里把 mod 拉起来。
+ *
+ * `cli-dispatcher` 已经把 `--plugin-dir` 的目录列表写进 `CODEBUDDY_PLUGIN_DIRS`
+ * （以 `path.delimiter` 分隔），本模块是它在 mods 侧的消费者：挑出其中**带
+ * function hooks 的目录**（有 `hooks/hooks.json` 且列了 `modules`），逐个加载
+ * 并组装成一个 `ModsRuntime`。
+ *
+ * 因此 `codebuddy --plugin-dir mods/diff` 与官方 `claude --plugin-dir mods/diff`
+ * 走的是同一条路：读 manifest（`.codebuddy-plugin` 优先、`.claude-plugin` 兼容）
+ * → 加载 TS register 模块 → 按 tier 坐好 → `engine.create` fold 出 `$`。
+ *
+ * 全程受 `CBC_ENABLE_FUNCTION_HOOKS` 约束：开关未开时返回 `undefined`，
+ * 宿主照旧走老 shell hooks 路径，零副作用。
+ */
+/** `--plugin-dir` 发布目录列表的环境变量名（由 cli-dispatcher 写入）。 */
+export declare const PLUGIN_DIRS_ENV = "CODEBUDDY_PLUGIN_DIRS";
+/** 一次 bootstrap 的入参。 */
+export interface BootstrapOptions {
+    /** 读取的环境（默认 `process.env`）。 */
+    readonly env?: NodeJS.ProcessEnv;
+    /** 显式指定目录，跳过环境变量（测试 / 编程式使用）。 */
+    readonly dirs?: readonly string[];
+    /**
+     * `core` 层行为。不传则用 `createCoreHandler(bindings)` —— 即真实的宿主能力面。
+     *
+     * 显式传入只有两种场合：测试要固定 core 的答案，或宿主要在默认之上再包一层。
+     */
+    readonly core?: CoreHandler;
+    /**
+     * 宿主能力绑定（cwd / root / ui / settings / store 落盘位置）。
+     *
+     * 不传等于「什么能力都没接」：mod 仍能注册、仍能拿到 `$`，但调 `$.ui.log()` /
+     * `$.settings.read()` 会得到明确的拒绝。`core` 显式给出时本项被忽略。
+     */
+    readonly bindings?: HostBindings;
+    /** 载入每个 mod 时的选项（tier / options / importer）。 */
+    readonly load?: LoadOptions;
+    /** 加载失败时的回调；不传则静默跳过该目录。 */
+    readonly onError?: (dir: string, error: unknown) => void;
+    /**
+     * 是否挂载宿主自带的 builtin mod（telemetry / sec-default）。默认挂。
+     *
+     * 关掉它的唯一正当场景是测试要一个**干净**的引擎 —— 内置 mod 会往 `$` 上
+     * 加 noun、会拦 `$.fs.*`，混在断言里会让「是谁干的」变得不清楚。
+     */
+    readonly withBuiltins?: boolean;
+    /**
+     * hook 运行期失败（抛错 / 超时）的上报出口。
+     *
+     * 与 `onError` 不同：那是**加载期**的失败，这是 mod 已经跑起来之后某次
+     * dispatch 里的失败。后者已被隔离成「该层未干预」，不上报就完全没有声音。
+     */
+    readonly onHookFailure?: HookFailureReporter;
+}
+/** bootstrap 的结果。 */
+export interface BootstrapResult {
+    /**
+     * 已启动的运行时（`$` 已 fold 完毕）。
+     *
+     * 一个 mod 都没成功加载、或 host 的 fold 也失败时为 `undefined` —— 此时
+     * `skipped` 说明每个目录为什么没上车，caller 应当把它报出来而不是当作
+     * 「无事发生」。
+     */
+    readonly runtime?: ModsRuntime;
+    /** 成功加载的 mod。 */
+    readonly mods: readonly LoadedMod[];
+    /** 被跳过的目录（不是 mod，或加载失败）与原因。 */
+    readonly skipped: readonly {
+        readonly dir: string;
+        readonly reason: string;
+    }[];
+    /** 启动阶段各 mod 的失败（注册抛错、`engine.create` 违规等）。 */
+    readonly failures: readonly ModStartupFailure[];
+}
+/** 从环境变量解析出目录列表。 */
+export declare function pluginDirsOf(env?: NodeJS.ProcessEnv): readonly string[];
+/**
+ * 加载 `--plugin-dir` 里的 mod 并启动运行时。
+ *
+ * ## 绝不阻塞调用方
+ *
+ * 这是宿主启动链上的一站，因此**本函数不向外抛**。任何一层出问题都被降级成
+ * 「记录 + 继续」：
+ *
+ * | 出错的地方 | 结果 |
+ * |---|---|
+ * | 某个目录不是 mod / 读不出 manifest / TS 加载失败 | 进 `skipped`，其余目录照常 |
+ * | 某个 mod 的 `register()` 自己抛错 | 进 `failures`，其余 mod 照常 |
+ * | 某个 mod 的 `engine.create` 违规 | 进 `failures`，它拿不到 `$`，其余照常 |
+ * | 连 host 的 fold 都失败 | `runtime` 为 `undefined`，宿主退化成「无 mods 能力」 |
+ * | 任何未预料的异常 | 兜住并记入 `failures`，返回已有结果 |
+ *
+ * 返回 `undefined` **只在真的无事可做时**：function hooks 未启用，或没有任何
+ * `--plugin-dir`。只要有目录被指定，就一定返回结果对象，调用方因此永远能报告
+ * 出「为什么我的 --plugin-dir 没生效」。
+ *
+ * @param options 环境 / 显式目录 / core 行为 / 载入选项
+ */
+export declare function bootstrapModsFromPluginDirs(options?: BootstrapOptions): Promise<BootstrapResult | undefined>;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/loader/bundle-cache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * mod bundle 的磁盘缓存 —— 让「带 JSX 的 mod 每次冷启动重 build」这件事只发生一次。
+ *
+ * ## 为什么需要
+ *
+ * 加载策略是双通道（见 `ts-runtime.ts`）：非 JSX 的 mod 走 Node 内建 type
+ * stripping，本来就不 build；**只有带 JSX 的 mod** 需要 esbuild 真转译。实测
+ * 官方 `diff` mod（785 个文件）走 esbuild 通道约 **2s** —— 放在 CLI 启动路径上
+ * 每次都付这个钱是不可接受的。
+ *
+ * ## 缓存键与失效
+ *
+ * 键 = `sha256(entry 绝对路径 + loader 版本 + esbuild 版本)`。**不把源码内容算进键**
+ * ——那要先把几百个文件全读一遍，等于白付一次 IO。内容变化靠 **manifest 校验**：
+ *
+ * 首次 build 时让 esbuild 交出 `metafile.inputs`（这次 bundle 真正读过的文件），
+ * 把每个 input 的 `mtimeMs` + `size` 连同产物一起记下。后续命中先 `stat` 这批
+ * 文件（只取元数据，不读内容），全部一致才复用产物。任何一个文件被改动、增删，
+ * 校验失败 → 重 build。
+ *
+ * 这与 `tsc --incremental` / bundler 的 filesystem cache 是同一套思路：用廉价的
+ * stat 换昂贵的 parse。
+ */
+/**
+ * 缓存格式版本。改动 bundle 选项（target / format / jsx 等）或产物语义时**必须**
+ * 递增 —— 否则旧产物会被错误复用。
+ */
+export declare const CACHE_VERSION = 1;
+/** 缓存查询结果。 */
+export interface CacheLookup {
+    /** 产物的绝对路径（ESM flavor 为 `.mjs`，isolated flavor 为 `.cjs`）。 */
+    readonly modulePath: string;
+    /** manifest 的绝对路径。 */
+    readonly manifestPath: string;
+    /** 命中则为 true —— 直接 import `modulePath` 即可。 */
+    readonly isFresh: boolean;
+}
+/** 缓存根目录：尊重 `CODEBUDDY_CONFIG_DIR`，否则 `~/.codebuddy`。 */
+export declare function cacheRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * 查缓存：产物在不在、还新鲜不新鲜。
+ *
+ * @param entry register 模块的绝对路径
+ * @param esbuildVersion 转译器版本（参与缓存键）
+ * @param env 环境（用于定位缓存根）
+ * @param flavor 产物风味：`''`（默认）= ESM `.mjs`（走 `import()`）；非空（如
+ *   `'cjs-vm'`）= CJS `.cjs`（读回字符串塞进 vm 沙箱执行）。不同 flavor 各占
+ *   独立缓存键，互不覆盖。
+ */
+export declare function lookupCache(entry: string, esbuildVersion: string, env?: NodeJS.ProcessEnv, flavor?: string): Promise<CacheLookup>;
+/**
+ * 写缓存。产物先写临时文件再 `rename`，避免并发进程读到半截内容。
+ *
+ * @param lookup `lookupCache` 给出的路径
+ * @param entry register 模块绝对路径
+ * @param code bundle 产物
+ * @param inputPaths 本次 bundle 读过的文件（来自 esbuild `metafile.inputs`）
+ */
+export declare function writeCache(lookup: CacheLookup, entry: string, code: string, inputPaths: readonly string[]): Promise<void>;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/loader/index.d.ts

@@ -0,0 +1,8 @@
+export * from './bundle-cache.js';
+export * from './ts-runtime.js';
+export * from './manifest-dir.js';
+export * from './load-mod.js';
+export * from './isolated-import.js';
+export * from './mounted-import.js';
+export * from './types-emitter.js';
+export * from './bootstrap.js';

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/loader/isolated-import.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 在隔离 realm 里执行一份 CJS bundle，取回它的 `module.exports`。
+ *
+ * @param code esbuild 出的 CJS 单文件产物
+ * @param filename 供栈帧显示（一般是 register 入口的绝对路径）
+ * @param modName mod 名（错误信息用）
+ */
+export declare function runModuleInSandbox(code: string, filename: string, modName: string, log?: (...args: unknown[]) => void): unknown;
+/**
+ * 隔离通道的模块加载器 —— 与 `defaultImporter` 同签名（`ModuleImporter`），可直接
+ * 作为 `LoadOptions.importModule` 传入。
+ *
+ * esbuild bundle → CJS 单文件（内容寻址磁盘缓存，flavor `cjs-vm`，与 ESM 产物分键）
+ * → 加固 realm 执行 → 取回 `module.exports`。
+ *
+ * @param entry register 模块的绝对路径
+ * @param root mod 的 root（仅用于取 mod 名，做错误信息）
+ * @param env 环境（决定缓存根目录；测试可指向临时目录）
+ */
+export declare function importModuleIsolated(entry: string, root?: string, env?: NodeJS.ProcessEnv): Promise<unknown>;