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

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>;

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

@@ -0,0 +1,151 @@
+import { type PlatformPath } from 'node:path';
+import type { Plugin } from 'esbuild';
+import type { PluginOptions, Register, RegisteredMod, Tier } from '../types/index.js';
+import { type ManifestDir } from './manifest-dir.js';
+/** `plugin.json` 的形状（对齐官方 mod 的 manifest）。 */
+export interface PluginManifest {
+    name: string;
+    version?: string;
+    description?: string;
+    author?: {
+        name?: string;
+    } | string;
+    /**
+     * 该 plugin 的类型契约路径，相对 plugin root、以 `./` 开头。
+     *
+     * 官方约束（`plugin validate` 会查）：一个**自包含**的 `.d.ts` —— 不含
+     * import / export-from / require / reference，顶层导出它在 `engine.create`
+     * 里加的 noun 的类型，并在 `declare module 'codebuddy-code' { interface
+     * EngineInterface { … } }`（或 `'claude-code'`）里声明该 noun，别无其他。
+     */
+    types?: string;
+    /** 该 mod 的默认配置项。 */
+    options?: PluginOptions;
+}
+/** `hooks/hooks.json` 的形状。 */
+export interface HooksManifest {
+    description?: string;
+    /** register 模块路径列表（相对 hooks.json 所在目录）。 */
+    modules: readonly string[];
+}
+/** 一个已解析、可挂载的 mod 包。 */
+export interface LoadedMod extends RegisteredMod {
+    readonly manifest: PluginManifest;
+    /** manifest 实际来自哪个受支持的插件元数据目录。 */
+    readonly manifestDir: ManifestDir;
+    readonly hooks: HooksManifest;
+}
+/** 模块加载器：把一个 TS/JS 入口变成运行时模块。 */
+export type ModuleImporter = (absPath: string, root?: string) => Promise<unknown>;
+/** 载入 mod 时的可选项。 */
+export interface LoadOptions {
+    /** Metadata and code must use the same mounted filesystem. */
+    readonly readText?: (path: string) => Promise<string>;
+    readonly paths?: Pick<PlatformPath, 'join' | 'resolve' | 'isAbsolute'>;
+    /** 挂载 tier，默认 `user`。 */
+    readonly tier?: Tier;
+    /** 覆盖/补充 manifest 里的 options。 */
+    readonly options?: PluginOptions;
+    /**
+     * 自定义模块加载器。默认用 esbuild 把入口 bundle 成一个临时 ESM 文件再
+     * `import()` —— 官方 mod 的 TS 源码（目录 import、`.js` specifier、
+     * `import type … from 'claude-code'`）都能直接吃下。
+     */
+    readonly importModule?: ModuleImporter;
+    /**
+     * 是否走**隔离通道**：把 register 模块塞进 vm 沙箱执行，脚本因此够不到宿主的
+     * `require` / `process` / `global` 等高危面（见 `isolated-import.ts`）。
+     *
+     * 缺省 `false`，保持「宿主 realm 内 `import()`、mod 可直接用 Node 内建」的既有
+     * 语义。`options.importModule` 显式给出时本项被忽略（自定义加载器优先）。
+     */
+    readonly isolate?: boolean;
+}
+/**
+ * JSX factory shim，原地嵌入（不能读磁盘：CLI 打进 `dist/codebuddy.js` 后源码
+ * 不再挨着 bundle）。ESM 通道与 isolated CJS 通道共用同一份 —— 两者的 esbuild
+ * 配置都 `inject: ['cbc-jsx-shim']`，factory 名 `h` 与各文件头部的 `@jsx h`
+ * pragma 对齐。
+ */
+export declare const JSX_SHIM_SOURCE = "\n// The JSX factory. Named `h` (Preact / classic-pragma convention) so the\n// esbuild config's `jsxFactory: 'h'` matches per-file `/* @jsx h */`\n// pragmas exactly. Aliased as `__cbcH` for internal spec tests that\n// reference it under the old name.\nexport function h(type, props, ...children) {\n    const flat = [];\n    for (const child of children) {\n        if (child === null || child === undefined || child === false || child === true) continue;\n        if (Array.isArray(child)) {\n            for (const inner of child) {\n                if (inner !== null && inner !== undefined && inner !== false && inner !== true) flat.push(inner);\n            }\n            continue;\n        }\n        flat.push(child);\n    }\n    const finalProps = { ...(props ?? {}) };\n    // Function-typed `type` means `<Box>` came from a destructured factory\n    // (`const { Box } = await $.ui.resolve(e)`) \u2014 official diff mod pattern.\n    // React's createElement treats that as a component: call it with props +\n    // children slot and return whatever it produces. Our `$.ui.resolve`\n    // factories return `{ type: 'Box', ... }` at runtime, so this collapses\n    // the JSX call into the real element in one step.\n    if (typeof type === 'function') {\n        return type({ ...finalProps, children: flat.length === 1 ? flat[0] : flat });\n    }\n    if (type === 'Text' && finalProps.text === undefined && flat.every(c => typeof c === 'string' || typeof c === 'number')) {\n        finalProps.text = flat.join('');\n        return { type, props: finalProps, children: [] };\n    }\n    return { type, props: finalProps, children: flat };\n}\nexport const __cbcH = h;\nexport const Fragment = 'Fragment';\nexport const __cbcFragment = Fragment;\nexport const Box = 'Box';\nexport const Text = 'Text';\nexport const Button = 'Button';\nexport const Input = 'Input';\nexport const Select = 'Select';\nexport const Link = 'Link';\nexport const Code = 'Code';\nexport const Markdown = 'Markdown';\nexport const Image = 'Image';\nexport const Svg = 'Svg';\nexport const Raster = 'Raster';\nexport const Client = 'Client';\n";
+/**
+ * 懒加载 esbuild —— 只有走转译通道（JSX / isolated CJS）才需要。缺失时把「为什么
+ * 需要转译器」「怎么补」讲清楚，别让用户对着光秃秃的 `ERR_MODULE_NOT_FOUND` 去猜。
+ *
+ * @param entry register 模块的绝对路径（仅用于错误信息）
+ */
+export declare function loadEsbuild(entry: string): Promise<typeof import('esbuild')>;
+/**
+ * 用 esbuild 把 mod 入口 bundle 成单文件。`format` 决定产物形态：
+ * - `'esm'`：给 `import()` 通道（`bundleAndImport`）
+ * - `'cjs'`：给 isolated vm 通道（`importModuleIsolated`），产物在沙箱里以
+ *   `module`/`exports` 执行，`require` 被拦截
+ *
+ * 两个 format 共用同一套解析 / JSX / external 配置，只差 `format` 一项 —— 保证
+ * 「同一个 mod 在两条通道里编译出的语义完全一致」。
+ *
+ * @returns bundle 产物文本，以及本次真正读过的输入文件（缓存失效判定用）
+ */
+export declare function runEsbuild(esbuild: typeof import('esbuild'), entry: string, format: 'esm' | 'cjs', plugins?: readonly Plugin[]): Promise<{
+    code: string;
+    inputs: string[];
+}>;
+/**
+ * 通道二：esbuild bundle → 临时 `.mjs` → 动态 `import()`。
+ *
+ * **只在 Node 内建通道搞不定时才用**（唯一已知场景：mod 里有 JSX，官方 `diff`
+ * 就是）。因此 esbuild 是**可选依赖** —— 缺了它，非 JSX 的 mod 照样能跑，带 JSX
+ * 的 mod 会得到一句明确的话。
+ *
+ * 产物走**内容寻址磁盘缓存**（`bundle-cache.ts`）：命中就直接 `import` 缓存的
+ * `.mjs`，完全不启动 esbuild。
+ *
+ * @param entry register 模块的绝对路径
+ * @param env 环境（决定缓存根目录；测试可指向临时目录）
+ */
+export declare function bundleAndImport(entry: string, env?: NodeJS.ProcessEnv): Promise<unknown>;
+/**
+ * 默认加载器：**JSX 一律走 esbuild，其余先试 Node 内建通道**。
+ *
+ * 0. **`.tsx` / JSX 一律走 esbuild** —— Bun / Node（22.6+ strip-types / 22.15+
+ *    hooks / 20.x）对 JSX 的默认 factory 各不相同（Bun 用 `React.createElement`，
+ *    Node 根本不认 JSX），而 mod 作者不 import 任何 factory。让所有 JSX 集中
+ *    走 esbuild 的 `jsxFactory: '__cbcH'` + `inject: [jsx-shim]`，是**唯一**
+ *    能保证「不管在哪版 Node/Bun 都编译到同一个 factory」的路径。命中 bundle
+ *    缓存后无感（`.tsx` 首次 build 后 stat 比对，几毫秒）。
+ * 1. runtime 原生支持（Bun）—— **非 JSX** mod 直接 `import()`，零开销、零钩子。
+ * 2. Node 内建 type stripping + **作用域化**的 resolve 钩子（只对该 mod root
+ *    之下的路径生效，加载完即卸载）。零第三方依赖，覆盖官方 `telemetry` /
+ *    `sec-default` / `agents-md`。
+ * 3. 只有当报错表明「strip-types 不认这个语法」时，才 `bundleAndImport()` 用
+ *    esbuild 真转译。
+ *
+ * 其它错误（源码本身写错、依赖缺失）**原样抛出** —— 不会被误判成「需要转译器」
+ * 而绕一圈给出无关的 esbuild 提示。
+ *
+ * @param entry register 模块的绝对路径
+ */
+export declare function defaultImporter(entry: string, root?: string): Promise<unknown>;
+/**
+ * 从一个 mod 目录载入 mod —— 等价官方 `claude --plugin-dir <path>`。
+ *
+ * 期望目录结构（与 `anthropics/claude-code/mods/*` 完全一致）：
+ * ```
+ * <root>/
+ * ├── .codebuddy-plugin/plugin.json   # cbc 优先；官方 mod 用 .claude-plugin，同样识别
+ * └── hooks/
+ *     ├── hooks.json                  # { description, modules: ["./register.ts"] }
+ *     └── register.ts                 # export function register(on, options)
+ * ```
+ *
+ * 多个 `modules` 的 `register` 按声明顺序执行（等价一个 mod 内多段注册，
+ * 先声明的更外层）。
+ *
+ * @param root mod 目录（含 `.codebuddy-plugin/` 或 `.claude-plugin/`）
+ * @param options tier / options / 自定义 importer
+ */
+export declare function loadModFromDirectory(root: string, options?: LoadOptions): Promise<LoadedMod>;
+/** 判断一个目录是否是 mod（带 function hooks 的 plugin）。 */
+export declare function isModDirectory(root: string, readText?: (path: string) => Promise<string>, joinPath?: (...paths: string[]) => string): Promise<boolean>;
+/** 把一个已在内存里的 `register` 包成 mod（测试 / 宿主自带 mod 用）。 */
+export declare function modOf(name: string, tier: Tier, register: Register, options?: PluginOptions, root?: string): RegisteredMod;

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

