@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/types/events.d.ts

@@ -0,0 +1,651 @@
+/**
+ * Tier —— 与 Anthropic claude-code `mods/types/claude-code.d.ts` 的
+ * `const TIERS: readonly ["prepend", "user", "append", "builtin", "core"]` 完全一致。
+ *
+ * 外层先执行：`prepend`（企业强制最外）→ `user`（用户装的）→ `append`（企业兜底）
+ * → `builtin`（引擎自带 mod）→ `core`（引擎核心行为，也是老 shell hooks 的落点）。
+ */
+export declare const TIERS: readonly ['prepend', 'user', 'append', 'builtin', 'core'];
+export type Tier = (typeof TIERS)[number];
+/**
+ * `next.to(e, tier)` 的合法目标：只能往内跳，不能跳回 `prepend` / `user`。
+ * 对齐官方 `TargetTier = Exclude<Tier, 'prepend' | 'user'>`。
+ */
+export type TargetTier = Exclude<Tier, 'prepend' | 'user'>;
+/** 一个 mod 的可配置项（来自 plugin.json / settings）。对齐官方 `PluginOptions`。 */
+export type PluginOptions = Readonly<Record<string, string | number | boolean | readonly string[]>>;
+/** mod 入口函数签名。对齐官方 `Register = (on: On, options: PluginOptions) => unknown`。 */
+export type Register = (on: On, options: PluginOptions) => unknown;
+/** 引擎 middleware 事件名（对齐官方 `EngineEventOf` 的键集）。 */
+export type EngineEventName = 'tool.call' | 'tool.check' | 'tool.describe' | 'ui.render' | 'ui.resolve' | 'ui.press' | 'ui.input' | 'ui.select' | 'ui.message' | 'ui.scroll' | 'ui.focus' | 'agent.offer' | 'agent.spawn' | 'prompt.submit' | 'prompt.fill' | 'prompt.suggest' | 'prompt.edit' | 'prompt.section' | 'prompt.context' | 'prompt.attachment' | 'command.run' | 'command.describe' | 'config.set' | 'config.describe' | 'skill.prompt' | 'attribution.text' | 'session.start' | 'session.receive' | 'session.compact' | 'session.attach' | 'session.detach' | 'session.measure' | 'session.end' | 'plugin.register' | 'turn.start' | 'turn.step' | 'turn.complete' | 'engine.create';
+/**
+ * Op 事件名 —— `$.<noun>.<op>()` 每次调用同时是一个可拦截的事件。
+ * 对齐官方 `OpEventOf` 的键集。
+ */
+export type OpEventName = 'model.complete' | 'model.classify' | 'model.fork' | 'audio.play' | 'audio.speak' | 'mcp.call' | 'session.cwd' | 'session.root' | 'session.model' | 'session.turns' | 'session.id' | 'session.messages' | 'session.repo' | 'session.surface' | 'session.surfaces' | 'session.authorize' | 'session.usage' | 'turn.abort' | 'prompt.read' | 'tool.list' | 'tool.register' | 'tool.unregister' | 'command.list' | 'command.register' | 'command.unregister' | 'config.list' | 'agent.list' | 'agent.register' | 'ui.ask' | 'ui.toast' | 'ui.status' | 'ui.log' | 'ui.notice' | 'ui.invalidate' | 'ui.open' | 'ui.close' | 'ui.panes' | 'ui.blit' | 'fs.read' | 'fs.write' | 'fs.list' | 'fs.exists' | 'fs.stat' | 'fs.ancestors' | 'store.get' | 'store.set' | 'store.delete' | 'store.keys' | 'clock.now' | 'clock.sleep' | 'clock.after' | 'clock.every' | 'http.fetch' | 'process.run' | 'settings.read' | 'env.get' | 'env.set';
+/** cbc 老 shell hook 事件名（PascalCase，来自 `HookEvent` 枚举值）。 */
+export type ClassicHookEvent = 'PreToolUse' | 'PostToolUse' | 'Notification' | 'UserPromptSubmit' | 'Stop' | 'SubagentStop' | 'PreCompact' | 'SessionStart' | 'SessionEnd' | 'WorktreeCreate' | 'WorktreeRemove' | 'PostToolUseFailure' | 'SubagentStart' | 'StopFailure' | 'PostCompact' | 'ConfigChange' | 'InstructionsLoaded' | 'PermissionRequest' | 'PermissionDenied' | 'Elicitation' | 'ElicitationResult' | 'TaskCreated' | 'TaskCompleted' | 'TeammateIdle' | 'Setup' | 'FileChanged' | 'CwdChanged' | 'FinalStop';
+/** `classic.<Event>` 事件名族（对齐官方 `ClassicEventName`）。 */
+export type ClassicEventName = `classic.${ClassicHookEvent}`;
+/** 所有事件名。 */
+export type EventName = EngineEventName | OpEventName | ClassicEventName;
+/** 事件名的 namespace 部分（`tool.call` → `tool`）。 */
+export type Namespace<_E = unknown> = 'tool' | 'ui' | 'agent' | 'prompt' | 'command' | 'config' | 'skill' | 'attribution' | 'session' | 'turn' | 'plugin' | 'engine' | 'model' | 'audio' | 'mcp' | 'fs' | 'store' | 'clock' | 'http' | 'process' | 'settings' | 'env' | 'classic';
+/** Glob pattern：`*`（全部）或 `<namespace>.*`。对齐官方 `Glob`。 */
+export type Glob = '*' | `${Namespace}.*`;
+/** Negation pattern：`!<EventName | Glob>`。对齐官方 `Negation`。 */
+export type Negation = `!${Exclude<EventName | Glob, '*'>}`;
+/** `on()` 的第一参：具名事件、Glob 或 Negation。对齐官方 `Pattern`。 */
+export type Pattern = EventName | Glob | Negation;
+/**
+ * 事件 input 的通用形状。
+ *
+ * 官方为每个事件定义了精确类型；cbc 侧用「已知关键字段 + index signature 兜底」
+ * 的结构兼容形态：官方 mod 的 `register.ts` 读什么字段都能通过，运行时按 host
+ * 实际注入的 payload 为准。
+ */
+export interface EventInputBase {
+    /**
+     * 事件主体的提供方（`tool.describe` / `command.describe` / `agent.offer` /
+     * `agent.spawn` 上由引擎钉住）。`sec-default` 的 `pastUsers` 读它判断归属。
+     */
+    provider?: {
+        tier?: unknown;
+        plugin?: string;
+    } | null;
+    [key: string]: unknown;
+}
+/** 事件 input（所有事件统一形状）。 */
+export type EventInput = EventInputBase;
+/**
+ * 事件结果。
+ *
+ * - **Op 事件**（`<noun>.<op>`）：`{ value }` 承载返回值，`{ deny }` 拒绝。
+ * - **Middleware 事件**：各事件自己的字段（`{ result }` / `{ text }` /
+ *   `{ description }` / `{ isOffered }` / `{ model }` / `{ value }` …）。
+ *
+ * 用 index signature 兜底，让官方 mod 的各种返回形态都合法。
+ */
+/**
+ * Type-parameterised for upstream compatibility (`EventResult<N>`, where `N`
+ * is the event name whose result this is). cbc uses a structural fallback
+ * shape; the type parameter is accepted for compat and not enforced.
+ */
+export interface EventResult<_N = unknown> {
+    /** Op 事件的返回值。 */
+    value?: unknown;
+    /** 拒绝原因；`tool.call` 场景 = 阻止工具执行。 */
+    deny?: string;
+    /** `tool.call` 的执行结果。 */
+    result?: unknown;
+    /** `plugin.register` 拒绝一个 mod 入场。 */
+    refuse?: string;
+    [key: string]: unknown;
+}
+/**
+ * matcher —— 浅字段 + 深嵌套 + 数组任一 + RegExp + 谓词。
+ *
+ * 官方用例：
+ * - `{ tool: 'Read' }`（值相等）
+ * - `{ command: ['clear', 'resume'] }`（数组任一）
+ * - `{ component: 'Pane' }`
+ * - `{ fork: true }`
+ * - `{ instructionFiles: { kind: [...] } }`（深嵌套 + 数组）
+ */
+export type MatcherValue<_A = unknown> = string | number | boolean | null | RegExp | readonly unknown[] | ((v: unknown) => boolean) | {
+    readonly [k: string]: MatcherValue;
+};
+/**
+ * Type-parameterised for upstream compatibility (`Matcher<Args<N>>`); at cbc
+ * runtime we discard the parameter and use the structural predicate table,
+ * so any generic argument is accepted.
+ */
+export interface Matcher<_A = unknown> {
+    readonly [k: string]: MatcherValue;
+}
+/**
+ * `next` —— 执行下游链。语义对齐官方 `StarNext` / `GlobNext`。
+ *
+ * - `next(e)`：继续下一层（改写 e 即改写下游看到的入参）
+ * - `next.to(e, tier)`：跳到指定 tier 起点继续（只能往内）
+ * - `next.origin`：当前 hook 所在的 tier + plugin
+ * - `next.event`：本次分发的具名事件（glob hook 靠它分辨）
+ * - `next.is(pattern, e)`：事件归属判定（glob hook 内的守卫）
+ * - `next.signal`：下游被放弃（超时 / 上层短路）时 abort
+ * - `next.budget`：本层的时间预算
+ * - `next.trace`：已执行各层的轨迹
+ */
+/**
+ * Type-parameterised for upstream compatibility (`Next<P, N>`), where `P` is
+ * the pattern and `N` the event name. cbc's runtime is structural; the type
+ * parameters are accepted but not enforced beyond the shape below.
+ */
+export interface Next<_P = unknown, _N = unknown, _E = unknown, _S = unknown> {
+    (e: EventInput): Promise<EventResult>;
+    readonly origin: Origin;
+    readonly to: (e: EventInput, tier: TargetTier) => Promise<EventResult>;
+    readonly event: EventName;
+    readonly is: (pattern: Pattern, e: unknown) => boolean;
+    readonly signal: AbortSignal;
+    readonly budget: NextBudget;
+    readonly trace: readonly TraceEntry[];
+}
+/** hook 所属来源。对齐官方 `Origin`。 */
+export interface Origin {
+    readonly plugin: string;
+    readonly tier: Tier;
+}
+/** 本层剩余预算。对齐官方 `NextBudget`。 */
+export interface NextBudget {
+    readonly ms: number;
+    readonly remainingMs: number;
+}
+/** hook 时间预算常量。对齐官方 `HookBudget`。 */
+export declare const HOOK_BUDGET: {
+    /** 普通 hook 预算。 */
+    readonly ms: 10000;
+    /** `catch` handler 预算。 */
+    readonly catchMs: 1000;
+    /** 返回后下游仍可继续跑的宽限。 */
+    readonly lingerMs: 5000;
+};
+export type HookBudget = typeof HOOK_BUDGET;
+/** hook 失败形态。对齐官方 `HookFailure`。 */
+export interface HookFailure {
+    readonly kind: 'throw' | 'timeout';
+    readonly message?: string;
+    readonly budget: number;
+}
+/** 一层执行结果。对齐官方 `TraceOutcome`。 */
+export type TraceOutcome = 'answered' | 'passed' | 'denied' | 'threw' | 'timedout';
+/**
+ * 单层轨迹。对齐官方 `TraceEntry<E, I, R>` — cbc discards the extra type
+ * parameters; the structural fields are the wire shape.
+ */
+export interface TraceEntry<_E = unknown, _I = unknown, _R = unknown> {
+    readonly index: number;
+    readonly plugin: string;
+    readonly tier: Tier;
+    readonly event: EventName;
+    readonly outcome: TraceOutcome;
+    readonly reason?: string;
+    readonly ms: number;
+    readonly received: EventInput;
+    readonly returned: EventResult | undefined;
+}
+/**
+ * 一个 hook。`$` 是 `engine.create` fold 后的 capability surface。
+ *
+ * 返回 `undefined` 等价于「不干预」（下游/核心结果直接冒泡）。
+ */
+export type Hook = ($: EngineInterface, e: EventInput, next: Next) => EventResult | undefined | Promise<EventResult | undefined>;
+/** `on()` 的返回值：可挂 `catch` 处理器。对齐官方 `Registration`。 */
+export interface Registration {
+    readonly catch: (handler: CatchHandler) => void;
+}
+/** catch handler 拿到的 next：额外带 `error` 与 `called`。对齐官方 `Caught`。 */
+export type CaughtNext = Next & {
+    readonly error: HookFailure;
+    readonly called: boolean;
+};
+/** Alias of `CaughtNext` matching upstream's exported name. */
+export type Caught = CaughtNext;
+/** hook 抛错/超时时的兜底处理器；返回 undefined 表示「按未干预处理」。 */
+export type CatchHandler = ($: EngineInterface, e: EventInput, next: CaughtNext) => EventResult | undefined | Promise<EventResult | undefined>;
+/** 注册器。对齐官方 `On` 的两种重载。 */
+export interface On {
+    (pattern: Pattern, hook: Hook): Registration;
+    (pattern: Pattern, matcher: Matcher, hook: Hook): Registration;
+}
+export interface SessionAuthorization {
+    handle: string;
+    kind: 'bearer' | 'api-key';
+}
+export interface HttpInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    auth?: string;
+    socketPath?: string;
+}
+export interface HttpResponse {
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    text: string;
+}
+export interface ProcessRunInit {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    timeoutMs?: number;
+}
+export interface ProcessRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface FsAncestorsRequest {
+    /** 相对 `.md` 文件名，可含子路径（官方用 `.claude/AGENTS.md`），不得含 `..`。 */
+    names: readonly string[];
+    /** 从哪个路径往上走，缺省会话 cwd。 */
+    of?: string;
+    /** 遍历的下界目录（含它），把走查关在项目内。 */
+    below?: string;
+}
+/** 一个祖先条目里的一段：文件自己，或它 `@` 导入进来的一个文件。 */
+export interface FsAncestorPart {
+    /** 绝对路径。 */
+    path: string;
+    content: string;
+}
+export interface FsAncestor {
+    dir: string;
+    name: string;
+    /** 文件文本，后面接着它 `@include` 带进来的内容。 */
+    content: string;
+    /**
+     * 文件自己，然后它 `@` 导入的每个文件，按加载顺序。
+     *
+     * **必填**，不是可选装饰：官方 `agents-md` 的 `filesOf()` 直接
+     * `entry.parts.map(...)`，缺了它当场 `undefined.map` 抛错，表现为
+     * 「mod 加载成功但一点效果没有」。
+     */
+    parts: readonly FsAncestorPart[];
+}
+export type Settings = Readonly<Record<string, unknown>>;
+/** 设置来源。对齐官方 `SettingsSource`。 */
+export type SettingsSource = 'user' | 'project' | 'local' | 'flag' | 'policy';
+export interface SettingsReadArgs {
+    source?: SettingsSource;
+}
+/** 一个 mod 静态声明的能力面。对齐官方 `PluginRegisterUses`。 */
+export interface PluginRegisterUses {
+    events: readonly string[];
+    calls: readonly string[];
+    env?: {
+        reads: readonly string[];
+        writes: readonly string[];
+    };
+}
+/** `plugin.register` 事件入参。对齐官方 `PluginRegisterInput`。 */
+export interface PluginRegisterInput {
+    name: string;
+    tier: Exclude<Tier, 'core'>;
+    root: string;
+    version?: string;
+    provenance: string;
+    uses: PluginRegisterUses;
+}
+/** `engine.create` 事件入参。对齐官方 `EngineCreateInput`。 */
+export interface EngineCreateInput {
+    plugins: readonly string[];
+}
+import type { ToolCallInput, ToolCallOverloads, ToolCallResult, ToolCheckArgs, ToolCheckInput, ToolCheckResult, ToolDescribeInput, ToolDescribeResult, ToolInfo, ToolRegisterResult, ToolSpec } from './events/tool.js';
+import type { AgentOfferInput, AgentOfferResult, AgentSpawnInput, AgentSpawnResult, AgentInfo, AgentSpec, AgentRegisterResult } from './events/agent.js';
+import type { CommandRunInput, CommandRunResult, CommandDescribeInput, CommandDescribeResult, CommandInfo, CommandSpec, CommandRegisterResult } from './events/command.js';
+import type { PromptSubmitInput, PromptSubmitResult, PromptFillInput, PromptFillResult, PromptFilled, PromptFillArgs, PromptSuggestInput, PromptSuggestResult, PromptEditInput, PromptEditResult, PromptSectionInput, PromptSectionResult, PromptContextInput, PromptContextResult, PromptAttachmentInput, PromptAttachmentResult, PromptBox } from './events/prompt.js';
+export type * from './events/tool.js';
+export type * from './events/agent.js';
+export type * from './events/command.js';
+export type * from './events/prompt.js';
+export type * from './events/upstream.js';
+/**
+ * 一个可取消的定时器。对齐官方 `Timer`。
+ *
+ * `$.clock.after(ms, fn)` / `$.clock.every(ms, fn)` 返回这个形状 —— 官方 mod
+ * 保存 timer 引用后靠 `timer.cancel()` 清理（`diff` mod 的 `polled` / `redraw`
+ * / `refresh` 三个 timer 都是这个模式）。返回一个裸函数不够 —— mod 会写
+ * `timers.get(k)?.cancel()`，裸函数上取 `.cancel` 是 undefined。
+ */
+export interface Timer {
+    /** 取消这个 timer。已被取消或已 fire 过是幂等 no-op。 */
+    readonly cancel: () => void;
+}
+/**
+ * 一个可渲染的面板（`$.ui.open` 的入参）。对齐官方 `PaneOpenArgs`。
+ *
+ * 官方 mod 里 `dialogPane()` 组装这个对象，含 `id` / `title` / `holdToasts`
+ * / `closeOnEscape` / `rows` / `focus`；除了 `id` 都是可选。
+ */
+export interface PaneOpenArgs {
+    /** 面板唯一 id。用于 `$.ui.close`、`ui.render`/`ui.scroll` 事件的 `requestId`。 */
+    id: string;
+    title?: string;
+    /** 打开期间是否吞 toast（弹窗态用）。 */
+    holdToasts?: boolean;
+    /** Escape 键是否关闭该面板（对话框态用）。 */
+    closeOnEscape?: boolean;
+    /** 期望行数（对话框态自适应内容）。 */
+    rows?: number;
+    /** 打开后是否请求 focus。 */
+    focus?: boolean;
+    /** 承载 mod 自身扩展字段（比如 `placement: 'dock' | 'inline'`）。 */
+    [key: string]: unknown;
+}
+/**
+ * 一个会话消息（`$.session.messages()` 返回数组的元素类型）。
+ *
+ * 用 `type` 判别；`diff` mod 只关心 `tool.call` 消息（`toolName` / `input`），
+ * 官方类型更细，这里给一个通用 discriminated union + index signature 兜底。
+ */
+export type SessionMessage = {
+    readonly type: 'user' | 'assistant' | 'system';
+    readonly text?: string;
+    readonly [k: string]: unknown;
+} | {
+    readonly type: 'tool.call';
+    readonly toolName?: string;
+    readonly input?: Record<string, unknown>;
+    readonly output?: unknown;
+    readonly [k: string]: unknown;
+} | {
+    readonly type: string;
+    readonly [k: string]: unknown;
+};
+/**
+ * 每个 EventName 对应的入参形状 —— `Args<E>` 是给 mod 作者写
+ * `hook($, e: Args<'tool.call'>, next)` 用的。
+ *
+ * 精确入参存在 `EventInputMap` 里：一次迁一个 namespace，把 upstream 的
+ * `EventOf` 键补进来。**未迁**的事件回落到宽松的 `EventInputBase`，保证
+ * 老 hook 仍然可写。
+ *
+ * 迁移次序见 plan 文件 §R1.1；`tool.*` 已迁。
+ */
+export interface EventInputMap {
+    'tool.call': ToolCallInput;
+    'tool.check': ToolCheckInput;
+    'tool.describe': ToolDescribeInput;
+    'agent.offer': AgentOfferInput;
+    'agent.spawn': AgentSpawnInput;
+    'command.run': CommandRunInput;
+    'command.describe': CommandDescribeInput;
+    'prompt.submit': PromptSubmitInput;
+    'prompt.fill': PromptFillInput;
+    'prompt.suggest': PromptSuggestInput;
+    'prompt.edit': PromptEditInput;
+    'prompt.section': PromptSectionInput;
+    'prompt.context': PromptContextInput;
+    'prompt.attachment': PromptAttachmentInput;
+}
+export type Args<E extends EventName = EventName> = E extends keyof EventInputMap ? EventInputMap[E] : EventInputBase;
+/**
+ * 每个 EventName 对应的结果形状 —— `ResultOf['tool.call']` 之类的官方索引访问。
+ *
+ * 与 `Args<E>` 一样：精确结果在 `EventResultMap` 里；未迁的回落到宽松
+ * `EventResult`。
+ */
+export interface EventResultMap {
+    'tool.call': ToolCallResult;
+    'tool.check': ToolCheckResult;
+    'tool.describe': ToolDescribeResult;
+    'agent.offer': AgentOfferResult;
+    'agent.spawn': AgentSpawnResult;
+    'command.run': CommandRunResult;
+    'command.describe': CommandDescribeResult;
+    'prompt.submit': PromptSubmitResult;
+    'prompt.fill': PromptFillResult;
+    'prompt.suggest': PromptSuggestResult;
+    'prompt.edit': PromptEditResult;
+    'prompt.section': PromptSectionResult;
+    'prompt.context': PromptContextResult;
+    'prompt.attachment': PromptAttachmentResult;
+}
+export type ResultOf = {
+    readonly [E in EventName]: E extends keyof EventResultMap ? EventResultMap[E] : EventResult;
+};
+/**
+ * 一次 `$.ui.resolve(e)` 的返回：一张元素工厂表。
+ *
+ * `diff` mod 的 `ui.render` hook 里写 `const { Box, Text, Button, Select, Code }
+ * = await $.ui.resolve(e)` 拿到工厂，然后当 JSX 组件用。这些工厂在运行时**返回
+ * `SerializedElement`**（与 `<Box>` 全局函数同形），mod 侧当组件调用。
+ *
+ * 这也是「元素表是闭集」在 mod 视角的落点：不在这张表里的 tag 无法被 resolve。
+ */
+export interface ResolvedElements {
+    Box: (props: Record<string, unknown>) => JsxElement;
+    Text: (props: Record<string, unknown>) => JsxElement;
+    Button: (props: Record<string, unknown>) => JsxElement;
+    Input: (props: Record<string, unknown>) => JsxElement;
+    Select: (props: Record<string, unknown>) => JsxElement;
+    Link: (props: Record<string, unknown>) => JsxElement;
+    Code: (props: Record<string, unknown>) => JsxElement;
+    Markdown: (props: Record<string, unknown>) => JsxElement;
+    Image: (props: Record<string, unknown>) => JsxElement;
+    Svg: (props: Record<string, unknown>) => JsxElement;
+    Raster: (props: Record<string, unknown>) => JsxElement;
+    Client: (props: Record<string, unknown>) => JsxElement;
+    Fragment: (props: Record<string, unknown>) => JsxElement;
+}
+/** JSX 元素形状（对齐 `SerializedElement`）。 */
+export interface JsxElement {
+    readonly type: string;
+    readonly props: Record<string, unknown>;
+    readonly children: readonly JsxElement[];
+}
+/** 老 shell hook 的结果字段全集。对齐官方 `ClassicResult`。 */
+export interface ClassicResult {
+    block?: string;
+    preventContinuation?: true;
+    stopReason?: string;
+    additionalContext?: string[];
+    sessionTitle?: string;
+    suppressOriginalPrompt?: true;
+    initialUserMessage?: string;
+    watchPaths?: string[];
+    reloadSkills?: true;
+    permissionDecision?: 'allow' | 'deny' | 'ask';
+    permissionDecisionReason?: string;
+    decision?: string;
+    updatedToolOutput?: unknown;
+    updatedMCPToolOutput?: unknown;
+    retry?: true;
+    displayContent?: string;
+    worktreePath?: string;
+}
+/** hooks 模块的导出形状。对齐官方 `HooksModule`。 */
+export interface HooksModule {
+    register: Register;
+}
+/** `$.ui.invalidate()` 可重放的事件。 */
+export type InvalidatableEventName = 'ui.render' | 'prompt.section' | 'prompt.context' | 'prompt.attachment' | 'tool.describe' | 'command.describe' | 'config.describe';
+/**
+ * `$` —— 每个 hook 的第一参。对齐官方 `CoreEngineInterface` 的 19 个 noun。
+ *
+ * 每个方法调用同时 dispatch 对应的 op 事件（`$.fs.read(p)` → `fs.read`），
+ * 所以上层 mod 可以拦截、改写、拒绝另一个 mod 的任意能力调用 —— 这是
+ * `sec-default` 式管控与审计型 mod 的基础。
+ *
+ * 用 `interface` 而非 `type`，让 mod 通过**声明合并**添加自有 noun（官方
+ * telemetry mod 的 `declare module 'claude-code' { interface EngineInterface
+ * { telemetry: Telemetry } }` 范式）。
+ */
+export interface UiAskOptions {
+    options: readonly string[];
+    header?: string;
+    multiSelect?: boolean;
+    signal?: AbortSignal;
+}
+export interface SessionCompactInput {
+    reason?: string;
+    customInstructions?: string;
+    signal?: AbortSignal;
+}
+export interface SessionCompactResult extends EventResult {
+    /** True only after the host has finished compaction successfully. */
+    compacted?: true;
+}
+export interface EngineInterface {
+    /** 当前 plugin 自身信息。 */
+    plugin: {
+        readonly name: string;
+        readonly root: string;
+    };
+    ui: {
+        notice: (tool_use_id: string, text: string | undefined) => Promise<void>;
+        invalidate: (event: InvalidatableEventName) => Promise<void>;
+        log: (text: string, options?: {
+            to?: string;
+        }) => Promise<void>;
+        ask: (question: string, options?: readonly string[] | UiAskOptions) => Promise<string>;
+        toast: (text: string, options?: {
+            timeoutMs?: number;
+        }) => Promise<void>;
+        status: (text: string | undefined) => Promise<void>;
+        open: (pane: PaneOpenArgs) => Promise<{
+            isPlaced?: boolean;
+            [k: string]: unknown;
+        } | void>;
+        close: (pane: {
+            id: string;
+            [k: string]: unknown;
+        }) => Promise<{
+            deny?: string;
+            [k: string]: unknown;
+        }>;
+        panes: () => Promise<readonly unknown[]>;
+        blit: (args: Record<string, unknown>) => Promise<unknown>;
+        render: (input: Record<string, unknown>) => Promise<unknown>;
+        /**
+         * 拿到 `ui.render` 事件对应的**元素工厂表**（Box / Text / Button / …）。
+         *
+         * 官方 mod 在 `ui.render` hook 里用 `const { Box, Text } = await $.ui.resolve(e)`
+         * 取工厂，然后当 JSX 组件用（例如 `<Box><Text text="hi"/></Box>`）。工厂运行
+         * 时返回 `SerializedElement`，宿主可原样过线到远端面。
+         */
+        resolve: (e: EventInput) => Promise<ResolvedElements>;
+        scroll: (args: Record<string, unknown>) => Promise<unknown>;
+        focus: (args: Record<string, unknown>) => Promise<unknown>;
+    };
+    model: {
+        complete: (request: Record<string, unknown>) => Promise<string>;
+        fork: (request: Record<string, unknown>) => Promise<unknown>;
+        classify: (text: string, labels: readonly string[], options?: Record<string, unknown>) => Promise<string | undefined>;
+    };
+    audio: {
+        play: (clip: unknown, options?: Record<string, unknown>) => Promise<void>;
+        speak: (text: string, options?: Record<string, unknown>) => Promise<unknown>;
+    };
+    mcp: {
+        call: (server: string, tool: string, args?: Record<string, unknown>) => Promise<unknown>;
+    };
+    session: {
+        messages: () => Promise<SessionMessage[]>;
+        cwd: () => Promise<string>;
+        root: () => Promise<string>;
+        model: () => Promise<string>;
+        turns: () => Promise<number>;
+        id: () => Promise<string>;
+        repo: () => Promise<unknown>;
+        surfaces: () => Promise<readonly string[]>;
+        surface: () => Promise<string | null>;
+        usage: (args?: Record<string, unknown>) => Promise<unknown>;
+        authorize: () => Promise<SessionAuthorization>;
+        compact: (input?: SessionCompactInput) => Promise<SessionCompactResult>;
+        start: (input: Record<string, unknown>) => Promise<EventResult>;
+        end: (input: Record<string, unknown>) => Promise<EventResult>;
+        receive: (input: Record<string, unknown>) => Promise<EventResult>;
+    };
+    turn: {
+        abort: (input: {
+            turnId: string;
+        }) => Promise<void>;
+    };
+    prompt: {
+        submit: (input: Pick<PromptSubmitInput, 'text' | 'attachments'>) => Promise<PromptSubmitResult>;
+        read: () => Promise<PromptBox>;
+        fill: (input: PromptFillArgs) => Promise<PromptFilled>;
+        suggest: (input: Pick<PromptSuggestInput, 'text'>) => Promise<PromptSuggestResult>;
+        section: (input: PromptSectionInput) => Promise<PromptSectionResult>;
+        context: (input: PromptContextInput) => Promise<PromptContextResult>;
+    };
+    tool: {
+        list: () => Promise<readonly ToolInfo[]>;
+        call: ToolCallOverloads;
+        check: (input: ToolCheckArgs) => Promise<ToolCheckResult>;
+        describe: (input: Pick<ToolDescribeInput, 'tool' | 'description'>) => Promise<ToolDescribeResult>;
+        register: (tool: ToolSpec) => Promise<ToolRegisterResult>;
+        unregister: (name: string) => Promise<void>;
+    };
+    command: {
+        list: () => Promise<readonly CommandInfo[]>;
+        run: (input: Pick<CommandRunInput, 'command' | 'args'>) => Promise<CommandRunResult>;
+        describe: (input: Pick<CommandDescribeInput, 'command' | 'description'>) => Promise<CommandDescribeResult>;
+        register: (command: CommandSpec) => Promise<CommandRegisterResult>;
+        unregister: (name: string) => Promise<void>;
+    };
+    config: {
+        list: () => Promise<unknown[]>;
+        set: (input: Record<string, unknown>) => Promise<EventResult>;
+    };
+    agent: {
+        spawn: (input: import('./events/agent.js').AgentSpawnArgs) => Promise<AgentSpawnResult>;
+        offer: (input: Pick<AgentOfferInput, 'agent' | 'description'>) => Promise<AgentOfferResult>;
+        list: () => Promise<readonly AgentInfo[]>;
+        register: (spec: AgentSpec) => Promise<AgentRegisterResult>;
+    };
+    fs: {
+        read: (path: string, options?: {
+            as?: string;
+        }) => Promise<unknown>;
+        write: (path: string, text: string) => Promise<void>;
+        list: (path?: string) => Promise<unknown[]>;
+        exists: (path: string) => Promise<boolean>;
+        stat: (path: string, options?: {
+            resolve?: boolean;
+        }) => Promise<unknown>;
+        ancestors: (request: FsAncestorsRequest) => Promise<readonly FsAncestor[]>;
+    };
+    store: {
+        get: (key: string) => Promise<unknown>;
+        set: (key: string, value: unknown) => Promise<void>;
+        delete: (key: string) => Promise<void>;
+        keys: () => Promise<string[]>;
+    };
+    clock: {
+        now: () => Promise<number>;
+        sleep: (ms: number, options?: Record<string, unknown>) => Promise<void>;
+        /**
+         * 单次定时器。返回 `Timer`（不是 `void`）—— mod 常保存引用以便
+         * `timer.cancel()`。
+         */
+        after: (ms: number, fn: () => unknown) => Promise<Timer>;
+        /** 周期定时器；同样返回 `Timer`。 */
+        every: (ms: number, fn: () => unknown) => Promise<Timer>;
+    };
+    http: {
+        fetch: (url: string, init?: HttpInit) => Promise<HttpResponse>;
+    };
+    process: {
+        run: (argv: readonly string[], init?: ProcessRunInit) => Promise<ProcessRunResult>;
+    };
+    settings: {
+        read: (args?: SettingsReadArgs) => Promise<Settings>;
+    };
+    env: {
+        get: (name: string) => Promise<string | undefined>;
+        set: (name: string, value: string | undefined) => Promise<void>;
+    };
+    /** mod 通过 `engine.create` fold 添加的自有 noun 落在这里。 */
+    [noun: string]: unknown;
+}
+/**
+ * `engine.create` 的 `next(e)` 结果：`$` 如内层 fold 后的样子。
+ * 对齐官方 `EngineInterfaceBuilt`。
+ */
+export type EngineInterfaceBuilt = EngineInterface;
+/** 一个待挂载的 mod。 */
+export interface RegisteredMod {
+    /** plugin.json 的 name。 */
+    readonly name: string;
+    /** 挂载 tier。 */
+    readonly tier: Tier;
+    /** 入口。对齐官方 `Register`：第二参是 options。 */
+    readonly register: Register;
+    /** plugin.json 的 root 目录（可选，`$.plugin.root` 用）。 */
+    readonly root?: string;
+    /** 该 mod 的配置项。 */
+    readonly options?: PluginOptions;
+}

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

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

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

@@ -0,0 +1 @@
+export declare function mapWithConcurrencyLimit<T, R>(items: readonly T[], concurrency: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;