/**
 * mcpProxyTool —— 借鉴 pi-mcp-adapter 的「单 mcp 代理工具」编排器(core,env 无关)。
 *
 * 取代此前「eager 把所有 MCP server 连上 + listTools 拍平成 N 个 AgentTool」的展开方式:
 * 只向 LLM 暴露**一个** `mcp` 代理工具(~200 tokens),由模型按需
 * status / connect / list / search / describe / call 发现并调用 MCP 工具。收益:
 * - 不再把 N 个工具 schema 灌进系统提示,省上下文;
 * - server **懒连接**:run 开始不连,首次代理调用才连;单 server 连接失败被隔离记录,
 *   不再像旧 `Promise.all` 那样一损俱错击穿整轮 runAgentLoop;
 * - run 内内存缓存 listTools 结果(本 runtime 每次 run 独立、无磁盘缓存)。
 *
 * 工具透出收敛(allowedTools):消费 {@link IMcpServerSpec}[](由
 * {@link aggregateMcpServers} 把协议级 IMcpResource + IMcpToolResource 按 serverName 聚合
 * 而来)。connect 时取 `server.listTools()` 全量结果,再按 `spec.allowedTools` 过滤——
 * **在 listTool 层就不透出未声明 tool**(executeList/executeSearch/executeDescribe/
 * executeCall/resolve 全读这份已过滤的 `entry.tools`),非 callTool 拦截。allowedTools
 * 为 undefined 表示该 server 无 tool 级声明,全放行(等价旧行为)。
 *
 * 同时实现 {@link IMcpToolRegistry}:卡片 resolver 经 `resolve(resourceId, toolName)`
 * 取得 MCP 工具句柄(可能触发该 server 懒连接),而非吃预先展开的描述符数组。resourceId
 * 经 `specByResourceId` 反查到所属 spec(同 serverName 多 resourceId 已聚合为一个连接)。
 *
 * 不在范围(相对 pi-mcp-adapter):OAuth/auth flow、elicitation、UI panel、sampling、
 * 磁盘元数据缓存、npx/stdio、regex 安全检查、output guard、directTools 配置开关。
 * linkque 的 MCP server 始终经 `IMcpServerProvider`(远端 SSE 网关)连接。
 */
import type { IAgentToolDescriptor, IMcpServerProvider, IMcpToolHandle, IMcpToolRegistry } from './ports.js';
import type { IMcpServerSpec } from './mcpAggregator.js';
/** 代理工具暴露给 LLM 的稳定名。 */
export declare const MCP_PROXY_TOOL_NAME = "mcp";
/** 构造选项。 */
export interface IMcpProxyToolOptions {
    /** 诊断日志下沉点(透传自 runAgentLoop 的 debugLog);缺省不写。 */
    debugLog?: (line: string) => void;
}
/**
 * McpProxyTool —— 组合 {@link IMcpServerProvider} + {@link IMcpServerSpec}[],产出单个
 * `mcp` 代理工具,并作为 {@link IMcpToolRegistry} 供卡片 resolver 消费。
 */
export declare class McpProxyTool implements IMcpToolRegistry {
    private readonly provider;
    /** serverName → 缓存条目(同 serverName 多 resourceId 聚合为一个连接)。 */
    private readonly entries;
    /** 进行中的连接(去重并发 ensureEntry)。 */
    private readonly inFlight;
    private readonly specByServerName;
    /** 原始 resourceId → 所属 spec(resolve(resourceId,...) 反查用)。 */
    private readonly specByResourceId;
    private readonly specs;
    private readonly debugLog;
    constructor(provider: IMcpServerProvider, specs: IMcpServerSpec[], options?: IMcpProxyToolOptions);
    /**
     * 产单个 `mcp` 代理工具描述符,注入 `agentReq.tools`。
     * `execute` 闭包按入参字段派发到 status/connect/list/search/describe/call。
     */
    asTool(): IAgentToolDescriptor;
    /** {@link IMcpToolRegistry.resolve}:按 (resourceId, toolName) 解析可调用句柄。 */
    resolve(resourceId: string, toolName: string, signal?: AbortSignal): Promise<IMcpToolHandle | undefined>;
    /** 关闭所有已连 server(忽略单 server 关闭错误)。 */
    closeAll(): Promise<void>;
    /** 确保某 server 已连;返回 connected 条目,依失败返回 null(不抛错)。 */
    private ensureEntry;
    /** 连单个 server 并 listTools;按 spec.allowedTools 过滤后缓存;失败记为 failed。 */
    private connect;
    /** 按入参字段派发;返回 LLM 可读文本。 */
    private dispatch;
    /** `mcp({})` / `mcp({ status: true })`:列各 server 连接状态 + 工具数。 */
    private executeStatus;
    /** `mcp({ connect: "server" })`:显式连接并刷元数据,返回该 server 工具列表。 */
    private executeConnect;
    /** `mcp({ server: "name" })`:列该 server 工具名 + 截断 description。 */
    private executeList;
    /** `mcp({ search: "query" })`:空格分词 OR 子串匹配 name/description(跨所有 server)。 */
    private executeSearch;
    /** `mcp({ describe: "tool" })`:输出工具所属 server + 参数 schema。 */
    private executeDescribe;
    /** `mcp({ tool: "name", args: {...} })`:调用工具,返回序列化结果。 */
    private executeCall;
    /** 跨(或按 hint)已连 server 查找工具;未连则触发懒连接。 */
    private findTool;
    /** 按 serverName 或原始 resourceId 找 spec(server 入参可为二者)。 */
    private findSpec;
    /** serverHint(serverName 或 resourceId)命中的 spec 子集。 */
    private specsMatching;
    /** 格式化某 server 的工具列表。 */
    private formatToolList;
}
/**
 * 解析代理工具入参为派发用的字段对象;非对象/空对象 → 空对象(status 派发)。
 * 仅提取已知字段,忽略其余(对齐 additionalProperties:false 的语义)。
 */
export declare function parseProxyArgs(args: unknown): {
    connect?: string;
    describe?: string;
    search?: string;
    tool?: string;
    server?: string;
    args?: unknown;
};
/** 极简 JSON schema → 参数清单文本(不引外部依赖)。 */
export declare function formatSchema(schema: unknown, indent?: string): string;
/** 序列化工具调用结果为 LLM 可读文本。 */
export declare function serializeToolResult(value: unknown): string;