@@ -0,0 +1,33 @@
+/**
+ * plugin manifest 目录名 —— cbc 优先自有命名，同时**兼容识别** Claude Code 的。
+ *
+ * 顺序即优先级，与普通插件扫描共用 codebuddy、workbuddy、claude 的约定。
+ */
+export declare const MANIFEST_DIRS: string[];
+export type ManifestDir = (typeof MANIFEST_DIRS)[number];
+/** manifest 文件名（各实现一致）。 */
+export declare const MANIFEST_FILE = "plugin.json";
+/** hooks manifest 相对 plugin root 的路径（各实现一致）。 */
+export declare const HOOKS_MANIFEST: readonly ['hooks', 'hooks.json'];
+/** 一次探测的结果。 */
+export interface ManifestLocation {
+    /** 命中的目录名。 */
+    readonly dir: ManifestDir;
+    /** `<root>/<dir>/plugin.json` 的绝对路径。 */
+    readonly path: string;
+    /** 已读到的原文。 */
+    readonly text: string;
+}
+/**
+ * 在 plugin root 下按 PLUGINS_METADATA_DIRS 的优先级寻找 manifest。
+ *
+ * 这样一来，`anthropics/claude-code/mods/*` 这类**未经改动的官方 mod 目录**
+ * 可以直接被 cbc 加载（它们只有 `.claude-plugin`），而 cbc 自有生态可以用
+ * `.codebuddy-plugin` 且不与 Claude 争抢同一个目录名。
+ *
+ * @param root plugin 根目录
+ * @returns 命中的位置；候选目录都没有则 undefined
+ */
+export declare function findManifest(root: string, readText?: (path: string) => Promise<string>, joinPath?: (...paths: string[]) => string): Promise<ManifestLocation | undefined>;
+/** 供诊断用：列出候选路径。 */
+export declare function manifestCandidates(root: string): readonly string[];

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

