@tencent-ai/agent-harness 0.2.0-beta.6 → 0.2.0-beta.8

package/cli/dist-server/types/node/agent/interceptors/image-interceptors.d.ts

@@ -0,0 +1,47 @@
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { ImageBlobService } from '../../blob-store';
+import { SettingsManager } from '../../settings';
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+/**
+ * ImageRehydration 拦截器
+ *
+ * 在 API 请求发出前处理历史中的图片：
+ * - 最近 N 轮用户消息中的 ImageBlobRef → 还原为完整 base64 data URI
+ * - 更早轮次的 ImageBlobRef → 替换为文本占位符（含来源和路径信息）
+ *
+ * 优先级 1050：在 History(1400) 注入完整历史之后，在 State(1000) 之前执行
+ */
+export declare class ImageRehydrationAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly imageBlobService: ImageBlobService;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * 将 item 中包含的所有 blob_id 标记为已发送，
+     * 这样后续 turn 中 Read 工具读取相同图片时会返回占位符。
+     */
+    private trackBlobRefsInItem;
+    /**
+     * 检查单个 item 是否包含 ImageBlobRef
+     */
+    private itemContainsBlobRef;
+}
+/**
+ * 图片压缩拦截器
+ *
+ * 对 user message 中的 base64 图片进行长边压缩（默认 2000px），
+ * 确保无论图片来源（ACP / plugin-chat / TUI 粘贴）都统一压缩。
+ *
+ * 只做尺寸压缩，不做大小限制，不会丢弃图片。
+ *
+ * 优先级 1075：在 ImageRehydration(1050) 之前，在 MemoryContext(1150) 之后
+ */
+export declare class ImageCompressionAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly logger: Logger;
+    protected init(): void;
+    intercept(request: AgentRunRequest): Promise<void>;
+    private compressImagesInMessage;
+    private compressInputImageBlock;
+}

package/cli/dist-server/types/node/agent/interceptors/index.d.ts

@@ -0,0 +1,16 @@
+export { HistoryAgentRunInterceptor, MessageReorganizeAgentRunInterceptor, ProviderDataAgentRunInterceptor, MessageQueueAgentRunInterceptor, SkipRunAgentRunInterceptor, UserInputAgentRunInterceptor, UserQueryWrapperAgentRunInterceptor, PreMessageCompactInterceptor, } from '../../../vendor/cbc-core/node/index.js';
+export * from './env-interceptor';
+export * from './initial-prompt-interceptor';
+export * from './sensitive-user-input-interceptor';
+export * from './team-resume-intent-interceptor';
+export * from './command-interceptors';
+export * from './manual-compact-request-handler';
+export * from './system-reminder-interceptor';
+export * from './model-interceptors';
+export * from './file-interceptors';
+export * from './telemetry-interceptors';
+export * from './image-interceptors';
+export * from './sandbox-interceptor';
+export * from './ultracode-keyword-interceptor';
+export * from './ultracode-effort-reminder-interceptor';
+export * from './deep-research-pending-interceptor';

package/cli/dist-server/types/node/agent/interceptors/initial-prompt-interceptor.d.ts

