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

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

@@ -0,0 +1,215 @@
+import type { EngineInterface, SessionCompactInput, Settings, UiAskOptions } from '../types/index.js';
+/**
+ * 一个渲染面。对齐官方 `RenderSurface`。
+ *
+ * 这套 UI API **不是终端专用**：官方把它做成了面抽象，`session.start` 带
+ * `surface`，`$.session.surfaces()` 返回**多个**面，`RenderViewport` 还区分
+ * 「terminal 按字符格」与「远端面按代码字体折算」。同一个 mod 的 UI hook 要能
+ * 同时服务终端和远端 GUI。
+ *
+ * 映射到 cbc：`terminal` = Ink TUI，`cbc-webui` = `--serve` 的 CLI Web UI，
+ * `desktop` = WorkBuddy Desktop，`vscode` = VS Code 扩展。`web` / `mobile`
+ * 保留给未来的浏览器版 / 移动端外壳（官方 mod 已在用这两个名字，类型层要认）。
+ */
+export type RenderSurface = 'terminal' | 'cbc-webui' | 'desktop' | 'web' | 'mobile' | 'vscode';
+/**
+ * 宿主注入给 `core` 层的**窄接口**。
+ *
+ * ## 为什么是接口而不是直接调 agent-cli
+ *
+ * mods 位于 `cbc-plugins`，而会话、cwd、TUI 输出这些只有宿主知道。反过来 import
+ * 宿主会把依赖方向掉个头（也会撞上 cbc-core/shared 的单向依赖卡点）。所以这里只
+ * 声明「core 需要宿主回答什么」，由宿主填。
+ *
+ * ## 每一项都可选，缺省有诚实的退化
+ *
+ * 官方 mod 不会假设宿主实现了全部能力 —— `agents-md` 就把 `$.telemetry` 包在
+ * `Telemetry.quietly()` 里，因为那个 noun 可能根本没被 seat。同理，宿主没接的
+ * 能力必须给出**明确的拒绝**而不是静默 `undefined`：前者 mod 能感知并退化，后者
+ * 会变成难查的错误值。`createCoreHandler` 因此对未注入的能力回 `{ deny }`。
+ */
+export interface HostBindings {
+    /** An embedding host owns its filesystem and environment; do not fall through to Node. */
+    readonly fs?: EngineInterface['fs'];
+    readonly env?: EngineInterface['env'];
+    /** 当前会话的工作目录（绝对路径）。`$.session.cwd()` */
+    readonly cwd?: () => string;
+    /**
+     * 项目根（通常是 git 仓库根）。`$.session.root()`
+     *
+     * `agents-md` 用它判断「这是不是一个 CLAUDE.md 项目」，拿不到会退化成
+     * 「不是」，所以返回 undefined 是合法答案，不是错误。
+     */
+    readonly root?: () => string | undefined | Promise<string | undefined>;
+    /** 会话 id。`$.session.id()` */
+    readonly sessionId?: () => string | undefined;
+    /** 当前模型 id。`$.session.model()` */
+    readonly model?: () => string | undefined;
+    /** 是否交互式（TUI）。`session.start` 的 `isInteractive` 用。 */
+    readonly isInteractive?: () => boolean;
+    /** 仓库信息。`$.session.repo()` */
+    readonly repo?: () => {
+        root: string;
+        remote: string | null;
+        internal: boolean;
+        name: string | null;
+    } | undefined | Promise<{
+        root: string;
+        remote: string | null;
+        internal: boolean;
+        name: string | null;
+    } | undefined>;
+    /** 用户已提交的 prompt 数（transcript 中的 user turns）。`$.session.turns()` */
+    readonly turns?: () => number | Promise<number>;
+    /** Await real compaction; false is a failure, never a successful no-op. */
+    readonly compact?: (input: SessionCompactInput, signal: AbortSignal) => Promise<boolean>;
+    /** 会话消息。`$.session.messages()` */
+    readonly messages?: () => readonly unknown[] | Promise<readonly unknown[]>;
+    /**
+     * 当前渲染面。`$.session.surface()`
+     *
+     * 没有可渲染的面（`--print` / ACP stdio 这类无界面运行）时回 `null` ——
+     * 那是官方 `SessionStartInput.surface: RenderSurface | null` 里的合法取值，
+     * mod 据此决定要不要画东西，不是错误。
+     */
+    readonly surface?: () => RenderSurface | null;
+    /** 全部渲染面。`$.session.surfaces()` —— 同一个会话可以同时挂多个。 */
+    readonly surfaces?: () => readonly RenderSurface[] | Promise<readonly RenderSurface[]>;
+    /** 用量。`$.session.usage()` */
+    readonly usage?: (args?: Record<string, unknown>) => unknown | Promise<unknown>;
+    /** 中断当前轮次。`$.turn.abort()` */
+    readonly abortTurn?: (input: Record<string, unknown>) => void | Promise<void>;
+    /** 当前 prompt 文本。`$.prompt.read()` */
+    readonly readPrompt?: () => string | undefined | Promise<string | undefined>;
+    /** Apply the final middleware text to a live surface; receipt is not model completion. */
+    readonly fillPrompt?: (input: {
+        text: string;
+    }, signal: AbortSignal) => Promise<{
+        accepted: true;
+    }>;
+    readonly submitPrompt?: (input: {
+        text: string;
+    }, signal: AbortSignal) => Promise<{
+        accepted: true;
+    }>;
+    readonly suggestPrompt?: (input: {
+        text: string;
+    }, signal: AbortSignal) => Promise<{
+        accepted: true;
+    }>;
+    /** 已注册工具。`$.tool.list()` */
+    readonly tools?: () => readonly unknown[] | Promise<readonly unknown[]>;
+    /** 已注册命令。`$.command.list()` */
+    readonly commands?: () => readonly unknown[] | Promise<readonly unknown[]>;
+    /** 已注册 agent。`$.agent.list()` */
+    readonly agents?: () => readonly unknown[] | Promise<readonly unknown[]>;
+    /** 配置项。`$.config.list()` */
+    readonly configs?: () => readonly unknown[] | Promise<readonly unknown[]>;
+    /**
+     * 注册一个斜杠命令。`$.command.register(spec)`
+     *
+     * 未提供时 core 缺省按「名义成功」处理（返回 `{ command: name }`），与
+     * `agent.register` 对齐——很多官方 mod 用命令注册作为 `bind()` 的必要前置，
+     * 若在 e2e / test harness / 未接命令表的宿主里被 deny，整个 mod 就此空转。
+     * 想把命令真正接进 CLI 的宿主实现这里并覆盖 fallback。
+     */
+    readonly registerCommand?: (spec: Record<string, unknown>) => unknown | Promise<unknown>;
+    /** 注册工具。`$.tool.register(spec)`——同 registerCommand，未提供时缺省名义成功。 */
+    readonly registerTool?: (spec: Record<string, unknown>) => unknown | Promise<unknown>;
+    /**
+     * 注销工具。`$.tool.unregister(name)`
+     *
+     * 与 register 不同，缺 host 时 core 明确拒绝：一个"名义成功"的 unregister
+     * 会让 mod 以为清理妥当，实际宿主里工具仍在挂着。
+     */
+    readonly unregisterTool?: (name: string) => void | Promise<void>;
+    /** 注销斜杠命令。`$.command.unregister(name)`——同 unregisterTool，缺 host 时 deny。 */
+    readonly unregisterCommand?: (name: string) => void | Promise<void>;
+    readonly isCommandUnregistered?: (name: string) => boolean;
+    /** 注册 agent。`$.agent.register(spec)` */
+    readonly registerAgent?: (spec: Record<string, unknown>) => unknown | Promise<unknown>;
+    /**
+     * 往会话记录/调试流里写一行。`$.ui.log()`
+     *
+     * `plugin` 是发起本次调用的 mod 名（`origin.plugin`）—— 宿主要把这行落到用户
+     * 可见的位置（TUI 消息历史 / Web UI chat view）时需要它来做前缀 / 分组 / 归属。
+     * 宿主自身发起的引擎调用会拿到 `'engine'`（core 层的 origin 缺省值）。
+     */
+    readonly log?: (text: string, to: string, plugin: string) => void;
+    /** Uses the host's real question UI. Cancellation rejects, never implies consent. */
+    readonly ask?: (question: string, options: UiAskOptions, signal: AbortSignal) => Promise<string>;
+    /** 一次性提示。`$.ui.toast()` */
+    readonly toast?: (text: string, timeoutMs?: number) => void;
+    /** 状态行。`$.ui.status()` */
+    readonly status?: (text: string) => void;
+    /** 打开一个面板。`$.ui.open()` */
+    readonly openPane?: (pane: Record<string, unknown>) => unknown | Promise<unknown>;
+    /** 关闭一个面板。`$.ui.close()` */
+    readonly closePane?: (pane: Record<string, unknown>) => unknown | Promise<unknown>;
+    /** 当前面板列表。`$.ui.panes()` */
+    readonly panes?: () => readonly unknown[] | Promise<readonly unknown[]>;
+    /** 作废某个渲染事件的缓存。`$.ui.invalidate()` */
+    readonly invalidate?: (event: string) => void;
+    /** 给某次工具调用附一条说明。`$.ui.notice()` */
+    readonly notice?: (toolUseId: string, text: string) => void;
+    /**
+     * 把一棵**已序列化**的渲染树送到各个面。
+     *
+     * 刻意收成「一个面无关的出口」：终端在本进程里画，desktop / web / vscode 在
+     * 另一个进程里画（cbc 走 ACP 的 `extNotification`）。宿主自己决定送给哪些面
+     * —— `$.session.surfaces()` 本就返回复数，同一棵树可能要同时喂好几个。
+     *
+     * 树里已经没有函数：交互闭包留在 agent 侧，按元素 key 寻址（见
+     * `render-registry.ts`）。因此这个出口的入参一定是可序列化的。
+     */
+    readonly paint?: (tree: unknown, context: {
+        plugin: string;
+        surface?: RenderSurface | null;
+    }) => void | Promise<void>;
+    /**
+     * 允许 mod 发起外部网络请求（`$.http.fetch()`）。
+     *
+     * 默认**不开**：mod 是第三方代码，让它无条件出网是一个需要宿主明确表态的
+     * 决定，不该由「忘了配置」来默认开启。不传即明确拒绝。
+     */
+    readonly allowHttp?: boolean;
+    /**
+     * 允许 mod 起子进程（`$.process.run()`）。同上，默认不开。
+     */
+    readonly allowProcess?: boolean;
+    /** 合并后的设置。`$.settings.read()` */
+    readonly settings?: (source?: string) => Settings | Promise<Settings>;
+    /**
+     * 每个 plugin 各自的持久化 KV 的落盘目录。
+     *
+     * 不传则 `$.store` 退化成**进程内**存储：能用，但重启即失忆。这是刻意的 —— 让
+     * 能力可用比让它悄悄失败重要，而「重启丢失」对 mod 来说是可观测的正常状态。
+     */
+    readonly storeDir?: string;
+    /** `$.model.complete(request)` — the host's model completion call. */
+    readonly modelComplete?: (request: Record<string, unknown>, signal: AbortSignal) => Promise<string>;
+    /** `$.model.fork(request)` — start a background fork of the current session. */
+    readonly modelFork?: (request: Record<string, unknown>, signal: AbortSignal) => Promise<unknown>;
+    /**
+     * `$.model.classify(text, labels, options)` — pick the label that best fits.
+     *
+     * The default implementation (when this binding is missing but
+     * `modelComplete` is present) reuses `modelComplete` with a fixed
+     * classification prompt template; hosts that have a purpose-built
+     * classifier should override.
+     */
+    readonly modelClassify?: (text: string, labels: readonly string[], options: Record<string, unknown> | undefined, signal: AbortSignal) => Promise<string | undefined>;
+    /** `$.mcp.call(server, tool, args)` — dispatch an MCP tool call. */
+    readonly mcpCall?: (server: string, tool: string, args: Record<string, unknown>, signal: AbortSignal) => Promise<unknown>;
+    /** `$.audio.play(clip, options?)` — play a sound. */
+    readonly audioPlay?: (clip: unknown, options: Record<string, unknown> | undefined) => Promise<void>;
+    /** `$.audio.speak(text, options?)` — read text aloud (returns TTS receipt). */
+    readonly audioSpeak?: (text: string, options: Record<string, unknown> | undefined) => Promise<unknown>;
+    /** `$.session.authorize()` — hand back a short-lived credential handle. */
+    readonly authorize?: () => Promise<{
+        handle: string;
+        kind: 'bearer' | 'api-key';
+    }>;
+    /** `$.ui.blit(args)` — repaint a Raster in place without a full re-render. */
+    readonly blit?: (args: Record<string, unknown>) => Promise<unknown>;
+}

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

@@ -0,0 +1,6 @@
+export * from './core-handler.js';
+export * from './host-bindings.js';
+export * from './plugin-store.js';
+export * from './render-component.js';
+export * from './render-registry.js';
+export * from './terminal-play.js';