@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/provider-ai-sdk.js

@@ -0,0 +1,541 @@
+/**
+ * AI SDK provider backend ("ai-sdk" protocol).
+ *
+ * Consumes AI SDK provider packages at the LanguageModelV3 spec layer
+ * (`model.doStream`) rather than through the high-level `streamText` API:
+ * pre-stream HTTP errors throw natively (which our retry/rate-limit contract
+ * needs), tool-call inputs arrive as JSON strings (matching `argumentsFull`),
+ * and no step machinery or extra dependencies come along.
+ *
+ * Registered providers: google (Gemini native API). Adding another AI SDK
+ * provider is one entry in AI_SDK_PROVIDER_FACTORIES.
+ */
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { APICallError } from "@ai-sdk/provider";
+import { RateLimitError } from "./network/errors.js";
+import { ProviderStreamInterruptedError, computeRetryDelayMs, getProviderMaxRetries, isRetryableHttpStatus, sleepBeforeRetry, } from "./network/retry.js";
+import { createProviderFetch, isProviderTransportError } from "./network/provider-transport.js";
+const GEMINI_DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
+const AI_SDK_PROVIDER_FACTORIES = {
+    google: (options) => {
+        const provider = createGoogleGenerativeAI({
+            apiKey: options.apiKey,
+            ...(options.baseURL ? { baseURL: normalizeBaseURL(options.baseURL) } : {}),
+            ...(options.headers ? { headers: options.headers } : {}),
+            fetch: (options.fetch ?? createProviderFetch({
+                providerName: "Google Gemini",
+                verboseEnvVar: "BUBBLE_AI_SDK_FETCH_VERBOSE",
+            })),
+        });
+        return (modelId) => provider(modelId);
+    },
+};
+export function isAiSdkProviderId(providerId) {
+    return !!providerId && providerId in AI_SDK_PROVIDER_FACTORIES;
+}
+export function createAiSdkProvider(options) {
+    const providerId = options.providerId || "google";
+    const factory = AI_SDK_PROVIDER_FACTORIES[providerId];
+    if (!factory) {
+        const known = Object.keys(AI_SDK_PROVIDER_FACTORIES).join(", ");
+        throw new Error(`Provider "${providerId}" is configured with protocol "ai-sdk" but no AI SDK backend is registered for it (known: ${known}).`);
+    }
+    const getModel = factory(options);
+    async function* streamChat(messages, chatOptions) {
+        const model = getModel(chatOptions.model);
+        const callOptions = buildCallOptions(messages, chatOptions, options);
+        const maxRetries = getProviderMaxRetries();
+        for (let attempt = 0;; attempt++) {
+            let stream;
+            try {
+                ({ stream } = await model.doStream(callOptions));
+            }
+            catch (error) {
+                // No stream established: the request is safe to classify and re-issue.
+                handlePreStreamError(error, {
+                    attempt,
+                    maxRetries,
+                    rateLimitPolicy: chatOptions.rateLimitPolicy,
+                    signal: chatOptions.abortSignal,
+                });
+                await sleepBeforeRetry(computeRetryDelayMs(attempt + 1, { retryAfterMs: retryAfterMsFromError(error) }), chatOptions.abortSignal);
+                continue;
+            }
+            const translator = new StreamTranslator();
+            let surfacedContent = false;
+            try {
+                for await (const part of stream) {
+                    // The SDK surfaces post-200 failures as error parts and lets the
+                    // stream "finish" normally; that would look like an empty reply to
+                    // the agent loop, so convert them back into throws here.
+                    if (part.type === "error") {
+                        throw coerceError(part.error);
+                    }
+                    for (const chunk of translator.translate(part)) {
+                        surfacedContent = surfacedContent || isContentChunk(chunk);
+                        yield chunk;
+                    }
+                }
+                yield { type: "done" };
+                return;
+            }
+            catch (error) {
+                if (chatOptions.abortSignal?.aborted)
+                    throw coerceError(error);
+                if (surfacedContent) {
+                    // Partial content already reached the UI — only the agent loop can
+                    // discard the half-built assistant message and re-issue the request.
+                    throw new ProviderStreamInterruptedError(`Gemini stream interrupted: ${errorMessage(error)}`, { cause: error });
+                }
+                if (attempt >= maxRetries || !isRetryableStreamError(error))
+                    throw coerceError(error);
+                await sleepBeforeRetry(computeRetryDelayMs(attempt + 1), chatOptions.abortSignal);
+            }
+        }
+    }
+    async function complete(messages, completeOptions) {
+        const modelId = completeOptions?.model;
+        if (!modelId)
+            throw new Error("ai-sdk provider requires an explicit model for complete().");
+        const model = getModel(modelId);
+        const callOptions = buildCallOptions(messages, {
+            model: modelId,
+            temperature: completeOptions?.temperature,
+            thinkingLevel: completeOptions?.thinkingLevel ?? "off",
+            abortSignal: completeOptions?.abortSignal,
+        }, options);
+        const result = await model.doGenerate(callOptions);
+        return result.content
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join("");
+    }
+    return { streamChat, complete };
+}
+// ============================================================================
+// Request building
+// ============================================================================
+function buildCallOptions(messages, chatOptions, providerOptions) {
+    const prompt = convertMessages(messages);
+    const thinking = buildGoogleThinkingOptions(chatOptions.model, chatOptions.thinkingLevel ?? providerOptions.thinkingLevel);
+    return {
+        prompt,
+        ...(chatOptions.temperature !== undefined ? { temperature: chatOptions.temperature } : {}),
+        ...(chatOptions.abortSignal ? { abortSignal: chatOptions.abortSignal } : {}),
+        ...(chatOptions.tools?.length
+            ? {
+                tools: chatOptions.tools.map((tool) => ({
+                    type: "function",
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.parameters,
+                })),
+                toolChoice: { type: chatOptions.toolChoice === "none" ? "none" : "auto" },
+            }
+            : {}),
+        ...(thinking ? { providerOptions: { google: thinking } } : {}),
+    };
+}
+/**
+ * Gemini 3+ models take a graded thinking_level; 2.5-era models take a token
+ * budget. "off" (budget 0) is only offered in the catalog for models that
+ * accept it (2.5 Flash); xhigh/max/ultra clamp to high.
+ */
+function buildGoogleThinkingOptions(modelId, level) {
+    if (!level)
+        return undefined;
+    const version = geminiVersion(modelId);
+    // Gemini 4 accepts only low/medium/high: MINIMAL is a 400 and thinkingBudget
+    // is undocumented. Side calls (titles, compaction) request "off" by default,
+    // so floor those at low rather than sending a value the API rejects.
+    if (version >= 4 && (level === "off" || level === "minimal"))
+        level = "low";
+    if (level === "off")
+        return { thinkingConfig: { thinkingBudget: 0 } };
+    const clamped = level === "xhigh" || level === "max" || level === "ultra" ? "high" : level;
+    if (version >= 3) {
+        return { thinkingConfig: { thinkingLevel: clamped, includeThoughts: true } };
+    }
+    const budgets = { minimal: 512, low: 2048, medium: 8192, high: 24576 };
+    return { thinkingConfig: { thinkingBudget: budgets[clamped] ?? 8192, includeThoughts: true } };
+}
+function convertMessages(messages) {
+    const out = [];
+    const toolNamesById = new Map();
+    for (const message of messages) {
+        if (message.role === "system") {
+            out.push({ role: "system", content: message.content });
+            continue;
+        }
+        if (message.role === "user") {
+            out.push({ role: "user", content: convertUserContent(message.content) });
+            continue;
+        }
+        if (message.role === "assistant") {
+            for (const call of message.toolCalls ?? [])
+                toolNamesById.set(call.id, call.name);
+            const content = convertAssistantContent(message);
+            if (content.length > 0)
+                out.push({ role: "assistant", content });
+            continue;
+        }
+        // tool result
+        out.push({
+            role: "tool",
+            content: [{
+                    type: "tool-result",
+                    toolCallId: message.toolCallId,
+                    toolName: toolNamesById.get(message.toolCallId) ?? "unknown_tool",
+                    output: toToolResultOutput(message.content, message.isError),
+                }],
+        });
+    }
+    return out;
+}
+function convertUserContent(content) {
+    if (typeof content === "string")
+        return [{ type: "text", text: content }];
+    const parts = [];
+    for (const part of content) {
+        if (part.type === "text" && typeof part.text === "string") {
+            parts.push({ type: "text", text: part.text });
+        }
+        else if (part.type === "image_url" && part.image_url?.url) {
+            parts.push(toImageFilePart(part.image_url.url));
+        }
+    }
+    return parts.length > 0 ? parts : [{ type: "text", text: "" }];
+}
+function toImageFilePart(url) {
+    const dataUrl = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(url);
+    if (dataUrl) {
+        return {
+            type: "file",
+            mediaType: dataUrl[1] || "image/png",
+            data: dataUrl[2] ? dataUrl[3] : decodeURIComponent(dataUrl[3]),
+        };
+    }
+    const extension = /\.(png|jpe?g|gif|webp)(?:[?#]|$)/i.exec(url)?.[1]?.toLowerCase();
+    const mediaType = extension === "jpg" || extension === "jpeg"
+        ? "image/jpeg"
+        : extension
+            ? `image/${extension}`
+            : "image/png";
+    return { type: "file", mediaType, data: new URL(url) };
+}
+function convertAssistantContent(message) {
+    const parts = [];
+    const blocks = message.providerMetadata?.google?.contentBlocks ?? [];
+    const toolCallSignatures = new Map();
+    // Replay captured Gemini parts: signed reasoning comes back verbatim so the
+    // thought signature round-trips; tool-call signatures re-attach by id.
+    for (const block of blocks) {
+        if (block.type === "reasoning" && typeof block.text === "string" && typeof block.thoughtSignature === "string") {
+            parts.push({
+                type: "reasoning",
+                text: block.text,
+                providerOptions: { google: { thoughtSignature: block.thoughtSignature } },
+            });
+        }
+        else if (block.type === "tool-call" && typeof block.toolCallId === "string" && typeof block.thoughtSignature === "string") {
+            toolCallSignatures.set(block.toolCallId, block.thoughtSignature);
+        }
+    }
+    if (message.content)
+        parts.push({ type: "text", text: message.content });
+    for (const call of message.toolCalls ?? []) {
+        const signature = toolCallSignatures.get(call.id);
+        parts.push({
+            type: "tool-call",
+            toolCallId: call.id,
+            toolName: call.name,
+            input: parseToolArguments(call.arguments),
+            ...(signature ? { providerOptions: { google: { thoughtSignature: signature } } } : {}),
+        });
+    }
+    return parts;
+}
+function parseToolArguments(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function toToolResultOutput(content, isError) {
+    return isError ? { type: "error-text", value: content } : { type: "text", value: content };
+}
+function normalizeBaseURL(baseURL) {
+    return baseURL.trim().replace(/\/+$/, "");
+}
+// ============================================================================
+// Stream translation
+// ============================================================================
+class StreamTranslator {
+    reasoningText = "";
+    reasoningSignature;
+    toolNamesById = new Map();
+    translate(part) {
+        switch (part.type) {
+            case "text-delta":
+                return part.delta ? [{ type: "text", content: part.delta }] : [];
+            case "reasoning-start":
+                this.reasoningText = "";
+                this.reasoningSignature = thoughtSignatureOf(part.providerMetadata);
+                return [];
+            case "reasoning-delta": {
+                this.reasoningText += part.delta;
+                this.reasoningSignature ??= thoughtSignatureOf(part.providerMetadata);
+                return part.delta ? [{ type: "reasoning_delta", content: part.delta }] : [];
+            }
+            case "reasoning-end": {
+                this.reasoningSignature ??= thoughtSignatureOf(part.providerMetadata);
+                if (!this.reasoningSignature || !this.reasoningText)
+                    return [];
+                const block = {
+                    type: "reasoning",
+                    text: this.reasoningText,
+                    thoughtSignature: this.reasoningSignature,
+                };
+                this.reasoningText = "";
+                this.reasoningSignature = undefined;
+                return [{ type: "provider_content_block", provider: "google", block }];
+            }
+            case "tool-input-start":
+                this.toolNamesById.set(part.id, part.toolName);
+                return [{ type: "tool_call", id: part.id, name: part.toolName, arguments: "", isStart: true, isEnd: false }];
+            case "tool-input-delta": {
+                if (!part.delta)
+                    return [];
+                const name = this.toolNamesById.get(part.id) ?? "";
+                return [{ type: "tool_call", id: part.id, name, arguments: part.delta, isStart: false, isEnd: false }];
+            }
+            case "tool-call": {
+                const argumentsFull = typeof part.input === "string" ? part.input : JSON.stringify(part.input ?? {});
+                const chunks = [{
+                        type: "tool_call",
+                        id: part.toolCallId,
+                        name: part.toolName,
+                        arguments: "",
+                        isStart: false,
+                        isEnd: true,
+                        argumentsFull,
+                    }];
+                const signature = thoughtSignatureOf(part.providerMetadata);
+                if (signature) {
+                    chunks.push({
+                        type: "provider_content_block",
+                        provider: "google",
+                        block: { type: "tool-call", toolCallId: part.toolCallId, thoughtSignature: signature },
+                    });
+                }
+                return chunks;
+            }
+            case "finish": {
+                const usage = translateUsage(part.usage);
+                return usage ? [{ type: "usage", usage }] : [];
+            }
+            default:
+                // stream-start, response-metadata, text-start/end, tool-input-end,
+                // source, raw: nothing to surface.
+                return [];
+        }
+    }
+}
+function thoughtSignatureOf(metadata) {
+    const signature = metadata?.google?.thoughtSignature;
+    return typeof signature === "string" && signature.length > 0 ? signature : undefined;
+}
+function translateUsage(usage) {
+    const inputTokens = usage?.inputTokens?.total;
+    const outputTokens = usage?.outputTokens?.total;
+    // Without a real input count the chunk would poison the agent's context
+    // budget tracking (lastInputTokens), so skip rather than report zeros.
+    if (!Number.isFinite(inputTokens))
+        return undefined;
+    const result = {
+        promptTokens: inputTokens,
+        completionTokens: Number.isFinite(outputTokens) ? outputTokens : 0,
+    };
+    const cacheRead = usage?.inputTokens?.cacheRead;
+    const noCache = usage?.inputTokens?.noCache;
+    const cacheWrite = usage?.inputTokens?.cacheWrite;
+    const reasoning = usage?.outputTokens?.reasoning;
+    if (Number.isFinite(cacheRead))
+        result.promptCacheHitTokens = cacheRead;
+    if (Number.isFinite(noCache))
+        result.promptCacheMissTokens = noCache;
+    if (Number.isFinite(cacheWrite))
+        result.cacheCreationTokens = cacheWrite;
+    if (Number.isFinite(reasoning))
+        result.reasoningTokens = reasoning;
+    if (Number.isFinite(inputTokens) && Number.isFinite(outputTokens)) {
+        result.totalTokens = inputTokens + outputTokens;
+    }
+    return result;
+}
+function isContentChunk(chunk) {
+    return chunk.type === "text" || chunk.type === "reasoning_delta" || chunk.type === "tool_call";
+}
+// ============================================================================
+// Error handling
+// ============================================================================
+/**
+ * Classify a pre-stream error. Throws (RateLimitError / the original error)
+ * when the request must not be retried here; returns normally when the caller
+ * should back off and retry.
+ */
+function handlePreStreamError(error, context) {
+    if (context.signal?.aborted)
+        throw coerceError(error);
+    const status = APICallError.isInstance(error) ? error.statusCode : undefined;
+    if (status === 429) {
+        const retryAfterMs = retryAfterMsFromError(error);
+        if (context.rateLimitPolicy === "defer") {
+            // Rate-limit contract: under "defer" the transport does no 429 backoff;
+            // the subagent scheduler owns it.
+            throw new RateLimitError(`Gemini API rate limited (429): ${errorMessage(error)}`, {
+                status: 429,
+                retryAfterMs,
+                cause: error,
+            });
+        }
+        if (context.attempt >= context.maxRetries) {
+            throw new RateLimitError(`Gemini API rate limited (429) after ${context.attempt + 1} attempts: ${errorMessage(error)}`, { status: 429, retryAfterMs, cause: error });
+        }
+        return;
+    }
+    const retryable = APICallError.isInstance(error)
+        ? (error.isRetryable || (typeof status === "number" && isRetryableHttpStatus(status)))
+        : isProviderTransportError(error);
+    if (!retryable || context.attempt >= context.maxRetries)
+        throw coerceError(error);
+}
+function retryAfterMsFromError(error) {
+    if (!APICallError.isInstance(error))
+        return undefined;
+    const header = error.responseHeaders?.["retry-after"]?.trim();
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.round(seconds * 1000);
+    const date = Date.parse(header);
+    if (!Number.isNaN(date))
+        return Math.max(0, date - Date.now());
+    return undefined;
+}
+function isRetryableStreamError(error) {
+    if (APICallError.isInstance(error)) {
+        return error.isRetryable || (typeof error.statusCode === "number" && isRetryableHttpStatus(error.statusCode));
+    }
+    return isProviderTransportError(error);
+}
+function coerceError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// Specialised variants that are not general text/coding models.
+const GEMINI_MODEL_EXCLUDE = /(tts|image|audio|embedding|live|computer-use|robotics|banana|aqa|learnlm|gemma|imagen|veo)/i;
+/**
+ * Fetch Google's model list and keep the newest general-purpose text models.
+ * Newly released Gemini versions appear without a catalog change; the static
+ * BUILTIN_MODELS entries stay as the offline/no-key fallback.
+ */
+export async function fetchGeminiModels(options) {
+    const baseURL = normalizeBaseURL(options.baseURL || GEMINI_DEFAULT_BASE_URL);
+    const fetchImpl = options.fetch ?? createProviderFetch({
+        providerName: "Google Gemini",
+        verboseEnvVar: "BUBBLE_AI_SDK_FETCH_VERBOSE",
+    });
+    const response = await fetchImpl(`${baseURL}/models?pageSize=1000`, {
+        headers: { "x-goog-api-key": options.apiKey },
+    });
+    if (!response.ok) {
+        throw new Error(`Gemini model list failed (${response.status}): ${await response.text().catch(() => response.statusText)}`);
+    }
+    const data = await response.json();
+    return selectLatestGeminiModels(data.models ?? [], options.limit ?? 5);
+}
+/**
+ * Ranking: one entry per (version, tier) family — GA ids beat dated previews —
+ * then newest version first, flagship (pro/argon) before flash before
+ * flash-lite, top N.
+ */
+export function selectLatestGeminiModels(entries, limit = 5) {
+    // Gemini 4 introduced named flagship tiers (gemini-4-argon). Unknown names
+    // stay excluded rather than guessing whether they are text models.
+    const TIER_RANK = { argon: 0, pro: 0, flash: 1, "flash-lite": 2 };
+    const candidates = [];
+    for (const entry of entries) {
+        const id = (entry.name ?? "").replace(/^models\//, "");
+        if (!id.startsWith("gemini-"))
+            continue;
+        if (GEMINI_MODEL_EXCLUDE.test(id))
+            continue;
+        if (entry.supportedGenerationMethods && !entry.supportedGenerationMethods.includes("generateContent"))
+            continue;
+        const match = /^gemini-(\d+(?:\.\d+)?)-(argon|pro|flash)(-lite)?/.exec(id);
+        if (!match)
+            continue;
+        const tier = `${match[2]}${match[3] ?? ""}`;
+        candidates.push({
+            id,
+            entry,
+            version: Number.parseFloat(match[1]),
+            tier,
+            tierRank: TIER_RANK[tier] ?? 3,
+            isPreview: id.includes("preview") || id.includes("exp"),
+        });
+    }
+    // One winner per family: GA over preview, then the shortest (least-suffixed) id.
+    const families = new Map();
+    for (const candidate of candidates) {
+        const key = `${candidate.version}-${candidate.tier}`;
+        const current = families.get(key);
+        if (!current
+            || (current.isPreview && !candidate.isPreview)
+            || (current.isPreview === candidate.isPreview && candidate.id.length < current.id.length)) {
+            families.set(key, candidate);
+        }
+    }
+    return [...families.values()]
+        .sort((a, b) => (b.version - a.version) || (a.tierRank - b.tierRank))
+        .slice(0, limit)
+        .map((candidate) => ({
+        id: candidate.id,
+        name: candidate.entry.displayName || candidate.id,
+        contextWindow: Number.isFinite(candidate.entry.inputTokenLimit) ? candidate.entry.inputTokenLimit : undefined,
+        reasoningLevels: geminiReasoningLevels(candidate.id),
+        // Argon defaults to Google's recommended medium via the catalog.
+        ...(candidate.tier === "pro" ? { defaultReasoningLevel: "high" } : {}),
+    }));
+}
+function geminiVersion(modelId) {
+    return Number.parseFloat(/^gemini-(\d+(?:\.\d+)?)/.exec(modelId)?.[1] ?? "0");
+}
+/** Mirrors the static catalog's per-family thinking support. */
+export function geminiReasoningLevels(modelId) {
+    const version = geminiVersion(modelId);
+    const isPro = modelId.includes("-pro");
+    if (version >= 4)
+        return ["low", "medium", "high"];
+    // Live probes show 3.7 and 3.8 Flash share this newer ladder. Keep the
+    // exception bounded to verified releases instead of guessing for 3.9+.
+    if (!isPro && (version === 3.7 || version === 3.8)) {
+        return ["off", "low", "medium", "high"];
+    }
+    if (version >= 3) {
+        return isPro ? ["low", "medium", "high"] : ["minimal", "low", "medium", "high"];
+    }
+    if (version >= 2.5) {
+        return isPro ? ["low", "medium", "high"] : ["off", "low", "medium", "high"];
+    }
+    return ["off"];
+}

package/dist/provider-anthropic.d.ts

@@ -0,0 +1,126 @@
+import type { Provider, ProviderMessage, StreamChunk, ThinkingLevel, ToolChoiceMode, ToolDefinition } from "./types.js";
+declare const ANTHROPIC_PROMPT_CACHE_CONTROL: {
+    readonly type: "ephemeral";
+};
+export interface AnthropicProviderOptions {
+    providerId?: string;
+    apiKey: string;
+    baseURL: string;
+    thinkingLevel?: ThinkingLevel;
+    /** User-configured extra headers, merged last (client-identity gates). */
+    headers?: Record<string, string>;
+}
+interface AnthropicRequest {
+    model: string;
+    max_tokens: number;
+    messages: AnthropicMessage[];
+    system?: string | AnthropicSystemBlock[];
+    tools?: AnthropicTool[];
+    tool_choice?: {
+        type: "auto" | "any" | "none";
+    };
+    stream?: boolean;
+    temperature?: number;
+    thinking?: {
+        type: "adaptive" | "enabled" | "disabled";
+        display?: "summarized";
+        block_binding?: {
+            prefix_mismatch_behavior: "drop_block";
+        };
+    };
+    output_config?: {
+        effort: AnthropicEffort;
+    };
+}
+type AnthropicEffort = "low" | "medium" | "high" | "xhigh" | "max";
+type AnthropicCacheControl = typeof ANTHROPIC_PROMPT_CACHE_CONTROL;
+interface AnthropicSystemBlock {
+    type: "text";
+    text: string;
+    cache_control?: AnthropicCacheControl;
+}
+type AnthropicContentBlock = {
+    type: "text";
+    text: string;
+    cache_control?: AnthropicCacheControl;
+} | {
+    type: "image";
+    source: {
+        type: "url";
+        url: string;
+    } | {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+    cache_control?: AnthropicCacheControl;
+} | {
+    type: "thinking";
+    thinking: string;
+    signature?: string;
+} | {
+    type: "redacted_thinking";
+    data: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    cache_control?: AnthropicCacheControl;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+    cache_control?: AnthropicCacheControl;
+};
+interface AnthropicMessage {
+    role: "user" | "assistant";
+    content: string | AnthropicContentBlock[];
+}
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: ToolDefinition["parameters"];
+    cache_control?: AnthropicCacheControl;
+}
+export declare function createAnthropicMessagesProvider(options: AnthropicProviderOptions): Provider;
+export declare function buildAnthropicRequest(options: AnthropicProviderOptions, messages: ProviderMessage[], chatOptions: {
+    model: string;
+    tools?: ToolDefinition[];
+    toolChoice?: ToolChoiceMode;
+    temperature?: number;
+    thinkingLevel?: ThinkingLevel;
+    stream?: boolean;
+}): AnthropicRequest;
+/**
+ * Roll prompt-cache breakpoints along the conversation so each turn's context is
+ * read back on the next turn instead of being re-billed as fresh input.
+ *
+ * Two breakpoints, and both are load-bearing:
+ *
+ * - the **tail** (last block of the last message) writes the entry that the next
+ *   request reads;
+ * - the **anchor** reads it. It goes on the message just before the final
+ *   assistant message — which is exactly where the previous request ended, since
+ *   consecutive agent-loop requests differ by one `[assistant, tool results]`
+ *   step. Landing on the written position directly is what makes this correct
+ *   for any turn size: Anthropic only looks back 20 content blocks from a
+ *   breakpoint to find a prior write, and a turn with many parallel tool calls
+ *   easily exceeds that (1 + 2N blocks for N calls). Measured on Opus 4.8 with
+ *   30 parallel calls: tail-only and a fixed-distance anchor both collapse to an
+ *   8.6% hit rate, while this anchor holds 77%.
+ *
+ * Mutates `messages` (built fresh per request by toAnthropicMessages) and
+ * returns how many breakpoints it used, never more than `budget`.
+ */
+export declare function placeMessageCacheBreakpoints(messages: AnthropicMessage[], budget: number): number;
+export declare function resolveAnthropicMaxTokens(options: AnthropicProviderOptions, model: string): number;
+export declare function supportsAnthropicPromptCache(options: AnthropicProviderOptions, model: string): boolean;
+export declare function toAnthropicMessages(messages: ProviderMessage[], echoThinking?: boolean | "all", allowUnsignedThinking?: boolean): {
+    system: string;
+    messages: AnthropicMessage[];
+};
+export declare function translateAnthropicStream(events: AsyncIterable<Record<string, unknown>>): AsyncIterable<StreamChunk>;
+export declare function readSseEvents(response: Response): AsyncIterable<Record<string, unknown>>;
+export {};