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

package/cli/dist-server/types/node/command/resume-command-executor.d.ts

@@ -0,0 +1,21 @@
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { NavigationManager } from '../navigation';
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+export declare class ResumeCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly sessionManager: SessionManager;
+    protected readonly navigationManager: NavigationManager;
+    protected readonly logger: Logger;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+    private handleList;
+    /**
+     * Notify ACP clients that session has been switched via session_info_update.
+     * This allows Web UI to update its sessionId, URL, and reload chat history.
+     * Broadcast to all connections — the stored acpConnectionId goes stale on
+     * reconnect/multi-client and unicast used to drop the reset silently.
+     */
+    private notifySessionReset;
+}

package/cli/dist-server/types/node/command/rewind-command-executor.d.ts

@@ -0,0 +1,10 @@
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+/**
+ * Rewind 命令执行器
+ */
+export declare class RewindCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/sandbox-command-executor.d.ts

@@ -0,0 +1,20 @@
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+import { SettingsManager as ISettingsManager } from '../settings/settings-protocol';
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { NavigationManager } from '../navigation';
+import { BashSandboxManager as IBashSandboxManager } from '../bash-sandbox';
+export declare class SandboxCommandExecutor implements CommandExecutor {
+    protected readonly settingsManager: ISettingsManager;
+    protected readonly sessionManager: SessionManager;
+    protected readonly navigationManager: NavigationManager;
+    protected readonly bashSandboxManager: IBashSandboxManager;
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+    /**
+     * 处理 exclude 子命令
+     * 用法: /sandbox exclude <command>
+     */
+    private handleExcludeCommand;
+}

package/cli/dist-server/types/node/command/save-workflow-command-executor.d.ts

@@ -0,0 +1,43 @@
+/**
+ * /save-workflow <runId> <name> [--scope=project|user]
+ *
+ * 单一职责:解析参数 + 调用 WorkflowManager.saveAs 把脚本快照复制到 registry。
+ *
+ * 实际的"找快照 → 校验 name → mkdir + copyFile → invalidate"逻辑沉到 Manager,
+ * 与 UI 端 WorkflowSavePanel 共享同一段代码(R1 领域下沉)。
+ *
+ * 行为:
+ *   - --scope=project (默认): `<cwd>/.codebuddy/workflows/<name>.js`
+ *   - --scope=user           : `~/.codebuddy/workflows/<name>.js`
+ *   - 同名直接覆盖(对齐 CC)
+ */
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import type { WorkflowManager } from '../../workspace/cbc-workflow/lib/node/index.js';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+interface ParsedArgs {
+    runId?: string;
+    name?: string;
+    scope: 'project' | 'user';
+    error?: string;
+}
+export declare class SaveWorkflowCommandExecutor implements CommandExecutor {
+    name: string;
+    autoGenerateHistory: boolean;
+    protected readonly logger: Logger;
+    protected readonly sessionManager: SessionManager;
+    protected readonly manager: WorkflowManager;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+    private run;
+    /**
+     * 解析 argv:
+     *   /save-workflow <runId> <name> [--scope=project|user]
+     *   /save-workflow <runId> <name> --user / --project (短形式)
+     *
+     * Visible-for-testing(无副作用、无依赖,可作为 instance 方法直接调用)。
+     */
+    parseArgs(args: unknown[]): ParsedArgs;
+    static usage(reason?: string): string;
+    private appendHistory;
+}
+export {};

package/cli/dist-server/types/node/command/skills-command-executor.d.ts

@@ -0,0 +1,9 @@
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+export declare class SkillsCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly sessionManager: SessionManager;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/stats-command-executor.d.ts

@@ -0,0 +1,11 @@
+import { NavigationManager } from '../navigation';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+export declare class StatsCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly sessionManager: SessionManager;
+    protected readonly navigationManager: NavigationManager;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/status-command-executor.d.ts

@@ -0,0 +1,11 @@
+import { NavigationManager } from '../navigation';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+export declare class StatusCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly sessionManager: SessionManager;
+    protected readonly navigationManager: NavigationManager;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/tasks-command-executor.d.ts

@@ -0,0 +1,9 @@
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+export declare class TasksCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly sessionManager: SessionManager;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/terminal-setup-command-executor.d.ts

@@ -0,0 +1,7 @@
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+export declare class TerminalSetupCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/theme-command-executor.d.ts

@@ -0,0 +1,7 @@
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+export declare class ThemeCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/todos-command-executor.d.ts

