@tencent-ai/agent-harness 0.2.0-beta.3 → 0.2.0-beta.4

package/cli/dist-server/types/node/acp/acp-protocol.d.ts

@@ -737,6 +737,8 @@ export interface AcpRequestTracking {
     conversationRequestId?: string;
 }
 export interface AcpPromptItem {
+    /** Host-validated mod receipt; never copied from client metadata. */
+    modsPromptSubmitted?: true;
     request: PromptRequest;
     responseDeferred: Deferred<PromptResponse>;
     tracking: AcpRequestTracking;
@@ -954,6 +956,12 @@ export interface AcpAgentManager {
      * 获取所有已注册的 AcpAgent 实例
      */
     getAll(): Map<string, AcpAgent>;
+    /**
+     * Subscribe to agent-registered events. Enables the mods paint pipe
+     * to push a first-frame MOD_RENDER to a newly-connected webui
+     * without waiting for the mod's own `$.ui.invalidate` cadence.
+     */
+    onAgentRegistered?(cb: (connectionId: string, agent: AcpAgent) => void): () => void;
     /**
      * 移除并释放指定连接的 AcpAgent 实例。重复移除同一连接是 no-op。
      * @param connectionId 连接 ID

package/cli/dist-server/types/node/loopback/server-protocol.d.ts

@@ -9,6 +9,11 @@ export interface CommonRequest extends SessionOptions {
      * 字段，只给 native 会话创建时盖站立键用。ACP 请求走 `acp:true`，不在这里盖。
      */
     agent?: string;
+    /** Request-level debug options forwarded from CLI/serve callers. */
+    debug?: boolean | string;
+    debugToStderr?: boolean;
+    /** Automatically connect to a single available IDE on startup. */
+    ide?: boolean;
 }
 export interface ResumeRequest {
     resume: boolean | string;

package/cli/dist-server/types/node/tools/tool-protocol.d.ts

@@ -261,6 +261,8 @@ export interface Tool<TParameters extends ToolInputParameters = any, Context = U
      * The name of the tool. Must be unique within the agent.
      */
     name: string;
+    /** Host-created mod proxies dispatch once, inside their own execute method. */
+    readonly dispatchesModToolCall?: boolean;
     /**
      * Stability of the model-facing definition while the process is alive.
      * Agent tools default to stable; runtime-varying definitions opt into volatile.
@@ -349,6 +351,12 @@ export interface Tool<TParameters extends ToolInputParameters = any, Context = U
 }
 export type { BackgroundTask, TerminalEvidence } from '../../vendor/cbc-core/node/index.js';
 export interface ToolManager {
+    /** Dynamic definitions share the registry used by get/execute. Builtins cannot be replaced. */
+    register(tool: Tool): Promise<void>;
+    unregister(name: string): Promise<void>;
+    listDynamicToolNames(): string[];
+    /** Agent tool snapshots must be rebuilt when this version changes. */
+    readonly registryVersion: number;
     get<TParameters extends ToolInputParameters = any, Context = UnknownContext>(name: string, agentConfig?: ProductAgent, cachedProductConfig?: {
         agents?: any[];
         models?: any[];
@@ -940,26 +948,15 @@ export interface VideoService {
 }
 export declare const AudioTranscribeService: unique symbol;
 /**
- * 录音文件识别（长音频转文本）请求参数。
- * `channel_num:1` 由 service 固定注入，不暴露给调用方。
+ * tool 层已判定好的音频来源。
+ * 本地文件需要先上传 COS 才有公网可下载地址；调用方给出的 URL 直接提交。
  */
-export interface AudioTranscribeOptions {
-    /** 说话人分离：0 关闭（默认）/ 1 开启（需 channel_num=1） */
-    speaker_diarization?: 0 | 1;
-    /** 临时热词表 "词|权重,..."（最多 128） */
-    hotword_list?: string;
-    /** 阿拉伯数字智能转换：0 / 1 / 3 */
-    convert_num_mode?: 0 | 1 | 3;
-    /** 脏词过滤：0 / 1 / 2 */
-    filter_dirty?: 0 | 1 | 2;
-    /** 标点过滤：0 / 1 / 2 */
-    filter_punc?: 0 | 1 | 2;
-    /** 语气词过滤：0 / 1 / 2 */
-    filter_modal?: 0 | 1 | 2;
-    /** 上游附加参数（合法 JSON 字符串），如 '{"Domain":3}' */
-    extra?: string;
-}
-/** service 内部解析出的音频来源（COS-only：始终为 audio_url）。 */
+export type AudioTranscribeSource = {
+    readonly filePath: string;
+} | {
+    readonly audioUrl: string;
+};
+/** 提交给上游的音频来源（本服务始终用 audio_url，从不用 audio_data）。 */
 export interface AudioSource {
     audio_url: string;
 }
@@ -1036,11 +1033,15 @@ export interface AudioTranscribeResult {
 }
 /**
  * 录音文件识别服务接口。
- * COS-only：本地文件先经后端预签名上传 COS，再以 audio_url 提交异步转写并轮询。
+ * 本地文件先经后端预签名上传 COS 换取 download_url；调用方给的 URL 直接用。
+ * 两种来源都以 audio_url 提交异步转写并轮询。
+ *
+ * 识别参数（`channel_num` / `speaker_diarization`）由 service 固定注入，
+ * 按 #128310 不向 Agent 暴露开关。
  */
 export interface AudioTranscribeService {
     /**
-     * 转写本地音频文件：预签名上传 → 提交任务 → 轮询直至终态。
+     * 转写音频：解析来源（本地文件则预签名上传）→ 提交任务 → 轮询直至终态。
      */
-    transcribe(filePath: string, options: AudioTranscribeOptions, context: RunContext<Session>): Promise<AudioTranscribeResult>;
+    transcribe(source: AudioTranscribeSource, context: RunContext<Session>): Promise<AudioTranscribeResult>;
 }

package/cli/dist-server/types/vendor/cbc-core/node/agent/runner-factory.d.ts

@@ -21,6 +21,14 @@ export interface ModelInputMemoryPressure {
     headroom: number;
     inputItems: number;
     estimatedInputBytes?: number;
+    /**
+     * Whether the retained-size walk finished (fully traversed, or provably ≥ the byte budget).
+     * `false` means the walk stopped on the node cap with bytes still under budget — the graph is
+     * deep/wide but not necessarily large, so `estimatedInputBytes` must NOT drive a rejection.
+     */
+    estimateComplete: boolean;
+    /** Real, content-independent OOM signal: heap is already near its ceiling. */
+    heapCritical: boolean;
     reject: boolean;
 }
 export declare function assessModelInputMemoryPressure(input: AgentInputItem[], heapUsed?: number, heapLimit?: number): ModelInputMemoryPressure;
@@ -80,8 +88,18 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
      * 否则前端的 sending 态无人清除、永久转圈（#73022）。
      */
     protected readonly acpBroadcastService?: AgentQueueOutput;
+    /** Sessions with a deferred emergency compaction already scheduled (see scheduleEmergencyCompact). */
+    private readonly emergencyCompactInFlight;
     create(config?: Partial<RunConfig>): Promise<Runner>;
     private assertModelInputCloneHeadroom;
+    /**
+     * Fire a one-shot emergency compaction for an over-large history so the user's retry can
+     * succeed. Deferred + de-duplicated per session; failures are swallowed because the surfaced
+     * error already tells the user how to recover. Mirrors checkAutoCompact's non-blocking branch
+     * (setImmediate keeps it off the current runner's abort signal). compactAndSummarize has its
+     * own session-level lock, so the in-flight set only avoids scheduling redundant callbacks.
+     */
+    private scheduleEmergencyCompact;
     /**
      * 在每次模型请求前检查是否需要自动压缩。
      * 此时所有工具都已执行完毕，可以安全地触发压缩。

package/cli/dist-server/types/vendor/cbc-core/node/context/index.d.ts

@@ -1,6 +1,7 @@
 export * from './context-protocol';
 export * from './compaction-lineage';
 export * from './context-host-protocol';
+export * from './mods-bridge';
 export * from './prompt-context-provider';
 export * from './prompt-renderer';
 export * from './context-compact-summarizer';

package/cli/dist-server/types/vendor/cbc-core/node/context/mods-bridge.d.ts

@@ -0,0 +1,115 @@
+import type { AgentInputItem } from '../../../cbc-shared/node/index.js';
+import type { PromptContext } from './context-protocol';
+export interface ModsPromptSubmitResult {
+    text?: string;
+    drop?: string;
+}
+/** Host-only provenance: a mod initiated submission has already traversed the fold. */
+export declare const MODS_PROMPT_SUBMITTED_KEY = "modsPromptSubmitted";
+/**
+ * Function hooks（Claude mods）在 core 侧的**窄接口**。
+ *
+ * ## 为什么 core 不直接调 mods
+ *
+ * `cbc-core` 只允许依赖 `@genie/cbc-shared`（见仓库 CODEBUDDY.md 的单向依赖卡点，
+ * `package-boundaries.spec.ts` 会扫源码 import、动态 import 与依赖声明）。而 mods
+ * 引擎住在 `cbc-plugins`。所以 core 这一侧只声明「我会在这几个时刻问一句」，具体
+ * 分发由宿主实现后注入。
+ *
+ * ## 为什么形状映射也不在 core
+ *
+ * cbc 的 `PromptContext` 是一个松散字典，官方 `prompt.context` 事件是
+ * `{ blocks, instructionFiles }`。两者的对应关系属于**适配**，而适配是宿主的事 ——
+ * 让 core 认识官方 payload 等于把上游协议渗进核心包，将来上游改一次形状，core 就
+ * 得跟着改。因此接口按 core 自己的类型说话，桥的实现负责翻译。
+ *
+ * ## 未注入时必须是零开销
+ *
+ * function hooks 默认关闭。没有桥时每个调用点只多一次 `=== undefined` 判断，
+ * 不构造对象、不进 async、不改变任何既有行为。
+ */
+export interface ModsBridge {
+    /**
+     * 上下文装配完成、尚未拼成最终 prompt 时问一句。
+     *
+     * @param context 当前这一版上下文
+     * @returns 可能被 mod 改写过的上下文；桥自身出问题时应原样返回入参
+     */
+    promptContext(context: PromptContext): Promise<PromptContext>;
+    /**
+     * 会话建立时通知一次。
+     *
+     * @param input 会话 cwd 与是否交互式 —— 官方 `session.start` 的入参
+     */
+    sessionStart(input: {
+        cwd: string;
+        isInteractive: boolean;
+    }): Promise<void>;
+    /**
+     * 用户提交输入时问一句。对齐官方 `prompt.submit`。
+     *
+     * @param input 即将送达模型的文本
+     * @returns `{ drop }` 阻断输入，`{ text }` 改写可见文本；附件与隐藏上下文由 core 保留。
+     */
+    promptSubmit(input: {
+        text: string;
+        sessionId?: string;
+        signal?: AbortSignal;
+    }): Promise<ModsPromptSubmitResult | undefined>;
+    /**
+     * 把一条 mod 打出来的 `$.ui.log` 行落到用户可见的会话里。
+     *
+     * ## 为什么走桥而不是让 core 直接推消息
+     *
+     * `$.ui.log` 是 mod 侧发起的用户可见事件（官方语义：进 transcript），但 core
+     * 不知道"当前会话"是哪一个（AsyncLocalStorage 上下文由宿主入口决定），也不认
+     * `plugin` 这个身份维度（那是 mods 引擎的概念）。宿主拿到这一对
+     * `(text, plugin)` 之后，负责取当前 session 并 push 进 `inputSubject` /
+     * `combineSubject` / `sessionStore.appendHistory`，就跟宿主自己的系统消息
+     * 是同一条路径。
+     *
+     * ## 未装桥时的兜底在哪
+     *
+     * 宿主没实现这一项时，`bindings.log` 侧应当把行文继续写到 stderr（headless /
+     * bootstrap 早期 / 无当前 session 时用得到）—— 那种场景下用户看不到"消息历史"，
+     * 但仍能通过日志追溯这一行，与既有行为保持一致。
+     *
+     * @param text 已由宿主前缀好 `<plugin>: ` 的完整行文（core 不重复加前缀）
+     * @param meta 至少携带 `plugin`；用于前端识别 / 分组
+     */
+    pushModLog?(text: string, meta: {
+        plugin: string;
+    }): void;
+}
+/**
+ * 注入桥。宿主在 mods 运行时起来之后调用一次。
+ *
+ * @param next 桥实现；传 `undefined` 卸载（测试用）
+ */
+export declare function setModsBridge(next: ModsBridge | undefined): void;
+/** 当前桥；未注入时 undefined。 */
+export declare function currentModsBridge(): ModsBridge | undefined;
+/**
+ * 经桥过一遍上下文。
+ *
+ * **桥出问题不能影响主流程**：mod 是第三方代码，它抛错、超时、返回垃圾，都只该
+ * 让 function hooks 这一层失效，而不是让会话起不来。因此这里兜住一切异常并回退到
+ * 原上下文 —— 与「加载失败不阻塞宿主」同一条原则。
+ *
+ * @param context 当前上下文
+ * @returns 改写后的上下文；无桥或出错时是原对象
+ */
+export declare function throughModsPromptContext(context: PromptContext): Promise<PromptContext>;
+/** A failed third-party fold must not corrupt or lose the original input. */
+export declare function throughModsPromptSubmit(text: string, sessionId?: string, signal?: AbortSignal): Promise<ModsPromptSubmitResult | undefined>;
+/** Mutates only user text, before the shared history/model consumers see these items. */
+export declare function applyModsPromptSubmit(items: AgentInputItem[], sessionId: string, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * 通知会话开始。同样绝不向外抛。
+ *
+ * @param input 会话 cwd 与是否交互式
+ */
+export declare function notifyModsSessionStart(input: {
+    cwd: string;
+    isInteractive: boolean;
+}): Promise<void>;

package/cli/dist-server/types/vendor/cbc-core/node/message-queue/followup-queue-protocol.d.ts

@@ -30,12 +30,13 @@ export interface FollowupQueueSnapshot {
     items: FollowupQueueItemView[];
 }
 /** ACP `session/steer` 回调。服务不直接碰 ACP，方便单测。 */
-export type FollowupSteerFn = (contentBlocks: unknown[]) => Promise<{
+export type FollowupSteerFn = (contentBlocks: unknown[], modsPromptSubmitted?: true) => Promise<{
     steered: boolean;
 }>;
 export interface FollowupQueueService {
     snapshot(session: Session): FollowupQueueSnapshot;
-    enqueue(session: Session, contentBlocks: unknown[], hold: boolean): FollowupQueueSnapshot;
+    /** modsPromptSubmitted is host-validated provenance, never a client flag. */
+    enqueue(session: Session, contentBlocks: unknown[], hold: boolean, modsPromptSubmitted?: true): FollowupQueueSnapshot;
     remove(session: Session, itemId: string): FollowupQueueSnapshot;
     /**
      * 立即发送：能插入当前回合就 `steer` 并从队列拿掉；否则只摘 queueHold。

package/cli/dist-server/types/vendor/cbc-core/node/message-queue/followup-queue.d.ts

@@ -23,7 +23,7 @@ export declare class FollowupQueueServiceImpl implements FollowupQueueService {
      */
     private readonly pendingBroadcasts;
     snapshot(session: Session): FollowupQueueSnapshot;
-    enqueue(session: Session, contentBlocks: unknown[], hold: boolean): FollowupQueueSnapshot;
+    enqueue(session: Session, contentBlocks: unknown[], hold: boolean, modsPromptSubmitted?: true): FollowupQueueSnapshot;
     remove(session: Session, itemId: string): FollowupQueueSnapshot;
     sendNow(session: Session, itemId: string, steer?: FollowupSteerFn): Promise<FollowupQueueSnapshot>;
     watch(session: Session): void;

package/cli/dist-server/types/vendor/cbc-core/node/message-queue/steer-input-buffer-protocol.d.ts

@@ -28,6 +28,8 @@ export declare const SteerInputBuffer: unique symbol;
  * drain 返回的一组：待插入内容 + 独立对账 id + 客户端不透明 metadata。
  */
 export interface SteerDrainedGroup {
+    /** Set only after the host validates a one-time mod prompt receipt. */
+    readonly modsPromptSubmitted?: true;
     readonly blocks: unknown[];
     /** Native, already reviewed messages. Kept by reference for in-memory admission markers. */
     readonly messages?: readonly UserMessageItem[];
@@ -49,6 +51,8 @@ export interface SteerDrainedGroup {
  * push 的归属 + 客户端不透明 metadata 入参（合并为一个对象，避免 push 参数过多）。
  */
 export interface SteerPushInput {
+    /** Server-only provenance, independent of untrusted clientMeta. */
+    readonly modsPromptSubmitted?: true;
     /**
      * 这组消息归属的请求 id（当前正在执行的 turn 的 requestId）；
      * `undefined` 表示无归属信息（drain 时按「当前也无归属」放行，退化为旧行为）。

package/cli/dist-server/types/vendor/cbc-core/node/session/can-use-tool.d.ts

@@ -40,6 +40,8 @@ export type PermissionResult = {
     updatedPermissions?: PermissionUpdate[];
     toolUseID?: string;
     decisionClassification?: PermissionDecisionClassification;
+    /** Optional host response metadata; interpreted only by the requesting tool. */
+    metadata?: Record<string, unknown>;
 } | {
     behavior: 'deny';
     message: string;
@@ -68,6 +70,8 @@ export interface CanUseToolOptions {
     displayName?: string;
     /** 桥端渲染的副标题说明。 */
     description?: string;
+    /** Tool-provided display/context metadata for host permission UIs. Not an authorization grant. */
+    metadata?: Record<string, unknown>;
     /** 本次工具调用在 assistant 消息内的唯一 id。 */
     toolUseID: string;
     /** 子代理上下文中触发时，子代理的 id。 */

package/cli/dist-server/types/vendor/cbc-core/node/session/session-manager.d.ts

@@ -32,6 +32,7 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
     private skipHistoryContext;
     private sessionStartTimes;
     private addHistoryLocks;
+    private promptAdmissions;
     private resultSubscriptions;
     private readonly resultSubscriptionOwners;
     /**
@@ -108,6 +109,7 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
     private readonly loadedSessionIds;
     private resetIdleTimer;
     addHistory(session: Session, input: string | AgentInputItem[]): Promise<void>;
+    private writeHistory;
     /**
      * Record a UserPromptSubmit hook block as an in-band assistant message
      * (issue #71907, cc-aligned: cc surfaces a warning system message and ends the
@@ -125,6 +127,34 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
      * (use-message-sender). chalk=false because ACP does not strip ANSI codes.
      */
     private recordHookBlockedMessage;
+    /**
+     * 把一条 mod 打出来的 `$.ui.log` 落到当前 session 的可见消息流里。
+     *
+     * ## 与 `recordHookBlockedMessage` 的关系
+     *
+     * 二者走**同一条落地路径**（history + inputSubject + combineSubject +
+     * sessionStore.appendHistory），因此 TUI / ACP / persisted transcript 都用
+     * 既有渲染，不必新增 sessionUpdate 类型（对齐根 CODEBUDDY.md 的 ACP 约束）。
+     *
+     * ## 与 hook 阻断消息刻意不同的三点
+     *
+     * 1. **不动 `session.lastMessageId`**：hook-block 是回合终点，需要挂上 replay
+     *    分支；mod-log 是**装饰性**通知，如果推进 lastMessageId 会让 `/rewind`
+     *    退到"一条 log 中间"，语义混乱。
+     * 2. **不挂 `parentId`**：同样出于 replay 分支洁净。
+     * 3. **`chalk: false`**：ACP 侧不剥 ANSI，chalk 转义码会露出到 Web UI；此外
+     *    宿主已在 `<plugin>: <text>` 里给足了归属信号，terminal 也不再需要额外
+     *    颜色包装（TUI 侧后续可按 `hookStatus === 'mod-log'` 做专属渲染）。
+     *
+     * ## 失败语义
+     *
+     * 与 hook-block 同款：写盘失败只记日志，不向外抛 —— mod 打日志不该把 CLI 弄挂。
+     *
+     * @param session 目标 session（宿主取当前 session 后传入）
+     * @param text 已由宿主前缀成 `<plugin>: <text>` 的完整行文
+     * @param plugin 发起本次调用的 mod 名（`origin.plugin`），用于前端识别
+     */
+    recordModLogMessage(session: Session, text: string, plugin: string): Promise<void>;
     private readonly inflightSessionStarts;
     emitSessionStart(session: Session, source: SessionStartSource): Promise<void>;
     create(options?: Partial<Session>, needHandleRunResult?: boolean, parentSession?: Session): Promise<Session>;

package/cli/dist-server/types/vendor/cbc-core/node/session/session-protocol.d.ts

@@ -1117,6 +1117,18 @@ export interface SessionManager {
      * before injecting `additionalContext`.
      */
     emitSessionStart(session: Session, source: SessionStartSource): Promise<void>;
+    /**
+     * Record a mod-plugin `$.ui.log` line as a user-visible message on the
+     * session transcript (mirrors `recordHookBlockedMessage` — same
+     * inputSubject / combineSubject / sessionStore path — but leaves
+     * `lastMessageId` and `parentId` untouched because mod logs are
+     * decorative and must not become anchors on the replay branch).
+     *
+     * @param session target session (host resolves current session and passes it in)
+     * @param text already prefixed as `<plugin>: <text>` by the host bridge
+     * @param plugin the calling mod's name (`origin.plugin`), for provider metadata
+     */
+    recordModLogMessage(session: Session, text: string, plugin: string): Promise<void>;
     addHistory(session: Session, input: string | AgentInputItem[]): Promise<void>;
     save(session: Session): Promise<void>;
     /** Initialize an immutable full snapshot for a new fork; target must be absent or empty. */

package/cli/dist-server/types/vendor/cbc-core/node/utils/input-item-utils.d.ts

@@ -1,6 +1,6 @@
 import { type AcpTerminalStateItem, type AgentInputItem, type AssistantMessageItem, type CustomTitleItem, type FileHistorySnapshotItem, type FunctionCallItem, type FunctionCallResultItem, type HookBlockingDetail, HookEvent, type ResendForkNoticeItem, type UserMessageItem } from '../../../cbc-shared/node/index.js';
 type ItemStatus = 'in_progress' | 'completed' | 'incomplete';
-export type HookStatus = 'success' | 'blocked' | 'warning' | 'error';
+export type HookStatus = 'success' | 'blocked' | 'warning' | 'error' | 'mod-log';
 interface ItemOptions {
     readonly skipRun?: boolean;
     readonly status?: ItemStatus;

package/cli/dist-server/types/workspace/agent-client-protocol/lib/common/prompt-codec.d.ts

@@ -24,6 +24,8 @@ export interface AcpResourceLinkProviderData {
     [extra: string]: unknown;
 }
 export interface DecodeInputTextToAcpContentBlocksOptions {
+    /** Defaults to legacy badge parsing. False restores only explicit resource metadata. */
+    parseInlineReferences?: boolean;
     resolveImageOrdinal?: (ordinal: number, label: string) => ContentBlock | undefined;
     /** 标题/摘要等纯展示场景允许缺少 providerData 的 badge 降级为不可交互的可读块。 */
     allowDisplayOnlyFallback?: boolean;
@@ -36,6 +38,8 @@ export interface DecodeInputTextToAcpContentBlocksOptions {
     allowUnicodeSlashTokens?: boolean;
 }
 export interface DecodePersistedUserContentToAcpContentBlocksOptions {
+    /** Keep ordinary text literal while restoring explicitly encoded attachments. */
+    parseInlineReferences?: boolean;
     convertPersistedImageBlock?: (block: Record<string, any>) => ContentBlock | undefined;
 }
 export declare function getAcpResourceLinkDisplayName(uri: string, name?: string): string;

package/cli/dist-server/types/workspace/agent-client-protocol/lib/common/types.d.ts

@@ -41,12 +41,26 @@ export declare const ExtensionMethod: {
     readonly DELEGATE_TOOLS_CHANGED: '_codebuddy.ai/delegateToolsChanged';
     /** UI control for operating Web UI elements */
     readonly UI_CONTROL: '_codebuddy.ai/uiControl';
+    /**
+     * A `--plugin-dir` mod's `ui.render` output — one serialized tree per
+     * paint. Payload: `{ sessionId, plugin, tree }`. The webui / desktop
+     * surface re-hydrates the tree into React nodes; a `<Button>` in the
+     * tree renders as a real HTML button whose click sends MOD_PRESS.
+     */
+    readonly MOD_RENDER: '_codebuddy.ai/modRender';
+    /**
+     * Interaction back-channel for MOD_RENDER trees. Payload:
+     * `{ sessionId, plugin, element, surface }`. The agent dispatches
+     * `ui.press` and runs the closure the mod registered under that
+     * element key.
+     */
+    readonly MOD_PRESS: '_codebuddy.ai/modPress';
 };
 export type ExtensionMethodName = (typeof ExtensionMethod)[keyof typeof ExtensionMethod];
 /**
  * All known extension methods
  */
-export declare const KNOWN_EXTENSIONS: readonly ["_codebuddy.ai/artifact", "_codebuddy.ai/artifactBatch", "_codebuddy.ai/question", "_codebuddy.ai/checkpoint", "_codebuddy.ai/command", "_codebuddy.ai/authUrl", "_codebuddy.ai/file_history_snapshot", "_codebuddy.ai/delegateTool", "_codebuddy.ai/delegateToolsChanged"];
+export declare const KNOWN_EXTENSIONS: readonly ["_codebuddy.ai/artifact", "_codebuddy.ai/artifactBatch", "_codebuddy.ai/question", "_codebuddy.ai/checkpoint", "_codebuddy.ai/command", "_codebuddy.ai/authUrl", "_codebuddy.ai/file_history_snapshot", "_codebuddy.ai/delegateTool", "_codebuddy.ai/delegateToolsChanged", "_codebuddy.ai/modRender", "_codebuddy.ai/modPress"];
 /**
  * 恶意网站拦截的错误码标记，随工具调用结果经 ACP 传给客户端。
  *

package/cli/dist-server/types/workspace/cbc-core/lib/node/agent/runner-factory.d.ts

@@ -21,6 +21,14 @@ export interface ModelInputMemoryPressure {
     headroom: number;
     inputItems: number;
     estimatedInputBytes?: number;
+    /**
+     * Whether the retained-size walk finished (fully traversed, or provably ≥ the byte budget).
+     * `false` means the walk stopped on the node cap with bytes still under budget — the graph is
+     * deep/wide but not necessarily large, so `estimatedInputBytes` must NOT drive a rejection.
+     */
+    estimateComplete: boolean;
+    /** Real, content-independent OOM signal: heap is already near its ceiling. */
+    heapCritical: boolean;
     reject: boolean;
 }
 export declare function assessModelInputMemoryPressure(input: AgentInputItem[], heapUsed?: number, heapLimit?: number): ModelInputMemoryPressure;
@@ -80,8 +88,18 @@ export declare class RunnerFactoryImpl implements RunnerFactory {
      * 否则前端的 sending 态无人清除、永久转圈（#73022）。
      */
     protected readonly acpBroadcastService?: AgentQueueOutput;
+    /** Sessions with a deferred emergency compaction already scheduled (see scheduleEmergencyCompact). */
+    private readonly emergencyCompactInFlight;
     create(config?: Partial<RunConfig>): Promise<Runner>;
     private assertModelInputCloneHeadroom;
+    /**
+     * Fire a one-shot emergency compaction for an over-large history so the user's retry can
+     * succeed. Deferred + de-duplicated per session; failures are swallowed because the surfaced
+     * error already tells the user how to recover. Mirrors checkAutoCompact's non-blocking branch
+     * (setImmediate keeps it off the current runner's abort signal). compactAndSummarize has its
+     * own session-level lock, so the in-flight set only avoids scheduling redundant callbacks.
+     */
+    private scheduleEmergencyCompact;
     /**
      * 在每次模型请求前检查是否需要自动压缩。
      * 此时所有工具都已执行完毕，可以安全地触发压缩。

package/cli/dist-server/types/workspace/cbc-core/lib/node/context/index.d.ts

@@ -1,6 +1,7 @@
 export * from './context-protocol.js';
 export * from './compaction-lineage.js';
 export * from './context-host-protocol.js';
+export * from './mods-bridge.js';
 export * from './prompt-context-provider.js';
 export * from './prompt-renderer.js';
 export * from './context-compact-summarizer.js';

package/cli/dist-server/types/workspace/cbc-core/lib/node/context/mods-bridge.d.ts

@@ -0,0 +1,115 @@
+import type { AgentInputItem } from '../../../../cbc-shared/lib/node/index.js';
+import type { PromptContext } from './context-protocol.js';
+export interface ModsPromptSubmitResult {
+    text?: string;
+    drop?: string;
+}
+/** Host-only provenance: a mod initiated submission has already traversed the fold. */
+export declare const MODS_PROMPT_SUBMITTED_KEY = "modsPromptSubmitted";
+/**
+ * Function hooks（Claude mods）在 core 侧的**窄接口**。
+ *
+ * ## 为什么 core 不直接调 mods
+ *
+ * `cbc-core` 只允许依赖 `@genie/cbc-shared`（见仓库 CODEBUDDY.md 的单向依赖卡点，
+ * `package-boundaries.spec.ts` 会扫源码 import、动态 import 与依赖声明）。而 mods
+ * 引擎住在 `cbc-plugins`。所以 core 这一侧只声明「我会在这几个时刻问一句」，具体
+ * 分发由宿主实现后注入。
+ *
+ * ## 为什么形状映射也不在 core
+ *
+ * cbc 的 `PromptContext` 是一个松散字典，官方 `prompt.context` 事件是
+ * `{ blocks, instructionFiles }`。两者的对应关系属于**适配**，而适配是宿主的事 ——
+ * 让 core 认识官方 payload 等于把上游协议渗进核心包，将来上游改一次形状，core 就
+ * 得跟着改。因此接口按 core 自己的类型说话，桥的实现负责翻译。
+ *
+ * ## 未注入时必须是零开销
+ *
+ * function hooks 默认关闭。没有桥时每个调用点只多一次 `=== undefined` 判断，
+ * 不构造对象、不进 async、不改变任何既有行为。
+ */
+export interface ModsBridge {
+    /**
+     * 上下文装配完成、尚未拼成最终 prompt 时问一句。
+     *
+     * @param context 当前这一版上下文
+     * @returns 可能被 mod 改写过的上下文；桥自身出问题时应原样返回入参
+     */
+    promptContext(context: PromptContext): Promise<PromptContext>;
+    /**
+     * 会话建立时通知一次。
+     *
+     * @param input 会话 cwd 与是否交互式 —— 官方 `session.start` 的入参
+     */
+    sessionStart(input: {
+        cwd: string;
+        isInteractive: boolean;
+    }): Promise<void>;
+    /**
+     * 用户提交输入时问一句。对齐官方 `prompt.submit`。
+     *
+     * @param input 即将送达模型的文本
+     * @returns `{ drop }` 阻断输入，`{ text }` 改写可见文本；附件与隐藏上下文由 core 保留。
+     */
+    promptSubmit(input: {
+        text: string;
+        sessionId?: string;
+        signal?: AbortSignal;
+    }): Promise<ModsPromptSubmitResult | undefined>;
+    /**
+     * 把一条 mod 打出来的 `$.ui.log` 行落到用户可见的会话里。
+     *
+     * ## 为什么走桥而不是让 core 直接推消息
+     *
+     * `$.ui.log` 是 mod 侧发起的用户可见事件（官方语义：进 transcript），但 core
+     * 不知道"当前会话"是哪一个（AsyncLocalStorage 上下文由宿主入口决定），也不认
+     * `plugin` 这个身份维度（那是 mods 引擎的概念）。宿主拿到这一对
+     * `(text, plugin)` 之后，负责取当前 session 并 push 进 `inputSubject` /
+     * `combineSubject` / `sessionStore.appendHistory`，就跟宿主自己的系统消息
+     * 是同一条路径。
+     *
+     * ## 未装桥时的兜底在哪
+     *
+     * 宿主没实现这一项时，`bindings.log` 侧应当把行文继续写到 stderr（headless /
+     * bootstrap 早期 / 无当前 session 时用得到）—— 那种场景下用户看不到"消息历史"，
+     * 但仍能通过日志追溯这一行，与既有行为保持一致。
+     *
+     * @param text 已由宿主前缀好 `<plugin>: ` 的完整行文（core 不重复加前缀）
+     * @param meta 至少携带 `plugin`；用于前端识别 / 分组
+     */
+    pushModLog?(text: string, meta: {
+        plugin: string;
+    }): void;
+}
+/**
+ * 注入桥。宿主在 mods 运行时起来之后调用一次。
+ *
+ * @param next 桥实现；传 `undefined` 卸载（测试用）
+ */
+export declare function setModsBridge(next: ModsBridge | undefined): void;
+/** 当前桥；未注入时 undefined。 */
+export declare function currentModsBridge(): ModsBridge | undefined;
+/**
+ * 经桥过一遍上下文。
+ *
+ * **桥出问题不能影响主流程**：mod 是第三方代码，它抛错、超时、返回垃圾，都只该
+ * 让 function hooks 这一层失效，而不是让会话起不来。因此这里兜住一切异常并回退到
+ * 原上下文 —— 与「加载失败不阻塞宿主」同一条原则。
+ *
+ * @param context 当前上下文
+ * @returns 改写后的上下文；无桥或出错时是原对象
+ */
+export declare function throughModsPromptContext(context: PromptContext): Promise<PromptContext>;
+/** A failed third-party fold must not corrupt or lose the original input. */
+export declare function throughModsPromptSubmit(text: string, sessionId?: string, signal?: AbortSignal): Promise<ModsPromptSubmitResult | undefined>;
+/** Mutates only user text, before the shared history/model consumers see these items. */
+export declare function applyModsPromptSubmit(items: AgentInputItem[], sessionId: string, signal?: AbortSignal): Promise<string | undefined>;
+/**
+ * 通知会话开始。同样绝不向外抛。
+ *
+ * @param input 会话 cwd 与是否交互式
+ */
+export declare function notifyModsSessionStart(input: {
+    cwd: string;
+    isInteractive: boolean;
+}): Promise<void>;

package/cli/dist-server/types/workspace/cbc-core/lib/node/message-queue/followup-queue-protocol.d.ts

@@ -30,12 +30,13 @@ export interface FollowupQueueSnapshot {
     items: FollowupQueueItemView[];
 }
 /** ACP `session/steer` 回调。服务不直接碰 ACP，方便单测。 */
-export type FollowupSteerFn = (contentBlocks: unknown[]) => Promise<{
+export type FollowupSteerFn = (contentBlocks: unknown[], modsPromptSubmitted?: true) => Promise<{
     steered: boolean;
 }>;
 export interface FollowupQueueService {
     snapshot(session: Session): FollowupQueueSnapshot;
-    enqueue(session: Session, contentBlocks: unknown[], hold: boolean): FollowupQueueSnapshot;
+    /** modsPromptSubmitted is host-validated provenance, never a client flag. */
+    enqueue(session: Session, contentBlocks: unknown[], hold: boolean, modsPromptSubmitted?: true): FollowupQueueSnapshot;
     remove(session: Session, itemId: string): FollowupQueueSnapshot;
     /**
      * 立即发送：能插入当前回合就 `steer` 并从队列拿掉；否则只摘 queueHold。

package/cli/dist-server/types/workspace/cbc-core/lib/node/message-queue/followup-queue.d.ts

@@ -23,7 +23,7 @@ export declare class FollowupQueueServiceImpl implements FollowupQueueService {
      */
     private readonly pendingBroadcasts;
     snapshot(session: Session): FollowupQueueSnapshot;
-    enqueue(session: Session, contentBlocks: unknown[], hold: boolean): FollowupQueueSnapshot;
+    enqueue(session: Session, contentBlocks: unknown[], hold: boolean, modsPromptSubmitted?: true): FollowupQueueSnapshot;
     remove(session: Session, itemId: string): FollowupQueueSnapshot;
     sendNow(session: Session, itemId: string, steer?: FollowupSteerFn): Promise<FollowupQueueSnapshot>;
     watch(session: Session): void;