@@ -0,0 +1,12 @@
+import { type PlatformPath } from 'node:path';
+import { type ModuleImporter } from './load-mod.js';
+export interface ModFileSystem {
+    readText(path: string): Promise<string>;
+    log?(...args: unknown[]): void;
+    paths: Pick<PlatformPath, 'resolve' | 'relative' | 'dirname' | 'join' | 'isAbsolute'>;
+}
+/** esbuild's virtual-module API keeps every source read on the host's mount.
+ * Each evaluation gets a fresh realm; only the session owner retains module state.
+ * No native-fs fallback, npm resolution or shared evaluated-module cache.
+ */
+export declare function mountedModuleImporter(fs: ModFileSystem): ModuleImporter;

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

@@ -0,0 +1,64 @@
+/**
+ * 按绝对路径做**真正的** ESM 动态 import。
+ *
+ * ## 两个 magic comment 都是必需的，不是装饰
+ *
+ * agent-cli 的发布产物是 rspack 打出的 CJS bundle。打包器默认会接管它**能看见**
+ * 的每一个 `import(x)`：在 CJS 输出里退化成自己的 `require(x)`。而 mod 的入口是
+ * 运行时才知道的绝对路径，落到 CJS `require` 上必然失败 —— 实测发布产物报
+ * `Cannot find module 'file:///…/register.ts'`：CJS 既不认 `file://` URL，也不认
+ * `.ts` 扩展名，更不会经过我们注册的 ESM resolve 钩子。
+ *
+ * `webpackIgnore` 让 rspack/webpack 原样保留这行 `import()`，交给 Node 的 ESM
+ * 加载器；`@vite-ignore` 让 vitest/Vite 别去静态分析一个运行时才成形的 specifier。
+ *
+ * 源码直跑（vitest / raw node）时没有打包器介入，所以缺了注释的坑**只在打包产物
+ * 里暴露** —— 这也是为什么这条路径必须用真实产物验证，单测全绿不能说明它通。
+ */
+export declare function importByPath(absPath: string): Promise<unknown>;
+/**
+ * 把一个本地 specifier 解析成实际存在的 TS 文件路径。
+ *
+ * @param p 已按 parent 解析出的绝对路径（可能无扩展名 / 是目录 / 带 .js 后缀）
+ * @returns 命中的文件绝对路径；没有则 undefined
+ */
+export declare function resolveTsPath(p: string): string | undefined;
+/** 本进程是否跑在 Bun 上。 */
+export declare function isBun(): boolean;
+/**
+ * runtime 是否自己就能吃下官方 mod 的写法（TS + 目录 import + `.js`→`.ts` + JSX）。
+ *
+ * 目前只有 Bun 满足。实测 Bun 1.4 原样加载全部四个官方 mod。
+ */
+export declare function hasNativeTypeScriptSupport(): boolean;
+/**
+ * 本进程是否具备 Node 内建通道 —— **两个条件都要**：
+ *
+ * 1. `module.registerHooks()`（Node 22.15+）—— 补 Bun 式模块解析
+ * 2. type stripping 开启 —— 擦类型
+ *
+ * 光有其一没用。真实存在的缺口是 **Node 22.15–22.17**：`registerHooks` 已经有了，
+ * 但 type stripping 要等 22.18 才默认开。那个区间若只按 `registerHooks` 判断，
+ * 每个 mod 都得先尝试失败一次才回退，白付一次开销（实测：strip 关闭时缓存里
+ * 出现 2 个产物而不是 1 个，说明连非 JSX 的 mod 也绕了一圈）。提前判掉更干净。
+ */
+export declare function isNodeTypeScriptAvailable(): boolean;
+/**
+ * 在「只对 `root` 之下生效」的钩子作用域内跑一段加载逻辑。
+ *
+ * 并发安全：多个 mod 同时加载时共用一次注册，引用计数归零才 `deregister()`。
+ * 因此钩子存在的时间被压到最短，宿主此后的模块解析不再经过它。
+ *
+ * @param root 允许被补解析的目录（mod 的 root）
+ * @param body 加载逻辑
+ */
+export declare function withModResolveScope<T>(root: string, body: () => Promise<T>): Promise<T>;
+/** 该错误是否说明「这个 mod 需要真转译器」。 */
+export declare function needsTranspiler(error: unknown): boolean;
+/**
+ * 通道一 / 二：runtime 原生，或 Node 内建 type stripping + 作用域化 resolve 钩子。
+ *
+ * @param entry register 模块的绝对路径
+ * @param root 该 mod 的 root（钩子白名单；缺省用 entry 所在目录）
+ */
+export declare function importWithNodeTypeStripping(entry: string, root?: string): Promise<unknown>;

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