@@ -0,0 +1,16 @@
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { TaskStorageService } from '../tools/task-storage-service';
+import { TodoStorageService } from '../tools/todo-storage-service';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+export declare class TodosCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly sessionManager: SessionManager;
+    protected readonly todoStorageService: TodoStorageService;
+    protected readonly taskStorageService: TaskStorageService;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+    private extractTodoListFromHistory;
+    private formatTodos;
+    private getStatusIcon;
+}

package/cli/dist-server/types/node/command/upgrade-command-executor.d.ts

@@ -0,0 +1,13 @@
+import { Logger } from '@celljs/core';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { ExternalUriOpener } from '../../workspace/runtime/lib/common/index.js';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+export declare class UpgradeCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly productManager: ProductManager;
+    protected readonly externalUriOpener: ExternalUriOpener;
+    protected readonly logger: Logger;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/vim-command-executor.d.ts

@@ -0,0 +1,11 @@
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+import { VimManager } from '../vim';
+export declare class VimCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly sessionManager: SessionManager;
+    protected readonly vimManager: VimManager;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+}

package/cli/dist-server/types/node/command/web-command-executor.d.ts

@@ -0,0 +1,18 @@
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { EndpointProvider } from '../loopback/server-protocol';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+/**
+ * `/web`：在默认浏览器中打开当前会话的 Web UI。
+ *
+ * endpoint 由 loopback 服务提供，无 Web UI 的宿主（无 loopback / 远端会话）
+ * 会拿不到地址，此时只提示不可用，不误开浏览器。
+ */
+export declare class WebCommandExecutor implements CommandExecutor {
+    name: string;
+    message: string;
+    autoGenerateHistory: boolean;
+    protected readonly endpointProvider: EndpointProvider;
+    protected readonly sessionManager: SessionManager;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+    private write;
+}

