@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/builtin/index.d.ts

@@ -0,0 +1,14 @@
+import type { RegisteredMod } from '../types/index.js';
+export * from './sec-default.js';
+export * from './telemetry.js';
+/**
+ * 宿主自带的 mod，坐在 `builtin` tier。
+ *
+ * tier 顺序是 `prepend → user → append → builtin → core`，builtin 在 user 之内 ——
+ * 用户装的 mod 包在外层，可以观察、改写甚至拦掉内置行为。内置的是**缺省值**，
+ * 不是不可绕过的沙箱；真正不可绕过的边界在宿主自己的权限系统里。
+ *
+ * 顺序也有意义：`telemetry` 排在 `sec-default` 前面，这样后者若要记录自己拦了
+ * 什么，`$.telemetry` 已经 seat 好了。
+ */
+export declare function builtinMods(): readonly RegisteredMod[];

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

@@ -0,0 +1,32 @@
+import type { Register } from '../types/index.js';
+/**
+ * 内置 `sec-default` mod —— 给 mod 能力面加一条**最小**的安全底线。
+ *
+ * ## 为什么要有，又为什么要克制
+ *
+ * `--plugin-dir` 加载的是第三方代码，`$.fs.*` 让它能读写任意路径。宿主给一条
+ * 默认底线是合理的；但内置策略过严会**悄悄弄坏**合法 mod，而且用户很难猜到是
+ * 被内置规则拦的。所以这里只拦「几乎不可能有正当理由」的那一类：
+ *
+ * - SSH 私钥、云厂商凭据、`.env`、浏览器/钥匙串数据库；
+ * - 写操作额外拦住 shell 启动文件（`.bashrc`/`.zshrc` 之类）—— 往里写一行就是
+ *   持久化的任意代码执行，而一个 mod 有正当理由改它的情形基本不存在。
+ *
+ * 其余一律放行：真正的收紧应当由用户自己装 policy mod 来做，而不是宿主替他决定。
+ *
+ * ## 坐在 builtin tier，因此可被用户覆盖
+ *
+ * tier 顺序 `prepend → user → append → builtin → core`：用户装的 mod 在**外层**，
+ * 可以先于本 mod 应答、也可以把调用拦在到达这里之前。这是刻意的 —— 内置底线是
+ * 缺省值，不是不可绕过的沙箱。真正不可绕过的边界在宿主自己的权限系统里
+ * （PreToolUse hook、permission 检查），那一层 mod 动不了。
+ *
+ * ## 拒绝必须说清楚是谁拦的
+ *
+ * 否则用户看到的是「mod 读文件失败」，会去查文件权限、查路径拼写，唯独想不到是
+ * 一条内置规则。每条拒绝都带上本 mod 的名字和命中的类别。
+ */
+/** 内置 sec-default mod 的名字。 */
+export declare const BUILTIN_SEC_NAME = "cbc-sec-default";
+/** 内置 sec-default 的 register。 */
+export declare const registerBuiltinSecDefault: Register;

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