@@ -0,0 +1,29 @@
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { AgentManager, AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+/**
+ * Prepends the main agent's `initialPrompt` (from `.md` frontmatter or product
+ * config) to the FIRST user turn of a main session — Claude Code parity for
+ * running a whole session as an agent via `--agent <name>` / `settings.agent`.
+ *
+ * Scope guards (all must hold, otherwise no-op):
+ * - main session only: sub-agent sessions (`meta.parentSessionId`) and teammate
+ *   sessions (`meta.teamContext`) get their task prompt from the Agent tool /
+ *   mailbox, not from a user's first message;
+ * - first turn only: `session.history` is still empty at this priority (the
+ *   History interceptor appends input at 1400, after us), so a non-empty
+ *   history means an ongoing or resumed conversation — never re-inject;
+ * - real user runs only: queued (`skipRun`), internal replays
+ *   (`skipAddHistory`), and token-calculation probes are skipped.
+ */
+export declare class InitialPromptAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly agentManager: AgentManager;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * The effective main agent is the settings/--agent override when the run
+     * comes in under the default agent name (same mapping as the telemetry
+     * interceptor's session.agentName resolution).
+     */
+    private resolveInitialPrompt;
+}

package/cli/dist-server/types/node/agent/interceptors/manual-compact-request-handler.d.ts

@@ -0,0 +1,29 @@
+import { AgentManager, ContextCompactSummarizer, type IdleQueueDrainService as IdleQueueDrainServiceContract, type InterruptionService as InterruptionServiceContract, type ManualCompactRequestHandler as ManualCompactRequestHandlerContract, type Session, SessionRunStateMachine } from '../../../vendor/cbc-core/node/index.js';
+import { type AgentInputItem } from '../../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { ConsoleManager } from '../../console';
+interface ManualCompactCommand {
+    customInstructions?: string;
+}
+export declare const extractManualCompactCommand: (input: string | AgentInputItem[]) => ManualCompactCommand | undefined;
+/** Routes external TUI `/compact` requests before AgentService claims a normal run. */
+export declare class ManualCompactRequestHandlerImpl implements ManualCompactRequestHandlerContract {
+    protected readonly agentManager: AgentManager;
+    protected readonly contextCompactSummarizer: ContextCompactSummarizer;
+    protected readonly logger: Logger;
+    protected readonly consoleManager: ConsoleManager;
+    protected readonly stateMachine: SessionRunStateMachine;
+    protected readonly interruptionService?: InterruptionServiceContract;
+    protected readonly idleQueueDrainService?: IdleQueueDrainServiceContract;
+    private operations?;
+    tryHandle(input: string | AgentInputItem[], session: Session): Promise<boolean>;
+    compact(session: Session, options?: {
+        customInstructions?: string;
+        waitForIdle?: boolean;
+    }): Promise<boolean>;
+    private runCompact;
+    private claimIdleCompactWindow;
+    private waitForIdleOrApproval;
+    private hasPendingApproval;
+}
+export {};

package/cli/dist-server/types/node/agent/interceptors/model-interceptors.d.ts

@@ -0,0 +1,43 @@
+import { AgentManager, AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest, Session, SessionManager } from '../../../vendor/cbc-core/node/index.js';
+import { Agent } from '../../../vendor/cbc-shared/node/index.js';
+import { LanguageModel, ProductManager } from '../../../workspace/product/lib/common/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { SettingsManager } from '../../settings';
+export { StateAgentRunInterceptor, ContinueAgentRunInterceptor } from '../../../vendor/cbc-core/node/index.js';
+export declare class ModelConfigAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly productManager: ProductManager;
+    protected readonly agentManager: AgentManager;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly sessionManager: SessionManager;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+    protected getModelByCliOptions(agent: Agent<any, any>, session: Session): Promise<LanguageModel | undefined>;
+    protected getModelByRequestOptions(agent: Agent<any, any>, session: Session): Promise<LanguageModel>;
+    protected configureModelConfig(agent: Agent<any, any>, session: Session): Promise<void>;
+    /**
+     * 配置 thinking 相关的 modelSettings（Issue #12554 / §16.4）。
+     *
+     * 优先级（从高到低）：
+     *   1. 会话级 override（SessionManager.getOverrideThinking）— 来自 ACP setSessionConfigOption('thought_level')
+     *   2. CLI 参数 / 全局 settings（alwaysThinkingEnabled / reasoningEffort）
+     *   3. modelConfig.reasoning.defaultEffort（产品配置兜底）
+     *   4. legacy 'high' 兜底
+     *
+     * 关键设计点：
+     *   - thinkingEnabled === false 必须显式短路 + delete agent.modelSettings.reasoning，
+     *     否则下面的 modelConfig.reasoning 兜底会把 thinking 又打开（"假关闭"假闭环）
+     *   - 'max' 在共享契约里合法。发送前先按当前模型能力把 effort 收敛（Issue #87437），
+     *     `toSdkEffort` 只对收敛后的值做类型断言、值不变；SDK 类型枚举虽不含 'max'，
+     *     但运行时纯透传（见 toSdkEffort 注释）。#79843
+     */
+    protected configureThinkingSettings(agent: Agent<any, any>, modelConfig: LanguageModel, session: Session): Promise<void>;
+}
+export declare class ImageFilterAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly productManager: ProductManager;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+    private filterImagesFromMessage;
+    private filterImagesFromFunctionCallResult;
+}

package/cli/dist-server/types/node/agent/interceptors/sandbox-interceptor.d.ts

