/**
 * Tool Cascade — provider-native tool augmentation layer.
 *
 * When a provider (e.g. Zhipu GLM) offers native utility APIs (web search, reader,
 * tokenizer, etc.), the tool cascade automatically routes through the provider API
 * first, falling back to the host-provided implementation (e.g. SearXNG) on failure.
 *
 * ## Architecture
 *
 * Two levels of provider tool integration:
 *
 * 1. **D-level (builtin tools)**: Injected directly into chat completion request
 *    via `builtinWebSearch` / `builtinCodeInterpreter` / `builtinUrlContext` / `builtinMapsGrounding` / `builtinFileSearch` quirks.
 *    The LLM decides to use these inline during generation — no agent intervention.
 *    → Handled by openai-chat.ts (GLM/Kimi) and gemini-generatecontent.ts (Google) transport layers.
 *
 * 2. **C-level (independent APIs)**: Discrete API endpoints the agent calls explicitly
 *    as tool steps (web_search, reader, tokenizer, moderations).
 *    → Handled by this cascade layer — wraps host-provided tool deps with
 *      provider-native backends, falling back on error.
 *
 * ## Usage
 *
 * ```ts
 * import { cascadeWebSearch } from "./tool-cascade.js";
 * const providerApi = host.resolveProviderToolApi();
 *
 * const providerApi = new ZhipuToolAPI({ baseUrl, apiKey });
 * const cascadedSearch = cascadeWebSearch(providerApi, fallbackSearchFn);
 * const tool = createWebSearchTool({ search: cascadedSearch });
 * ```
 */
import type { WebSearchBackend } from "../runtime/ports/web-search-contracts.js";
export interface ProviderToolApiPort {
    capabilities: readonly string[];
    webSearch?(query: string, options?: {
        maxResults?: number;
    }): Promise<Array<{
        title: string;
        url: string;
        snippet: string;
    }>>;
}
/**
 * Cascade web search: provider-native search → host fallback.
 * Returns a WebSearchToolDeps.search function that tries the provider's
 * webSearch API first, falling back to the host's search on error.
 */
export declare function cascadeWebSearch(providerApi: ProviderToolApiPort | undefined, fallbackSearch: WebSearchBackend["search"]): WebSearchBackend["search"];
