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

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

@@ -0,0 +1,9 @@
+import { Logger } from '@celljs/core';
+import { Context } from '@celljs/core/lib/node';
+import { ErrorHandler } from '@celljs/web/lib/node';
+export declare class CliServerErrorHandler implements ErrorHandler {
+    readonly priority: number;
+    readonly logger: Logger;
+    canHandle(ctx: Context, err: Error): Promise<boolean>;
+    handle(ctx: Context, err: Error): Promise<void>;
+}

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

@@ -0,0 +1,4 @@
+export * from './server-protocol';
+export * from './endpoint-provider';
+export * from './error-provider';
+export * from './loopback-body-limit';

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

@@ -0,0 +1,52 @@
+/**
+ * Loopback（`127.0.0.1` 上的 `/internal/*`）请求的体积边界。
+ *
+ * ## 为什么需要显式配置
+ *
+ * loopback 客户端走 celljs `RestOperationsFactory.create()` → `axios@0.26.1`
+ * （由 `@celljs/http` 钉死）。该版本 http 适配器只在 `maxBodyLength > -1` 时才
+ * 把值透传给 `follow-redirects`，**没有 else 分支**：
+ *
+ * ```js
+ * // axios@0.26.1 lib/adapters/http.js:233
+ * if (config.maxBodyLength > -1) {
+ *     options.maxBodyLength = config.maxBodyLength;
+ * }
+ * ```
+ *
+ * axios 默认 `maxBodyLength = -1`，于是什么都不透传，`follow-redirects` 退回自带默认值
+ * `10 * 1024 * 1024`（10 MiB，见 follow-redirects@1.16.0 index.js:517），超出即在本地抛
+ * `ERR_FR_MAX_BODY_LENGTH_EXCEEDED` / "Request body larger than maxBodyLength limit"——
+ * **一个字节都没发出去**。
+ *
+ * 而同一跳的服务端是刻意配成 100mb 的（`genie*.yaml` 的 `cell.web.body.limit`，
+ * 注释写明"本地 ACP 最多承载 50 MiB 图片；base64 后约 67 MiB"）。客户端那 10 MiB
+ * 从来不是有意设置的上限，纯粹是上述漏传造成的意外，且比服务端严格一个量级：
+ * 带几张截图的一轮对话（实测 18–19 MB）会在模型被调用之前就确定性失败。
+ *
+ * ## 取 Infinity 而不是某个具体数值
+ *
+ * 体积裁决点只能有一个，否则客户端和 `cell.web.body.limit` 两个数字要长期手工对齐。
+ * 客户端不再自行设限，超限一律由服务端裁决并返回真实的 HTTP 413 —— 那是一个带响应体的
+ * 正常响应，可以被归类、可以拿到可读文案，而不是本地抛出的内部传输字符串。
+ *
+ * 同款修复与原因分析另见 `node/model/model-provider.ts` 的模型请求配置。
+ */
+export declare const LOOPBACK_BODY_LIMIT_CONFIG: {
+    readonly maxBodyLength: number;
+    readonly maxContentLength: number;
+};
+/**
+ * 把"请求体超限"翻译成用户可行动的文案。
+ *
+ * 覆盖两种形态：
+ *   1. 客户端本地拒收（`ERR_FR_MAX_BODY_LENGTH_EXCEEDED`）——修掉
+ *      {@link LOOPBACK_BODY_LIMIT_CONFIG} 未覆盖的路径时的兜底；
+ *   2. 服务端按 `cell.web.body.limit` 拒收，返回 HTTP 413。
+ *
+ * 刻意不在文案里写死具体上限：上限由 `genie*.yaml` 单点定义，复述一份就要长期手工对齐。
+ * 只报实际体积 + 该怎么办。
+ *
+ * @returns 命中时返回可展示文案；不是体积问题则返回 `undefined`，交回原有错误处理。
+ */
+export declare function describeOversizedPayloadError(error: unknown): string | undefined;

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

@@ -0,0 +1,6 @@
+/**
+ * LSP 模块导出
+ */
+export * from './lsp-protocol';
+export * from './lsp-client';
+export * from './lsp-manager';

package/cli/dist-server/types/node/lsp/lsp-client.d.ts