@@ -0,0 +1,105 @@
+import type { LoadedMod } from './load-mod.js';
+/**
+ * mods 的对外 TS 契约 —— 生产、命名空间与落盘位置。
+ *
+ * ## 命名空间
+ *
+ * cbc 以 `codebuddy-code` 为**主模块名**，并把 `claude-code` 作为**兼容别名**
+ * 一起声明。于是：
+ * - cbc 生态：`import type { On } from 'codebuddy-code'`
+ * - 未经改动的官方 mod：`import type { On } from 'claude-code'` 同样成立
+ *
+ * 两个模块名指向同一套声明（别名文件 `export * from` 主文件），所以不会出现
+ * 「同名类型两份实例」的问题。
+ *
+ * ## 落盘位置
+ *
+ * 与官方 `/plugin-types` 的布局对齐（官方写 `.claude/types/`）：
+ *
+ * ```
+ * <cwd>/.codebuddy/types/
+ * ├── codebuddy-code.d.ts               # 引擎 API 声明（主）
+ * ├── claude-code.d.ts                  # 兼容别名，re-export 主文件
+ * ├── codebuddy-code-plugins.d.ts       # 已启用 plugin 契约的索引
+ * └── codebuddy-code-plugins/
+ *     └── <plugin>.d.ts                 # 每个 plugin 的契约副本
+ * ```
+ *
+ * ## 怎么生产
+ *
+ * `emitPluginTypes()` 是唯一入口（宿主把它挂到 `/plugin-types` 斜杠命令或
+ * `codebuddy plugin types` 子命令上）：
+ * 1. 写引擎声明（来源是本包 `mods/types/` 的编译产物 `.d.ts`，见 `engineDeclarations`）
+ * 2. 逐个拷贝各 plugin 的 `types` 契约到 `codebuddy-code-plugins/<plugin>.d.ts`
+ * 3. 生成索引 `codebuddy-code-plugins.d.ts`（`/// <reference path="…" />` 汇总）
+ */
+/** 主模块名。 */
+export declare const PRIMARY_MODULE = "codebuddy-code";
+/** 兼容模块名（让官方 mod 原样通过类型检查）。 */
+export declare const COMPAT_MODULE = "claude-code";
+/** 产出根目录（相对工作目录）。 */
+export declare const TYPES_DIR: string;
+/** 兼容读取的老目录（Claude Code 的位置）。 */
+export declare const COMPAT_TYPES_DIR: string;
+/** 各产物文件名。 */
+export declare const TYPE_FILES: {
+    readonly engine: "codebuddy-code.d.ts";
+    readonly engineCompat: "claude-code.d.ts";
+    readonly pluginsIndex: "codebuddy-code-plugins.d.ts";
+    readonly pluginsDir: "codebuddy-code-plugins";
+    readonly mcp: "codebuddy-code-mcp.d.ts";
+};
+/** `emitPluginTypes` 的入参。 */
+export interface EmitOptions {
+    /** 工作目录（产物落到 `<cwd>/.codebuddy/types/`）。 */
+    readonly cwd: string;
+    /**
+     * 引擎 API 的声明正文。
+     *
+     * 宿主传入本包 `mods/types` 的编译产物（`lib/node/mods/types/events.d.ts`
+     * 或其打平版本）。这里不自己跑 tsc —— 保持本函数纯 IO，便于测试。
+     */
+    readonly engineDeclarations: string;
+    /** 已启用的 mod（用其 `manifest.types` 找契约文件）。 */
+    readonly mods?: readonly LoadedMod[];
+    /** MCP 工具输入声明（可选）。 */
+    readonly mcpDeclarations?: string;
+}
+/** 一次生产的结果。 */
+export interface EmitResult {
+    /** 写出的文件绝对路径。 */
+    readonly written: readonly string[];
+    /** 被跳过的 plugin 契约与原因。 */
+    readonly skipped: readonly {
+        readonly plugin: string;
+        readonly reason: string;
+    }[];
+}
+/** 契约校验失败的原因。 */
+export interface ContractProblem {
+    readonly line?: number;
+    readonly reason: string;
+}
+/**
+ * 校验一个 plugin 的类型契约是否「自包含、纯类型」。
+ *
+ * 规则与官方 `claude plugin validate` 对齐：
+ * - 不含 import / export-from / require / `/// <reference>`
+ * - 不含会运行的代码（`class` / `const` / `enum` / `function` / `let` / `var`）
+ * - 不含隐藏或改变阅读顺序的字符
+ *
+ * @param source 契约文件正文
+ * @returns 问题列表；空数组表示通过
+ */
+export declare function validateContract(source: string): readonly ContractProblem[];
+/**
+ * 生成 mods 的对外 TS 契约。
+ *
+ * @param options 工作目录 / 引擎声明 / 已启用 mod
+ * @returns 写出的文件与跳过项
+ */
+export declare function emitPluginTypes(options: EmitOptions): Promise<EmitResult>;
+/** 两个候选 types 目录（`.codebuddy/types` 优先，`.claude/types` 兼容）。 */
+export declare function typesDirCandidates(cwd: string): readonly string[];
+/** 给 mod 作者用的 tsconfig 片段（把产物纳入类型检查）。 */
+export declare function tsconfigHint(): string;

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

