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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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