@@ -0,0 +1,104 @@
+/**
+ * LSP 客户端实现
+ * 使用 vscode-languageserver-protocol 和 vscode-jsonrpc 与 LSP 服务器通信
+ */
+import { Workspace } from '../../workspace/runtime/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { LspServerConfig } from '../../workspace/cbc-plugins/lib/node/index.js';
+import { LSPCallHierarchyIncomingCall, LSPCallHierarchyItem, LSPCallHierarchyOutgoingCall, LSPClient as ILSPClient, LSPDocumentSymbol, LSPHover, LSPLocation, LSPPosition, LSPSymbolInformation } from './lsp-protocol';
+export declare class LSPClientImpl implements ILSPClient {
+    protected readonly workspace: Workspace;
+    protected readonly logger: Logger;
+    private config;
+    private languageId;
+    private workspaceRoot;
+    private process?;
+    private connection?;
+    private isInitialized;
+    private openedDocuments;
+    init(config: LspServerConfig, languageId: string): void;
+    /**
+     * 初始化 LSP 客户端并启动服务器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 启动 stdio 传输方式的 LSP 服务器
+     */
+    private startServerStdio;
+    /**
+     * 设置消息处理器 - 处理服务器发起的请求和通知
+     */
+    private setupMessageHandlers;
+    /**
+     * 发送 initialize 请求
+     */
+    private sendInitializeRequest;
+    /**
+     * 确保文档已打开
+     */
+    private ensureDocumentOpened;
+    /**
+     * 转换 LSP Position (0-based) 为内部 Position
+     */
+    private toLSPPosition;
+    /**
+     * 跳转到定义
+     */
+    goToDefinition(uri: string, position: LSPPosition): Promise<LSPLocation[]>;
+    /**
+     * 查找引用
+     */
+    findReferences(uri: string, position: LSPPosition): Promise<LSPLocation[]>;
+    /**
+     * 获取 hover 信息
+     */
+    hover(uri: string, position: LSPPosition): Promise<LSPHover | null>;
+    /**
+     * 获取文档符号
+     */
+    documentSymbol(uri: string): Promise<LSPSymbolInformation[] | LSPDocumentSymbol[]>;
+    /**
+     * 工作区符号搜索
+     */
+    workspaceSymbol(query: string): Promise<LSPSymbolInformation[]>;
+    /**
+     * 跳转到实现
+     */
+    goToImplementation(uri: string, position: LSPPosition): Promise<LSPLocation[]>;
+    /**
+     * 准备调用层次结构
+     */
+    prepareCallHierarchy(uri: string, position: LSPPosition): Promise<LSPCallHierarchyItem[]>;
+    /**
+     * 获取入站调用
+     */
+    incomingCalls(item: LSPCallHierarchyItem): Promise<LSPCallHierarchyIncomingCall[]>;
+    /**
+     * 获取出站调用
+     */
+    outgoingCalls(item: LSPCallHierarchyItem): Promise<LSPCallHierarchyOutgoingCall[]>;
+    /**
+     * 跳转到类型定义
+     */
+    goToTypeDefinition(uri: string, position: LSPPosition): Promise<LSPLocation[]>;
+    /**
+     * 获取代码补全
+     */
+    completion(uri: string, position: LSPPosition): Promise<any[]>;
+    /**
+     * 规范化位置信息
+     */
+    private normalizeLocations;
+    /**
+     * 检查服务器是否正在运行
+     */
+    isRunning(): boolean;
+    /**
+     * 关闭 LSP 服务器
+     */
+    shutdown(): Promise<void>;
+    /**
+     * 清理资源
+     */
+    private cleanup;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * LSP 服务器管理器
+ * 负责 LSP 服务器的注册、启动、管理和关闭
+ */
+import { type LspServerConfig, PluginManager } from '../../workspace/cbc-plugins/lib/node/index.js';
+import { Workspace } from '../../workspace/runtime/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { LSPClient as ILSPClient, LSPManager as ILSPManager, LSPServerInstance } from './lsp-protocol';
+export declare class LSPManagerImpl implements ILSPManager {
+    protected readonly logger: Logger;
+    protected readonly workspace: Workspace;
+    protected readonly pluginManager: PluginManager;
+    /** 语言 ID 到服务器配置的映射 */
+    private languageConfigs;
+    /** 是否已加载插件的 LSP 配置 */
+    private hasLoadedPlugins;
+    /** 文件扩展名到语言 ID 的映射 */
+    private extensionToLanguage;
+    /** 正在启动的服务器Promise，用于防止并发启动同一服务器 */
+    private startingServers;
+    /** Serialize explicit plugin reloads so teardown and rebuild cannot overlap. */
+    private reloadPluginServersTail;
+    /** exit 清理钩子仅在首个 LSP 子进程真实启动时注册（见 startServerSafe）。 */
+    private exitHookRegistered;
+    protected init(): void;
+    private ensureExitHook;
+    /**
+     * 确保已加载所有插件的 LSP 配置
+     */
+    private ensurePluginsLoaded;
+    /**
+     * 注册 LSP 服务器配置
+     */
+    registerServers(lspConfigs: Record<string, LspServerConfig>, pluginName: string, marketplaceName: string): void;
+    /**
+     * 验证配置
+     */
+    private validateConfig;
+    /**
+     * 根据文件路径获取对应的 LSP 客户端
+     */
+    getClientForFile(filePath: string): Promise<ILSPClient | null>;
+    /**
+     * 后台启动服务器（不等待结果，用于注册时立即启动）
+     */
+    private startServerInBackground;
+    /**
+     * 安全启动服务器（确保单例，防止并发启动）
+     */
+    private startServerSafe;
+    /**
+     * 启动服务器
+     */
+    private startServer;
+    /**
+     * 检查是否应该重启
+     */
+    private shouldRestart;
+    /**
+     * 安排重启
+     */
+    private scheduleRestart;
+    /**
+     * 获取所有已注册的语言 ID
+     */
+    getRegisteredLanguages(): string[];
+    /**
+     * 关闭所有 LSP 服务器
+     */
+    shutdownAll(): Promise<void>;
+    reloadPluginServers(): Promise<void>;
+    private drainStartingServers;
+    /**
+     * 同步关闭所有服务器(用于进程退出时)
+     */
+    private shutdownAllSync;
+    /**
+     * 获取服务器实例信息(用于调试)
+     */
+    getServerInstance(languageId: string): LSPServerInstance | undefined;
+    /**
+     * 预热指定语言的 LSP 服务器（可选，用于提前启动常用语言）
+     * @param languageIds 要预热的语言 ID 列表，为空则预热所有已注册语言
+     */
+    warmup(languageIds?: string[]): Promise<void>;
+    /**
+     * 检查指定语言的 LSP 服务器是否已启动
+     */
+    isServerRunning(languageId: string): boolean;
+}

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

@@ -0,0 +1,245 @@
+/**
+ * LSP 协议类型和接口定义
+ */
+import type { LspServerConfig } from '../../workspace/cbc-plugins/lib/node/index.js';
+/**
+ * LSP 服务器状态
+ */
+export declare enum LSPServerStatus {
+    /** 未启动 */
+    Stopped = "stopped",
+    /** 启动中 */
+    Starting = "starting",
+    /** 运行中 */
+    Running = "running",
+    /** 已崩溃 */
+    Crashed = "crashed",
+    /** 不可用 */
+    Unavailable = "unavailable"
+}
+/**
+ * LSP 服务器实例信息
+ */
+export interface LSPServerInstance {
+    /** 语言 ID */
+    languageId: string;
+    /** 服务器配置 */
+    config: LspServerConfig;
+    /** 服务器状态 */
+    status: LSPServerStatus;
+    /** 客户端实例 */
+    client?: LSPClient;
+    /** 重启次数 */
+    restartCount: number;
+    /** 插件名称 */
+    pluginName: string;
+    /** 市场名称 */
+    marketplaceName: string;
+}
+/**
+ * LSP 位置信息 (0-based)
+ */
+export interface LSPPosition {
+    line: number;
+    character: number;
+}
+/**
+ * LSP 范围信息
+ */
+export interface LSPRange {
+    start: LSPPosition;
+    end: LSPPosition;
+}
+/**
+ * LSP 位置链接
+ */
+export interface LSPLocation {
+    uri: string;
+    range: LSPRange;
+}
+/**
+ * LSP 符号类型
+ */
+export declare enum LSPSymbolKind {
+    File = 1,
+    Module = 2,
+    Namespace = 3,
+    Package = 4,
+    Class = 5,
+    Method = 6,
+    Property = 7,
+    Field = 8,
+    Constructor = 9,
+    Enum = 10,
+    Interface = 11,
+    Function = 12,
+    Variable = 13,
+    Constant = 14,
+    String = 15,
+    Number = 16,
+    Boolean = 17,
+    Array = 18,
+    Object = 19,
+    Key = 20,
+    Null = 21,
+    EnumMember = 22,
+    Struct = 23,
+    Event = 24,
+    Operator = 25,
+    TypeParameter = 26
+}
+/**
+ * LSP 符号信息
+ */
+export interface LSPSymbolInformation {
+    name: string;
+    kind: LSPSymbolKind;
+    location: LSPLocation;
+    containerName?: string;
+}
+/**
+ * LSP 文档符号
+ */
+export interface LSPDocumentSymbol {
+    name: string;
+    kind: LSPSymbolKind;
+    range: LSPRange;
+    selectionRange: LSPRange;
+    detail?: string;
+    children?: LSPDocumentSymbol[];
+}
+/**
+ * LSP Hover 信息
+ */
+export interface LSPHover {
+    contents: string | {
+        language: string;
+        value: string;
+    };
+    range?: LSPRange;
+}
+/**
+ * LSP 调用层次结构项
+ */
+export interface LSPCallHierarchyItem {
+    name: string;
+    kind: LSPSymbolKind;
+    uri: string;
+    range: LSPRange;
+    selectionRange: LSPRange;
+    detail?: string;
+}
+/**
+ * LSP 调用层次结构入站调用
+ */
+export interface LSPCallHierarchyIncomingCall {
+    from: LSPCallHierarchyItem;
+    fromRanges: LSPRange[];
+}
+/**
+ * LSP 调用层次结构出站调用
+ */
+export interface LSPCallHierarchyOutgoingCall {
+    to: LSPCallHierarchyItem;
+    fromRanges: LSPRange[];
+}
+/**
+ * LSP 客户端接口
+ */
+export declare const LSPClient: unique symbol;
+export interface LSPClient {
+    init(config: LspServerConfig, languageId: string): void;
+    /**
+     * 初始化 LSP 客户端并启动服务器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 关闭 LSP 服务器
+     */
+    shutdown(): Promise<void>;
+    /**
+     * 跳转到定义
+     */
+    goToDefinition(uri: string, position: LSPPosition): Promise<LSPLocation[]>;
+    /**
+     * 查找引用
+     */
+    findReferences(uri: string, position: LSPPosition): Promise<LSPLocation[]>;
+    /**
+     * 获取 hover 信息
+     */
+    hover(uri: string, position: LSPPosition): Promise<LSPHover | null>;
+    /**
+     * 获取文档符号
+     */
+    documentSymbol(uri: string): Promise<LSPSymbolInformation[] | LSPDocumentSymbol[]>;
+    /**
+     * 工作区符号搜索
+     */
+    workspaceSymbol(query: string): Promise<LSPSymbolInformation[]>;
+    /**
+     * 跳转到实现
+     */
+    goToImplementation(uri: string, position: LSPPosition): Promise<LSPLocation[]>;
+    /**
+     * 跳转到类型定义
+     */
+    goToTypeDefinition(uri: string, position: LSPPosition): Promise<LSPLocation[]>;
+    /**
+     * 获取代码补全
+     */
+    completion(uri: string, position: LSPPosition): Promise<any[]>;
+    /**
+     * 准备调用层次结构
+     */
+    prepareCallHierarchy(uri: string, position: LSPPosition): Promise<LSPCallHierarchyItem[]>;
+    /**
+     * 获取入站调用
+     */
+    incomingCalls(item: LSPCallHierarchyItem): Promise<LSPCallHierarchyIncomingCall[]>;
+    /**
+     * 获取出站调用
+     */
+    outgoingCalls(item: LSPCallHierarchyItem): Promise<LSPCallHierarchyOutgoingCall[]>;
+    /**
+     * 检查服务器是否正在运行
+     */
+    isRunning(): boolean;
+}
+/**
+ * LSP Manager 接口
+ */
+export declare const LSPManager: unique symbol;
+export interface LSPManager {
+    /**
+     * 注册 LSP 服务器配置
+     */
+    registerServers(lspConfigs: Record<string, LspServerConfig>, pluginName: string, marketplaceName: string): void;
+    /**
+     * 根据文件路径获取对应的 LSP 客户端
+     */
+    getClientForFile(filePath: string): Promise<LSPClient | null>;
+    /**
+     * 获取所有已注册的语言 ID
+     */
+    getRegisteredLanguages(): string[];
+    /**
+     * 关闭所有 LSP 服务器
+     */
+    shutdownAll(): Promise<void>;
+    /** Replace plugin-provided LSP registrations from the current active snapshot. */
+    reloadPluginServers?(): Promise<void>;
+    /**
+     * 获取服务器实例信息(用于调试)
+     */
+    getServerInstance(languageId: string): LSPServerInstance | undefined;
+    /**
+     * 预热指定语言的 LSP 服务器（可选，用于提前启动常用语言）
+     * @param languageIds 要预热的语言 ID 列表，为空则预热所有已注册语言
+     */
+    warmup(languageIds?: string[]): Promise<void>;
+    /**
+     * 检查指定语言的 LSP 服务器是否已启动
+     */
+    isServerRunning(languageId: string): boolean;
+}

package/cli/dist-server/types/node/mcp/agent-scoped-mcp-manager.d.ts

@@ -0,0 +1,38 @@
+import { Logger } from '@celljs/core';
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { AgentMcpServerSpec } from '../../workspace/product/lib/common/index.js';
+import { SettingsManager } from '../settings';
+import { AgentScopedMcpManager, McpConfig, McpManager, MCPServer, McpServerManager } from './mcp-protocol';
+export declare class AgentScopedMcpManagerImpl implements AgentScopedMcpManager {
+    /**
+     * Do not route these configs through McpConfigManager/McpManager. Those are
+     * process-global registries; using them would make a subagent's inline MCP
+     * visible to the parent and sibling agents.
+     */
+    protected readonly mcpManager: McpManager;
+    protected readonly mcpServerManager: McpServerManager;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly logger: Logger;
+    private readonly states;
+    private readonly toolsChanged;
+    readonly onDidChangeTools: import("@celljs/core").Event<void>;
+    private isProjectInlineAllowed;
+    setupForSubAgent(input: {
+        session: Session;
+        agentName: string;
+        agentSource?: string;
+        isFlagSettingsAgent?: boolean;
+        specs: AgentMcpServerSpec[];
+        strictMcpConfig?: boolean;
+    }): Promise<void>;
+    getServers(sessionId: string): MCPServer[];
+    getInlineServers(sessionId: string): Array<{
+        server: MCPServer;
+        config: McpConfig;
+    }>;
+    getMergedServers(session: Session | undefined, globalServers: MCPServer[]): MCPServer[];
+    cleanup(sessionId: string): Promise<void>;
+    private readInlineSpec;
+    private hasBareNameConfig;
+    private normalizeConfig;
+}

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

@@ -0,0 +1,32 @@
+export * from './mcp-protocol';
+export * from './mcp-manager';
+export * from './mcp-config-manager';
+export * from './mcp-config-store';
+export * from './mcp-connection-manager';
+export * from './mcp-controller';
+export * from './mcp-validate-middleware';
+export * from './mcp-server-manager';
+export * from './mcp-oauth-manager';
+export * from './mcp-oauth-store';
+export * from './mcp-oauth-controller';
+export * from './mcp-oauth-store';
+export * from './mcp-permissions-manager';
+export * from './mcp-toggle-manager';
+export * from './mcp-log-service';
+export * from './mcp-transport-manager';
+export * from './mcp-server-model-manager';
+export * from './node-websocket-transport';
+export * from './mcp-subagent-tool-manager';
+export * from './agent-scoped-mcp-manager';
+export * from './sdk-mcp-transport';
+export * from './sdk-mcp-server';
+export * from './mcp-ready-service';
+export * from './mcp-cli-config-initializer';
+export * from './mcp-config-env-expand-service';
+export * from './mcp-config-diagnostics-manager';
+export * from './mcp-first-run-status-protocol';
+export * from './mcp-first-run-status-service';
+export * from './mcp-plugin-registry';
+export * from './official-mcp-egress-policy';
+export * from './mcp-resource-catalog-protocol';
+export * from './mcp-resource-catalog';

package/cli/dist-server/types/node/mcp/mcp-cli-config-initializer.d.ts

@@ -0,0 +1,18 @@
+import { McpCliConfigInitializer, McpManager } from './mcp-protocol';
+/**
+ * 从命令行参数初始化 MCP 配置
+ *
+ * 专门处理 --mcp-config 参数，在 SDK 模式下 middleware 未执行时提供初始化。
+ */
+export declare class McpCliConfigInitializerImpl implements McpCliConfigInitializer {
+    protected readonly mcpManager: McpManager;
+    private initialized;
+    initialize(): void;
+    /**
+     * Initialize DYNAMIC scope from --mcp-config command line args.
+     *
+     * Supports both JSON/JSONC strings and file paths, consistent with
+     * McpValidateMiddleWare.processMcpConfig.
+     */
+    private initDynamicConfigFromArgs;
+}

package/cli/dist-server/types/node/mcp/mcp-config-diagnostics-manager.d.ts

@@ -0,0 +1,29 @@
+import { Subject } from 'rxjs';
+import { McpConfigDiagnostic, McpConfigDiagnosticSeverity, McpConfigDiagnosticsManager, McpScope } from './mcp-protocol';
+/**
+ * Implementation of McpConfigDiagnosticsManager.
+ *
+ * Passively collects diagnostics for MCP server configurations.
+ * This service is independent of other MCP services to avoid circular dependencies.
+ */
+export declare class McpConfigDiagnosticsManagerImpl implements McpConfigDiagnosticsManager {
+    readonly changedSubject: Subject<McpConfigDiagnostic[]>;
+    /**
+     * Internal storage: array of all diagnostics
+     */
+    private diagnostics;
+    addDiagnostic(diagnostic: McpConfigDiagnostic): void;
+    addDiagnostics(diagnostics: McpConfigDiagnostic[]): void;
+    getDiagnostics(): McpConfigDiagnostic[];
+    getDiagnosticsForServer(serverName: string): McpConfigDiagnostic[];
+    getDiagnosticsForServerScope(serverName: string, scope: McpScope): McpConfigDiagnostic[];
+    getDiagnosticCount(severity?: McpConfigDiagnosticSeverity): number;
+    hasDiagnostics(severity?: McpConfigDiagnosticSeverity): boolean;
+    clearDiagnostics(): void;
+    clearServerDiagnostics(serverName: string): void;
+    clearServerScopeDiagnostics(serverName: string, scope: McpScope): void;
+    /**
+     * Check if a diagnostic is a duplicate (same serverName + scope + category + message)
+     */
+    private isDuplicate;
+}

package/cli/dist-server/types/node/mcp/mcp-config-env-expand-service.d.ts

@@ -0,0 +1,45 @@
+import { Logger } from '@celljs/core';
+import { McpConfig, McpConfigEnvExpandOptions, McpConfigEnvExpandResult, McpConfigEnvExpandService, McpScope } from './mcp-protocol';
+/**
+ * Service for expanding environment variables in MCP configurations.
+ *
+ * Handles `${VAR_NAME}` and `${VAR_NAME:-default}` placeholders in:
+ * - McpConfigStdio: `command`, `args[]`, `env` values
+ * - McpConfigSSE/HTTP/Remote: `url`, `headers` values
+ *
+ * Variables with default values (e.g., `${VAR:-default}`) always succeed.
+ * Missing variables without defaults are preserved as-is and reported as diagnostics.
+ *
+ * @example
+ * // Variables with defaults always succeed:
+ * "${API_URL:-https://api.example.com}" → uses default if API_URL is not set
+ *
+ * // Variables without defaults report warnings:
+ * "${API_KEY}" → reported as missing if API_KEY is not set
+ */
+export declare class McpConfigEnvExpandServiceImpl implements McpConfigEnvExpandService {
+    protected readonly logger: Logger;
+    expandConfig(name: string, config: McpConfig, scope: McpScope, options?: McpConfigEnvExpandOptions): McpConfigEnvExpandResult;
+    /**
+     * 脱敏诊断日志：汇总 URL 类 config 里原始含 `${VAR}` 占位符的 header / url，
+     * 打出插值后的**状态**而非明文。
+     *
+     * 每个 header 状态取值：
+     * - `missing` —— 解析后仍是 `${...}` 占位符（env 未注入，会导致指纹与"注入后"不一致）
+     * - `empty`   —— 解析成空串
+     * - `<前4字符>…(len=N)` —— 成功解析（脱敏预览，绝不打完整值）
+     *
+     * 只有当原始 url/headers 里出现过 `${` 时才打日志（避免无插值 config 刷屏）。
+     */
+    private logEnvExpansion;
+    /**
+     * Expand environment variables in a stdio config.
+     * Returns a new config object, does not modify the original.
+     */
+    private expandStdioConfig;
+    /**
+     * Expand environment variables in a URL-based config (SSE, HTTP, Remote).
+     * Returns a new config object, does not modify the original.
+     */
+    private expandUrlConfig;
+}