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

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

@@ -16,6 +16,7 @@ import { CompactStrategy, type ContextCompactResult, ContextCompactSummarizeOpti
  * 不包含任何具体的压缩逻辑实现。
  */
 export declare class ContextCompactSummarizerImpl implements ContextCompactSummarizer {
+    private activeCompactions?;
     protected readonly productManager: ProductManager;
     protected readonly agentManager: AgentManager;
     protected readonly logger: Logger;
@@ -25,6 +26,7 @@ export declare class ContextCompactSummarizerImpl implements ContextCompactSumma
     protected readonly strategyProvider: Provider<CompactStrategy>;
     compactAndSummarize(session: Session, options?: ContextCompactSummarizeOptions): Promise<boolean>;
     compactWithResult(session: Session, options?: ContextCompactSummarizeOptions): Promise<ContextCompactResult>;
+    private compactWithResultOwned;
     /**
      * 按优先级匹配（PreMessage → MaxToken），跳过 Blocking（仅作最终兜底），执行第一个命中的策略；
      * 都不命中则安全网回落到 Blocking。逻辑与压缩 span 化之前完全一致，只是把散落的 `return` 收敛成

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

@@ -1,7 +1,10 @@
+import type { AgentInputItem } from '../../../../cbc-shared/lib/node/index.js';
+import type { CompactionTrigger } from '../../../../telemetry/lib/common/index.js';
 import { Session } from '../session/session-protocol.js';
 export declare const PromptContextProvider: unique symbol;
 export declare const PromptContextInitializer: unique symbol;
 export declare const ContextCompactSummarizer: unique symbol;
+export declare const ManualCompactRequestHandler: unique symbol;
 export declare const PromptRenderer: unique symbol;
 export declare const COMPACT_PROMPT = "compact-prompt";
 export declare const DEFAULT_TOKEN_THRESHOLD = 0.7;
@@ -190,6 +193,8 @@ export interface ContextCompactSummarizeOptions {
     type?: CompactType;
     /** Stable identity shared by live updates and the durable compact boundary. */
     compactionId?: string;
+    /** Why this compaction runs; defaults from `type` (manual / pre_message_threshold / emergency_threshold). */
+    trigger?: CompactionTrigger;
 }
 export type ContextCompactSkipReason = 'already_compacting' | 'pending_interruption' | 'auto_disabled' | 'empty_history' | 'already_compacted' | 'non_default_agent' | 'below_threshold';
 export type ContextCompactFailureReason = 'strategy_failed' | 'strategy_unavailable';
@@ -214,6 +219,8 @@ export declare function createCompactionId(): string;
 export declare const SESSION_META_COMPACT_TYPE: 'compactType';
 /** Current stable compaction identity, persisted onto the boundary item. */
 export declare const SESSION_META_COMPACTION_ID: 'compactionId';
+/** Trigger of the compaction the summarizer is running; unset for a typed `/compact`. */
+export declare const SESSION_META_COMPACTION_TRIGGER: 'compactionTrigger';
 /**
  * session.meta 上标记当前 compact 成功后会继续执行一次真实 agent run。
  *
@@ -321,6 +328,16 @@ export interface ContextCompactSummarizer {
     /** Compatibility wrapper for existing automatic-compaction callers. */
     compactAndSummarize(session: Session, options?: ContextCompactSummarizeOptions): Promise<boolean>;
 }
+/**
+ * Host-owned boundary for external `/compact` requests.
+ *
+ * AgentService invokes this before creating a normal run lifecycle when an
+ * interactive host opts in. Implementations must return false for internal compact
+ * inputs so strategy-owned internal runs cannot recursively re-enter this boundary.
+ */
+export interface ManualCompactRequestHandler {
+    tryHandle(input: string | AgentInputItem[], session: Session): Promise<boolean>;
+}
 export interface PromptRenderer {
     render(template: string, context?: PromptContext): Promise<string>;
 }

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

@@ -1,5 +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/context/pre-message-compact-strategy.d.ts