package/cli/dist-server/types/node/command/workflows-command-executor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * /workflows —— 列出所有 saved + builtin workflow,以及当前 session 内运行中的 workflow run。
+ *
+ * 单一职责:把 WorkflowManager.listActive() + WorkflowRegistry.list() 拼成
+ * markdown 字符串,通过标准 finalize 路径写入 session 历史。
+ *
+ * Batch 4 简化:不实现交互式键位(`s/p/r/x/j/k`),只输出文本列表。
+ * 后续 UI batch 接入 Ink 组件后再补。
+ */
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import type { WorkflowManager, WorkflowRegistry } from '../../workspace/cbc-workflow/lib/node/index.js';
+import { CommandExecuteContext, CommandExecutor } from './command-protocol';
+export declare class WorkflowsCommandExecutor implements CommandExecutor {
+    name: string;
+    autoGenerateHistory: boolean;
+    protected readonly logger: Logger;
+    protected readonly sessionManager: SessionManager;
+    protected readonly manager: WorkflowManager;
+    protected readonly registry: WorkflowRegistry;
+    execute(ctx: CommandExecuteContext): Promise<void>;
+    private buildOutput;
+    private renderRunningSection;
+    private renderSavedSection;
+    private appendHistory;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Command Parser Protocol
+ *
+ * Defines interfaces and symbols for the command parsing service.
+ * This module enables parsing complex shell commands and extracting
+ * individual commands from them for permission rule matching.
+ */
+/**
+ * Represents an extracted command from a shell command string
+ */
+export interface ExtractedCommand {
+    /** The command name (e.g., "git", "npm", "cd") */
+    command: string;
+    /** The command arguments */
+    args: string[];
+    /** The full command string (command + args) */
+    fullCommand: string;
+}
+/**
+ * Parsing strategy identifier
+ */
+export type ParsingStrategy = 'tree-sitter' | 'shell-quote' | 'regex';
+/**
+ * Command Parser Service
+ *
+ * Main service for parsing shell commands. Uses a tiered strategy:
+ * 1. tree-sitter-bash for accurate AST parsing (when available)
+ * 2. shell-quote for token-based parsing (handles quotes/escapes)
+ * 3. regex for basic fallback
+ */
+export declare const CommandParserService: unique symbol;
+export interface CommandParserService {
+    /**
+     * Extract all commands from a command string
+     *
+     * This is the main entry point for command extraction.
+     * Uses the best available parsing strategy.
+     *
+     * @param commandString The shell command string to parse
+     * @returns Array of extracted commands
+     */
+    extractCommands(commandString: string): ExtractedCommand[];
+}
+/**
+ * Command Parser Strategy
+ *
+ * Interface for parsing strategy implementations.
+ * Each strategy provides a different method for extracting commands.
+ */
+export declare const CommandParserStrategy: unique symbol;
+export interface CommandParserStrategy {
+    /**
+     * Strategy name/identifier
+     */
+    readonly name: ParsingStrategy;
+    /**
+     * Priority of this strategy (higher = preferred)
+     */
+    readonly priority: number;
+    /**
+     * Check if this strategy is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Extract commands using this strategy
+     *
+     * @param commandString The shell command string to parse
+     * @returns Array of extracted commands, or null if parsing failed
+     */
+    extractCommands(commandString: string): ExtractedCommand[] | null;
+    /**
+     * Kick off (idempotent) lazy initialization for strategies that need to
+     * load heavy resources (e.g. tree-sitter WASM) before becoming available.
+     *
+     * Optional: strategies that are always synchronously available (shell-quote,
+     * regex) do not implement it. The service invokes it fire-and-forget on the
+     * first `extractCommands` call, so the heavy resource is only paid for when
+     * command parsing is actually needed — not eagerly at container assembly.
+     */
+    ensureInitialized?(): Promise<void>;
+}

package/cli/dist-server/types/node/console/console-manager.d.ts

@@ -0,0 +1,37 @@
+import { Subject } from 'rxjs';
+import { ConsoleManager, ConsoleMessage, GlobalConsoleOptions } from './console-protocol';
+export declare class ConsoleManagerImpl implements ConsoleManager {
+    readonly messageSubject: Subject<ConsoleMessage>;
+    private readonly originalConsole;
+    private isIntercepted;
+    private options;
+    private paused;
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    interceptGlobalConsole(options: GlobalConsoleOptions): void;
+    restoreGlobalConsole(): void;
+    pause(): void;
+    resume(): void;
+    isPaused(): boolean;
+    private parseArgs;
+    private output;
+    /**
+     * 解析输出模式
+     */
+    private resolveOutputMode;
+    /**
+     * 输出到 process.stdout/stderr
+     */
+    private outputToProcess;
+    /**
+     * 输出到原生 console
+     */
+    private outputToNativeConsole;
+    /**
+     * 输出到 UI 组件
+     */
+    private outputToUI;
+}

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

@@ -0,0 +1,112 @@
+import { Subject } from 'rxjs';
+export declare const ConsoleManager: unique symbol;
+/**
+ * Console 输出模式
+ */
+export declare enum ConsoleOutputMode {
+    /** UI 模式：通过 Subject 发送到 UI 组件渲染（默认） */
+    UI = "ui",
+    /** 原生 Console 模式：使用原生 console.log/warn/error 等 */
+    NATIVE = "native",
+    /** Process Stream 模式：直接使用 process.stdout/stderr */
+    PROCESS = "process",
+    /** 静默模式：不输出任何内容 */
+    SILENT = "silent"
+}
+/**
+ * Console 输出选项
+ */
+export interface ConsoleOutputOptions {
+    /**
+     * 输出模式
+     * - 'ui': 发送到 UI 组件（仅交互模式有效）
+     * - 'native': 使用原生 console
+     * - 'process': 使用 process.stdout/stderr
+     *
+     * 默认行为：
+     * - 交互模式：使用 'ui'
+     * - print 模式：使用 'process'
+     */
+    mode?: ConsoleOutputMode;
+    /**
+     * 消息展示时长（毫秒），仅在 UI 模式下有效
+     * @default 5000
+     */
+    displayDuration?: number;
+    /**
+     * Custom color override for UI mode (CSS color name or hex).
+     * Takes precedence over type-based color in ConsoleMessageBox.
+     */
+    color?: string;
+}
+/**
+ * Console 消息
+ */
+export interface ConsoleMessage {
+    type: 'log' | 'warn' | 'error' | 'debug' | 'info';
+    content: string;
+    displayDuration: number;
+    /** Optional custom color override (CSS color name or hex). Takes precedence over type-based color. */
+    color?: string;
+}
+export interface GlobalConsoleOptions {
+    isDebug: boolean;
+    isPrint: boolean;
+}
+/**
+ * Console 管理器
+ * 统一管理所有 console 输出，根据运行模式自动选择输出方式
+ */
+export interface ConsoleManager {
+    /**
+     * 日志输出
+     */
+    log(message: string, options?: ConsoleOutputOptions): void;
+    log(...args: unknown[]): void;
+    /**
+     * 警告输出
+     */
+    warn(message: string, options?: ConsoleOutputOptions): void;
+    warn(...args: unknown[]): void;
+    /**
+     * 错误输出
+     */
+    error(message: string, options?: ConsoleOutputOptions): void;
+    error(...args: unknown[]): void;
+    /**
+     * 调试输出
+     */
+    debug(message: string, options?: ConsoleOutputOptions): void;
+    debug(...args: unknown[]): void;
+    /**
+     * 信息输出
+     */
+    info(message: string, options?: ConsoleOutputOptions): void;
+    info(...args: unknown[]): void;
+    /**
+     * 消息流，供 UI 组件订阅
+     */
+    readonly messageSubject: Subject<ConsoleMessage>;
+    /**
+     * 接管全局 console
+     */
+    interceptGlobalConsole(params: GlobalConsoleOptions): void;
+    /**
+     * 恢复全局 console
+     */
+    restoreGlobalConsole(): void;
+    /**
+     * 暂停 console 输出
+     * 暂停后所有 console 消息将被静默丢弃
+     */
+    pause(): void;
+    /**
+     * 恢复 console 输出
+     * 恢复后 console 消息将正常打印
+     */
+    resume(): void;
+    /**
+     * 检查当前是否处于暂停状态
+     */
+    isPaused(): boolean;
+}

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

@@ -0,0 +1,2 @@
+export * from './console-protocol';
+export * from './console-manager';

package/cli/dist-server/types/node/context/deferred-tools-description-builder.d.ts

@@ -0,0 +1,145 @@
+import { Logger } from '@celljs/core';
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import { AgentScopedMcpManager, McpConfigManager, McpManager, McpToggleManager } from '../mcp/mcp-protocol';
+import { DeferToolConfigService } from '../tools/defer-tool-config-protocol';
+import { ToolSearchService } from '../tools/tool-search-protocol';
+import { ToolDeferOverlay } from '../tools/tool-spec';
+export declare const DeferredToolsDescriptionBuilder: unique symbol;
+/**
+ * Options for building deferred tools description.
+ */
+export interface DeferredToolsDescriptionBuildOptions {
+    /** Explicit session-view input; omit when building a process-wide cached description. */
+    session?: Session;
+    /**
+     * Filter by agent's tool names. Only show deferred tools that are in this list.
+     * MCP tools (starting with "mcp__") are always included regardless of this filter.
+     */
+    agentToolNames?: string[];
+    /**
+     * 会话级 defer overlay 的 snapshot。命中 `forceNoDefer` 的工具从描述中剔除
+     * （它们已通过 NoDefer 直接进入 LLM 工具列表，无需再经 ToolSearch 发现）。
+     * 命中 `forceDefer` 的工具会被一并展示——前提是调用方在调用 build 之前已经
+     * 预热过这些工具的索引（详见 tool-manager 的 ToolSearch description 渲染处）。
+     */
+    overlay?: import('../tools/tool-spec/index.js').ToolDeferOverlaySnapshot | ToolDeferOverlay;
+    /**
+     * 会话级 `--tools` 白名单（已剥离 Defer/NoDefer 修饰的纯名）。提供后会**叠加**
+     * 在 agentToolNames 之上做交集过滤——即工具必须同时出现在 agent 的 tools
+     * 配置和 session 白名单里才会展示。MCP 工具不受此过滤约束（与 agentToolNames 同）。
+     *
+     * 当用户写 `--tools "Bash,Read,Defer(Edit)"` 时，session 白名单是
+     * `["Bash","Read","Edit","ToolSearch","DeferExecuteTool"]`（含自动附加），
+     * 描述里只会列出实际可达的延迟工具，避免噪音。
+     */
+    sessionToolNames?: string[];
+}
+/**
+ * Result of building deferred tools description.
+ */
+export interface DeferredToolsDescriptionResult {
+    /** Formatted deferred tools list (includes both builtin and MCP tools, grouped by server) */
+    toolSearchDeferredTools?: string;
+    /** Total count of deferred tools */
+    toolSearchDeferredToolsCount?: number;
+    /** Info about omitted tools/servers due to char budget (for template rendering) */
+    toolSearchOmittedInfo?: string;
+}
+/**
+ * Service for building deferred tools description for ToolSearch.
+ *
+ * Display strategy:
+ * - Builtin tools: show `name: summary` format (small count, descriptions aid LLM understanding)
+ * - MCP tools with mcp__ prefix: grouped by server with server description in group header, tool names only within group
+ * - Bare-name MCP tools: rendered in the builtin-style section because their public name has no server prefix
+ * - Character budget controls total output size; servers are dropped as whole groups when budget exceeded
+ * - The prompt template wraps the returned text in XML tags; this builder returns only the inner list
+ */
+export interface DeferredToolsDescriptionBuilder {
+    build(options?: DeferredToolsDescriptionBuildOptions): Promise<DeferredToolsDescriptionResult>;
+}
+export declare class DeferredToolsDescriptionBuilderImpl implements DeferredToolsDescriptionBuilder {
+    protected readonly toolSearchService: ToolSearchService;
+    protected readonly deferToolConfigService: DeferToolConfigService;
+    protected readonly mcpConfigManager: McpConfigManager;
+    protected readonly mcpToggleManager: McpToggleManager;
+    protected readonly logger: Logger;
+    protected readonly mcpManager: McpManager;
+    protected readonly agentScopedMcpManager: AgentScopedMcpManager;
+    build(options?: DeferredToolsDescriptionBuildOptions): Promise<DeferredToolsDescriptionResult>;
+    /**
+     * Get character budget from env var or default.
+     */
+    private getCharBudget;
+    /**
+     * Group tools by server name.
+     */
+    private groupToolsByServer;
+    /**
+     * Build structured server groups, separating builtin-style tools from mcp__-prefixed MCP groups.
+     * Bare-name MCP tools are intentionally kept in the builtin-style section.
+     * Also includes MCP servers that have no indexed tools yet (configured but not connected).
+     */
+    private buildServerGroups;
+    /**
+     * Format tool list with character budget enforcement.
+     *
+     * Strategy:
+     * 1. Always include all builtin tools (small count, high value)
+     * 2. Add MCP server groups one by one until budget exceeded
+     * 3. Remaining servers are omitted with a summary line
+     */
+    private formatWithBudget;
+    /**
+     * Format builtin tools section. Each tool gets `name: summary` format.
+     */
+    private formatBuiltinTools;
+    /**
+     * Format a single MCP server group.
+     * Group header: `mcp__serverName: <truncated description>`
+     * Group body: one tool name per line
+     */
+    private formatServerGroup;
+    /**
+     * Truncate a description to maxChars, adding "…" if truncated.
+     */
+    private truncateDescription;
+    /**
+     * Extract server name from MCP tool name.
+     * Format: mcp__serverName__toolName
+     */
+    private extractServerName;
+    /**
+     * Collect MCP server names and descriptions from configuration.
+     * These are available synchronously from config, independent of async server connections.
+     */
+    private collectMcpServerInfos;
+    /**
+     * Snapshot MCP servers whose projected connection has not settled.
+     *
+     * Aligned with `WaitForMcpServersTool.isEnabled()`: that tool is exposed
+     * iff at least one server is PENDING/CONNECTING. We use the same source of truth
+     * (`McpManager.list()`) so the hint and the
+     * tool come and go together.
+     *
+     * Errors swallowed: better to render no hint than to fail description build.
+     */
+    private collectConnectingServerNames;
+    /**
+     * Snapshot MCP servers currently CONNECTED, used by #90171 to hide the
+     * misleading empty group of a connected-but-zero-indexed server (all its
+     * tools are defer_loading:false direct and never enter the deferred index).
+     * Errors swallowed: better to render the legacy empty group than to fail
+     * description build.
+     */
+    private collectConnectedServerNames;
+    private isWaitForMcpServersEnabled;
+    /**
+     * 求两个工具白名单约束的交集。任一为 undefined 则返回另一个（"未提供该约束" 等价于 "全通过"）。
+     * 两者都提供时返回交集；都未提供时返回 undefined。
+     *
+     * 该函数面向 `ToolSearchService.getDeferredToolsSummary` 的 `filterByAgentTools`
+     * 参数——它只对**内置工具**生效，MCP 工具不受过滤约束（service 内部已实现）。
+     */
+    private intersectFilterSets;
+}

package/cli/dist-server/types/node/context/token-calculator/token-calculator-protocol.d.ts

@@ -0,0 +1,27 @@
+import { AgentInputItem } from '../../../vendor/cbc-shared/node/index.js';
+export declare const TokenCalculator: unique symbol;
+/**
+ * Token 计算器接口
+ */
+export interface TokenCalculator {
+    /**
+     * 估算AgentInputItem数组的token数量
+     * @param items 输入项数组
+     * @returns 估算的token数量
+     */
+    estimateTokens(items: AgentInputItem[]): number;
+    /**
+     * 估算单个AgentInputItem的token数量
+     * @param item 输入项
+     * @returns 估算的token数量
+     */
+    estimateItemTokens(item: AgentInputItem): number;
+    /**
+     * 检查是否超过token限制
+     * @param items 输入项数组
+     * @param maxTokens 最大token限制
+     * @param safeMargin 安全边界系数
+     * @returns 是否超限
+     */
+    isOverLimit(items: AgentInputItem[], maxTokens: number, safeMargin: number): boolean;
+}