aieo 0.1.41 → 0.2.0

package/dist/index.d.cts

@@ -1,846 +0,0 @@
-import { ModelMessage, LanguageModel, ToolSet } from 'ai';
-export { ModelMessage, Tool, ToolSet } from 'ai';
-import { AnthropicProviderOptions } from '@ai-sdk/anthropic';
-
-interface Conversation {
-    id: string;
-    summary: string;
-    timestamp: number;
-}
-interface ConversationData {
-    id: string;
-    summary: string;
-    messages: ModelMessage[];
-    lastUpdated: number;
-}
-declare const MAX_CONVERSATIONS = 100;
-declare abstract class ConversationStorage {
-    abstract currentConversationId(): Promise<string>;
-    abstract selectConversation(conversationId: string): Promise<void>;
-    abstract listConversations(): Promise<Conversation[]>;
-    abstract getConversation(conversationId: string): Promise<ConversationData | null>;
-    abstract storeConversationData(conversationId: string, data: ConversationData): Promise<void>;
-    abstract deleteConversationData(conversationId: string): Promise<boolean>;
-    createConversation(messages: ModelMessage[]): Promise<ConversationData>;
-    addMessageToConversation(conversationId: string, message: ModelMessage): Promise<ConversationData>;
-    getCurrentConversation(): Promise<ConversationData | null>;
-    getLatestConversation(): Promise<ConversationData | null>;
-    updateConversationSummary(conversationId: string, summary: string): Promise<ConversationData>;
-    private pruneOldConversations;
-    protected generateSummary(content: string): string;
-}
-
-interface Logger {
-    info(message: string): void;
-    error(message: string): void;
-    warn?(message: string): void;
-    debug?(message: string): void;
-    trace?(message: string): void;
-    fatal?(message: string): void;
-}
-declare function consoleLogger(name: string): Logger;
-
-type Provider = "anthropic" | "google" | "openai" | "openrouter" | "xai";
-/**
- * Per-provider path Bifrost (and compatible gateways) expose for each
- * provider's drop-in SDK. Exported so spawners can build per-provider
- * URLs without hand-rolling the suffix.
- *
- * NOTE: OpenRouter has no dedicated Bifrost route and rides the OpenAI
- * path (model id prefixed `openrouter/` in getModel so Bifrost routes it
- * upstream). If you spawn an agent in a way where the runtime would
- * override the model to an OpenRouter model, you want the OpenAI suffix
- * here too. xAI likewise rides the OpenAI-compat path (model id prefixed
- * `xai/` in getModel), since Bifrost has no dedicated Grok route.
- */
-declare const GATEWAY_PATHS: Record<Provider, string>;
-declare function getGatewayBaseURL(provider: Provider): string | undefined;
-/**
- * Build the fully-formed `<base>/<provider-path>` URL that an official
- * SDK (or Goose, or a workflow LLM node) expects.
- *
- * This is the single source of truth for "which suffix do I add to the
- * gateway root for this provider." Spawners (Hive, Stakwork, anyone
- * launching an agent) should call this when stamping `ANTHROPIC_BASE_URL`,
- * `OPENAI_BASE_URL`, `GOOGLE_BASE_URL`, etc. on a child process or
- * workflow context.
- *
- * Behavior:
- *  - Trims a trailing slash.
- *  - Returns the URL unchanged if it already ends with the provider's
- *    gateway path (`/anthropic/v1`, `/openai/v1`, `/genai/v1beta`), so
- *    the function is idempotent.
- *  - Returns the URL unchanged if it already targets a provider/version
- *    path (e.g. `.../v1`, `.../v1beta`, `.../anthropic/...`). This lets
- *    callers pass fully-qualified URLs through without surprise.
- *  - Otherwise appends `GATEWAY_PATHS[provider]`.
- *
- * Examples
- * --------
- * gatewayUrlFor("anthropic", "https://swarm38.sphinx.chat:8181")
- *   => "https://swarm38.sphinx.chat:8181/anthropic/v1"
- *
- * gatewayUrlFor("openai", "https://swarm38.sphinx.chat:8181/")
- *   => "https://swarm38.sphinx.chat:8181/openai/v1"
- *
- * gatewayUrlFor("anthropic", "https://swarm38.sphinx.chat:8181/anthropic/v1")
- *   => "https://swarm38.sphinx.chat:8181/anthropic/v1"   (idempotent)
- *
- * gatewayUrlFor("openai", "https://api.openai.com/v1")
- *   => "https://api.openai.com/v1"                       (left alone)
- */
-declare function gatewayUrlFor(provider: Provider, baseUrl: string): string;
-/**
- * Like {@link gatewayUrlFor} but takes a model name (shortcut like
- * `"sonnet"`, namespaced like `"anthropic/claude-sonnet-5"`, or a full
- * model id like `"claude-sonnet-5"`) and resolves the provider for you.
- *
- * Convenient for spawners that have a model name in hand but not a
- * provider — e.g. Hive picking up a user's chosen model and needing to
- * tell the agent which Bifrost route to use.
- */
-declare function gatewayUrlForModel(modelName: string | undefined, baseUrl: string): string;
-/**
- * Build a `{ ANTHROPIC_BASE_URL, OPENAI_BASE_URL, GOOGLE_BASE_URL }`-style
- * env map for spawning agents (Goose, Python, raw SDK callers) that
- * don't normalize the URL themselves. Pass the gateway root once; get
- * back the per-provider URLs.
- *
- * The keys match the env var names the official SDKs read by default:
- *   - `ANTHROPIC_BASE_URL`        (anthropic-sdk-{ts,python,go})
- *   - `OPENAI_BASE_URL`           (openai SDK)
- *   - `GOOGLE_GENERATIVE_AI_BASE_URL` (google-genai SDK / `@ai-sdk/google`)
- *
- * Spawners can spread the result into the child's env. Callers that
- * only need one provider should use {@link gatewayUrlFor} directly.
- */
-declare function gatewayEnvForProviders(baseUrl: string): {
-    ANTHROPIC_BASE_URL: string;
-    OPENAI_BASE_URL: string;
-    GOOGLE_GENERATIVE_AI_BASE_URL: string;
-};
-/**
- * @deprecated Use {@link gatewayUrlFor}. Kept as an alias for internal
- * call sites; both have identical behavior.
- */
-declare const normalizeCallerBaseURL: typeof gatewayUrlFor;
-declare const PROVIDERS: Provider[];
-type ModelName = "sonnet" | "opus" | "haiku" | "gemini" | "gpt" | "kimi" | "glm" | "grok";
-type ModelId = string;
-declare const MODELS: Record<Provider, Partial<Record<ModelName, ModelId>>>;
-declare const DEFAULT_MODELS: Record<Provider, string>;
-declare function getLightModelForProvider(provider: Provider): string;
-interface TokenPricing {
-    inputTokenPrice: number;
-    outputTokenPrice: number;
-    cacheReadPrice?: number;
-    cacheWritePrice?: number;
-}
-interface TokenUsageForCost {
-    input: number;
-    cache_read: number;
-    cache_write: number;
-    output: number;
-}
-declare function computeSessionCost(provider: Provider, usage: TokenUsageForCost, modelId?: string, actualCost?: number): number;
-declare function getProviderForModel(modelName?: ModelName | string): Provider;
-/**
- * Treat blank/whitespace-only keys as absent.
- *
- * A truthy-but-blank key (a request body with `apiKey: " "`, an env var set to
- * an empty-ish value) otherwise sails past every `!!key` check and reaches the
- * provider SDK, which happily builds `Authorization: Bearer ` and gets a
- * confusing 401 ("Missing Authentication header" from OpenRouter) on every
- * single call instead of failing fast. Also trims stray whitespace so a key
- * pasted with a trailing space still authenticates.
- */
-declare function normalizeApiKey(key?: string | null): string | undefined;
-/**
- * The env var each provider's API key is read from. Exported so a host with
- * its own secret store knows which NAME to look up (see resolve.ts).
- */
-declare const API_KEY_ENV: Record<Provider, string>;
-declare function hasApiKeyForProvider(provider: Provider | string): boolean;
-declare function getApiKeyForProvider(provider: Provider | string): string;
-interface GetModelOptions {
-    apiKey?: string;
-    baseUrl?: string;
-    modelName?: ModelName | string;
-    cwd?: string;
-    executablePath?: string;
-    logger?: Logger;
-    /**
-     * Custom HTTP headers to attach to every request the provider client makes
-     * to the LLM endpoint. Useful for gateway auth, tenant IDs, etc.
-     */
-    headers?: Record<string, string>;
-    /**
-     * AbortSignal from the run's AbortController. When fired (busy timeout /
-     * `/repo/agent/abort`), in-flight model calls and streams are cancelled.
-     * Stays armed for the entire request/stream lifetime.
-     */
-    abortSignal?: AbortSignal;
-    /**
-     * Per-request timeout in milliseconds for the connect / first-response
-     * phase only. Once the provider replies with headers the timer is disarmed,
-     * so a slow-but-progressing stream is never killed. Defaults to the
-     * `LLM_HTTP_TIMEOUT_MS` env var when not supplied.
-     */
-    timeoutMs?: number;
-}
-interface ModelDetails {
-    provider: Provider;
-    apiKey: string;
-    model: LanguageModel;
-    modelId: string;
-    contextLimit: number;
-}
-declare function getModelDetails(modelName?: ModelName | string, apiKeyIn?: string, baseUrl?: string, headers?: Record<string, string>, abortSignal?: AbortSignal, timeoutMs?: number): ModelDetails;
-declare function getModel(provider: Provider, opts?: string | GetModelOptions): LanguageModel;
-/**
- * Get the context window size (max input tokens) for a given model.
- */
-declare function getContextLimit(modelId: string, provider: Provider): number;
-declare function getTokenPricing(provider: Provider): TokenPricing;
-declare function loadModelPricing(): Promise<void>;
-type ThinkingSpeed = "thinking" | "fast";
-declare function getProviderOptions(provider: Provider, thinkingSpeed?: ThinkingSpeed, modelName?: string): {
-    anthropic: AnthropicProviderOptions;
-    google?: undefined;
-    openai?: undefined;
-    openrouter?: undefined;
-    xai?: undefined;
-} | {
-    google: {
-        thinkingConfig: {
-            thinkingBudget: number;
-        };
-    };
-    anthropic?: undefined;
-    openai?: undefined;
-    openrouter?: undefined;
-    xai?: undefined;
-} | {
-    openai: {};
-    anthropic?: undefined;
-    google?: undefined;
-    openrouter?: undefined;
-    xai?: undefined;
-} | {
-    openrouter: {
-        usage: {
-            include: true;
-        };
-    };
-    anthropic?: undefined;
-    google?: undefined;
-    openai?: undefined;
-    xai?: undefined;
-} | {
-    xai: {};
-    anthropic?: undefined;
-    google?: undefined;
-    openai?: undefined;
-    openrouter?: undefined;
-};
-interface LLMConfig {
-    provider: Provider;
-    apiKey: string;
-    model: LanguageModel;
-    modelName?: string;
-}
-/**
- * Resolve LLM configuration from request params with env fallback.
- * Priority: request body/query → env vars → defaults.
- * Use `light: true` for batch/cheap operations (descriptions, learnings, etc.)
- */
-declare function resolveLLMConfig(opts?: {
-    model?: string;
-    apiKey?: string;
-    provider?: string;
-    light?: boolean;
-}): LLMConfig;
-
-interface ModelOption {
-    provider: Provider;
-    alias: ModelName;
-    modelId: string;
-    /** The provider's default — what you get with no model name at all. */
-    default: boolean;
-}
-/**
- * Every alias in the MODELS table, in PROVIDERS order. Pure and keyless,
- * which is what a UI picker or a server-config endpoint needs.
- */
-declare function listModels(): ModelOption[];
-interface ParsedModelName {
-    /** Set only when the name carries an explicit "<provider>/" prefix. */
-    provider?: Provider;
-    /** The name with that prefix stripped. Aliases are NOT resolved here.
-     *  undefined for an empty name (or a bare "<provider>/"). */
-    modelId?: string;
-}
-/** Pure syntax: strip an explicit provider prefix, nothing else. */
-declare function parseModelName(name?: string): ParsedModelName;
-interface ModelRef {
-    provider: Provider;
-    /** Concrete id as the provider knows it (alias resolved, prefix stripped). */
-    modelId: string;
-    /** Canonical "<provider>/<modelId>" — unambiguous, itself a valid model name. */
-    name: string;
-}
-/**
- * Resolve a model name to its provider + concrete id WITHOUT an API key.
- * Follows getModel's rules — explicit `provider` wins, then an explicit
- * prefix, then getProviderForModel's inference; aliases map through MODELS;
- * no name → the provider's default — so what this reports is what
- * resolveModel / getModel will build. (One deliberate extra: an alias after
- * a prefix, "anthropic/sonnet", resolves too.)
- *
- * Rejects the one input getModel silently gets wrong: a slashed name whose
- * first segment is NOT a provider ("moonshotai/kimi-k2.6") with nothing
- * else naming the provider — inference falls to the default and the request
- * 404s at the wrong API. Say so up front, with the fix. LLM_PROVIDER, when
- * set, counts as "something naming the provider", exactly as it does for
- * getProviderForModel.
- */
-declare function canonicalModelName(model?: string, provider?: Provider | string): ModelRef;
-/**
- * Per-call output-token cap. An explicit MAX_OUTPUT_TOKENS env always wins.
- * Otherwise the default is provider-aware: Anthropic runs at 128k because
- * @ai-sdk/anthropic clamps known models down to their true per-model max
- * instead of erroring, while OpenAI-compatible hosts (OpenRouter et al)
- * reject max_tokens above the model limit rather than clamping, so they keep
- * the conservative 64k default. Thinking tokens count against this same
- * budget, so headroom matters more than the visible text length suggests.
- */
-declare function maxOutputTokensFor(provider?: string): number;
-interface ResolveOptions {
-    /** alias | id | "provider/id" | "openrouter/org/id". Omit for the provider's default. */
-    model?: string;
-    /** Explicit provider; otherwise inferred from `model`. */
-    provider?: Provider | string;
-    apiKey?: string;
-    /**
-     * Async key source consulted by env-var NAME ("OPENAI_API_KEY", …) before
-     * process.env — a host's own secret store. Only called when `apiKey` is
-     * absent.
-     */
-    getSecret?: (envName: string) => Promise<string | undefined>;
-    baseUrl?: string;
-    headers?: Record<string, string>;
-    abortSignal?: AbortSignal;
-    timeoutMs?: number;
-}
-interface ResolvedModel extends ModelRef {
-    model: LanguageModel;
-    apiKey: string;
-    contextLimit: number;
-    maxOutputTokens: number;
-}
-/**
- * Name → everything a caller needs to run: provider, concrete id, canonical
- * name, the API key that was used, the LanguageModel, its context window,
- * and the output-token cap. Key precedence: `apiKey` → `getSecret(envName)`
- * → process.env; none → an error that names the env var. Logs nothing.
- */
-declare function resolveModel(opts?: ResolveOptions): Promise<ResolvedModel>;
-
-interface AiUsage {
-    input: number;
-    cache_read: number;
-    cache_write: number;
-    output: number;
-    total: number;
-}
-interface AiUsageWithLegacy extends AiUsage {
-    inputTokens: number;
-    outputTokens: number;
-    totalTokens: number;
-}
-type RawUsage = {
-    input?: number;
-    cache_read?: number;
-    cache_write?: number;
-    output?: number;
-    total?: number;
-    inputTokens?: number;
-    inputTokenDetails?: {
-        noCacheTokens?: number;
-        cacheReadTokens?: number;
-        cacheWriteTokens?: number;
-    };
-    cachedInputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-};
-declare function emptyUsage(): AiUsage;
-declare function withLegacyUsage(usage: AiUsage): AiUsageWithLegacy;
-declare function normalizeUsage(raw?: RawUsage | null): AiUsageWithLegacy;
-/**
- * Fold provider-metadata cache info into a normalized usage. The v6-alpha
- * OpenRouter provider drops inputTokensDetails from the SDK usage object
- * (cached-token counts survive only in providerMetadata.openrouter.usage),
- * so without this every OpenRouter step reports cache_read 0 regardless of
- * whether the upstream host actually cached.
- */
-declare function withProviderCacheUsage(usage: AiUsageWithLegacy, providerMetadata?: Record<string, any> | null): AiUsageWithLegacy;
-declare function addUsage(...usages: Array<AiUsage | undefined | null>): AiUsage;
-
-interface CallModelOptions {
-    provider: Provider;
-    apiKey: string;
-    messages: ModelMessage[];
-    tools?: ToolSet;
-    parser?: (fullResponse: string) => void;
-    thinkingSpeed?: ThinkingSpeed;
-    cwd?: string;
-    executablePath?: string;
-    modelName?: ModelName;
-}
-declare function callModel(opts: CallModelOptions): Promise<{
-    text: string;
-    usage: AiUsageWithLegacy;
-}>;
-interface GenerateObjectArgs {
-    provider: Provider;
-    apiKey: string;
-    prompt: string;
-    schema: any;
-}
-declare function callGenerateObject(args: GenerateObjectArgs): Promise<{
-    object: any;
-    usage: AiUsageWithLegacy;
-}>;
-interface GenerateTextArgs {
-    provider: Provider;
-    apiKey: string;
-    prompt: string;
-    thinkingSpeed?: ThinkingSpeed;
-}
-declare function callGenerateText(args: GenerateTextArgs): Promise<{
-    text: string;
-    usage: AiUsageWithLegacy;
-}>;
-
-declare const SYSTEM = "You are an expert dev. You are given a codebase and a task. You need to write the code for the task. You can also suggest changes to the codebase if needed.\n\nAvoid assuming that certain functions are available in the codebase. Don't use to_timestamp or to_date in SQL if you don't see examples of them being used. DO NOT make up functions like a logger or other utils. Only use utility functions that you ABSOLUTELY know exist in the code.\n\nTry to write as simple and straightforward code as possible. Make a real implementation, do NOT do a mockup or add sample data. Assume there is already mock data in the database. If you see snippets of backend code, that means you have access to the backend codebase and can add new backend endpoints or other functionality as needed.\n\nYou will be provided with code snippets to edit or create. Please preserve the EXACT file paths when you make edits. Do not truncate the file paths.\n\nYou may see multiple code snippets from the same file! In that case, please organize the code properly: if you need to add an import statement, do it in the snippet that has other imports in it! Since you won't always be able to see the whole file, try to be careful and avoid adding new code just above a snippet, since you might not know exactly what other code is there.\n\nAlways remember to add correct code that will compile!!! Make sure to properly add function signatures if needed, such as to Go interfaces or Rust traits (if you see those in the code snippets).\n\nIf asked to make further changes after already writing code, use the <content> blocks from your previous edits in order to identify code snippets to replace.\n";
-declare const OUTRO = "\nPlease write all the necessary code to fully implement the feature end-to-end. Do not make mock data or example placeholders!!!\n";
-
-type ProviderTool = "webSearch" | "webFetch" | "bash";
-/**
- * Provider-native tool by name.
- *
- * `webSearch` and `webFetch` are special: only Anthropic has native
- * ones, so every other provider gets a shim of the same name and result
- * shape instead of an exception — Exa-backed search from `./search.js`,
- * a guarded HTTP GET from `./fetch.js`. That keeps both tools available
- * (as `web_search` / `web_fetch`) on any model. This entry point returns
- * the bare tool — for the result bookkeeping, citation indices and
- * prompt snippet, call `createWebSearch` / `createWebFetch` directly.
- *
- * Returns `undefined` for those two when the chosen backend has no key
- * configured; callers should drop the tool rather than fail the request.
- * Other tools still throw for unsupported providers.
- */
-declare function getProviderTool(provider: Provider, apiKey: string, toolName: ProviderTool): any;
-
-/**
- * Web search, uniform across providers.
- *
- * Anthropic ships a server-executed `web_search` tool: the search loop
- * runs inside their API, results never round-trip through us, and the
- * model emits `<cite index="N-M">` tags referencing a flat, 1-based list
- * of every result returned across the whole turn. It's the best option
- * when it's available — no extra model hop, no per-search bill on us.
- *
- * Nobody else has an equivalent we can drop in. OpenAI, Google,
- * OpenRouter and xAI each expose *some* server-side search, but every
- * one has a different tool name, a different result shape, and a
- * different citation mechanism (Google's sources arrive as
- * `groundingMetadata`, OpenRouter's as message `annotations` — neither
- * is a tool-result at all). Adapting four of those into one pipeline is
- * four adapters and four citation normalizers.
- *
- * So: keep Anthropic on its native tool, and give every other provider a
- * client-executed tool of the same name, backed by Exa, that returns the
- * same shape. Consumers see one `web_search` tool, one result type, one
- * citation convention, regardless of which model is driving.
- *
- * Usage:
- *
- *   const ws = createWebSearch({ provider, apiKey });
- *   const tools = { ...(ws.tool ? { [WEB_SEARCH_TOOL_NAME]: ws.tool } : {}) };
- *   const system = basePrompt + ws.promptSnippet;
- *   // in onStepFinish:  ws.capture(step.content)
- *   // when writing up:  linkifyCitations(markdown, ws.results)
- *
- * `ws.results` ends the run holding every result in citation order on
- * both paths, so downstream code never branches on the backend.
- */
-/** Tool name registered with the model. Load-bearing: consumers key UI
- *  and step-walking off this exact string. */
-declare const WEB_SEARCH_TOOL_NAME = "web_search";
-/** Which implementation backs the tool. */
-type SearchBackend = "anthropic" | "exa";
-/**
- * One search hit. Field-compatible with Anthropic's
- * `web_search_result` output (`url` / `title` / `pageAge` / `type`), so
- * code that walks Anthropic tool-results parses Exa results unchanged.
- */
-interface WebSearchResult {
-    url: string;
-    title: string | null;
-    /** Publish date when the backend reports one. */
-    pageAge: string | null;
-    /**
-     * Extracted page text. Exa path only — Anthropic returns
-     * `encryptedContent` that only their model can read, so on the native
-     * path the text is never visible to us (or to this process).
-     */
-    text?: string;
-    /**
-     * 1-based citation index, flat across every `web_search` call in the
-     * run — the number the model is told to cite. Exa path only; on the
-     * Anthropic path the model derives indices itself.
-     */
-    index?: number;
-    type: "web_search_result";
-}
-interface WebSearchOptions {
-    /** Max `web_search` calls per run. Default 3, matching the previous
-     *  Anthropic-only default. Enforced in-process on the Exa path. */
-    maxUses?: number;
-    /** Results per call on the Exa path. Default 5. */
-    numResults?: number;
-    /** Per-result text budget on the Exa path. Default 4000. Raise for
-     *  research writeups, lower for quick factual lookups. */
-    maxCharacters?: number;
-    allowedDomains?: string[];
-    blockedDomains?: string[];
-}
-interface CreateWebSearchOptions extends WebSearchOptions {
-    /** LLM provider driving the run — decides the backend. */
-    provider: Provider;
-    /** LLM API key. Only used on the Anthropic path. Falls back to env. */
-    apiKey?: string;
-    /** Exa key. Falls back to `EXA_API_KEY`. */
-    searchApiKey?: string;
-    /**
-     * Force a backend regardless of provider. `"exa"` is how you A/B the
-     * shim against Anthropic's native tool on identical prompts.
-     */
-    backend?: SearchBackend;
-    /**
-     * Ask the model to cite sources as `<cite index="N">` tags, so
-     * `formatOutput` can turn them into markdown links. Default `false`:
-     * no citation instructions go out, and any tag the model emits anyway
-     * is stripped to plain prose.
-     *
-     * Only turn this on for surfaces that actually render source links
-     * (a research writeup). Claude honors the instruction unreliably —
-     * measured 0/3 runs against claude-sonnet-5, which writes bare
-     * parentheticals like `(Bitcoin Magazine)` instead — so a chat reply
-     * asking for citations tends to get prose with no links either way.
-     * See `npm run cite-rate`.
-     */
-    citations?: boolean;
-    abortSignal?: AbortSignal;
-}
-interface WebSearchHandle {
-    /** Register under {@link WEB_SEARCH_TOOL_NAME}. `undefined` when no
-     *  key is configured for the chosen backend — drop the tool rather
-     *  than failing the request. */
-    tool: any | undefined;
-    backend: SearchBackend | undefined;
-    /** True when the model runs the search server-side (Anthropic). */
-    native: boolean;
-    /** Every result from the run, in citation order. */
-    results: WebSearchResult[];
-    /**
-     * Feed each step's content here (AI SDK `onStepFinish`). Walks
-     * Anthropic tool-results into `results`; a no-op on the Exa path,
-     * where `execute` already appended them. Safe to call either way.
-     */
-    capture(stepContent: unknown): void;
-    /** Citation instructions to append to the system prompt. Empty unless
-     *  `citations: true` was requested. */
-    promptSnippet: string;
-    /**
-     * Run the model's final text through the right citation treatment for
-     * this handle: markdown links when `citations` is on, plain prose when
-     * it isn't. Either way no raw `<cite>` markup survives — a leftover
-     * tag renders as literal text in any GFM viewer.
-     */
-    formatOutput(markdown: string): {
-        content: string;
-        converted: number;
-        skipped: number;
-    };
-}
-declare function getSearchApiKey(): string | undefined;
-declare function hasSearchApiKey(): boolean;
-/**
- * Which backend a provider gets. Anthropic keeps its native tool;
- * everything else falls to Exa.
- */
-declare function resolveSearchBackend(provider: Provider): SearchBackend;
-/**
- * Raw Exa search. Exposed for callers that want results without an LLM
- * in the loop (a research pre-fetch, a URL enrichment pass).
- *
- * Throws on transport/HTTP failure — {@link createWebSearch} catches and
- * hands the model a readable error instead of failing the whole turn.
- */
-declare function searchWeb(query: string, opts?: WebSearchOptions & {
-    apiKey?: string;
-    abortSignal?: AbortSignal;
-}): Promise<WebSearchResult[]>;
-/**
- * Build the `web_search` tool for a run, plus the citation bookkeeping
- * that goes with it. See the module header for the usage shape.
- */
-declare function createWebSearch(opts: CreateWebSearchOptions): WebSearchHandle;
-/**
- * Walk one AI SDK step's content for `web_search` tool-results and
- * append each hit to `target`, in order.
- *
- * Order is load-bearing: Anthropic's `<cite index="N-M">` tags index
- * this flat list 1-based across the entire turn.
- *
- * Tolerates both result shapes (`output` and `result`) and skips any
- * non-array body — adapters vary across AI SDK versions, and a shape we
- * don't recognize should cost us citations, not the run.
- */
-declare function captureNativeResults(stepContent: unknown, target: WebSearchResult[]): void;
-/**
- * Remove citation markup, leaving readable prose.
- *
- * The default treatment when `citations` is off. Models emit `<cite`
- * tags unprompted often enough that we can't just hope: Claude produces
- * them spontaneously with server-side search, and a raw tag renders as
- * literal text in any GFM viewer, which looks broken.
- *
- * Three shapes, in order:
- *   1. Empty markers — `a claim. <cite index="4"></cite>` — are
- *      trailing footnotes with nothing to say. They take their leading
- *      whitespace with them, so the sentence closes up cleanly.
- *   2. Anchored tags collapse to their anchor text, which is the words
- *      the model was sourcing and reads as normal prose.
- *   3. Any orphan `<cite ...>` or `</cite>` left by a truncated stream
- *      is swept, so no half-tag survives a cut-off response.
- */
-declare function stripCitations(markdown: string): string;
-/**
- * Replace `<cite index="N">anchor</cite>` tags with markdown links into
- * `results`. Handles Anthropic's multi-part form (`index="2-1"`,
- * `index="2-1,3-4"`) by keying off the leading number, which is the
- * flat result index.
- *
- * Out-of-range or unresolvable indices collapse to the bare anchor
- * text. That span loses its link, but no raw `<cite>` markup survives
- * into the output — persisted markdown is usually rendered as plain
- * GFM, where a leftover tag shows up as literal text.
- *
- * Models regularly ignore the "anchor text is required" instruction and
- * emit a trailing `<cite index="4"></cite>` marker instead (grok-4 does
- * it consistently). An empty anchor would linkify to `[](url)` — a
- * broken, invisible link — so it falls back to a `[N]` footnote marker.
- */
-declare function linkifyCitations(markdown: string, results: WebSearchResult[]): {
-    content: string;
-    converted: number;
-    skipped: number;
-};
-
-/**
- * Web fetch, uniform across providers. Sibling of `./search.js`.
- *
- * Anthropic ships a server-executed `web_fetch` tool: given a URL, their
- * API retrieves the page (HTML or PDF), turns it into text and hands it
- * to the model with no round-trip through us. Same reasons that make it
- * the best option when available: no extra hop, nothing to host,
- * nothing to secure.
- *
- * Nobody else has one. So, as with search: keep Anthropic native, and
- * give every other provider a client-executed tool of the same name and
- * result shape, backed by a plain HTTP GET plus an HTML-to-text pass.
- *
- * Two things differ from search that consumers should know:
- *
- *   1. On the Anthropic path the model can only fetch URLs that already
- *      appeared in the conversation — pasted by the user, or returned by
- *      an earlier `web_search` / `web_fetch`. It refuses URLs it made
- *      up. The HTTP path has no such memory and fetches whatever the
- *      model asks for; what it WON'T do is reach anything private.
- *
- *   2. The HTTP path runs in *our* process, so the model can point it at
- *      our network. Every URL — and every redirect hop — is checked
- *      before connecting: http(s) only, no credentials, and the host
- *      must resolve exclusively to public unicast addresses (loopback,
- *      RFC 1918, link-local incl. cloud metadata, CGNAT, ULA and the
- *      v4-in-v6 forms are all refused). There is a DNS-rebinding window
- *      between our lookup and the socket's own; pin `allowedDomains` if
- *      the deployment cares.
- *
- * Usage:
- *
- *   const wf = createWebFetch({ provider, apiKey });
- *   const tools = { ...(wf.tool ? { [WEB_FETCH_TOOL_NAME]: wf.tool } : {}) };
- *   // in onStepFinish:  wf.capture(step.content)
- *   // afterwards:       wf.results — every page fetched, in order
- */
-/** Tool name registered with the model. Matches Anthropic's native name
- *  so consumers key UI and step-walking off one string on both paths. */
-declare const WEB_FETCH_TOOL_NAME = "web_fetch";
-/** Which implementation backs the tool. */
-type FetchBackend = "anthropic" | "http";
-/**
- * One fetched page. Same fields on both paths; the notes say where the
- * backends differ in what they put in them.
- */
-interface WebFetchResult {
-    /** Where the content came from. The final URL after redirects on the
-     *  HTTP path; the URL Anthropic reports on the native path. */
-    url: string;
-    title: string | null;
-    /**
-     * Extracted text. Absent for a PDF on the Anthropic path — their API
-     * returns it base64-encoded, which is only useful to their model.
-     */
-    text?: string;
-    /** Original `content-type` on the HTTP path; Anthropic's normalized
-     *  `text/plain` / `application/pdf` on the native path. */
-    mediaType: string | null;
-    retrievedAt: string | null;
-    /** True when the HTTP path cut the text at `maxCharacters`. */
-    truncated?: boolean;
-    type: "web_fetch_result";
-}
-interface WebFetchOptions {
-    /** Max `web_fetch` calls per run. Default 5. Enforced in-process on
-     *  the HTTP path, passed as `max_uses` to Anthropic. */
-    maxUses?: number;
-    /**
-     * Text budget per page on the HTTP path, in characters. Default
-     * 40000 — about 10k tokens. When only `maxContentTokens` is given,
-     * derived from it at 4 chars/token so one option covers both paths.
-     */
-    maxCharacters?: number;
-    /**
-     * Content budget per page on the Anthropic path, in tokens (their
-     * `max_content_tokens`). Unset means Anthropic's own default. When
-     * only `maxCharacters` is given, derived from it.
-     */
-    maxContentTokens?: number;
-    /** Only fetch from these domains. Subdomains are included, so
-     *  `example.com` admits `docs.example.com`. */
-    allowedDomains?: string[];
-    blockedDomains?: string[];
-}
-/** Resolve a hostname to every address it answers with. */
-type HostLookup = (hostname: string) => Promise<string[]>;
-interface CreateWebFetchOptions extends WebFetchOptions {
-    /** LLM provider driving the run — decides the backend. */
-    provider: Provider;
-    /** LLM API key. Only used on the Anthropic path. Falls back to env. */
-    apiKey?: string;
-    /** Force a backend regardless of provider. `"http"` is how you A/B
-     *  the shim against Anthropic's native tool on identical prompts. */
-    backend?: FetchBackend;
-    abortSignal?: AbortSignal;
-    /**
-     * Override hostname resolution on the HTTP path. Tests inject a stub
-     * here; a deployment with its own resolver policy can too. Must return
-     * every address the host resolves to — the guard refuses a host if ANY
-     * of them is private.
-     */
-    lookup?: HostLookup;
-}
-interface WebFetchHandle {
-    /** Register under {@link WEB_FETCH_TOOL_NAME}. `undefined` only when
-     *  the Anthropic path has no API key — drop the tool rather than
-     *  failing the request. The HTTP path needs no key. */
-    tool: any | undefined;
-    backend: FetchBackend | undefined;
-    /** True when the fetch runs server-side (Anthropic). */
-    native: boolean;
-    /** Every page fetched during the run, in order. */
-    results: WebFetchResult[];
-    /**
-     * Feed each step's content here (AI SDK `onStepFinish`). Walks
-     * Anthropic tool-results into `results`; a no-op on the HTTP path,
-     * where `execute` already appended them. Safe to call either way.
-     */
-    capture(stepContent: unknown): void;
-}
-/**
- * Which backend a provider gets. Anthropic keeps its native tool;
- * everything else falls to the HTTP shim.
- */
-declare function resolveFetchBackend(provider: Provider): FetchBackend;
-/**
- * True for an IP literal (v4 or v6, brackets tolerated) the HTTP path
- * refuses to connect to. Anything that isn't an IP literal is `true`
- * too: an address we can't classify isn't one we connect to.
- */
-declare function isPrivateAddress(ip: string): boolean;
-/**
- * Validate a URL before the HTTP path connects to it. Throws a readable
- * error on any rejection — the model gets the message back as the
- * tool's `error` and can pick a different URL.
- *
- * A hostname is resolved and refused if ANY of its addresses is
- * private: a host that answers with a mix is misconfigured or hostile,
- * and we'd have no say in which address the socket picks.
- */
-declare function validateFetchUrl(raw: string, opts?: {
-    allowedDomains?: string[];
-    blockedDomains?: string[];
-    lookup?: HostLookup;
-}): Promise<URL>;
-interface FetchUrlOptions {
-    maxCharacters?: number;
-    allowedDomains?: string[];
-    blockedDomains?: string[];
-    abortSignal?: AbortSignal;
-    timeoutMs?: number;
-    lookup?: HostLookup;
-}
-/**
- * Raw fetch-and-extract. Exposed for callers that want a page without
- * an LLM in the loop (a URL enrichment pass, a link preview).
- *
- * Throws on any rejection or failure — {@link createWebFetch} catches
- * and hands the model a readable error instead of failing the turn.
- */
-declare function fetchUrl(rawUrl: string, opts?: FetchUrlOptions): Promise<WebFetchResult>;
-/**
- * Dependency-free HTML to text. Good enough for a model to read a page;
- * not a renderer. Scripts, styles and SVG go away entirely; block-level
- * boundaries become line breaks; list items get a leading dash; the
- * rest of the markup is dropped and entities decoded. Whitespace is
- * collapsed except for line breaks, so `<pre>` keeps its lines but not
- * its indentation.
- */
-declare function htmlToText(html: string): {
-    title: string | null;
-    text: string;
-};
-/**
- * Build the `web_fetch` tool for a run. See the module header for the
- * usage shape.
- */
-declare function createWebFetch(opts: CreateWebFetchOptions): WebFetchHandle;
-/**
- * Walk one AI SDK step's content for `web_fetch` tool-results and
- * append each page to `target`, in order.
- *
- * Tolerates both result shapes (`output` and `result`) and both key
- * casings for the nested fields — adapters vary across AI SDK versions,
- * and a shape we don't recognize should cost us a bookkeeping entry,
- * not the run. Anthropic's error results (`web_fetch_tool_result_error`)
- * are skipped: there's no page to record.
- */
-declare function captureNativeFetchResults(stepContent: unknown, target: WebFetchResult[]): void;
-
-export { API_KEY_ENV, type AiUsage, type AiUsageWithLegacy, type Conversation, type ConversationData, ConversationStorage, type CreateWebFetchOptions, type CreateWebSearchOptions, DEFAULT_MODELS, type FetchBackend, type FetchUrlOptions, GATEWAY_PATHS, type GetModelOptions, type HostLookup, type LLMConfig, type Logger, MAX_CONVERSATIONS, MODELS, type ModelName, type ModelOption, type ModelRef, OUTRO, PROVIDERS, type ParsedModelName, type Provider, type ProviderTool, type ResolveOptions, type ResolvedModel, SYSTEM, type SearchBackend, type ThinkingSpeed, type TokenPricing, type TokenUsageForCost, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, type WebFetchHandle, type WebFetchOptions, type WebFetchResult, type WebSearchHandle, type WebSearchOptions, type WebSearchResult, addUsage, callGenerateObject, callGenerateText, callModel, canonicalModelName, captureNativeFetchResults, captureNativeResults, computeSessionCost, consoleLogger, createWebFetch, createWebSearch, emptyUsage, fetchUrl, gatewayEnvForProviders, gatewayUrlFor, gatewayUrlForModel, getApiKeyForProvider, getContextLimit, getGatewayBaseURL, getLightModelForProvider, getModel, getModelDetails, getProviderForModel, getProviderOptions, getProviderTool, getSearchApiKey, getTokenPricing, hasApiKeyForProvider, hasSearchApiKey, htmlToText, isPrivateAddress, linkifyCitations, listModels, loadModelPricing, maxOutputTokensFor, normalizeApiKey, normalizeCallerBaseURL, normalizeUsage, parseModelName, resolveFetchBackend, resolveLLMConfig, resolveModel, resolveSearchBackend, searchWeb, stripCitations, validateFetchUrl, withLegacyUsage, withProviderCacheUsage };