@@ -0,0 +1,84 @@
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { type BashSandboxManager as IBashSandboxManager } from '../../bash-sandbox/bash-sandbox-protocol';
+import { isSandboxCLIPlatformSupported } from '../../sandbox-cli/sandbox-backend-support';
+import { type ISandboxCLILifecycle } from '../../sandbox-cli/sandbox-cli-lifecycle-protocol';
+import { type SandboxCLIProcessManager as ISandboxCLIProcessManager } from '../../sandbox-cli/sandbox-cli-protocol';
+import { type SandboxRuleSyncService as ISandboxRuleSyncService } from '../../sandbox-cli/sandbox-rule-sync-service';
+import { isFileBackupSupported, normalizeFileBackupMaxSizeMB, shouldUseSandboxCLI } from '../../sandbox-cli/sandbox-session-preparation';
+import { SandboxTurnConfig } from '../../sandbox-cli/sandbox-turn-config';
+import { type ThreatDomainChecker as IThreatDomainChecker } from '../../sandbox-cli/threat-domain-checker';
+import { type SandboxCenterIpcClient as ISandboxCenterIpcClient } from '../../sensitive-content/sandbox-center-ipc-client-protocol';
+import { SettingsManager } from '../../settings';
+import { type SandboxTelemetryReporter as ISandboxTelemetryReporter } from '../../telemetry/sandbox-telemetry-protocol';
+export declare function areSandboxExperimentalFeaturesSupported(): boolean;
+export { isSandboxCLIPlatformSupported };
+export { isFileBackupSupported, normalizeFileBackupMaxSizeMB, shouldUseSandboxCLI };
+export declare class SandboxAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly logger: Logger;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly sandboxTurnConfig: SandboxTurnConfig;
+    protected readonly sandboxLifecycle?: ISandboxCLILifecycle;
+    protected readonly sandboxCenterClient?: ISandboxCenterIpcClient;
+    protected readonly processManager?: ISandboxCLIProcessManager;
+    protected readonly telemetryReporter?: ISandboxTelemetryReporter;
+    protected readonly sandboxRuleSyncService?: ISandboxRuleSyncService;
+    protected readonly bashSandboxManager?: IBashSandboxManager;
+    protected readonly threatDomainChecker?: IThreatDomainChecker;
+    /**
+     * 标记本轮 intercept 执行期间 onSessionReady 回调是否已完成配置同步。
+     * 用于 bootstrap 场景下避免 ensureSandboxReady 回调和 intercept 后续代码
+     * 重复执行 syncModifyBackupConfig / syncRulesOnTurnStart。
+     */
+    private readonly executionStates;
+    private readonly defaultState;
+    private get turnState();
+    init(): void;
+    intercept(request: AgentRunRequest): Promise<void>;
+    private syncModifyBackupConfig;
+    /** 固化当前轮次的 SandboxTurnConfig 日志快照，避免输出后被下游 interceptor/hook 改写。 */
+    private snapshotSandboxTurnConfig;
+    private _deriveTurnDisabledReason;
+    private _logTurnTelemetryFailure;
+    /**
+     * fail-open 包装的 turn 起始规则同步。
+     *
+     * 规则同步失败时 center 里可能残留上一轮的表（松紧都有可能），本轮
+     * ruleProfile 仍按 permissionMode 决定，不去猜旧表、也不改执法口径。
+     * 对话主链路恒继续：沙箱是从属能力，从属能力故障不得阻断对话。
+     *
+     * 取舍：onSessionReady 失败后 _sessionReadySyncedThisTurn 仍置 true，
+     * 同 turn 的 intercept 不重试（避免 5s 连接超时双倍卡死）；下一 turn
+     * 再全量同步。真正防止钉死死 socket 的是 sidecar 纪元门禁。
+     *
+     * 生产事故反例（case 2）：残留旧纪元 sidecar 下，规则同步因 center 连不上
+     * 5s 超时抛出，异常穿出 intercept() → agent-service 的 interceptor 循环
+     * 将整个 run 判为 RUN_FAILED → 用户侧 3003"网络请求超时"，对话完全不可用。
+     */
+    private syncRulesFailOpen;
+    /**
+     * sandbox 生命周期管理：session 冲突检测 + ensureReady + 超时控制。
+     *
+     * @returns true 表示 sandbox 已就绪；false 表示启动失败，调用方应降级到本地执行。
+     */
+    private ensureSandboxReady;
+    /**
+     * 同步威胁库，失败与超时都只降级恶意域名匹配这一层。
+     *
+     * 必须自己兜住异常，不能并进 ensureSandboxReady 的 try：
+     * - 抛异常会落到 `return false`，等于把本轮沙箱的文件保护和网络策略一起关掉，
+     *   与设计里“恶意库不可用只关哈希匹配”的 fail-open 原则相反；
+     * - ThreatDomainChecker 已给 SET/CHECK 设置独立短超时，这里不再叠加一个不能
+     *   取消底层 IPC 的 Promise.race。
+     */
+    private syncThreatDatabase;
+}
+/** Telemetry interceptor 生成请求 ID 后，上报主用户 Turn 的 Sandbox 最终状态。 */
+export declare class SandboxTurnTelemetryAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly logger: Logger;
+    protected readonly telemetryReporter?: ISandboxTelemetryReporter;
+    intercept(request: AgentRunRequest): Promise<void>;
+    private _logFailure;
+}

