import { type ToolSet } from "ai";
import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
import type { JsonObject } from "#shared/json.js";
/**
 * The provider backend resolved for one web search tool invocation.
 */
export type WebSearchBackend = "anthropic" | "gateway" | "google" | "openai";
/**
 * Returns the framework tool name that produced an upstream provider tool
 * `type`, or `null` when the type is not one we know how to remove.
 *
 * Used by the harness recovery path to decide which tools to drop when a
 * gateway fallback provider rejects a tool. Unknown types fall through to
 * the existing terminal/recoverable handling.
 */
export declare function resolveFrameworkToolFromUpstreamType(type: string): string | null;
/**
 * Maps a {@link WebSearchBackend} to the gateway provider slug used in
 * `providerOptions.gateway.only` to pin routing to that provider.
 *
 * Returns `null` for the `"gateway"` backend (Perplexity via AI Gateway),
 * which is served by the gateway directly and does not need pinning.
 */
export declare function resolveGatewayPinForWebSearchBackend(backend: WebSearchBackend): string | null;
/**
 * Returns the output schema for the provider-managed web search tool that
 * will be injected for `backend`.
 */
export declare function resolveWebSearchOutputSchema(backend: WebSearchBackend): JsonObject;
/**
 * Returns a new `providerOptions` object with
 * `gateway.only = [provider]` merged into the existing `gateway`
 * sub-object so the AI Gateway only attempts the given provider.
 *
 * Used by the harness to pin routing when a provider-specific tool
 * (e.g. Anthropic's `web_search_20250305`) is in the per-step toolset,
 * so a transient primary outage produces a clean retryable 503 instead
 * of a fallback-to-incompatible-provider 400.
 *
 * Author overrides win — if `base.gateway.only` or `base.gateway.order`
 * is already set, the input is returned unchanged so explicit routing
 * preferences are never silently overwritten.
 */
export declare function mergeGatewayProviderPin(base: Readonly<Record<string, unknown>> | undefined, provider: string): Record<string, unknown>;
/**
 * Determines the web search backend for a model reference.
 *
 * - OpenAI models (gateway or BYO): native OpenAI search
 * - Anthropic models (gateway or BYO): native Anthropic search
 * - Direct/BYO Google models: native Google search grounding
 * - Other models on AI Gateway (including `google/...`): Perplexity search via gateway
 * - Other BYO models: not available (returns `null`)
 */
export declare function resolveWebSearchBackend(modelRef: RuntimeModelReference): WebSearchBackend | null;
/**
 * Constructs the AI SDK provider tool for web search based on the resolved
 * backend. Called once per harness step when web search is enabled.
 *
 * Dynamic imports keep unused provider SDKs out of the bundle — only the
 * provider matching the current model is loaded.
 */
export declare function resolveWebSearchProviderTool(backend: WebSearchBackend): Promise<ToolSet[string]>;