@@ -0,0 +1,43 @@
+import type { Register } from '../types/index.js';
+/**
+ * 内置 `telemetry` mod —— 把 `$.telemetry` 这个 noun 坐实。
+ *
+ * ## 为什么值得内置
+ *
+ * 官方 mod 把「`$.telemetry` 可能根本不存在」写进了代码：`agents-md` 每次调用都
+ * 包在 `Telemetry.quietly()` 里，noun 缺席时整段静默跳过。也就是说不装它并不会
+ * 报错，只会让所有 mod 的埋点**悄悄消失**。内置一份，官方 mod 的遥测路径就是通的，
+ * 而不是「看起来在跑，其实什么都没记」。
+ *
+ * ## 坐在 builtin tier
+ *
+ * tier 顺序是 `prepend → user → append → builtin → core`，builtin 在 user 之内。
+ * 这正是需要的：用户自己装的 mod 包在外层，可以观察、改写甚至拦掉内置行为；反过来
+ * 内置的不该越过用户的决定。
+ *
+ * ## 计数落 `$.store`
+ *
+ * `$.store` 按 plugin 隔离，所以这里的键不会和任何用户 mod 撞。跨会话累计也因此
+ * 免费得到 —— 埋点最常见的问题恰恰是「重启就归零，看不出趋势」。
+ */
+/** 一条埋点。 */
+export interface TelemetryRow {
+    readonly name: string;
+    readonly at: number;
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+/** `$.telemetry` 的形状。 */
+export interface TelemetryNoun {
+    /** 记一条。 */
+    log(name: string, data?: Record<string, unknown>): void;
+    /** 打一个标记（官方 `mark` 的位置）。 */
+    mark(name: string, data?: Record<string, unknown>): void;
+    /** 本次会话记下的全部条目。 */
+    rows(): readonly TelemetryRow[];
+    /** 落盘累计计数，返回累计值。 */
+    flush(): Promise<number>;
+}
+/** 内置 telemetry mod 的名字（`$.store` 按它分文件）。 */
+export declare const BUILTIN_TELEMETRY_NAME = "cbc-telemetry";
+/** 内置 telemetry 的 register。 */
+export declare const registerBuiltinTelemetry: Register;

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

@@ -0,0 +1,41 @@
+/**
+ * cbc-mods 的入口开关。
+ *
+ * ## 默认关 —— 必须显式 opt-in
+ *
+ * 语义：用户不显式声明就当作**未启用**。传 `--plugin-dir <mod>` 也不例外：
+ * 目录本身只表达"想指向这些文件"，而是否把里面的 hook 装配到进程内是独立的
+ * 安全决定，得由 `CBC_ENABLE_FUNCTION_HOOKS=1` 之类的 env 明确同意。
+ *
+ * 需要**显式开**：
+ * - `CBC_ENABLE_FUNCTION_HOOKS=1` / `true` / `on` / `yes`（大小写不敏感、允许前后空格）
+ * - `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` 同上（官方别名）
+ *
+ * 显式关（覆盖任何 ON）：
+ * - `CBC_ENABLE_FUNCTION_HOOKS=0` / `false` / `off` / `no`
+ * - `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=0` 同上
+ *
+ * 任一 alias 显式关就整体关；两个都不显式开即视为**默认关**。
+ * 未识别的字符串（如 `maybe` / 空串）不算 ON，也不算 OFF —— 走默认关。
+ */
+/**
+ * 判断当前环境是否启用 cbc-mods function hooks。
+ *
+ * 语义：
+ * - 任一 alias 显式关闭 → 关
+ * - 无显式关闭且至少一个显式开启 → 开
+ * - 其余（未设 / 空串 / 未识别值） → 关
+ */
+export declare function isFunctionHooksEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare const FUNCTION_HOOKS_ENV_VAR = "CBC_ENABLE_FUNCTION_HOOKS";
+export declare const CLAUDE_COMPAT_ENV_VAR = "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS";
+/** 关闭 mod 隔离沙箱的 env 变量名（默认开，仅用于逃生）。 */
+export declare const MODS_ISOLATE_ENV_VAR = "CBC_MODS_ISOLATE";
+/**
+ * mod 是否走隔离沙箱执行（`isolated-import.ts` 的加固 realm）。
+ *
+ * 与 function hooks 总开关不同，这一项**默认开** —— 隔离是安全默认，只有显式
+ * `CBC_MODS_ISOLATE=0/false/off/no` 才关（逃生阀，供确需直接摸 Node 内建的 mod
+ * 临时降级）。未识别值按「不关」处理，仍然隔离。
+ */
+export declare function isModIsolationEnabled(env?: NodeJS.ProcessEnv): boolean;

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

@@ -0,0 +1,61 @@
+import type { EngineInterface, RegisteredMod, Tier } from '../types/index.js';
+import { type HooksRegistry } from './hooks-registry.js';
+/** 判断一个值是否 withhold 占位。 */
+export declare function isWithheld(v: unknown): boolean;
+/**
+ * 构造 `$` —— 每个方法都经 `registry.dispatch()`，因此上层 mod 可以拦截、
+ * 改写、拒绝任何一次能力调用（`sec-default` 式管控 / 审计 mod 的基础）。
+ *
+ * 两类方法：
+ * - **Op 方法**（`OP_TABLE`）：分发 `<noun>.<op>` op 事件，结果取 `{ value }`；
+ *   `{ deny }` 则抛错（调用方视为能力被拒）。
+ * - **Event call 方法**（`EVENT_CALL_TABLE`）：分发 middleware 事件，
+ *   原样返回事件结果（`tool.call` / `command.run` / `session.start` …）。
+ *
+ * 每次分发都带上 `origin = { plugin, tier }` —— 官方语义里 `next.origin` 是
+ * **发起调用的那个 plugin**，`sec-default` 的 `tool.register` 就靠它判断
+ * 「调用者是组织装的还是用户装的」。
+ *
+ * @param registry 事件引擎
+ * @param plugin 该 `$` 所属 plugin 的身份（name / root / tier）
+ */
+export declare function buildBaseSurface(registry: HooksRegistry, plugin: {
+    readonly name: string;
+    readonly root: string;
+    readonly tier?: Tier;
+}): EngineInterface;
+/** `engine.create` fold 期间发现的违规。 */
+export interface NounViolation {
+    /** 被试图替换的 noun。 */
+    readonly noun: string;
+    readonly reason: string;
+}
+/**
+ * 跑 `engine.create` fold 组装最终 `$`。
+ *
+ * 语义对齐官方：
+ * - `next(e)` 直接 resolve 成 **`$` 本身**（`NextResult<'engine.create'> =
+ *   EngineInterfaceBuilt`），所以官方 mod 的 `{ ...await next(e), telemetry }`
+ *   能原样工作。
+ * - 一个 step **可以 ADD** noun
+ * - 一个 step **可以 WITHHOLD** noun（返回时不带某个 key，或不调 `next`）
+ * - 一个 step **不可 REPLACE** core 提供的 noun
+ * - fold 完成后 `$` 冻结
+ *
+ * ## 违规不连坐
+ *
+ * 试图替换 core noun 时**不让整个 fold 失败** —— fold 走的是整条 `engine.create`
+ * 链（含所有 mod 的 step），一个 mod 的违规若抛错，会让**其他无辜 mod 和 host
+ * 都拿不到 `$`**。正确的隔离是：丢弃违规那个 noun（换回 core 的原值），通过
+ * `onViolation` 报出来，fold 照常完成。
+ *
+ * @param registry 事件引擎（已 register 全部 mod）
+ * @param mods 参与 fold 的 mod 名单（决定 `engine.create` 的 `plugins` 入参）
+ * @param plugin 这份 `$` 归属的 plugin（含 tier，用于 `next.origin`）
+ * @param onViolation 发现违规时的回调（不传则静默丢弃）
+ */
+export declare function buildEngineInterface(registry: HooksRegistry, mods: readonly RegisteredMod[], plugin: {
+    readonly name: string;
+    readonly root: string;
+    readonly tier?: Tier;
+}, onViolation?: (violation: NounViolation) => void): Promise<EngineInterface>;

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

@@ -0,0 +1,188 @@
+import type { EngineInterface, EventInput, EventName, EventResult, Origin, RegisteredMod, Tier } from '../types/index.js';
+/**
+ * `core` 层行为：所有 hook 都 `next()` 到底后由它给出结果。
+ *
+ * `origin` 是**发起这次分发的调用方**（`next.origin` 的同一个值）。core 需要它做
+ * 两件事，缺了就做不成：按 plugin 隔离持久化（`$.store` 不能让一个 mod 读到另一个
+ * 的键），以及审计「谁动了宿主资源」。
+ */
+export type CoreHandler = (event: EventName, input: EventInput, origin: Origin) => EventResult | Promise<EventResult>;
+/** 一次 hook 运行期失败（已被隔离，仅作上报）。 */
+export interface HookRuntimeFailure {
+    /** 哪个 plugin 的 hook。 */
+    readonly plugin: string;
+    /** 哪个事件上。 */
+    readonly event: EventName;
+    readonly kind: 'throw' | 'timeout';
+    readonly message?: string;
+}
+/** hook 运行期失败的上报出口。 */
+export type HookFailureReporter = (failure: HookRuntimeFailure) => void;
+/** 一次 dispatch 的可选项。 */
+export interface DispatchOptions {
+    /** 覆盖本次的 core 结果（不走 `setCoreHandler`）。 */
+    /**
+     * 覆盖本次的 core 结果（不走 `setCoreHandler`）。
+     *
+     * 可以是一个**值**，也可以是一个**thunk**。给 thunk 的场合是「core 这一层是
+     * 一个动作而不是一个答案」—— 最典型的就是 `tool.call`：core = 真的把工具跑
+     * 起来。传值意味着调用方必须先执行再分发，那样一个 `{ deny }` 的 hook 也拦不
+     * 住已经发生的副作用；传 thunk 才能做到「链真的走到底才执行」。
+     */
+    readonly coreResult?: EventResult | ((e: EventInput) => EventResult | Promise<EventResult>);
+    /** Host-owned projection (e.g. instruction files → text) at every fold boundary. */
+    readonly normalize?: (value: EventInput, previous: EventInput) => EventInput | Promise<EventInput>;
+    /** Host cancellation; also inherited by nested dispatches. */
+    readonly signal?: AbortSignal;
+    /** 覆盖单层 hook 预算（ms）。测试可调小。 */
+    readonly budgetMs?: number;
+    /**
+     * 谁发起了这次分发 —— 即 `next.origin`。
+     *
+     * 官方语义：「Who raised a dispatch … the **calling** plugin's name and the
+     * tier it sits in; the engine reads `engine` in `core`.」
+     * 所以它是 **caller** 的身份，整条链每一层看到的都是同一个，不是各层自己。
+     *
+     * 缺省 `{ plugin: 'engine', tier: 'core' }`（引擎自身的调用点）。
+     */
+    readonly origin?: Origin;
+}
+/** 引擎自身发起调用时的 origin。 */
+export declare const ENGINE_ORIGIN: Origin;
+/**
+ * Host-internal only: runs `fn` outside the caller's hook frames. Other ALS
+ * (Session, tracing, etc.) is untouched. A timer/subscription's callback is
+ * a new asynchronous operation, not a continuation of the hook that armed it,
+ * so `$` calls inside must not inherit that hook's expired frame. Callers must
+ * not expose this on the plugin `$` surface.
+ */
+export declare function runOutsideHookFrames<T>(fn: () => T): T;
+/** Time in a downstream handler or $ capability is not the caller's work. */
+export declare function withHookWait<T>(operation: () => Promise<T>): Promise<T>;
+/** $.clock.sleep is deliberately charged, even beside an unawaited next(). */
+export declare function withHookSleep<T>(operation: () => Promise<T>): Promise<T>;
+/** Host-internal only: never exposed on the plugin's $ surface. */
+export declare function withTrustedHostWait<T>(operation: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;
+/**
+ * cbc-mods 的 middleware 引擎 —— 语义等价 Anthropic claude-code 的 function hooks。
+ *
+ * ## 分发模型
+ *
+ * 一次 `dispatch(event, input)`：
+ * 1. 挑出 pattern 命中 `event`、matcher 命中 `input` 的注册；
+ * 2. 按 tier 外→内（`prepend > user > append > builtin > core`）+ 注册序成链；
+ * 3. 逐层 `hook($, e, next)`：
+ *    - `await next(e)` 透传（改 `e` 即改下游入参）
+ *    - 直接返回结果 → 短路，下游不执行，`next.signal` abort
+ *    - `{ deny }` → 拒绝语义
+ *    - `undefined` → 未干预，冒泡下游/core 结果
+ *    - `next.to(e, tier)` → 跳到目标 tier
+ * 4. 链走完落 `core`（host 注入的 `CoreHandler`）。
+ *
+ * ## 运行时约束（对齐官方 `HookBudget`）
+ *
+ * - 单层 hook 预算 `10s`，`catch` handler `1s`；超时按 `HookFailure{kind:'timeout'}` 处理。
+ * - hook 抛错/超时：有 `.catch(handler)` 走它；否则该层按「未干预」继续下游，**不炸整条链**。
+ * - `next.trace` 累积每层 `TraceEntry`（plugin/tier/outcome/ms/received/returned）。
+ */
+export declare class HooksRegistry {
+    private readonly entries;
+    private readonly modsByTier;
+    private seqCounter;
+    private coreHandler;
+    /** 每个 plugin 自己的 `$`（官方：`engine.create` 一 plugin 一份）。 */
+    private readonly enginesByPlugin;
+    private engine;
+    private reportFailure;
+    /**
+     * §6.4 — currently-active hook entries on **this** async stack.
+     *
+     * A hook is never re-entered while its own frame is being dispatched:
+     * an `on('*', …)` that calls `$.ui.log(...)` inside itself would
+     * otherwise loop, because `ui.log` is itself an event that matches
+     * `*` again. `AsyncLocalStorage` scopes this per-dispatch-chain, so
+     * two genuinely concurrent dispatches (two mods each `await
+     * next(e)`) do not shadow each other's active set.
+     */
+    private readonly activeEntries;
+    /**
+     * Host-only boundary for a new operation delivered by a long-lived worker
+     * or subscription. Reset this registry's re-entry guard and hook frames;
+     * keep Session/tracing ALS intact. Never expose this on the plugin `$` API.
+     * Retained plugin next() closures still carry their original closed frame.
+     */
+    runOutsideHooks<T>(operation: () => T): T;
+    /**
+     * 订阅 hook 运行期失败（抛错 / 超时且没有 `.catch` 兜住）。
+     *
+     * 失败**已经**被隔离成「该层未干预」，链路照常往下走。上报是为了让这类故障
+     * **可见**：一个抛错的 hook 对外表现是「mod 完全不生效，但日志干净、加载成功」，
+     * 不上报就只能靠盲试定位。
+     *
+     * @param reporter 上报出口；不设则失败仍被隔离，只是无人知晓
+     */
+    onHookFailure(reporter: HookFailureReporter | undefined): void;
+    /** 设置 `core` 层行为（host 的真实实现）。 */
+    setCoreHandler(handler: CoreHandler): void;
+    /** 注入 fold 后的默认 `$`（没有 per-plugin 版本时用它）。 */
+    setEngine(engine: EngineInterface): void;
+    /** 注入某个 plugin 专属的 `$`。 */
+    setEngineFor(plugin: string, engine: EngineInterface): void;
+    private engineOf;
+    /**
+     * 挂一个 mod：立刻执行 `mod.register(on, options)` 收集注册。
+     *
+     * 同一 mod 内 `on()` 调用顺序 = middleware 嵌套顺序（先注册的更外层）。
+     *
+     * **事务语义**：`mod.register()` 是别人的代码，可能在中途抛错。若不回滚，
+     * 抛错前注册的那几个 hook 会半截留在链上 —— 一个只生效一半的 mod 比完全
+     * 没加载更危险（它的不变量没建立起来）。所以这里记录注册前的水位，出错就
+     * 截断回滚，并把异常原样抛给调用方去决定怎么报。
+     */
+    register(mod: RegisteredMod): void | Promise<void>;
+    /** 已挂载 mod 名单（按 tier 分组）。 */
+    listMods(): ReadonlyMap<Tier, readonly RegisteredMod[]>;
+    /** 已注册 hook 数（诊断用）。 */
+    registrationCount(): number;
+    /** 某个 mod 声明过的事件名（`plugin.register.uses.events` 用）。 */
+    eventsOf(plugin: string): readonly string[];
+    /**
+     * 针对某个事件 + 某个 discriminant 字段（如 `ui.render` 的 `component`），
+     * 汇总"哪些字段值有 hook 可能触发"—— 给宿主做 **cap 广播**用。
+     *
+     * ## 为什么需要
+     *
+     * 每个 Web UI slot 组件 mount 都发一次 `_codebuddy.ai/modRenderRequest`
+     * 到 agent、agent dispatch 后再 push 回来，光是 15 slot × N instance 的网络
+     * 开销就够呛。若能提前知道"根本没 mod 挂 `on('ui.render', { component: 'X' })`"，
+     * slot 组件可以**根本不发 request**，直接走默认 React JSX，零网络。
+     *
+     * ## 三种返回形态
+     *
+     * - **`'all'`**：至少有一条 `on('ui.render', hook)` **不带 matcher**（或 matcher
+     *   里没有该 discriminant 字段）—— 语义是通配匹配所有值，cap 必须包所有
+     *   component；宿主策略是 "只要有通配就都发"，Web UI 无法安全跳过。
+     * - **`ReadonlySet<string>`**：所有注册都精确 matcher 该字段，收集所有值。
+     * - **空 Set**：一条对该事件感兴趣的 hook 都没 —— slot 完全不发 request。
+     *
+     * ## 只看该事件的 pattern，不算跨事件的通配
+     *
+     * `on('*', hook)` 会在 `ui.render` 上触发（`patternMatches` 就是这么做的），
+     * 因此也必须视作 wildcard cap，把它返回成 `'all'`。
+     *
+     * @param event 目标事件名（例如 `'ui.render'`）
+     * @param discriminant 目标字段（例如 `'component'`）
+     */
+    matcherValuesFor(event: EventName, discriminant: string): 'all' | ReadonlySet<string>;
+    /**
+     * 分发一次事件。
+     *
+     * @param event 具名事件（`tool.call` / `classic.PreToolUse` / `fs.read` …）
+     * @param input 事件入参
+     * @param options core 结果覆盖 / 预算覆盖
+     */
+    dispatch(event: EventName, input: EventInput, options?: DispatchOptions): Promise<EventResult>;
+    private dispatchInScope;
+    private renderElements;
+    private runFrom;
+}

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

@@ -0,0 +1,6 @@
+export * from './pattern.js';
+export * from './op-table.js';
+export * from './hooks-registry.js';
+export * from './engine-builder.js';
+export * from './mods-runtime.js';
+export * from './enable-flag.js';

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

@@ -0,0 +1,101 @@
+import type { EngineInterface, EventInput, EventName, EventResult, RegisteredMod, Tier } from '../types/index.js';
+import { type CoreHandler, type DispatchOptions, type HookFailureReporter, HooksRegistry } from './hooks-registry.js';
+/** 一个 mod 在启动阶段的失败记录。 */
+export interface ModStartupFailure {
+    /** 出问题的 mod 名（host 自身的 fold 失败时是 host 名）。 */
+    readonly mod: string;
+    /** 哪个阶段：准入/注册，还是 `engine.create` fold。 */
+    readonly phase: 'register' | 'engine.create';
+    readonly reason: string;
+}
+/** `ModsRuntime` 的构造项。 */
+export interface RuntimeOptions {
+    /** `core` 层行为（host 的真实实现）。 */
+    readonly core?: CoreHandler;
+    /** 这份 `$` 归属的 plugin 身份（默认 host 自己）。 */
+    readonly plugin?: {
+        readonly name: string;
+        readonly root: string;
+    };
+    /**
+     * hook 运行期失败（抛错 / 超时）的上报出口。
+     *
+     * 失败本身已被隔离，链路照常。订阅它是为了让「mod 加载成功却完全不生效」
+     * 这类最难查的故障有声音。
+     */
+    readonly onHookFailure?: HookFailureReporter;
+}
+/**
+ * cbc-mods 运行时门面 —— 把「注册 mod → 跑 engine.create fold → 分发事件」串成一条线。
+ *
+ * ```ts
+ * const rt = new ModsRuntime({ core: (event, input) => hostHandle(event, input) });
+ * rt.add(telemetryMod);                 // builtin tier
+ * rt.add(await loadModFromDirectory(dir, { tier: 'user' }));
+ * const $ = await rt.start();           // engine.create fold，$ 冻结
+ * await rt.dispatch('tool.call', { tool: 'Bash', command: 'ls' });
+ * ```
+ */
+export declare class ModsRuntime {
+    private readonly registry;
+    private readonly mods;
+    private readonly plugin;
+    private engine;
+    private started;
+    private readonly failures;
+    constructor(options?: RuntimeOptions);
+    /**
+     * 供 legacy 扇出使用的 registry。
+     *
+     * `dispatchLegacyEvent` 需要直接拿到 registry 才能广播 `classic.<Event>`。
+     * 只开这一个窄口子，而不是把 registry 整个暴露出去 —— 其余调用方应当走
+     * `dispatch()`。
+     */
+    registryForLegacyFanOut(): HooksRegistry;
+    /**
+     * 某个 mod 实际注册到的事件列表。
+     *
+     * 诊断用：「mod 加载成功却不生效」时，第一个要回答的问题是「它到底有没有把
+     * hook 挂上去」—— 光看加载日志答不了。
+     *
+     * @param plugin mod 名
+     */
+    eventsOf(plugin: string): readonly string[];
+    /** 设置/替换 `core` 层行为。 */
+    setCore(core: CoreHandler): void;
+    /**
+     * 挂一个 mod。必须在 `start()` 之前调用。
+     *
+     * 先经 `plugin.register` 事件征询已挂载的 mod（对齐官方：上层可 `{ refuse }`
+     * 拒绝一个 mod 入场）—— 该判定在 `start()` 里统一执行，这里只收集。
+     */
+    add(mod: RegisteredMod): void;
+    /**
+     * 启动：按 tier 顺序逐个走 `plugin.register` 准入 → 注册 hook → 为每个 mod
+     * 跑一次 `engine.create` fold（官方：一 plugin 一份 `$`）→ 冻结。
+     *
+     * @returns host 自己那份 `$`；host 的 fold 也失败时 `undefined`
+     */
+    start(): Promise<EngineInterface | undefined>;
+    /**
+     * 记一条 noun 违规。
+     *
+     * fold 对每个 plugin 各跑一次，同一条违规会被看到 N 次；按 noun 去重，
+     * 让宿主的日志里只出现一条而不是刷屏。
+     */
+    private noteViolation;
+    /** 启动过程中各 mod 的失败记录（供宿主报给用户）。 */
+    get startupFailures(): readonly ModStartupFailure[];
+    /**
+     * fold 后的 `$`。
+     *
+     * host 那一份 fold 失败时为 `undefined` —— 调用方应当判空而不是假定它一定在。
+     */
+    get $(): EngineInterface | undefined;
+    /** 分发一次事件。 */
+    dispatch(event: EventName, input: EventInput, options?: DispatchOptions): Promise<EventResult>;
+    /** 底层引擎（诊断 / 高级用法）。 */
+    get hooks(): HooksRegistry;
+    /** 已挂载的 mod 名单（按 tier 分组）。 */
+    listMods(): ReadonlyMap<Tier, readonly RegisteredMod[]>;
+}

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

@@ -0,0 +1,37 @@
+import type { EventName } from '../types/index.js';
+/**
+ * `$` 上每个 noun 的方法 → op 事件名 + 入参打包方式。
+ *
+ * 对齐官方 `OpEventOf`（54 个）。每一项声明：
+ * - `event`：分发的事件名。绝大多数是 op 事件（`OpEventName`），但少数走
+ *   middleware 事件（`ui.resolve` 就是这样：mod 写 `const table = await
+ *   $.ui.resolve(e)`，但 `ui.resolve` 本身是 `EngineEventName` 中的一员）。
+ * - `pack`：把方法实参打成事件入参对象
+ *
+ * 这张表是 `$` 的唯一真源：`buildOpSurface()` 据此生成所有方法，
+ * 每个方法都先 `dispatch(event, packed)`，hook 可 `{ value }` 短路 /
+ * `{ deny }` 拒绝，否则落 host 实现。
+ */
+export interface OpSpec {
+    readonly event: EventName;
+    readonly pack: (...args: readonly unknown[]) => Record<string, unknown>;
+}
+/** noun → method → OpSpec。 */
+export declare const OP_TABLE: Readonly<Record<string, Readonly<Record<string, OpSpec>>>>;
+/**
+ * `$` 上直接分发 middleware 事件（而非 op 事件）的方法。
+ *
+ * 这些调用的结果是事件本身的结果形状（不是 `{ value }`），
+ * 对齐官方 `EventCalls`。
+ */
+export declare const EVENT_CALL_TABLE: Readonly<Record<string, Readonly<Record<string, EventName>>>>;
+/** 全部 noun 名（含只走 event call 的 skill / attribution）。 */
+export declare const ALL_NOUNS: readonly string[];
+/**
+ * op 事件 → 它对应的 `$` 调用写法（`$.fs.read` 这种）。
+ *
+ * 给 core 用：一个宿主没实现的能力必须回**指名道姓**的拒绝，而不是静默
+ * `undefined` —— 后者会让 mod 把「没实现」当成「值就是空」继续跑，错误被推迟到
+ * 很远的地方才炸。反查表让那句话能自己写出是哪个能力。
+ */
+export declare const OP_CALL_NAMES: ReadonlyMap<string, string>;

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

@@ -0,0 +1,20 @@
+import type { EventInput, EventName, Matcher, Pattern } from '../types/index.js';
+/**
+ * 判断一个 `on()` pattern 是否命中某个具名事件。
+ *
+ * 支持三种形态（对齐官方 `Pattern = EventName | Glob | Negation`）：
+ * - 具名：`'tool.call'` —— 精确相等
+ * - Glob：`'*'` 全部；`'classic.*'` / `'ui.*'` —— namespace 前缀
+ * - Negation：`'!tool.call'` / `'!ui.*'` —— 取反（命中被排除的以外全部）
+ *
+ * @param pattern on() 的第一参
+ * @param event 正在分发的具名事件
+ */
+export declare function patternMatches(pattern: Pattern, event: EventName): boolean;
+/**
+ * matcher 整体是否命中事件入参。matcher 未指定的字段视为通配。
+ *
+ * @param matcher on() 的第二参；undefined 表示无 matcher（永远命中）
+ * @param input 事件入参
+ */
+export declare function matcherApplies(matcher: Matcher | undefined, input: EventInput): boolean;

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

@@ -0,0 +1,78 @@
+import { type PlatformPath } from 'node:path';
+import { type CoreHandler } from '../engine/hooks-registry.js';
+import type { EventResult, FsAncestor } from '../types/index.js';
+import type { HostBindings } from './host-bindings.js';
+import { RenderRegistry, type SerializedElement } from './render-registry.js';
+/**
+ * `core` 层：`$` 上每个能力调用最终落到这里。
+ *
+ * ## 这一层的位置
+ *
+ * `$.fs.read(p)` 不是一次直接的文件读取，而是一次 `fs.read` 事件分发 —— 先经过每一
+ * 层 hook（别的 mod 可以拦、可以改路径、可以 `{ deny }`），没人应答才落到 core。
+ * 官方 `sec-default` 正是靠这个机制给宿主资源加策略。因此 core 只管「真的去做」，
+ * 不重复做准入判断。
+ *
+ * ## 未注入的能力返回 `{ deny }`，不返回 undefined
+ *
+ * 宿主可能只接了一部分绑定。这时必须给 mod 一个**明确的拒绝** —— `engine-builder`
+ * 会把 `deny` 变成一个带能力名的异常，mod 能 catch 并退化（官方 mod 就是这么写的）。
+ * 若回 `{ value: undefined }`，mod 会把「没实现」当成「值就是空」继续往下跑，错误
+ * 被推迟到很远的地方才炸。
+ */
+export interface CoreHandlerOptions {
+    readonly bindings?: HostBindings;
+    /** Host lifetime: reject new core calls after disposal, including retained `$` methods. */
+    readonly signal?: AbortSignal;
+    /**
+     * 共用的渲染树登记表。
+     *
+     * 必须由调用方持有：`ui.render` 的树是**链的返回值**（hook 画好后直接返回，
+     * 通常不会 `next(e)` 到 core），所以序列化只能发生在 dispatch 之后、由宿主
+     * 完成；而 `ui.press` 的回流又要在 core 里查同一张表。两边共用一个实例才对
+     * 得上。不传则 core 自己建一个（只有回流、没有登记，press 永远查不到）。
+     */
+    readonly renders?: RenderRegistry;
+}
+/**
+ * 从 `of`（缺省会话 cwd）逐级向上，收集名字命中的文件。
+ *
+ * 这是 `agents-md` 找祖先 `AGENTS.md` / `CLAUDE.md` 的唯一手段，语义要点（全部以
+ * 官方 `$.fs.ancestors` 的 jsdoc 为准）：
+ *
+ * - **root first** —— 最远的祖先排在前。这一条极易想反：直觉上「最近的最重要所以
+ *   放前面」，但官方明确 `@returns the files found, root first`，而 mod 依赖这个
+ *   顺序决定谁覆盖谁。顺序反了不会报错，只会让优先级悄悄颠倒。
+ * - `below` 给出**下界**（到这个目录为止，含它），把遍历关在项目内 —— 否则一路走到
+ *   `/`，用户家目录里无关的同名文件也会被吸进来。
+ * - `names` 是相对 `.md` 文件名，允许子路径（官方就用 `.claude/AGENTS.md`），
+ *   但**不允许 `..`** —— 那等于绕开 `below` 的约束。
+ * - 读不出来的文件**跳过**而不是中断整次遍历：权限不足的一个目录不该让能力失效。
+ */
+export interface AncestorFileSystem {
+    readText(path: string): Promise<string>;
+    isFile(path: string): Promise<boolean>;
+    paths: Pick<PlatformPath, 'resolve' | 'parse' | 'dirname' | 'join'>;
+}
+export declare function ancestorsOf(names: readonly string[], from: string, below?: string, fs?: AncestorFileSystem): Promise<FsAncestor[]>;
+/**
+ * 把一次 `ui.render` 的**链返回值**序列化并送到各个面。
+ *
+ * 为什么是这里而不是 core：`ui.render` 的语义是「hook 画好树并返回」，官方
+ * `NextResult<'ui.render'>` 就是 `RenderElement`。画界面的 hook 通常不会再
+ * `next(e)`，所以树根本不会到达 core —— 把序列化写在 core 里，结果就是
+ * 「mod 明明画了，宿主什么也没收到」。
+ *
+ * @param renders 与 core 共用的登记表（`ui.press` 要在里面查闭包）
+ * @param bindings 宿主绑定，提供 `paint` 出口
+ * @param plugin 画这棵树的 mod
+ * @param result 一次 `ui.render` dispatch 的结果
+ * @returns 序列化后的树；链上没人画则 undefined
+ */
+export declare function paintRenderResult(renders: RenderRegistry, bindings: HostBindings, plugin: string, result: EventResult): Promise<SerializedElement | undefined>;
+/**
+ * 建一个 `core` 处理器。
+ *
+ * @param options 宿主绑定及可选的生命周期；未注入时保留 CLI 默认行为。
+ */
+export declare function createCoreHandler(options?: CoreHandlerOptions): CoreHandler;