@@ -4,8 +4,7 @@ import { CompactStrategyContext, ContextCompactSummarizeOptions } from './contex
 /**
  * PreMessage 压缩策略：在发送用户消息前触发。
  *
- * 触发条件：PRE_MESSAGE_AUTO 或 WorkBuddy 的 USER_COMMAND。
- * CBC 手动 /compact 不走该策略，继续由 compact agent 路径处理。
+ * 触发条件：PRE_MESSAGE_AUTO 或 USER_COMMAND（WorkBuddy / TUI 手动压缩）。
  *
  * 流程：
  * 1. Engineering compact (no LLM call)

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;

package/cli/dist-server/types/workspace/cbc-core/lib/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/workspace/cbc-core/lib/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/workspace/cbc-core/lib/node/session/index.d.ts

@@ -36,6 +36,7 @@ export * from './stream-timeout-retry-budget.js';
 export { consumeRecoveryRequestPending } from './recovery-budget.js';
 export * from './session-run-state-machine-protocol.js';
 export * from './session-run-state-machine.js';
+export * from './model-request-retry-phase.js';
 export * from './session-run-state-projection-service.js';
 export * from './local-jsonl-session-store.js';
 export * from './transcript-branch.js';

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/interruption-service.d.ts

@@ -93,6 +93,13 @@ export declare class InterruptionServiceImpl implements InterruptionService {
     protected readonly idleQueueDrainService?: IIdleQueueDrainService;
     protected readonly traceCollector?: SessionInterruptionTraceHost;
     protected get startupProfiler(): SessionInterruptionProfilerHost;
+    /**
+     * 标记「用户取消本轮」的拒绝项（`reject(item, { cancelTurn: true })`）。
+     * 语义是取消当前 turn，而不是「拒绝并让模型带反馈续跑」。
+     * 记在 WeakSet 而不是 `rawItem.providerData`（那会落进历史），也不改
+     * deferred 的 reject 形状（下游按 error 类型分支的逻辑保持不变）。
+     */
+    private readonly cancelTurnItems;
     /** Claim before calling out: sandbox callbacks can throw or synchronously re-enter. */
     private takeSandboxResolve;
     approve(item: RunToolApprovalItem, options?: {
@@ -101,6 +108,7 @@ export declare class InterruptionServiceImpl implements InterruptionService {
     }): void;
     reject(item: RunToolApprovalItem, options?: {
         decision?: 'deny' | 'rejectAndExitPlan';
+        cancelTurn?: boolean;
     }): void;
     /**
      * 取消指定 session 上所有未决的 interruption Deferred。

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/model-request-retry-phase.d.ts

@@ -0,0 +1,16 @@
+import type { AgentRetryReason, Session } from './session-protocol.js';
+import { ModelRequestRetryPhase, SessionRunStateMachine } from './session-run-state-machine-protocol.js';
+export declare class ModelRequestRetryPhaseImpl implements ModelRequestRetryPhase {
+    protected readonly stateMachine: SessionRunStateMachine;
+    during<T>(session: Session | undefined, reason: AgentRetryReason, wait: () => Promise<T>): Promise<T>;
+    /**
+     * 辅助型调用复用主 session 却不回送 AGENT_ENDED（#52320），不得驱动其状态；
+     * 状态已离开 MODEL_REQUESTING 说明另有路径在推进，此时不抢写。
+     */
+    private enter;
+    /**
+     * 必须回到 MODEL_REQUESTING：RETRYING 不接收 TOOL_STARTED / MODEL_RESPONSE_DONE 等后续事件，
+     * 停留会让错误处理路径的转换被静默忽略。已被取消等事件推走时不再改写。
+     */
+    private leave;
+}

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/model-response-interceptors.d.ts

@@ -215,6 +215,21 @@ export declare class MediaContentErrorInterceptor implements ModelResponseInterc
     private static readonly MAX_RETRY_ATTEMPTS;
     private static readonly MAX_MIME_MISMATCH_RETRY_ATTEMPTS;
     private static readonly GIF_UNSUPPORTED_ERROR_CODES;