package/cli/dist-server/types/node/agent/interceptors/sensitive-user-input-interceptor.d.ts

@@ -0,0 +1,7 @@
+import { type SensitiveUserInputReview as SensitiveUserInputReviewInterface } from '../../sensitive-content/sensitive-content-protocol';
+import { AgentRunInterceptor, AgentRunInterceptorPriority, type AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+export declare class SensitiveUserInputAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly sensitiveUserInputReview?: SensitiveUserInputReviewInterface;
+    intercept(request: AgentRunRequest): Promise<void>;
+}

package/cli/dist-server/types/node/agent/interceptors/system-reminder-interceptor.d.ts

@@ -0,0 +1,101 @@
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+import { PromptManager } from '../../../workspace/prompts/lib/common/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { ChannelManager } from '../../channel';
+import { IDEService } from '../../ide-integration/ide-protocol';
+import { MemoryManager } from '../../memory';
+import { PlanStorageService } from '../../tools/plan-storage-service';
+export declare class SystemReminderAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    private readonly hostContexts;
+    protected readonly promptManager: PromptManager;
+    protected readonly memoryManager: MemoryManager;
+    protected readonly ideService: IDEService;
+    protected readonly channelManager: ChannelManager;
+    protected readonly planStorageService: PlanStorageService;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * Route a named system-prompt section through the mods `prompt.section`
+     * middleware event. Contract mirrors upstream Claude Code:
+     *
+     *   - `text: null` returned by a mod drops the section (returns undefined,
+     *     caller must not inject anything);
+     *   - `text: string` returned by a mod replaces the section body;
+     *   - `deny: string` drops the section (same as null);
+     *   - no hook match returns the input text unchanged.
+     *
+     * `undefined` inputs (no section body from cbc) pass a `null` text to the
+     * mod so a mod can *add* the section if it wants (upstream: `prompt.section`
+     * with `text: null` means "cbc has no content for this section, feel free
+     * to synthesise one").
+     */
+    private applyPromptSection;
+    /**
+     * 生成 Channel Instructions
+     * 从所有已注册的 channel 服务器收集 instructions 并注入
+     *
+     * **必须用 `<system-reminder>` 标签包裹**：addSystemReminder 直接把传入字符串
+     * unshift 到 user message 的 content 数组，前端 user-message-box.tsx 通过
+     * `stripSystemReminders` 剥离 `<system-reminder>...</system-reminder>` 内的
+     * 内容才能避免把它当真实 user 输入渲染。如果返回裸字符串（无标签），
+     * webui 会把整段 `Messages from WeChat arrive as ...` 长 instructions
+     * 渲染成用户气泡，并被 topic generator 误当作首条消息生成会话标题。
+     */
+    private generateChannelInstructions;
+    private isFirstOrResumeMessage;
+    /**
+     * 检查是否需要注入系统规则/记忆
+     * 在以下情况下需要注入：
+     * 1. 首条消息
+     * 2. 恢复会话
+     * 3. 当前历史不包含 system-reminder（压缩后或恢复后的场景）
+     */
+    private shouldInjectSystemReminder;
+    /**
+     * 检查历史消息中是否包含真正的系统规则 system-reminder 标签
+     * 区分两种类型的 system-reminder：
+     * 1. 规则型（CODEBUDDY.md 规则 / 条件规则）：不带 data-role 属性
+     * 2. 非规则型：带 data-role 属性（如 compact-summary, command-caveat, memory,
+     *    hook, ide-context, channel-event, team-context, error-recovery, tool-hint,
+     *    message-queue, memory-freshness 等），应该忽略
+     */
+    private historyContainsSystemReminder;
+    /**
+     * 检查文本中是否包含规则型 system-reminder
+     * 排除带 data-role 属性的非规则型 system-reminder
+     */
+    private hasRulesSystemReminder;
+    private isUserMessage;
+    /**
+     * 检查是否为 isMeta 消息（Stop Hook 自动触发的内部消息）
+     * 这些消息应该保持简洁，不添加额外的 system-reminder
+     */
+    private isMetaMessage;
+    private injectHostContext;
+    private renderSystemReminder;
+    private generateSystemReminder;
+    /**
+     * 极简模式没有 Plan 循环：会话若因切模式前的遗留状态停在 Plan，就把权限模式
+     * 收回去，否则模型会拿着一个永远无法 ExitPlanMode 的会话空转。
+     *
+     * 独立成显式命名的方法而不是塞在 `generatePlanModeReminder` 里 —— 那是个
+     * `generate*` 取值函数，在里面改 `permissionModeSubject` 是隐藏副作用。
+     * 只按 agent 名门控，WorkBuddy 默认 cli 不会进这条。
+     */
+    private enforceMinimalPermissionMode;
+    private generatePlanModeReminder;
+    private generateDelegateModeReminder;
+    private generateIDESelectionReminder;
+    /**
+     * Inject hook-provided contexts into user messages
+     * Implements Claude Code hooks specification for additionalContext injection
+     */
+    private injectHookContexts;
+    /**
+     * Route a hook-produced attachment text through the mods `prompt.attachment`
+     * middleware event. Contract mirrors upstream: `{ text }` rewrites, `{ text: null }`
+     * or `{ deny }` drops the attachment, no hook returns the input unchanged.
+     */
+    private applyPromptAttachment;
+}

