@omnicross/core 0.1.0

package/dist/index-DXazdTzZ.d.cts

@@ -0,0 +1,645 @@
+import { MessageBlock } from '@omnicross/contracts/message-blocks';
+import { SimpleChatMessage, ThinkLevel, SimpleChatAudio, SimpleChatVideo, AnthropicMessage, OpenAIMessage } from '@omnicross/contracts/completion-types';
+import { LLMProvider, OpenRouterProviderRouting } from '@omnicross/contracts/llm-config';
+import { C as CorePaths, U as UsageEventSink } from './usage-event-sink-BX7FE1NL.cjs';
+import { L as Logger, A as ApiKeyPoolService } from './ApiKeyPoolService-BmMkau07.cjs';
+import { W as WebSearchBackend, P as ProviderConfigSource, U as UsageRecorderImport } from './types-DZIQbgp0.cjs';
+import { MCPCallToolResponse, MCPTool } from '@omnicross/contracts/mcp-types';
+import { resolveProviderEndpoint as resolveProviderEndpoint$1 } from '@omnicross/contracts/endpoint-resolver';
+
+/**
+ * Native Search Types
+ *
+ * Type definitions for provider-native web search capabilities.
+ * Used by NativeSearchInjector to detect and configure built-in
+ * search for OpenAI, Anthropic, Google, xAI, and OpenRouter.
+ *
+ * @module completion/native-search-types
+ */
+
+/** Providers that support native/built-in web search */
+type NativeSearchProvider = 'openai' | 'anthropic' | 'google' | 'xai' | 'openrouter';
+/** Result of detecting native search support for a model */
+interface NativeSearchDetectionResult {
+    /** Whether the model supports native search */
+    supported: boolean;
+    /** Which native provider to use, if supported */
+    nativeProvider: NativeSearchProvider | null;
+}
+/** Native search tool names that should NOT be executed locally */
+declare const NATIVE_SEARCH_TOOL_NAMES: string[];
+/** User-facing configuration for native search */
+interface NativeSearchUserConfig {
+    /** Whether native search is enabled */
+    enabled: boolean;
+    /** Max search results / uses (maps to provider-specific settings) */
+    maxResults?: number;
+    /** Domains to block (Anthropic) */
+    blockedDomains?: string[];
+    /** xAI search mode override */
+    searchMode?: 'on' | 'off' | 'auto';
+    /** xAI search sources */
+    sources?: Array<{
+        type: 'web' | 'x' | 'news';
+    }>;
+}
+/**
+ * Request body augmentation produced by NativeSearchInjector.
+ *
+ * - `additionalTools`: Appended to the tools array in the request body.
+ * - `bodyFields`: Merged into the top-level request body.
+ */
+interface NativeSearchAugmentation {
+    /** Extra tools to append (OpenAI web_search, Anthropic web_search_20250305, Gemini grounding) */
+    additionalTools?: unknown[];
+    /** Top-level body fields (xAI search_parameters, OpenRouter plugins, OpenAI web_search_options) */
+    bodyFields?: Record<string, unknown>;
+}
+
+/**
+ * Completion Service Types
+ *
+ * Type definitions for completion options, results, and callbacks.
+ */
+
+interface CompletionOptions {
+    providerId: string;
+    model: string;
+    messages: SimpleChatMessage[];
+    maxTokens?: number;
+    temperature?: number;
+    stream?: boolean;
+    /** Thinking effort level for reasoning models */
+    thinkLevel?: ThinkLevel;
+    /** Native search augmentation to apply to the request body */
+    nativeSearchAugmentation?: NativeSearchAugmentation;
+    /** Session ID for API key pool affinity (preserves prompt cache) and usage attribution. */
+    sessionId?: string;
+    /**
+     * Assistant-message id this request is producing — used to attribute
+     * recorded usage rows back to host messages. Optional; if absent the row is
+     * still recorded but won't be linked.
+     */
+    messageId?: string;
+    /**
+     * Parent message id (for subagent-style nested calls). Best-effort: callers
+     * that know the parent should fill this; otherwise leave unset.
+     */
+    parentMessageId?: string;
+    /**
+     * Opt into the Anthropic 1M-context tier for this request. The transformer
+     * pipeline (and any direct Anthropic-format paths) inject the
+     * `'context-1m-2025-08-07'` beta into the outbound request body when this
+     * is true AND the resolved model is in the 1M-capable allowlist.
+     */
+    useExtendedContext?: boolean;
+}
+interface CompletionResult {
+    success: boolean;
+    message?: SimpleChatMessage;
+    error?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Provider finish reason (e.g. 'stop', 'tool_use', 'max_tokens') */
+    finishReason?: string;
+}
+interface StreamCallbacks {
+    onStart?: (messageId: string) => void;
+    onDelta?: (content: string) => void;
+    onReasoning?: (reasoning: string) => void;
+    onAudio?: (audio: SimpleChatAudio) => void;
+    onVideo?: (video: SimpleChatVideo) => void;
+    /** Called when a new content block is created (thinking, text, tool_use, tool_result) */
+    onBlock?: (block: MessageBlock) => void;
+    onDone?: (message: SimpleChatMessage, usage?: CompletionResult['usage'], metrics?: {
+        completionTokens: number;
+        timeCompletionMs: number;
+        timeFirstTokenMs?: number;
+    }) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * API format type for determining endpoint structure
+ */
+type ApiFormat = 'openai' | 'anthropic' | 'google' | 'azure-openai' | 'openai-response';
+
+/**
+ * Core-owned tool-shape types.
+ *
+ * The structural tool definitions (`OpenAITool`, `AnthropicTool`,
+ * `GeminiTools`) are pure data shapes with no host dependency — hoisted here
+ * (verbatim from the host `tools/mcp-users/ToolsLoader.ts`) so the serving core
+ * names no host module. The host `ToolsLoader.ts` re-exports these from
+ * `@omnicross/core`, keeping every existing host consumer unchanged.
+ *
+ * `McpToolProvider` is the narrow structural port for the single `callTool`
+ * method the completion tool-loop consumes from the host's concrete
+ * `McpService`. The concrete `McpService` instance is injected at the existing
+ * seam and satisfies this port structurally (type-only — no runtime coupling).
+ */
+
+/**
+ * OpenAI-compatible tool definition
+ */
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, any>;
+    };
+}
+/**
+ * Anthropic tool definition
+ */
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, any>;
+}
+/**
+ * Google Gemini tool definition
+ * Gemini REST API expects tools wrapped in functionDeclarations
+ */
+type GeminiTools = Array<{
+    functionDeclarations: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, any>;
+    }>;
+}>;
+/**
+ * Narrow structural port for the host MCP tool provider — only the `callTool`
+ * method the serving-core tool-loop dispatches to. The host's concrete
+ * `McpService` satisfies this structurally.
+ */
+interface McpToolProvider {
+    callTool(serverId: string, toolName: string, args: unknown, callId: string): Promise<MCPCallToolResponse>;
+}
+
+/**
+ * BuiltinToolExecutor — Executes built-in tools (web_search, web_fetch)
+ * for the non-agent chat pipeline.
+ *
+ * Built-in tools use `serverId: 'builtin'` in MCPTool metadata and are
+ * dispatched here instead of going through McpService.callTool().
+ */
+
+declare class BuiltinToolExecutor {
+    private webSearch;
+    constructor(webSearch: WebSearchBackend);
+    execute(toolName: string, args: Record<string, unknown>): Promise<MCPCallToolResponse>;
+    private executeWebSearch;
+    private resolveProviderChain;
+    private executeWebFetch;
+}
+/** Get the built-in MCPTool definitions for web search tools. */
+declare function getBuiltinSearchTools(): MCPTool[];
+
+/**
+ * ToolHandler - Handles streaming completion with MCP tool support
+ *
+ * Extracted from CompletionService to isolate the agentic loop logic
+ * that handles tool calls: LLM -> execute tools -> LLM again until done.
+ */
+
+/** Extended options for tool-based completion */
+interface StreamWithToolsOptions extends CompletionOptions {
+    tools: OpenAITool[] | AnthropicTool[] | GeminiTools;
+    mcpTools?: MCPTool[];
+}
+/** Extended callbacks for tool-based completion */
+interface StreamWithToolsCallbacks extends StreamCallbacks {
+    onToolCall?: (toolCall: {
+        id: string;
+        name: string;
+        args: unknown;
+    }) => void;
+    onToolResult?: (toolId: string, result: unknown) => void;
+}
+
+/**
+ * VisionFallbackProvider — serving-core port for image-to-text fallback.
+ *
+ * When the active completion model lacks vision capability but a message
+ * carries images, `CompletionService.applyVisionFallback` delegates to this
+ * port to turn the images into a text description (which is then appended to
+ * the message content) before stripping the image attachments.
+ *
+ * The concrete implementation is built ON TOP OF CompletionService, so it
+ * lives in the embedding host and is injected DOWN into the serving core via
+ * `setVisionFallbackProvider` at bootstrap (instead of the core importing
+ * upward).
+ *
+ * @module completion/VisionFallbackProvider
+ */
+/**
+ * Describe a batch of images as text using an auxiliary vision-capable model.
+ *
+ * @param images  Image data URLs to describe (`{ data: 'data:<mime>;base64,…' }`).
+ * @param context Free-form context (the surrounding user message content).
+ * @param model   The resolved vision aux ModelRef (`"providerId,modelId"`).
+ * @returns A textual description, or an empty / sentinel string when
+ *          unavailable. Callers MUST tolerate `''` and
+ *          `'[Image description unavailable]'`.
+ */
+interface VisionFallbackProvider {
+    describeImages(images: {
+        data: string;
+    }[], context: string, model: string): Promise<string>;
+}
+
+/**
+ * CompletionService - Handles completion API calls
+ *
+ * This service provides a unified interface for making completion API calls
+ * to different providers, handling format conversion as needed.
+ * Supports transformer chains for advanced request/response transformation.
+ *
+ * This is a thin facade that delegates to domain-specific handlers:
+ * - DirectApiHandler: Non-streaming API calls (OpenAI, Anthropic, Gemini)
+ * - StreamHandler: SSE-based streaming (OpenAI, Anthropic, Gemini)
+ * - TransformerHandler: Transformer chain-based completion
+ * - ToolHandler: Agentic tool-calling loop
+ * - ThinkingResolver: Thinking budget and max tokens resolution
+ */
+
+declare class CompletionService {
+    private paths;
+    private llmConfig;
+    private logger;
+    private apiKeyPool;
+    private usageRecorder;
+    private usageEventSink;
+    private visionFallbackProvider;
+    constructor(paths: CorePaths, llmConfig: ProviderConfigSource, logger: Logger);
+    /**
+     * Set the API key pool service for multi-key load balancing.
+     * When set, keys are resolved via the pool instead of directly from the provider.
+     */
+    setApiKeyPool(pool: ApiKeyPoolService): void;
+    /**
+     * Set the usage recorder so completion paths can persist token/cost stats.
+     * Optional — when unset, all calls succeed but nothing is recorded.
+     */
+    setUsageRecorder(recorder: UsageRecorderImport): void;
+    /**
+     * Set the usage-event sink so completion paths can push live usage events
+     * (context-meter, aggregate recorder) into the in-process hub. Injected DOWN
+     * at bootstrap with `getUsageEventHub()` immediately after construction, so
+     * emission is unconditional in production. Optional — when unset (unit-test
+     * constructors), the emit calls no-op, identical to `usageRecorder`.
+     */
+    setUsageEventSink(sink: UsageEventSink): void;
+    /**
+     * Set the vision-fallback provider used by `applyVisionFallback` to describe
+     * images for non-vision models. Injected DOWN by the host at bootstrap
+     * (the host's impl is built on top of CompletionService).
+     * Optional — when unset, `applyVisionFallback` strips images instead.
+     */
+    setVisionFallbackProvider(provider: VisionFallbackProvider): void;
+    /**
+     * Get provider by ID
+     * Delegates to the `ProviderConfigSource` which maintains its own in-memory cache.
+     */
+    getProvider(providerId: string): Promise<LLMProvider | null>;
+    /**
+     * Send a completion request
+     */
+    complete(options: CompletionOptions): Promise<CompletionResult>;
+    /**
+     * Send a streaming completion request
+     */
+    completeStream(options: CompletionOptions, callbacks: StreamCallbacks): Promise<void>;
+    /**
+     * Get available models for a provider
+     */
+    getAvailableModels(providerId: string): Promise<string[]>;
+    /**
+     * Test provider connection with a specific model.
+     * Sends "Hello" and returns the AI response, duration, etc.
+     */
+    testModel(providerId: string, modelId: string): Promise<{
+        success: boolean;
+        message: string;
+        response?: string;
+        model: string;
+        durationMs?: number;
+    }>;
+    /**
+     * Check if any messages contain images and the model lacks vision capability.
+     * If so, use the auxiliary vision model to describe images as text and remove
+     * the image attachments from the messages.
+     *
+     * Mutates options.messages in-place.
+     */
+    private applyVisionFallback;
+    /**
+     * Resolve API key for a request with priority:
+     * 1. Coding Plan override (if enabled)
+     * 2. API key pool (session-affinity weighted round-robin)
+     * 3. Legacy single key from provider config
+     */
+    private resolveApiKeyForRequest;
+    /**
+     * Extract HTTP status code from error messages like "API error (429): ..."
+     */
+    private extractHttpStatus;
+    /**
+     * Dispatch a non-streaming completion to the appropriate handler.
+     */
+    private callDirectHandler;
+    /**
+     * Dispatch a streaming completion to the appropriate handler.
+     */
+    private callStreamHandler;
+    /**
+     * Resolve API key (handle environment variable references)
+     */
+    resolveApiKey(apiKey: string): string;
+    /**
+     * Resolve effective max_tokens value with priority:
+     * 1. Session settings (if provided)
+     * 2. Global model parameters (if enabled)
+     * 3. Model's maxTokens from provider config
+     * 4. Discovered models cache (from API)
+     * 5. undefined - let API use its default
+     */
+    resolveEffectiveMaxTokens(providerId: string, modelId: string, sessionMaxTokens?: number): Promise<number | undefined>;
+    /**
+     * Get required max_tokens for providers that need it (e.g., Anthropic)
+     * Falls back to DEFAULT_MAX_TOKENS if no value is configured
+     */
+    getRequiredMaxTokens(providerId: string, modelId: string, sessionMaxTokens?: number): Promise<number>;
+    /**
+     * Calculate thinking budget and adjust max_tokens for the provider
+     */
+    resolveThinkingBudget(providerId: string, modelId: string, maxTokens: number, thinkLevel: ThinkLevel): Promise<{
+        adjustedMaxTokens: number;
+        thinkingBudget: number | undefined;
+        thinkingConfig: {
+            type?: 'enabled' | 'disabled';
+            budget_tokens?: number;
+        } | undefined;
+    }>;
+    /**
+     * Send a completion request using transformer chain
+     */
+    completeWithTransformers(options: CompletionOptions): Promise<CompletionResult>;
+    /**
+     * Send a streaming completion request using transformer chain
+     */
+    completeStreamWithTransformers(options: CompletionOptions, callbacks: StreamCallbacks): Promise<void>;
+    /**
+     * Stream completion with MCP tools support (direct API call)
+     * Implements agentic loop: calls LLM -> executes tools -> calls LLM again until done
+     */
+    streamWithTools(options: StreamWithToolsOptions, callbacks: StreamWithToolsCallbacks, mcpService?: McpToolProvider, builtinExecutor?: BuiltinToolExecutor): Promise<void>;
+}
+
+/**
+ * StreamEventBuffer — per-streamId event queue for streamed completion delivery.
+ *
+ * Closes the subscribe-vs-emit race between a producer that starts the LLM call
+ * asynchronously and a consumer that only attaches its listener after awaiting a
+ * reply. Events emitted before `attach(streamId)` is called are queued and
+ * replayed in order on attach.
+ */
+/**
+ * Minimal structural sender — the subset of an Electron `WebContents` (or any
+ * IPC channel) this buffer actually uses. Kept LOCAL so core has zero electron
+ * dependency; the host passes any object satisfying this shape.
+ */
+interface StreamSender {
+    isDestroyed(): boolean;
+    send(channel: string, payload: StreamEvent): void;
+}
+type StreamEventType = 'start' | 'delta' | 'reasoning' | 'tool_call' | 'tool_result' | 'tool_use' | 'block' | 'search_start' | 'search_result' | 'done' | 'error' | 'abort';
+interface StreamEvent {
+    type: StreamEventType;
+    [key: string]: unknown;
+}
+/**
+ * Register a new stream. Called by the engine / handler immediately after the
+ * `streamId` is created, before any `emit`. Idempotent re-registration replaces
+ * the sender (covers the rare case of the engine retrying with the same id).
+ */
+declare function register(streamId: string, sender: StreamSender): void;
+/**
+ * Emit an event for `streamId`. Forwards directly if the client has attached;
+ * otherwise queues until `attach` is called. Bounded at QUEUE_CAP — overflow
+ * evicts the oldest non-terminal event.
+ */
+declare function emit(streamId: string, event: StreamEvent): void;
+/**
+ * The client announced readiness via the `completion:stream:subscribe` IPC. Drains
+ * the queue synchronously to the bound sender, then flips to direct-forward mode.
+ * Returns the number of events drained for diagnostic purposes.
+ */
+declare function attach(streamId: string): {
+    ok: boolean;
+    drained: number;
+};
+/**
+ * Mark a stream finished. If the client has already attached, release
+ * synchronously. Otherwise defer one tick so a late `subscribe` arriving on the
+ * heels of the `done`/`error` event still drains the queue before cleanup.
+ */
+declare function release(streamId: string): void;
+
+/**
+ * API URL Building Utilities
+ *
+ * Functions for building correct API URLs based on provider format.
+ */
+
+/**
+ * Resolve API format from provider configuration
+ *
+ * Priority:
+ * 1. apiFormat (v3 preferred field)
+ * 2. chatApiFormat (legacy v3 field)
+ * 3. apiType if it's an explicit format (claudecode/anthropic/google)
+ * 4. Default to openai
+ *
+ * Note: This enables implicit routing - the API format determines which
+ * transformer is automatically applied without explicit router configuration.
+ */
+declare function resolveApiFormat(provider: LLMProvider): ApiFormat;
+/**
+ * Build OpenAI Chat Completions API URL
+ * Handles various input formats:
+ * - https://api.openai.com → https://api.openai.com/v1/chat/completions
+ * - https://api.openai.com/v1/chat/completions → unchanged
+ * - https://api.deepseek.com/v1 → https://api.deepseek.com/v1/chat/completions
+ * - https://api.z.ai/api/coding/paas/v4 → https://api.z.ai/api/coding/paas/v4/chat/completions
+ */
+declare function buildOpenAIApiUrl(baseUrl: string): string;
+/**
+ * Build Anthropic Messages API URL
+ * Handles various input formats:
+ * - https://api.anthropic.com → https://api.anthropic.com/v1/messages
+ * - https://api.anthropic.com/v1/messages → unchanged
+ * - https://api.z.ai/api/anthropic → https://api.z.ai/api/anthropic/v1/messages
+ * - https://api.z.ai/api/anthropic/v2 → https://api.z.ai/api/anthropic/v2/messages
+ */
+declare function buildAnthropicApiUrl(baseUrl: string): string;
+/**
+ * Build Google Gemini API URL
+ * Gemini uses a dynamic URL structure: /v1beta/models/{model}:generateContent or :streamGenerateContent
+ * @param baseUrl - Base URL (e.g., https://generativelanguage.googleapis.com)
+ * @param model - Model name (e.g., gemini-2.0-flash)
+ * @param stream - Whether to use streaming endpoint
+ */
+declare function buildGeminiApiUrl(baseUrl: string, model: string, stream: boolean): string;
+/**
+ * Normalize Azure OpenAI endpoint
+ * Strips trailing /, /openai, /openai/v1 etc.
+ */
+declare function normalizeAzureEndpoint(endpoint: string): string;
+/**
+ * Build Azure OpenAI API URL
+ * Format: {endpoint}/openai/deployments/{deploymentName}/chat/completions?api-version={version}
+ * @param baseUrl - Azure endpoint (e.g., https://my-resource.openai.azure.com)
+ * @param model - Deployment name (used as model in Azure)
+ * @param apiVersion - API version (e.g., 2024-08-01-preview)
+ */
+declare function buildAzureOpenAIApiUrl(baseUrl: string, model: string, apiVersion: string): string;
+/**
+ * Build OpenAI Responses API URL
+ * Format: {baseUrl}/v1/responses
+ */
+declare function buildOpenAIResponseApiUrl(baseUrl: string): string;
+
+declare const resolveProviderEndpoint: typeof resolveProviderEndpoint$1;
+/**
+ * Build API URL based on provider format and options
+ * This is the main entry point for URL building
+ */
+declare function buildProviderApiUrl(provider: LLMProvider, options?: {
+    model?: string;
+    stream?: boolean;
+}): string;
+
+/**
+ * Request Header Building Utilities
+ *
+ * Functions for building correct request headers based on provider format.
+ */
+
+/**
+ * Get request headers based on provider format
+ */
+declare function getProviderHeaders(provider: LLMProvider, apiKey: string): Record<string, string>;
+
+/**
+ * Message Format Conversion Utilities
+ *
+ * Functions for converting SimpleChatMessage to different API formats.
+ */
+
+/**
+ * Convert SimpleChatMessage to OpenAI-compatible format (covers OpenAI, OpenRouter,
+ * and other OpenAI-compatible providers — DO NOT call from Anthropic / Gemini paths,
+ * which have their own converters above).
+ *
+ * - Text only: { role, content: string }
+ * - With media: { role, content: [{ type: "text" | "image_url" | "input_audio" | "video_url", ... }] }
+ *
+ * Audio is emitted as `input_audio` with base64 + format (the standard OpenAI / OpenRouter
+ * shape). Video is emitted as `video_url`: HTTPS URLs pass through; local data is sent as a
+ * `data:<mime>;base64,...` URL with a 25 MB cap before the request is even built.
+ */
+declare function convertMessageToOpenAI(msg: SimpleChatMessage): OpenAIMessage;
+/**
+ * Convert SimpleChatMessage to Anthropic format (with vision support)
+ * Anthropic format:
+ * - Text only: { role, content: string }
+ * - With images: { role, content: [{ type: "text", text: "..." }, { type: "image", source: { type: "base64", media_type: "...", data: "..." } }] }
+ */
+declare function convertMessageToAnthropic(msg: SimpleChatMessage): AnthropicMessage;
+/**
+ * Minimal Gemini part shape for the simple-chat DIRECT path (text + inline
+ * media only), serialized with the official REST JSON casing
+ * (`inlineData` / `mimeType`).
+ *
+ * NOT the same wire model as the transformer pipeline's full `GeminiPart`
+ * union in `transformer/transformers/utils/gemini.util.ts` (function calls /
+ * file data, snake_case alias keys). The two paths intentionally serialize
+ * differently — do not merge them blindly.
+ */
+interface SimpleChatGeminiPart {
+    text?: string;
+    inlineData?: {
+        mimeType: string;
+        data: string;
+    };
+}
+/** Gemini message for the simple-chat direct path. */
+interface SimpleChatGeminiMessage {
+    role: string;
+    parts: SimpleChatGeminiPart[];
+}
+/**
+ * Convert SimpleChatMessage to Gemini format (with vision support)
+ * Gemini format:
+ * - { role: "user"|"model", parts: [{ text: "..." }, { inlineData: { mimeType: "...", data: "..." } }] }
+ */
+declare function convertMessageToGemini(msg: SimpleChatMessage): SimpleChatGeminiMessage;
+
+/**
+ * OpenRouter Provider Utilities
+ *
+ * Functions for handling OpenRouter-specific configuration and routing.
+ */
+
+/**
+ * Get OpenRouter provider routing config from model configuration
+ * Returns the provider routing config if the provider is OpenRouter and model has config
+ */
+declare function getOpenRouterProviderConfig(provider: LLMProvider, modelId: string): OpenRouterProviderRouting | undefined;
+/**
+ * Add OpenRouter provider routing to request body if applicable
+ */
+declare function addOpenRouterProviderToRequest(requestBody: Record<string, unknown>, provider: LLMProvider, modelId: string): Record<string, unknown>;
+
+/**
+ * Native Search Injector
+ *
+ * Detects provider-native web search support and builds request body
+ * augmentations for OpenAI, Anthropic, Google, xAI, and OpenRouter.
+ *
+ * This module does NOT execute searches — it only prepares the request
+ * so the LLM provider's server-side search runs automatically.
+ *
+ * @module completion/NativeSearchInjector
+ */
+
+/**
+ * Detect whether a model supports provider-native web search.
+ *
+ * Detection order:
+ * 1. OpenRouter — detected by provider base URL, not model pattern.
+ * 2. xAI — detected by base URL containing `x.ai` or `grok`.
+ * 3. Model-pattern match against known providers (OpenAI, Anthropic, Google).
+ * 4. If `userExplicit` is true, fall back to API format mapping even
+ *    when the model ID doesn't match known patterns (user opted-in).
+ */
+declare function detectNativeSearch(modelId: string, apiFormat: ApiFormat, provider: LLMProvider, userExplicit?: boolean): NativeSearchDetectionResult;
+/**
+ * Build a {@link NativeSearchAugmentation} for the given provider.
+ * Returns `null` if the provider is unknown or config is disabled.
+ */
+declare function buildNativeSearchAugmentation(nativeProvider: NativeSearchProvider, config: NativeSearchUserConfig, _apiFormat: ApiFormat, modelId: string): NativeSearchAugmentation | null;
+/**
+ * Merge an augmentation into the request body **in-place**.
+ *
+ * - `additionalTools` are appended to the existing `tools` array.
+ * - `bodyFields` are shallow-merged into the top-level body.
+ */
+declare function applyAugmentation(requestBody: Record<string, unknown>, augmentation: NativeSearchAugmentation): Record<string, unknown>;
+
+export { type AnthropicTool as A, BuiltinToolExecutor as B, type CompletionOptions as C, emit as D, getBuiltinSearchTools as E, getOpenRouterProviderConfig as F, type GeminiTools as G, getProviderHeaders as H, normalizeAzureEndpoint as I, register as J, release as K, resolveApiFormat as L, type McpToolProvider as M, NATIVE_SEARCH_TOOL_NAMES as N, type OpenAITool as O, resolveProviderEndpoint as P, type SimpleChatGeminiMessage as S, type VisionFallbackProvider as V, type ApiFormat as a, type CompletionResult as b, CompletionService as c, type NativeSearchAugmentation as d, type NativeSearchDetectionResult as e, type NativeSearchProvider as f, type NativeSearchUserConfig as g, type SimpleChatGeminiPart as h, type StreamCallbacks as i, type StreamEvent as j, type StreamEventType as k, type StreamSender as l, addOpenRouterProviderToRequest as m, applyAugmentation as n, attach as o, buildAnthropicApiUrl as p, buildAzureOpenAIApiUrl as q, buildGeminiApiUrl as r, buildNativeSearchAugmentation as s, buildOpenAIApiUrl as t, buildOpenAIResponseApiUrl as u, buildProviderApiUrl as v, convertMessageToAnthropic as w, convertMessageToGemini as x, convertMessageToOpenAI as y, detectNativeSearch as z };