@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/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';

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

@@ -0,0 +1,188 @@
+/**
+ * `types/events/agent.ts`
+ *
+ * Precise `agent.*` event shapes: `agent.spawn`, `agent.offer`, plus the
+ * op-facing types `AgentSpec` / `AgentInfo` / `AgentCallRecord` / `AgentLoop`.
+ *
+ * Field-for-field aligned with upstream so mods that read `e.subagentType`,
+ * `e.background`, `e.fork`, `e.parentModel`, `e.parentAgentId` etc. type-check
+ * unchanged after switching import specifier to `codebuddy-code`.
+ */
+import type { Origin } from '../events.js';
+/**
+ * What an Agent call a plugin raised answers as `result` once the agent
+ * settles; `text` is its final answer.
+ *
+ * A plugin's spawn always runs in the background, so the call resolves with
+ * this record and not the Agent tool's own `BuiltinToolResults` entry, which
+ * is what a model's Agent call carries at `tool.call`.
+ */
+export interface AgentCallRecord {
+    /** The spawned agent's id, as `$.agent.list()` names it. */
+    agentId: string;
+    /** The model the agent resolved to, when one is known. */
+    resolvedModel?: string;
+}
+/**
+ * One agent loop of this session as `$.agent.list()` returns it: a subagent
+ * or an in-process teammate.
+ */
+export interface AgentInfo {
+    /** The agent's id: same string its loop's `tool.call` events carry as `agentId`. */
+    id: string;
+    /** Its row's label. */
+    description: string;
+    /** The agent definition it runs as, or `teammate` for an in-process teammate. */
+    type: string;
+    /** `running`, `completed`, `failed`, `killed`, or another engine task status. */
+    status: string;
+    /** The id of the subagent whose loop spawned it; absent when the main loop did. */
+    parentId?: string;
+    /** The plugin whose `$.agent.spawn` started it; absent when the model or the person did. */
+    spawnedBy?: string;
+    /** What SendMessage addresses it by, when it has one; not `description` or `type`. */
+    name?: string;
+}
+/**
+ * Which model loop an event happened in: the loop's agent id inside a
+ * subagent's or a teammate's loop, absent on the main loop.
+ *
+ * The agent axis, not the origin axis: `next.origin` names the plugin whose
+ * hook frame caused the dispatch (the recursion skip), whichever loop it ran
+ * in; `agentId` names the loop, whoever caused the call.
+ */
+export interface AgentLoop {
+    /** The id of the loop this call runs in; absent on the main loop. Pinned. */
+    agentId?: string;
+}
+/**
+ * The input of `agent.offer`: one agent type, at the moment the engine
+ * offers it to the model.
+ *
+ * Listed for the model or named by it at dispatch: same event at each.
+ * Model-facing only: a plugin's own `$.agent.spawn` of a type is no offer.
+ */
+export interface AgentOfferInput {
+    /** Which type (`Explore`, `Plan`, a plugin's agent). */
+    agent: string;
+    /** Its listing line's text as the definition states it (`whenToUse`). */
+    description: string;
+    /** Where the definition came from (`built-in`, `plugin`, a settings source). */
+    source: string;
+    /** Who provides this agent. Pinned: a rewrite is refused. */
+    provider: Origin;
+}
+/**
+ * What an `agent.offer` hook returns: whether the model is offered the agent
+ * type, in its listing and at dispatch.
+ */
+export interface AgentOfferResult {
+    isOffered: boolean;
+}
+/**
+ * The input of `agent.spawn`: what the Agent tool decided about the subagent
+ * it is about to start, before its model is resolved.
+ *
+ * A hook rewrites content (prompt, description, subagentType, model,
+ * background, cwd), read back as the tool's parameters; tool_use_id, name,
+ * fork, parentModel, permissionMode, parentAgentId and provider are pinned.
+ */
+export interface AgentSpawnInput {
+    /** The Agent tool call this spawn belongs to. Pinned. */
+    tool_use_id: string;
+    /** The task the subagent is given. A rewrite is the prompt the subagent runs with. */
+    prompt: string;
+    /** The Agent tool's short `description` of the task. */
+    description: string;
+    /** The resolved agent type. A rewrite names another agent this call can dispatch. */
+    subagentType: string;
+    /** Who provides this agent. Pinned with the spawn's identity. */
+    provider: Origin;
+    /** The Agent tool's `model` parameter as given. */
+    model?: string;
+    /** The parent's effective model. Pinned. */
+    parentModel: string;
+    /** The id of the loop the spawn happens in; absent from main. Pinned. */
+    parentAgentId?: string;
+    /** The parent's permission mode. Pinned. */
+    permissionMode?: string;
+    /** True when the subagent will run in the background (or remotely). */
+    background: boolean;
+    /** True for a fork of the parent. Pinned. */
+    fork: boolean;
+    /** Given by the call (`Agent({ name })`); undefined when unnamed. Pinned. */
+    name?: string;
+    /** The directory the subagent runs in when the call set one. */
+    cwd?: string;
+}
+/**
+ * `agent.spawn`'s input as the call takes it: what the Agent tool's caller
+ * says; the engine fills the rest.
+ */
+export type AgentSpawnArgs = Pick<AgentSpawnInput, 'prompt'> & Partial<Pick<AgentSpawnInput, 'description' | 'subagentType' | 'model' | 'name' | 'cwd'>>;
+/**
+ * What an `agent.spawn` hook returns and what `next(e)` resolves to: the
+ * started subagent's `{ model, agentId }`, or `{ deny: reason }`, refusing it.
+ */
+export type AgentSpawnResult = {
+    /** What the subagent runs on. */
+    model: string;
+    /** The started subagent's id. Set by core; absent when a hook answered without `next`. */
+    agentId?: string;
+    deny?: undefined;
+} | {
+    /** Refuses the spawn; the model sees the text as the Agent tool's error. */
+    deny: string;
+    model?: undefined;
+    agentId?: undefined;
+};
+/**
+ * What `$.agent.register` takes: an agent type this plugin defines, spelled
+ * as an agent definition in settings JSON is, plus its `name`.
+ *
+ * Every field an agent file or `--agents` entry may carry is here and takes
+ * effect as it does there; the engine validates it with the same schema.
+ */
+export interface AgentSpec {
+    /** The type's short name (letters, digits, `_`, `-`; up to 64). */
+    name: string;
+    /** When to delegate to this agent: the line the model reads in its listing. */
+    description: string;
+    /** The agent's system prompt, whole: it replaces the session's. */
+    prompt: string;
+    /** What the agent may call, by tool name; a call to any other is refused. */
+    tools?: readonly string[];
+    /** Tools withheld from the agent, out of whatever `tools` allows. */
+    disallowedTools?: readonly string[];
+    /** The agent's model: an alias, a full id, or `inherit`. */
+    model?: string;
+    /** The agent's effort: a level or an integer budget. */
+    effort?: string | number;
+    /** How the agent's permission asks are decided. */
+    permissionMode?: string;
+    /** Servers connected over MCP for the agent's run. */
+    mcpServers?: readonly (string | Record<string, unknown>)[];
+    /** Settings hooks in force while the agent runs, in settings.json's `hooks` shape. */
+    hooks?: Record<string, unknown>;
+    /** The most turns the agent takes before it stops. */
+    maxTurns?: number;
+    /** Preloaded into the agent's context before its first turn: skill names. */
+    skills?: readonly string[];
+    /** The agent's first user turn; `{{intent}}` in it takes the spawn's prompt. */
+    initialPrompt?: string;
+    /** A persistent memory the agent keeps between runs, and where. */
+    memory?: 'user' | 'project' | 'local';
+    /** Set so that every spawn of the agent runs in the background. */
+    background?: true;
+    /** Set so that the agent's context carries no CLAUDE.md block. */
+    omitClaudeMd?: true;
+    /** Where the agent runs apart from the session. */
+    isolation?: 'worktree' | 'remote';
+}
+/**
+ * What `$.agent.register` resolves to: the type's fully-qualified name
+ * (`<plugin>:<name>`).
+ */
+export interface AgentRegisterResult {
+    agent: string;
+}