package/cli/dist-server/types/node/agent/interceptors/team-resume-intent-interceptor.d.ts

@@ -0,0 +1,31 @@
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+import { type AgentRunScope as IAgentRunScope } from '../../../vendor/cbc-core/node/index.js';
+/**
+ * Tags fresh, trusted human input before queue arbitration. The tag is carried
+ * with queued/merged user input and stripped before History, so replayed history
+ * cannot forge a human resume turn.
+ */
+export declare class HumanInputProvenanceAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    intercept(request: AgentRunRequest): Promise<void>;
+}
+/**
+ * Rehydrates interrupted team runtime at the model-run boundary, after queued
+ * user input has been selected and before the human marker is consumed.
+ */
+export declare class TeamRuntimeResumeAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+}
+/**
+ * Resolves the human-resume capability after MessageQueue has decided which
+ * input belongs to this actual model run, then strips the marker before History.
+ */
+export declare class TeamResumeIntentAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly agentRunScope?: IAgentRunScope;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+}

package/cli/dist-server/types/node/agent/interceptors/telemetry-interceptors.d.ts

@@ -0,0 +1,43 @@
+import { AgentManager, AgentRunInterceptor, AgentRunInterceptorPriority, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { FrictionAnalysisService, TelemetryService } from '../../telemetry';
+export declare class TelemetryAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly agentManager: AgentManager;
+    protected readonly logger: Logger;
+    protected readonly telemetryService: TelemetryService;
+    protected readonly frictionAnalysisService: FrictionAnalysisService;
+    intercept(request: AgentRunRequest): Promise<void>;
+    /**
+     * Check whether the given purpose value was left over from a compact cycle.
+     * If so, the interceptor should overwrite it for the next user request to
+     * prevent stale compact purposes from leaking into normal conversation traces.
+     */
+    private isCompactPurpose;
+    /**
+     * 消费 `conversation:compact` 的一次性凭据，返回本轮是否应保留该 purpose。
+     *
+     * 凭据无论 purpose 是否匹配都会被清掉，避免它在"压缩后 purpose 又被 memory
+     * extraction 等调用方覆盖"的路径上残留，隔几轮才被兑付。
+     */
+    private consumePendingCompactPurpose;
+    /**
+     * 取 RunState input 的最后一条 history 项；input 为 string/array/undefined/null 时返回 undefined。
+     * Issue #65138: input 可能为 undefined（sub-agent 路径 schema 必填但运行时无 parse 校验时透传），
+     * 裸读 .history 会抛 'reading history'。
+     */
+    private getLastInputMessage;
+}
+/**
+ * 假 run 的 abort 在 AgentService.run 入口就装上，Env 等后续 interceptor 仍可能 await。
+ * 必须在链首记下诊断句柄，calculateSession 才不会把并发真实 run 的 controller 当成自己的。
+ */
+export declare class TokenCalculationAbortSnapshotInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    intercept(request: AgentRunRequest): Promise<void>;
+}
+export declare class TokenCalculationAgentRunInterceptor implements AgentRunInterceptor {
+    priority: AgentRunInterceptorPriority;
+    protected readonly logger: Logger;
+    intercept(request: AgentRunRequest): Promise<void>;
+}