+    /**
+     * Gateway business codes that mean "the model refused the images in this
+     * request" (`11135 InvalidInputImage`).
+     *
+     * The code is the only stable signal. The gateway folds several unrelated
+     * upstream causes into one hard-coded English sentence and overwrites the
+     * upstream text, so `ERROR_TYPE_PATTERNS` matching that sentence breaks the
+     * moment the wording is changed or localized (`docs/error-codes.md` already
+     * ships a Chinese user-facing string for this code). The code is carried on
+     * the error object all the way here — `error-analyzer` puts the parsed body
+     * code into the response, the SDK surfaces it as `APIError.error.code`, and
+     * `ErrorUtils.extractBizCode` recovers it — so key off it and keep the
+     * phrasing match only as a fallback for gateways that send no code.
+     */
+    private static readonly IMAGE_REJECTED_ERROR_CODES;
     private static readonly GIF_UNSUPPORTED_PLACEHOLDER;
     private static readonly ERROR_TYPE_PATTERNS;
     intercept(ctx: ModelResponseInterceptorContext): Promise<boolean | void>;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-manager-host-protocol.d.ts

@@ -1,5 +1,5 @@
 import type { AgentInputItem } from '../../../../cbc-shared/lib/node/index.js';
-import type { ModelResponseMetadata, Session } from './session-protocol.js';
+import type { ModelCallGeneration, ModelResponseMetadata, Session } from './session-protocol.js';
 export declare const SessionCheckpointHost: unique symbol;
 export interface SessionCheckpointHost {
     createCheckpoint(session: Session): Promise<void>;
@@ -57,7 +57,8 @@ export declare const SessionResponseTelemetryHost: unique symbol;
 export interface SessionResponseTelemetryHost {
     reportChatRequestResponseTelemetry(session: Session, result: NonNullable<Session['resultSubject']['value']>, isSuccessful: boolean, error: unknown, metadata: ModelResponseMetadata): Promise<void>;
     reportMessageResponseTelemetryStream(session: Session, usage: SessionResponseUsage | undefined, metadata: ModelResponseMetadata, error: unknown): Promise<void>;
-    reportChatMessageStatus(session: Session, errorCode: string, error?: unknown): Promise<void>;
+    /** Status of one model call (`generation`); run failures no model call owns are not reported. */
+    reportChatMessageStatus(session: Session, errorCode: string, generation: ModelCallGeneration, error?: unknown): Promise<void>;
 }
 export type SessionResponseTelemetrySnapshot = Pick<NonNullable<Session['telemetry']>, 'modelId' | 'modelName' | 'currentTurn' | 'traceId'>;
 export declare const SessionResponseObserver: unique symbol;

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

@@ -4,7 +4,7 @@ import { Logger } from '../../../../telemetry/lib/common/index.js';
 import { BehaviorSubject } from 'rxjs';
 import { SessionRequestContextHost, SessionSettingsHost as SettingsManager, SessionUsageHost as UserStateManager } from './session-host-protocol.js';
 import { SessionBackgroundTaskHost as ToolManager, SessionCheckpointHost as CheckpointService, SessionProgressHost as ProgressSyncService, SessionResponseObserver as GalileoSessionBridge, SessionResponseTelemetryHost as TelemetryService, SessionSchedulerHost as CronSchedulerService, SessionSensitiveProjectionHost, SessionTaskLifecycleHost as AgentTaskManager } from './session-manager-host-protocol.js';
-import { AgentInputItemProcessor, InterruptionService, ModelResponseInterceptor, ModelResponseMetadata, Session, SessionFactory, SessionGetOptions, SessionHookManager, SessionManager, SessionStore } from './session-protocol.js';
+import { AgentInputItemProcessor, InterruptionService, ModelResponseInterceptor, ModelResponseMetadata, OverrideModelSource, Session, SessionFactory, SessionGetOptions, SessionHookManager, SessionManager, SessionStore } from './session-protocol.js';
 import { SessionRunStateMachine } from './session-run-state-machine-protocol.js';
 export declare class SessionManagerImpl implements SessionManager, ApplicationLifecycle<Application> {
     protected readonly sessionFactory: SessionFactory;
@@ -32,6 +32,7 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
     private skipHistoryContext;
     private sessionStartTimes;
     private addHistoryLocks;
+    private promptAdmissions;
     private resultSubscriptions;
     private readonly resultSubscriptionOwners;
     /**
@@ -44,6 +45,8 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
     private readonly liveSessionsById;
     private overridePermissionModes;
     private overrideModels;
+    /** 与 overrideModels 同生命周期的意图来源（user / declared / materialized）。 */
+    private overrideModelSources;
     /**
      * Issue #12554：会话级 thinking override（按 sessionId 隔离）。
      * 由 ACP setSessionConfigOption('thought_level') 或 prompt _meta 写入。
@@ -106,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
@@ -123,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>;
@@ -190,9 +222,11 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
     rename(session: Session, name: string): Promise<void>;
     setOverridePermissionMode(sessionId: string, mode: PermissionMode): void;
     getOverridePermissionMode(sessionId: string): PermissionMode | undefined;
-    setOverrideModel(sessionId: string, model: string): void;
+    setOverrideModel(sessionId: string, model: string, source?: OverrideModelSource): void;
     getOverrideModel(sessionId: string): string | undefined;
-    setRuntimeModel(session: Session | undefined, modelId: string): void;
+    getOverrideModelSource(sessionId: string): OverrideModelSource | undefined;
+    clearOverrideModel(sessionId: string): void;
+    setRuntimeModel(session: Session | undefined, modelId: string, source?: OverrideModelSource): void;
     setRuntimeOutputStyle(session: Session | undefined, style: string): void;
     /**
      * Issue #83229：把 settings.json 中的 model / outputStyle 读一次"钉"进 session.options，

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

@@ -2,6 +2,7 @@ import { Deferred } from '@celljs/core';
 import { type AgentInputItem, ApprovalOptions, type Checkpoint, FinalStopReason, NotificationType, PermissionMode, ReasoningEffortLevel, type ResponseStreamEvent, type RunItem, type RunResult, type RunState, type RunToolApprovalItem, type SdkCapabilities, SessionEndReason, SessionStartSource, type StreamedRunResult, type TerminalEvent, type ToolDeferOverlaySnapshot, ToolPermissionContext, type Usage } from '../../../../cbc-shared/lib/node/index.js';
 import { Command } from '../../../../product/lib/common/index.js';
 import { BehaviorSubject, Subject } from 'rxjs';
+import type { CompactionLineage } from '../context/compaction-lineage.js';
 import { BackgroundTask } from './background-task-protocol.js';
 import type { SessionRunStateSnapshot } from './session-run-state-machine-protocol.js';
 import type { Lane, LanePointer, SessionKey, SessionStoreEntry } from './session-store-contract.js';
@@ -86,6 +87,7 @@ export type AgentState = 'agent_pending' | 'agent_start' | 'agent_tool_start' |
  *                              则 emit，触发 UI 显示"正在同步文件"提示)
  */
 export type AgentPhase = 'preparing' | 'model_requesting' | 'model_streaming' | 'model_done' | 'tool_executing' | 'waiting_for_permission' | 'waiting_for_user' | 'retrying' | 'finalization_file_projection_sync' | 'finalization_file_projection_sync_notify' | 'idle';
+export type AgentRetryReason = 'network';
 export interface AgentPhaseInfo {
     phase: AgentPhase;
     toolName?: string;
@@ -102,6 +104,13 @@ export interface AgentPhaseInfo {
         current: number;
         total: number;
     };
+    /**
+     * 仅 retrying phase 使用，经 ACP `_meta['codebuddy.ai/agentPhase']` 透传给上层。
+     * 缺省表示原因未分类（如流超时），不代表网络正常。
+     */
+    retry?: {
+        reason: AgentRetryReason;
+    };
 }
 export declare const AgentPhaseUtils: {
     /** Create an AgentPhaseInfo with the current timestamp. */
@@ -353,6 +362,14 @@ export interface Session {
      * field and pass it through as `options.maxTurns` explicitly.
      */
     lastRunMaxTurns?: number;
+    /**
+     * Latest agent-loop model call number (`providerData.stepSeq`). Unlike the
+     * SDK turn counter it survives runs, compaction and resume; see
+     * `allocateModelStepSeq`.
+     */
+    modelStepSeq?: number;
+    /** Compactions of this Session's context; see `getCompactionLineage`. */
+    compactionLineage?: CompactionLineage;
     queue: AgentInputItem[];
     queueSubject: BehaviorSubject<AgentInputItem[]>;
     /**
@@ -860,7 +877,7 @@ export interface SubagentInvocationRecord {
     lifecycle: SubagentLifecycleSnapshot;
 }
 export type SubagentLifecycleDescriptor = Omit<SubagentLifecycleSnapshot, 'status' | 'updatedAt' | 'usage'>;
-export type CombineEvent = (AgentInputItemEvent | ModelRawResponseEvent | ResultEndEvent | InterruptResultEvent | NoticeEvent | SubagentStatusEvent | CompactionLifecycleEvent | TerminalEvent) & CombineEventMeta;
+export type CombineEvent = (AgentInputItemEvent | AgentSdkStreamEvent | ModelRawResponseEvent | ResultEndEvent | InterruptResultEvent | NoticeEvent | SubagentStatusEvent | CompactionLifecycleEvent | TerminalEvent) & CombineEventMeta;
 export interface CompactionLifecycleEvent {
     type: 'compaction';
     data: {
@@ -875,6 +892,11 @@ export interface SubagentStatusEvent {
     type: 'subagent_status';
     data: SubagentLifecycleSnapshot;
 }
+/** Original SDK stream payload, observed by the existing single stream consumer. */
+export interface AgentSdkStreamEvent {
+    type: 'sdk';
+    data: import('../../../../cbc-shared/lib/node/index.js').RunStreamEvent;
+}
 export interface AgentInputItemEvent {
     type: 'input';
     data: AgentInputItem;
@@ -1063,6 +1085,13 @@ export interface SessionRewindMutationOptions {
     cwd: string;
     headMessageId: string | undefined;
 }
+/**
+ * model override 的意图来源：决定该值是否等价于「用户显式选择」。
+ * - 'user'：/model 命令、ACP set_model、SDK 控制信号等用户动作；
+ * - 'declared'：主 Agent 声明模型（declaredModel）联动写入；
+ * - 'materialized'：Web UI 会话装配期钉住的兜底解析值（非用户意图）。
+ */
+export type OverrideModelSource = 'user' | 'declared' | 'materialized';
 export interface SessionManager {
     getCurrent(): Session;
     setCurrent(session: Session): void;
@@ -1088,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. */
@@ -1165,11 +1206,15 @@ export interface SessionManager {
     setOverridePermissionMode(sessionId: string, mode: PermissionMode): void;
     getOverridePermissionMode(sessionId: string): PermissionMode | undefined;
     /**
-     * 设置 session 的 model 覆盖值（来自 SDK control signal）
-     * 这些值会覆盖 CLI 参数和配置文件的设置
+     * 设置 session 的 model 覆盖值。source 记录意图来源，供「是否用户显式选择」判定：
+     * - 'user'（默认）：/model 命令、ACP set_model、SDK 控制信号等用户动作；
+     * - 'declared'：主 Agent 声明模型（declaredModel）联动写入；
+     * - 'materialized'：Web UI 会话装配期钉住的兜底解析值（非用户意图）。
      */
-    setOverrideModel(sessionId: string, model: string): void;
+    setOverrideModel(sessionId: string, model: string, source?: OverrideModelSource): void;
     getOverrideModel(sessionId: string): string | undefined;
+    getOverrideModelSource(sessionId: string): OverrideModelSource | undefined;
+    clearOverrideModel(sessionId: string): void;
     /**
      * 设置会话运行时模型：同步写 session.options.model + requestOptions.model + override map。
      *
@@ -1178,7 +1223,7 @@ export interface SessionManager {
      * 供 applyOverrideModel 每轮重建 requestOptions（Issue #82146）。/model 命令与模型面板
      * 共用此入口；ACP set_model（applyRuntimeSessionModel）仍为独立实现，待统一收敛。
      */
-    setRuntimeModel(session: Session | undefined, modelId: string): void;
+    setRuntimeModel(session: Session | undefined, modelId: string, source?: OverrideModelSource): void;
     /**
      * 设置会话运行时 outputStyle：同步写 session.options.outputStyle。
      *
@@ -1502,6 +1547,7 @@ export interface InterruptionService {
     approve(item: RunToolApprovalItem, options?: ApprovalOptions): void;
     reject(item: RunToolApprovalItem, options?: {
         decision?: 'deny' | 'rejectAndExitPlan';
+        cancelTurn?: boolean;
     }): void;
     waitFor(session: Session): Promise<void>;
     /** Resolve the main/leader session for a given session (returns self if already main). */
@@ -1712,6 +1758,12 @@ export interface TurnMetricsReporter {
      */
     unregister(sessionId: string): void;
 }
+/** Ids of one model call, as stamped by the model wrapper. */
+export interface ModelCallGeneration {
+    messageId: string;
+    conversationRequestId?: string;
+    stepSeq?: number;
+}
 export interface ModelResponseMetadata {
     /** 响应中的模型 ID */
     model?: string;
@@ -1725,6 +1777,8 @@ export interface ModelResponseMetadata {
      * 都带 providerData.messageId === 此值，handleContentFilteredResponse 据此剔除并替换为安全提示。
      */
     contentFilterMessageId?: string;
+    /** Correlation of the generation that just completed, as stamped by the model wrapper. */
+    generation?: ModelCallGeneration;
     usage?: {
         prompt_tokens: number;
         completion_tokens: number;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-run-state-machine-protocol.d.ts

@@ -1,5 +1,5 @@
 import type { Observable } from 'rxjs';
-import type { Session } from './session-protocol.js';
+import type { AgentRetryReason, Session } from './session-protocol.js';
 export declare const SessionRunStateMachine: unique symbol;
 export declare const SessionRunStateProjectionService: unique symbol;
 export declare const SESSION_RUN_STATE_PROJECTION_SCHEMA: 'session-run-state.v1';
@@ -144,6 +144,7 @@ export type SessionRunEvent = {
 } | {
     type: SessionRunEventType.RETRYING;
     reason?: string;
+    retryReason?: AgentRetryReason;
 } | {
     type: SessionRunEventType.COMPACT_STARTED;
     reason?: string;
@@ -189,6 +190,18 @@ export interface SessionRunStateMachine {
      */
     getChange$(session: Session, skipFirst?: boolean): Observable<void>;
 }
+export declare const ModelRequestRetryPhase: unique symbol;
+/**
+ * 模型请求层（宿主 provider）在同一次请求内部退避重发时，借此把会话投影为 retrying。
+ * 状态写入与守卫收口在 core，宿主只包住退避等待，不直接驱动状态机。
+ */
+export interface ModelRequestRetryPhase {
+    /**
+     * `wait` 期间会话显示 retrying 并携带 `reason`；结束（含抛错 / 取消）后恢复 model_requesting。
+     * 非本轮主请求（无 session、辅助型 purpose、状态不在 model_requesting）时只执行 `wait`。
+     */
+    during<T>(session: Session | undefined, reason: AgentRetryReason, wait: () => Promise<T>): Promise<T>;
+}
 /**
  * Pure derivations from a `SessionRunStatus`. The state machine implementation
  * MUST keep its instance methods (`getLifecycle`, `isBusy`, etc.) consistent

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/stream-timeout-retry-budget.d.ts

@@ -9,11 +9,18 @@ export declare function hasExhaustedStreamTimeoutRetryBudget(session: Session, i
 /**
  * `finish_reason=error` 且没有可用输出的两种空流：reasoning-only 与 no-token。
  * placeholder（空 200 / 心跳帧）仍是会话层终态，由拦截器切一次备站。
+ *
+ * 额外的时长闸门（#132616）：这两种 kind 之所以可重试，前提是「上游瞬时失败」——秒级
+ * 空响应重跑一次大概率就好了。但当这条流已经跑满上游的硬时限才收到 error 时，前提不成立：
+ * 同一段 prompt 重跑必然再次跑满同一个时限。实测 7 个会话全部重试、全部再次撞墙、0 次恢复，
+ * 而 `#130098` 把预算从 1 提到 3 之后，同样的输入会从 2×900s 变成 4×900s ≈ 60 分钟静默。
+ * 重试的期望收益不随 elapsed 增长，成本却线性增长，所以按 elapsed 收口。
  */
 export declare function isRetryableEmptyStreamError(error: unknown): boolean;
 /**
  * Empty 200 / placeholder-only：拦截器最多切一次备站，会话层终态（#115866）。
- * reasoning-only / no-token + finish_reason=error：上游瞬时失败，按 error 预算重试。
+ * reasoning-only / no-token + finish_reason=error：上游瞬时失败，按 error 预算重试；
+ * 已烧满上游硬时限的那些除外，见 {@link isRetryableEmptyStreamError} 的时长闸门（#132616）。
  * 流空闲超时 / 首 token 超时：按各自的超时预算重试。
  */
 export declare function shouldAutoRetryStreamTimeout(session: Session, error: unknown): boolean;