@@ -0,0 +1,84 @@
+import { HooksRegistry } from '../engine/index.js';
+import type { EngineInterface, EventInput, EventName, EventResult, On, RegisteredMod, Tier } from '../types/index.js';
+/**
+ * 测试脚手架 —— 语义对齐官方 `claude-code/testing`。
+ *
+ * 核心约定（原文）：「A test gets the engine's own `$` and a plugin's `on`. …
+ * The hooks the test registers with `on` sit **beneath** the mod, where the
+ * rest of the world would be, and **nothing is beneath them**: a call they
+ * leave unanswered throws, naming its event.」
+ *
+ * 所以：
+ * - 被测 mod 挂在 `tier(t)` 声明的层；
+ * - 测试用 `on()` 注册的 hook 挂在 `core` 层（世界层，在 mod 之下）；
+ * - 没有任何 hook 应答的 `$` 调用 → 抛错并点名事件。
+ */
+/** 一次 harness 的句柄。 */
+export interface Harness {
+    /** fold 后的 `$`（等于被测 mod 看到的那一个）。 */
+    readonly $: EngineInterface;
+    /** 世界层注册器（挂在 `core` tier，位于被测 mod 之下）。 */
+    readonly on: On;
+    /** 直接分发事件（绕过 `$`，用于测 middleware 行为）。 */
+    readonly dispatch: (event: EventName, input: EventInput, coreResult?: EventResult) => Promise<EventResult>;
+    /** 底层引擎。 */
+    readonly hooks: HooksRegistry;
+}
+/** `createHarness` 的入参。 */
+export interface HarnessOptions {
+    /** 被测 mod。 */
+    readonly mod: RegisteredMod;
+    /** 额外挂载的 mod（如 noun provider）。 */
+    readonly also?: readonly RegisteredMod[];
+}
+/**
+ * 建一套测试环境：被测 mod 在它声明的 tier，测试 hook 在 `core` 层。
+ *
+ * 未被应答的调用会抛错，形如：
+ * `nothing answered "fs.read"; register a hook for it in the test`
+ */
+export declare function createHarness(options: HarnessOptions): Promise<Harness>;
+/**
+ * 延迟建 harness 的形态：先让测试用 `on()` 注册世界层，再 `ready()` 构建 `$`。
+ *
+ * 官方 `test(name, async ($, on) => ...)` 里 `$` 与 `on` 同时可用，是因为
+ * 世界层 hook 的注册和 `$` 调用发生在同一个同步 body 的不同时刻；这里用
+ * 「先收集、首次 `$` 调用时 fold」的等价做法。
+ */
+export interface LazyHarness {
+    readonly on: On;
+    /** 首次访问时 fold；之后返回同一个 `$`。 */
+    readonly $: EngineInterface;
+    readonly dispatch: (event: EventName, input: EventInput, coreResult?: EventResult) => Promise<EventResult>;
+    readonly hooks: HooksRegistry;
+}
+/**
+ * 与 `createHarness` 等价，但 `$` 是惰性代理：任何方法首次被调用时才 fold，
+ * 这样测试可以「先 `on(...)` 铺世界层、后 `await $.xxx()`」，与官方写法一致。
+ */
+export declare function harness(options: HarnessOptions): LazyHarness;
+/** `mock.clock` 的句柄。 */
+export interface MockClock {
+    /** 当前虚拟时间。 */
+    now: () => number;
+    /** 推进虚拟时间，兑现所有到期的 sleep/after/every。 */
+    advance: (ms: number) => Promise<void>;
+    /** 让已 start 的 dispatch 有机会推进到下一个 await 点（时钟不动）。 */
+    settle: () => Promise<void>;
+}
+/**
+ * 从内存应答世界层的 noun。每个成员都是一个把 hook 注册到 `on` 上的普通函数 ——
+ * 与官方「each member a plain function over `on`」一致。
+ */
+export declare const mock: {
+    /** `$.env.get` / `$.env.set` 走内存变量表。 */
+    env(on: On, variables?: Record<string, string>): void;
+    /** `$.store.*` 走内存 KV。 */
+    store(on: On, entries?: Record<string, unknown>): void;
+    /** `$.clock.*` 走虚拟时钟；`advance(ms)` 兑现到期的等待。 */
+    clock(on: On, options?: {
+        startMs?: number;
+    }): MockClock;
+};
+/** 声明被测 mod 所在的层（对齐官方 `tier('builtin')`）。 */
+export declare function tierOf(t: Tier): Tier;

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

@@ -0,0 +1 @@
+export * from './harness.js';