package/cli/dist-server/types/node/agent/interceptors/ultracode-effort-reminder-interceptor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * UltracodeEffortReminderInterceptor —— 当 session 处于 effort=ultracode 模式时,
+ * 每轮在 input 末尾注入一段 `ultra_effort_active` reminder,提示主 agent
+ * 默认就用 Workflow 工具规划任务。
+ *
+ * 单一职责:在 ultracode 模式下持续注入"模式提醒"。enter/exit 事件由 EffortCommandExecutor 自己注入。
+ *
+ * 状态读取:`session.meta.workflowEffortLevel === 'ultracode'`(EffortCommandExecutor 维护)。
+ *
+ * 优先级:与 KeywordInterceptor 相同档(SystemReminderContext-35),先后顺序无所谓。
+ *
+ * Reminder 文本:从 prompt template `workflow-ultra-effort-active` 加载;打包/配置异常时走 FALLBACK。
+ */
+import { PromptManager } from '../../../workspace/prompts/lib/common/index.js';
+import { AgentRunInterceptor, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+export declare class UltracodeEffortReminderInterceptor implements AgentRunInterceptor {
+    priority: number;
+    protected readonly promptManager: PromptManager;
+    intercept(request: AgentRunRequest): Promise<void>;
+    private loadReminder;
+}

package/cli/dist-server/types/node/agent/interceptors/ultracode-keyword-interceptor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * UltracodeKeywordInterceptor —— 识别用户输入里的 `ultracode` / "use a workflow" 关键词,
+ * 注入 system-reminder 提示主 agent 优先用 Workflow 工具。
+ *
+ * 单一职责:Trigger 路由层。本拦截器只负责"提示",不负责真正起 workflow —— 那是 Agent 调用 Workflow 工具的事。
+ *
+ * 优先级:位于 SystemReminderContext(1200) 之后,MessageReorganize(1300) 之前。
+ * 与 ChannelEvent 同档(1170 → 这里 1165),时间维度上稍后,以避免覆盖 channel 事件。
+ *
+ * 触发规则(对齐深度文档):
+ * - 用户输入文本里包含独立 token `ultracode`(不在 ` `/`"`/字符串里) → 注入 reminder
+ * - 用户输入文本里出现 "use a workflow" / "run a workflow" / "use workflow" 等自然短语 → 注入
+ *
+ * 注入内容:一段 system-reminder,告知主 agent 当前请求适合用 Workflow 工具(opt-in 已满足)。
+ */
+import { PromptManager } from '../../../workspace/prompts/lib/common/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { AgentRunInterceptor, AgentRunRequest } from '../../../vendor/cbc-core/node/index.js';
+export declare class UltracodeKeywordInterceptor implements AgentRunInterceptor {
+    /** 比 ChannelEvent(1170)略低,确保不破坏 channel 事件结构 */
+    priority: number;
+    protected readonly logger: Logger;
+    protected readonly promptManager: PromptManager;
+    intercept(request: AgentRunRequest): Promise<void>;
+    private loadReminder;
+    /**
+     * 抽取用户消息文本(忽略 system-reminder / tool-hint 等内部消息)。
+     * 简单实现:最后一条 role='user' 的消息;只看 string 内容。
+     */
+    private extractUserText;
+    /** 排除完全由 system-reminder/tool-hint 包裹、无真实用户输入的消息。 */
+    private looksLikeUserText;
+    private isUltracodeRequest;
+}

package/cli/dist-server/types/node/agent/main-agent-policy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 主 Agent 四种模式的唯一政策面。
+ *
+ * 优先级：环境变量 > settings.json `codebuddy.mainAgent` > 内置默认。
+ * 所有入口（Web / TUI / `codebuddy config` / `--settings` / ACP）只读这里。
+ */
+export declare const ENV_MAIN_AGENT_ENABLED = "CODEBUDDY_MAIN_AGENT_ENABLED";
+export declare const ENV_MAIN_AGENT_ALLOW_UNOPTED = "CODEBUDDY_MAIN_AGENT_ALLOW_UNOPTED";
+/** ACP 未声明 mainAgentSupport 的宿主（WorkBuddy Desktop / sidecar / 其它 IDE）。 */
+export type MainAgentHostKind = 'native' | 'opted-in' | 'unopted';
+export interface MainAgentPolicy {
+    /** 总闸。关：无 picker、无 standing 解析。缺省开。 */
+    readonly enabled: boolean;
+    /**
+     * 未 opt-in 的 ACP 宿主是否也走 standing 解析。
+     * 缺省关：WorkBuddy 始终产品默认 cli。将来要开，只翻这一键。
+     */
+    readonly allowUnopted: boolean;
+    /** 能力生效时，新会话的默认主 agent 名。 */
+    readonly defaultName?: string;
+    /**
+     * 上次 chip / 新建智能体选择。不是「设为默认」。
+     * 仅当 `default` 未配置时，空白新会话才回落到这里。
+     */
+    readonly lastUsedName?: string;
+}
+export declare const DEFAULT_MAIN_AGENT_POLICY: MainAgentPolicy;
+export declare function parseEnvFlag(raw: string | undefined): boolean | undefined;
+export declare function trimOptionalName(value: unknown): string | undefined;
+export declare function resolveMainAgentPolicy(settings: unknown, env?: NodeJS.Dict<string>): MainAgentPolicy;
+/** standing 解析（mainKey / settings default）是否对当前宿主生效。 */
+export declare function isStandingMainAgentActive(policy: MainAgentPolicy, hostKind: MainAgentHostKind): boolean;
+export declare function hostKindFromClientOptIn(optedIn: boolean): MainAgentHostKind;

package/cli/dist-server/types/node/agent/main-agent-preset.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Opt-in for a custom `.codebuddy/agents/*.md` to appear in the main-agent
+ * picker (chip / 新建智能体 / 设为默认 / getAgents / set_agent).
+ *
+ * Canonical frontmatter: `mainAgent: true`.
+ * Loader maps that to this tag. Do **not** reuse `main-mode` — that tag plus a
+ * homonym file (`ptc.md`) would look like a shipped standing mode and refresh
+ * over the user's file.
+ *
+ * Files without the field still load as @agent / subagents (WorkBuddy / Claude
+ * subagent / 存量自定义). They just stay out of the four-mode picker.
+ */
+export declare const MAIN_AGENT_PRESET_TAG = "main-agent-preset";
+/** Canonical YAML key written by create mode and create-by-AI. */
+export declare const MAIN_AGENT_PRESET_FRONTMATTER_KEY = "mainAgent";
+/** Same base template as Standard / Creator. Body of the .md becomes appendInstructions. */
+export declare const MAIN_AGENT_PRESET_INSTRUCTIONS = "cli-agent-prompt";
+export declare function isCustomMainAgentPreset(agent: {
+    tags?: readonly string[];
+} | undefined): boolean;
+export interface MainAgentPresetFrontmatterRead {
+    /** True only when a recognized key parses as boolean true. */
+    readonly enabled: boolean;
+    /** Present when a recognized key existed but was not a boolean. */
+    readonly invalidRaw?: unknown;
+}
+/**
+ * Read the picker opt-in from agent frontmatter. Canonical `mainAgent` wins
+ * over `main_agent` when both are present.
+ */
+export declare function readMainAgentPresetFrontmatter(frontmatter: unknown): MainAgentPresetFrontmatterRead;
+export declare function withMainAgentPresetTag(tags: readonly string[], enabled: boolean): string[];