@verevoir/review 0.3.0 → 0.3.2

package/node_modules/@verevoir/llm/dist/anthropic/index.js

@@ -0,0 +1,711 @@
+/**
+ * @verevoir/llm/anthropic — Anthropic SDK adapter.
+ *
+ * Wraps `@anthropic-ai/sdk` in the provider-agnostic surface defined in
+ * the core. Importing this subpath requires `@anthropic-ai/sdk` as a
+ * peer dependency on the consumer.
+ *
+ * The model catalogue itself (PROVIDER, CATALOG) lives in `./catalog.js`,
+ * which has no SDK import — a consumer that only needs to resolve a model
+ * term (not place a real call) can import `@verevoir/llm/catalog` instead
+ * and never pull in `@anthropic-ai/sdk` at all. This file still imports and
+ * registers it exactly as before, so nothing here changes for an existing
+ * consumer of this subpath.
+ */
+import { fireUsageHook } from '../audit-hook.js';
+import { withGenAISpan } from '../otel.js';
+import { isAuthError, noteOAuthRejected, oauthSystemIdentity, resolveClient } from './client.js';
+import { PROVIDER, CATALOG, CONNECTION } from './catalog.js';
+import { registerModelCatalog, registerProviderConnection, } from '../index.js';
+// ────────────────────────────────────────────────────────────────────
+// Public model table
+// ────────────────────────────────────────────────────────────────────
+export { PROVIDER };
+// Register the catalog into the core so normalisation, family-level pricing,
+// and labels work for any consumer (and any future version of these families).
+// Import side-effect; idempotent. Also registers currentId + aliases as labels.
+registerModelCatalog([...CATALOG]);
+/**
+ * Concrete model id per {@link ModelClass}, derived from {@link CATALOG} — the
+ * only place a call site needs. Upgrades happen in the catalog, not here.
+ */
+export const models = Object.fromEntries(CATALOG.filter((e) => e.modelClass).map((e) => [e.modelClass, e.currentId]));
+/**
+ * Per-model pricing keyed by the concrete current id, derived from
+ * {@link CATALOG}. Kept for back-compat with consumers that look pricing up by
+ * exact id.
+ *
+ * @deprecated Part of the old static-rates cost API. Use
+ * `createPriceBook(...)` / `book.costOf(...)` instead (see `src/pricing.ts`)
+ * — it prices from LiteLLM's live table (the bundled snapshot as fallback)
+ * and reports an unmatched model as `unpriced` rather than `0`.
+ */
+export const rates = Object.fromEntries(CATALOG.map((e) => [e.currentId, e.rates]));
+// ────────────────────────────────────────────────────────────────────
+// Internal
+// ────────────────────────────────────────────────────────────────────
+registerProviderConnection(CONNECTION);
+// Credential resolution, client construction, and the OAuth→API-key fallback live
+// in ./client.js (internal — off the public surface): `resolveClient`,
+// `isAuthError`, `noteOAuthRejected` and `oauthSystemIdentity` (imported above),
+// plus `resolveAnthropicAuth` + the reset seam the co-located tests import. The
+// mutable client/latch state is private to that module. `streamedCall` below drives it.
+/**
+ * Run a streamed model call with a one-time, session-wide OAuth→API-key fallback
+ * on an authentication error. The subscription-OAuth path leans on undocumented
+ * headers + an identity gate that can change; rather than hard-fail every call
+ * when they do, a 401 falls back to the metered key — but LOUDLY (see
+ * {@link noteOAuthRejected}), never silently resuming the spend the OAuth path
+ * exists to avoid. `makeRequest(oauth)` rebuilds the payload for the chosen auth
+ * (the OAuth path carries the Claude-Code identity system block; the key path
+ * does not), so the fallback request is correctly shaped — not the OAuth request
+ * retried against a key. Fallback fires only when the failed call was
+ * OAuth-authed, no per-call key was supplied, and a metered key is available.
+ */
+async function streamedCall(perCallApiKey, makeRequest, onProgress, onRetry) {
+    const first = resolveClient(perCallApiKey);
+    try {
+        const result = await callWithRetries(() => callStreamed(first.client, makeRequest(first.oauth), onProgress), onRetry);
+        return { ...result, route: first.oauth ? 'subscription-oauth' : 'api-key' };
+    }
+    catch (err) {
+        const canFallBack = first.oauth && !perCallApiKey && isAuthError(err) && !!process.env.ANTHROPIC_API_KEY?.trim();
+        if (!canFallBack)
+            throw err;
+        noteOAuthRejected(err);
+        const fallback = resolveClient(perCallApiKey); // now the metered-key client
+        const result = await callWithRetries(() => callStreamed(fallback.client, makeRequest(fallback.oauth), onProgress), onRetry);
+        return { ...result, route: fallback.oauth ? 'subscription-oauth' : 'api-key' };
+    }
+}
+// 16384 is the next escalation after 8192 hit the cap on a real
+// large-synthesis output. Anthropic Opus 4.7 supports 16k output
+// tokens; raising the cap doesn't increase cost unless the response
+// actually grows. This is the DEFAULT, not a ceiling on what a caller
+// can ask for — a caller with its own evidence of needing more (e.g.
+// aigency-governance's review panel, raised to 65536 after this exact
+// default truncated four of five lenses on one real diff) can override
+// it per call via ChatOptions.maxTokens, rather than every caller
+// silently inheriting whatever number lives here.
+const MAX_TOKENS = 16384;
+// The `report_progress` tool, auto-injected when the caller provides
+// `onProgress`. Description deliberately discourages over-use — the
+// cost of too many narrations is chat noise, the cost of too few is
+// silence.
+const REPORT_PROGRESS_TOOL = {
+    name: 'report_progress',
+    description: 'Report progress on a long-running task. Call 2-4 times during the work to keep the customer informed. percent should be 5-90 (not 0 or 100; the system handles those boundaries). message should be a short customer-facing status. Do NOT call on quick tasks or for final outputs — only mid-flight on substantive generation.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            percent: {
+                type: 'number',
+                description: 'Progress percentage in the range 5-90.',
+            },
+            message: {
+                type: 'string',
+                description: 'Short customer-facing status message.',
+            },
+        },
+        required: ['percent', 'message'],
+    },
+};
+// One ephemeral breakpoint shape, reused for every cache_control we
+// place. 5-minute TTL (the default) — long enough to span a tool
+// loop's burst of correlated calls.
+const EPHEMERAL_CACHE = { type: 'ephemeral' };
+/**
+ * Attach a cache_control breakpoint to the last content block of the
+ * last message, converting string content to a single text block so
+ * the marker has somewhere to live.
+ *
+ * This is the conversation-prefix half of prompt caching, used by the
+ * tool loop: each iteration re-sends a growing message history, so a
+ * breakpoint at the end lets the *next* iteration read the prior
+ * prefix from cache (~0.1× input cost) instead of reprocessing it at
+ * full price. The system breakpoint already caches tools + system;
+ * this caches the conversation that follows.
+ *
+ * Not used for single-shot `chat` / `chatWithTools`: there the last
+ * block is the varying current question, so a breakpoint on it would
+ * only write a cache entry that never gets read.
+ */
+function withConversationCacheBreakpoint(messages) {
+    if (messages.length === 0)
+        return messages;
+    const out = messages.slice();
+    const last = out[out.length - 1];
+    if (typeof last.content === 'string') {
+        out[out.length - 1] = {
+            ...last,
+            content: [{ type: 'text', text: last.content, cache_control: EPHEMERAL_CACHE }],
+        };
+    }
+    else if (Array.isArray(last.content) && last.content.length > 0) {
+        const blocks = last.content;
+        out[out.length - 1] = {
+            ...last,
+            content: blocks.map((block, i) => i === blocks.length - 1 ? { ...block, cache_control: EPHEMERAL_CACHE } : block),
+        };
+    }
+    return out;
+}
+function buildRequest({ modelClass, systemPrompt, turns, tools, cacheConversation = false, oauth = false, model, maxTokens, }) {
+    // Render order is tools → system → messages, so the breakpoint on
+    // the (single) system block caches the tools + system prefix
+    // together — no separate tool breakpoint needed.
+    const messages = turns.map((t) => ({ role: t.role, content: t.content }));
+    // OAuth path: the Claude-Code identity leads as the first system block; the
+    // cache breakpoint stays on the prompt block so identity + prompt cache together.
+    const promptBlock = { type: 'text', text: systemPrompt, cache_control: EPHEMERAL_CACHE };
+    const base = {
+        model: model ?? models[modelClass],
+        max_tokens: maxTokens ?? MAX_TOKENS,
+        system: oauth
+            ? [{ type: 'text', text: oauthSystemIdentity() }, promptBlock]
+            : [promptBlock],
+        messages: cacheConversation ? withConversationCacheBreakpoint(messages) : messages,
+    };
+    if (tools && tools.length > 0) {
+        base.tools = tools;
+    }
+    return base;
+}
+async function callStreamed(client, request, onProgress) {
+    const requestModel = typeof request.model === 'string' ? request.model : 'unknown';
+    return withGenAISpan({ provider: PROVIDER, requestModel }, async () => {
+        // The cast goes through `unknown` because the SDK's MessageStreamParams
+        // is a structural shape we can't match without pinning to its full
+        // generic. `buildRequest` is the source of truth for valid payloads.
+        const stream = client.messages.stream(request);
+        if (onProgress) {
+            stream.on('contentBlock', (block) => {
+                if (block.type !== 'tool_use' || block.name !== 'report_progress') {
+                    return;
+                }
+                const input = block.input;
+                const info = {
+                    percent: typeof input.percent === 'number' ? input.percent : 50,
+                    message: typeof input.message === 'string' ? input.message : '…',
+                };
+                void (async () => {
+                    try {
+                        await onProgress(info);
+                    }
+                    catch (err) {
+                        console.warn('callStreamed: onProgress callback threw', err);
+                    }
+                })();
+            });
+        }
+        const final = await stream.finalMessage();
+        const texts = [];
+        const toolUses = [];
+        const progressToolUses = [];
+        for (const block of final.content) {
+            if (block.type === 'text') {
+                texts.push(block.text);
+            }
+            else if (block.type === 'tool_use' && block.name === 'report_progress') {
+                progressToolUses.push({
+                    id: block.id,
+                    input: (block.input ?? {}),
+                });
+            }
+            else if (block.type === 'tool_use') {
+                toolUses.push({
+                    id: block.id,
+                    name: block.name,
+                    input: (block.input ?? {}),
+                });
+            }
+        }
+        // The SDK's stable Usage type has cache fields as `number | null`;
+        // the beta variants have them as plain numbers. Null-coalesce to 0
+        // either way so the rollup is well-formed.
+        const u = final.usage;
+        const cacheCreation = u
+            .cache_creation;
+        const result = {
+            text: texts.join('\n'),
+            toolUses,
+            progressToolUses,
+            rawUsage: {
+                inputTokens: u.input_tokens ?? 0,
+                outputTokens: u.output_tokens ?? 0,
+                cacheCreationInputTokens: u.cache_creation_input_tokens ?? 0,
+                cacheReadInputTokens: u.cache_read_input_tokens ?? 0,
+                cacheCreationEphemeral5mInputTokens: cacheCreation?.ephemeral_5m_input_tokens,
+                cacheCreationEphemeral1hInputTokens: cacheCreation?.ephemeral_1h_input_tokens,
+            },
+            stopReason: final.stop_reason ?? '',
+            responseId: final.id,
+        };
+        return {
+            result,
+            outcome: {
+                // providerRequestId: the request-id HTTP header isn't reachable here —
+                // the Anthropic SDK's streaming surface (`messages.stream`) doesn't
+                // expose the raw HTTP response the way `.create().withResponse()`
+                // does. Falling back to the message id (`final.id`, same value as
+                // `responseId`/gen_ai.response.id) as the next-best "the provider's
+                // own id for this call" — real, just not the header.
+                responseModel: final.model,
+                responseId: final.id,
+                providerRequestId: final.id,
+                inputTokens: result.rawUsage.inputTokens,
+                outputTokens: result.rawUsage.outputTokens,
+                cacheReadInputTokens: result.rawUsage.cacheReadInputTokens,
+                cacheCreationInputTokens: result.rawUsage.cacheCreationInputTokens,
+                cacheCreationEphemeral5mInputTokens: result.rawUsage.cacheCreationEphemeral5mInputTokens,
+                cacheCreationEphemeral1hInputTokens: result.rawUsage.cacheCreationEphemeral1hInputTokens,
+            },
+        };
+    });
+}
+// Anthropic outages of ~1 hour are real. Single-shot retry isn't
+// enough — keep trying with exponential backoff so the caller can
+// narrate the wait. Total budget ~2 min, comfortably under typical
+// serverless request timeouts. Outages longer than this exhaust the
+// budget and the underlying error surfaces.
+const RETRY_BACKOFFS_MS = [
+    5_000, //   5 sec
+    30_000, //  30 sec
+    120_000, // 2 min
+];
+async function callWithRetries(call, onRetry) {
+    for (let i = 0; i <= RETRY_BACKOFFS_MS.length; i++) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            const reason = retriableReason(err);
+            if (!reason)
+                throw err;
+            if (i === RETRY_BACKOFFS_MS.length)
+                throw err;
+            const delayMs = RETRY_BACKOFFS_MS[i];
+            if (onRetry) {
+                try {
+                    await onRetry({
+                        attempt: i + 1,
+                        maxAttempts: RETRY_BACKOFFS_MS.length,
+                        delayMs,
+                        reason,
+                    });
+                }
+                catch (notifyErr) {
+                    console.warn('callWithRetries: onRetry callback threw', notifyErr);
+                }
+            }
+            await delay(delayMs);
+        }
+    }
+    throw new Error('callWithRetries: exited loop without return or throw');
+}
+function retriableReason(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    const candidate = err;
+    const status = candidate.status;
+    const message = typeof candidate.message === 'string' ? candidate.message : '';
+    if (status === 529 || /\b529\b|overloaded_error/i.test(message)) {
+        return 'Anthropic overloaded (529)';
+    }
+    if (status === 503 || /\b503\b|service[_ ]unavailable/i.test(message)) {
+        return 'Anthropic service unavailable (503)';
+    }
+    if (status === 500 || /\b500\b|internal_server_error/i.test(message)) {
+        return 'Anthropic internal error (500)';
+    }
+    if (status === 429 || /\b429\b|rate[_ ]limit/i.test(message)) {
+        return 'Anthropic rate-limited (429)';
+    }
+    return null;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function shapeUsage(raw, direction, route, modelId, 
+// Only chat()'s call sites pass this today — see chat()'s own call sites
+// for why chatWithTools / chatWithToolLoop don't yet report it.
+responseId) {
+    return {
+        provider: PROVIDER,
+        model: modelId,
+        direction,
+        route,
+        ...raw,
+        providerRequestId: responseId,
+    };
+}
+/** Collapse the routes seen across an aggregated result's underlying calls to
+ * one {@link CredentialRoute} — the single route if every call agreed, else
+ * `'mixed'`, reported rather than picking one arbitrarily and hiding the
+ * other. Never called with an empty array: every aggregate return site has
+ * made at least one underlying call by the time it returns. */
+function combineRoutes(routes) {
+    const distinct = new Set(routes);
+    return distinct.size === 1 ? routes[0] : 'mixed';
+}
+/** Throw the AbortSignal's reason (or a generic AbortError) when
+ * the signal is aborted. No-op when no signal is provided or the
+ * signal has not been aborted. */
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    if (signal.reason instanceof Error)
+        throw signal.reason;
+    if (signal.reason !== undefined)
+        throw new Error(String(signal.reason));
+    throw new DOMException('Aborted', 'AbortError');
+}
+// ────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Single-shot LLM call. Streams the response, supports retry with
+ * narration, BYOK, and live progress reporting via the auto-injected
+ * `report_progress` tool when `onProgress` is set.
+ */
+export async function chat(options) {
+    if (options.turns.length === 0) {
+        throw new Error('anthropic.chat() requires at least one turn');
+    }
+    throwIfAborted(options.abortSignal);
+    const modelClass = options.modelClass ?? 'reasoning';
+    // See ChatOptions.model's doc comment: an explicit id wins over the
+    // catalog's class resolution, so two transports pinned to the same
+    // `model` answer with the same model regardless of what each one's
+    // class table currently maps to.
+    const modelId = options.model ?? models[modelClass];
+    // A model given the report_progress tool (auto-injected when
+    // onProgress is set) may end a turn having called ONLY that tool,
+    // with no text yet — smaller models (Haiku) do this readily. That's
+    // not a terminal state: acknowledge the progress call (feed a
+    // tool_result back) and let the model continue to the actual answer,
+    // rather than failing with "no text content". Cap the continuations
+    // so a misbehaving model can't loop forever. Usage is summed across
+    // the continuation calls; onUsage fires per call.
+    const MAX_PROGRESS_CONTINUATIONS = 4;
+    let messages = [...options.turns];
+    const aggregate = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheCreationInputTokens: 0,
+        cacheReadInputTokens: 0,
+        // Left undefined unless at least one attempt actually reports a value —
+        // see TokenUsage.cacheCreationEphemeral5mInputTokens's own "undefined
+        // when absent" contract. A plain running sum defaulting to 0 would
+        // report 0 (a claim of "reported zero") for a call that never saw
+        // this field at all.
+        cacheCreationEphemeral5mInputTokens: undefined,
+        cacheCreationEphemeral1hInputTokens: undefined,
+    };
+    const routesSeen = [];
+    for (let attempt = 0; attempt <= MAX_PROGRESS_CONTINUATIONS; attempt++) {
+        const streamed = await streamedCall(options.apiKey ?? null, (oauth) => buildRequest({
+            modelClass,
+            systemPrompt: options.systemPrompt,
+            turns: messages,
+            tools: options.onProgress ? [REPORT_PROGRESS_TOOL] : undefined,
+            // A continuation re-sends the growing history; cache its prefix.
+            cacheConversation: attempt > 0,
+            oauth,
+            model: options.model,
+            maxTokens: options.maxTokens,
+        }), options.onProgress, options.onRetry);
+        routesSeen.push(streamed.route);
+        aggregate.inputTokens += streamed.rawUsage.inputTokens;
+        aggregate.outputTokens += streamed.rawUsage.outputTokens;
+        aggregate.cacheCreationInputTokens += streamed.rawUsage.cacheCreationInputTokens;
+        aggregate.cacheReadInputTokens += streamed.rawUsage.cacheReadInputTokens;
+        if (streamed.rawUsage.cacheCreationEphemeral5mInputTokens !== undefined) {
+            aggregate.cacheCreationEphemeral5mInputTokens =
+                (aggregate.cacheCreationEphemeral5mInputTokens ?? 0) +
+                    streamed.rawUsage.cacheCreationEphemeral5mInputTokens;
+        }
+        if (streamed.rawUsage.cacheCreationEphemeral1hInputTokens !== undefined) {
+            aggregate.cacheCreationEphemeral1hInputTokens =
+                (aggregate.cacheCreationEphemeral1hInputTokens ?? 0) +
+                    streamed.rawUsage.cacheCreationEphemeral1hInputTokens;
+        }
+        await fireUsageHook(options.onUsage, shapeUsage(streamed.rawUsage, modelClass, streamed.route, modelId, streamed.responseId), 'anthropic.chat');
+        if (streamed.text) {
+            if (streamed.stopReason && streamed.stopReason !== 'end_turn') {
+                console.warn(`anthropic.chat: response stop_reason=${streamed.stopReason} (model=${models[modelClass]}, output_tokens=${streamed.rawUsage.outputTokens})`);
+            }
+            return {
+                content: streamed.text,
+                usage: shapeUsage(aggregate, modelClass, combineRoutes(routesSeen), modelId, streamed.responseId),
+                stopReason: streamed.stopReason,
+            };
+        }
+        // No text. If the turn ended on a progress-only tool call and we
+        // still have budget, acknowledge it and continue to the answer.
+        if (streamed.stopReason === 'tool_use' &&
+            streamed.progressToolUses.length > 0 &&
+            attempt < MAX_PROGRESS_CONTINUATIONS) {
+            const assistantBlocks = streamed.progressToolUses.map((p) => ({
+                type: 'tool_use',
+                id: p.id,
+                name: 'report_progress',
+                input: p.input,
+            }));
+            const toolResultBlocks = streamed.progressToolUses.map((p) => ({
+                type: 'tool_result',
+                tool_use_id: p.id,
+                content: 'ok',
+            }));
+            messages = [
+                ...messages,
+                { role: 'assistant', content: assistantBlocks },
+                { role: 'user', content: toolResultBlocks },
+            ];
+            continue;
+        }
+        // No text and nothing to continue on — a genuinely empty response.
+        throw new Error(`anthropic.chat: response had no text content (stop_reason=${streamed.stopReason})`);
+    }
+    throw new Error(`anthropic.chat: no text content after ${MAX_PROGRESS_CONTINUATIONS} progress continuations`);
+}
+/**
+ * Tool-calling variant. The model decides which tools to invoke
+ * against the supplied definitions; we surface every non-progress
+ * tool_use to the caller for execution. Single-shot — no automated
+ * multi-turn tool dance.
+ */
+export async function chatWithTools(options) {
+    if (options.turns.length === 0) {
+        throw new Error('anthropic.chatWithTools() requires at least one turn');
+    }
+    if (options.tools.length === 0) {
+        throw new Error('anthropic.chatWithTools() requires at least one tool');
+    }
+    throwIfAborted(options.abortSignal);
+    const modelClass = options.modelClass ?? 'reasoning';
+    const modelId = options.model ?? models[modelClass];
+    const augmentedTools = options.onProgress
+        ? [...options.tools, REPORT_PROGRESS_TOOL]
+        : options.tools;
+    const streamed = await streamedCall(options.apiKey ?? null, (oauth) => buildRequest({
+        modelClass,
+        systemPrompt: options.systemPrompt,
+        turns: options.turns,
+        tools: augmentedTools,
+        oauth,
+        model: options.model,
+        maxTokens: options.maxTokens,
+    }), options.onProgress, options.onRetry);
+    if (streamed.stopReason &&
+        streamed.stopReason !== 'end_turn' &&
+        streamed.stopReason !== 'tool_use') {
+        console.warn(`anthropic.chatWithTools: response stop_reason=${streamed.stopReason} (model=${modelId}, output_tokens=${streamed.rawUsage.outputTokens})`);
+    }
+    const usage = shapeUsage(streamed.rawUsage, modelClass, streamed.route, modelId);
+    await fireUsageHook(options.onUsage, usage, 'anthropic.chatWithTools');
+    return {
+        toolUses: streamed.toolUses,
+        text: streamed.text,
+        stopReason: streamed.stopReason,
+        usage,
+    };
+}
+/**
+ * Multi-turn tool-using chat. The caller supplies an executor; this
+ * function runs the model → execute tools → feed results back loop
+ * internally until the model produces a text-only response (or the
+ * iteration cap fires).
+ *
+ * Each loop iteration is a full Anthropic call. Tool execution
+ * happens between iterations; tool failures are surfaced to the model
+ * as `tool_result` blocks with `is_error: true` so it can recover
+ * (apologise, retry, switch approach) rather than the loop crashing.
+ *
+ * Usage and progress hooks fire per-iteration. Returned `usage` is
+ * the sum across all iterations of the loop, so cost accounting at
+ * the call site stays per-conversation-turn.
+ */
+export async function chatWithToolLoop(options) {
+    if (options.turns.length === 0) {
+        throw new Error('anthropic.chatWithToolLoop() requires at least one turn');
+    }
+    if (options.tools.length === 0) {
+        throw new Error('anthropic.chatWithToolLoop() requires at least one tool');
+    }
+    const modelClass = options.modelClass ?? 'reasoning';
+    const modelId = options.model ?? models[modelClass];
+    const augmentedTools = options.onProgress
+        ? [...options.tools, REPORT_PROGRESS_TOOL]
+        : options.tools;
+    const maxIterations = Math.max(1, options.maxIterations ?? 5);
+    // Working message history: we append to this as the loop progresses.
+    // The initial state mirrors what the consumer passed in.
+    let messages = [...options.turns];
+    const allToolUses = [];
+    const allToolResults = [];
+    const routesSeen = [];
+    // Counts only — the full TokenUsage (provider/model/direction/route) is
+    // built at each return site via shapeUsage, once the routes every
+    // underlying call actually used are known.
+    const aggregateUsage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheCreationInputTokens: 0,
+        cacheReadInputTokens: 0,
+    };
+    let iteration = 0;
+    while (iteration < maxIterations) {
+        iteration += 1;
+        // Abort check at the top of each iteration so the previous
+        // iteration's onUsage / onIteration hook can abort cleanly via
+        // its captured AbortController. The in-flight LLM call has
+        // already settled and its tokens are recorded; what we prevent
+        // is starting the NEXT iteration.
+        throwIfAborted(options.abortSignal);
+        const streamed = await streamedCall(options.apiKey ?? null, (oauth) => buildRequest({
+            modelClass,
+            systemPrompt: options.systemPrompt,
+            turns: messages,
+            tools: augmentedTools,
+            // Each iteration re-sends the growing history; a breakpoint on
+            // the last message lets the next iteration read this prefix
+            // from cache instead of reprocessing it.
+            cacheConversation: true,
+            oauth,
+            model: options.model,
+            maxTokens: options.maxTokens,
+        }), options.onProgress, options.onRetry);
+        routesSeen.push(streamed.route);
+        // Per-iteration usage hook + aggregate tally.
+        const iterUsage = shapeUsage(streamed.rawUsage, modelClass, streamed.route, modelId);
+        aggregateUsage.inputTokens += iterUsage.inputTokens;
+        aggregateUsage.outputTokens += iterUsage.outputTokens;
+        aggregateUsage.cacheCreationInputTokens += iterUsage.cacheCreationInputTokens;
+        aggregateUsage.cacheReadInputTokens += iterUsage.cacheReadInputTokens;
+        await fireUsageHook(options.onUsage, iterUsage, 'anthropic.chatWithToolLoop');
+        if (options.onIteration) {
+            try {
+                await options.onIteration({
+                    iteration,
+                    toolUses: streamed.toolUses,
+                    stopReason: streamed.stopReason,
+                });
+            }
+            catch (err) {
+                console.warn('chatWithToolLoop: onIteration callback threw', err);
+            }
+        }
+        // No more tools to call — we have the model's final answer.
+        if (streamed.toolUses.length === 0) {
+            return {
+                text: streamed.text,
+                toolUses: allToolUses,
+                toolResults: allToolResults,
+                iterations: iteration,
+                usage: shapeUsage(aggregateUsage, modelClass, combineRoutes(routesSeen), modelId),
+            };
+        }
+        allToolUses.push(...streamed.toolUses);
+        // Build the assistant content this iteration produced, including
+        // both the text (if any) and the tool_use blocks. The next call
+        // must include this verbatim so the model recognises the
+        // tool_result blocks that follow.
+        const assistantBlocks = [];
+        if (streamed.text) {
+            assistantBlocks.push({ type: 'text', text: streamed.text });
+        }
+        for (const u of streamed.toolUses) {
+            assistantBlocks.push({
+                type: 'tool_use',
+                id: u.id,
+                name: u.name,
+                input: u.input,
+            });
+        }
+        // Execute each tool_use; collect tool_result blocks.
+        const toolResultBlocks = [];
+        for (const use of streamed.toolUses) {
+            // Never collapsed: this adapter's ContentBlock already mirrors
+            // Anthropic's own wire shape, so an image/document block the
+            // executor returns passes through unchanged into tool_result.content.
+            let content;
+            let isError = false;
+            try {
+                content = await options.executor(use);
+            }
+            catch (err) {
+                content = err instanceof Error ? err.message : String(err);
+                isError = true;
+            }
+            toolResultBlocks.push({
+                type: 'tool_result',
+                tool_use_id: use.id,
+                content,
+                is_error: isError || undefined,
+            });
+            allToolResults.push({ toolUseId: use.id, content, isError });
+        }
+        // Append both sides to the working message history and loop.
+        messages = [
+            ...messages,
+            { role: 'assistant', content: assistantBlocks },
+            { role: 'user', content: toolResultBlocks },
+        ];
+    }
+    // Iteration cap hit while the model was still calling tools. Rather than
+    // return an empty answer (the model never wrote its final response), make
+    // one FINAL call with the tools removed — forcing it to synthesise a written
+    // answer from the history it built, instead of nothing. If this final call
+    // itself fails, degrade to the empty text rather than throwing.
+    throwIfAborted(options.abortSignal);
+    try {
+        const finalStreamed = await streamedCall(options.apiKey ?? null, (oauth) => buildRequest({
+            modelClass,
+            systemPrompt: options.systemPrompt,
+            turns: messages,
+            tools: [], // no tools → the model must answer in text
+            cacheConversation: true,
+            oauth,
+            model: options.model,
+            maxTokens: options.maxTokens,
+        }), options.onProgress, options.onRetry);
+        routesSeen.push(finalStreamed.route);
+        const finalUsage = shapeUsage(finalStreamed.rawUsage, modelClass, finalStreamed.route, modelId);
+        aggregateUsage.inputTokens += finalUsage.inputTokens;
+        aggregateUsage.outputTokens += finalUsage.outputTokens;
+        aggregateUsage.cacheCreationInputTokens += finalUsage.cacheCreationInputTokens;
+        aggregateUsage.cacheReadInputTokens += finalUsage.cacheReadInputTokens;
+        await fireUsageHook(options.onUsage, finalUsage, 'anthropic.chatWithToolLoop');
+        return {
+            text: finalStreamed.text,
+            toolUses: allToolUses,
+            toolResults: allToolResults,
+            iterations: iteration,
+            usage: shapeUsage(aggregateUsage, modelClass, combineRoutes(routesSeen), modelId),
+        };
+    }
+    catch (err) {
+        console.warn('anthropic.chatWithToolLoop: final synthesis call failed', err);
+        return {
+            text: '',
+            toolUses: allToolUses,
+            toolResults: allToolResults,
+            iterations: iteration,
+            usage: shapeUsage(aggregateUsage, modelClass, combineRoutes(routesSeen), modelId),
+        };
+    }
+}
+/**
+ * Namespaced re-export for callers that prefer the namespace form
+ * (`anthropic.chat(...)`) over named imports.
+ */
+export const anthropic = {
+    PROVIDER,
+    models,
+    rates,
+    chat,
+    chatWithTools,
+    chatWithToolLoop,
+};
+//# sourceMappingURL=index.js.map