@nodetool-ai/runtime 0.7.0-rc.22 → 0.8.1

package/dist/providers/anthropic-provider.js

@@ -1,20 +1,277 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { createLogger } from "@nodetool-ai/config";
 import { BaseProvider } from "./base-provider.js";
+import { anthropicContextExceeded } from "./context-exceeded.js";
+import { safeFetch } from "./safe-url.js";
+import { isNumber, isObjectLike, isRecord, isString } from "@nodetool-ai/protocol";
 const log = createLogger("nodetool.runtime.providers.anthropic");
+import { WEB_SEARCH_TOOL_NAME } from "./types.js";
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const MAX_PAUSE_TURN_CONTINUATIONS = 5;
+function toRawBlock(block) {
+    return Object.fromEntries(Object.entries(block));
+}
+function retryAfterMs(value) {
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.min(seconds * 1000, 60_000);
+    }
+    const date = Date.parse(value);
+    if (Number.isNaN(date))
+        return null;
+    return Math.min(Math.max(date - Date.now(), 0), 60_000);
+}
+function apiErrorStatus(error) {
+    if (isObjectLike(error) && "status" in error && isNumber(error.status)) {
+        return error.status;
+    }
+    return undefined;
+}
+function apiErrorRetryAfter(error) {
+    if (isObjectLike(error) &&
+        "headers" in error &&
+        error.headers instanceof Headers) {
+        return error.headers.get("retry-after");
+    }
+    return null;
+}
+function mapCitation(citation) {
+    switch (citation.type) {
+        case "char_location":
+            return {
+                type: citation.type,
+                citedText: citation.cited_text,
+                documentIndex: citation.document_index,
+                documentTitle: citation.document_title,
+                fileId: citation.file_id,
+                startCharIndex: citation.start_char_index,
+                endCharIndex: citation.end_char_index
+            };
+        case "page_location":
+            return {
+                type: citation.type,
+                citedText: citation.cited_text,
+                documentIndex: citation.document_index,
+                documentTitle: citation.document_title,
+                fileId: citation.file_id,
+                startPageNumber: citation.start_page_number,
+                endPageNumber: citation.end_page_number
+            };
+        case "content_block_location":
+            return {
+                type: citation.type,
+                citedText: citation.cited_text,
+                documentIndex: citation.document_index,
+                documentTitle: citation.document_title,
+                fileId: citation.file_id,
+                startBlockIndex: citation.start_block_index,
+                endBlockIndex: citation.end_block_index
+            };
+        case "web_search_result_location":
+            return {
+                type: citation.type,
+                citedText: citation.cited_text,
+                encryptedIndex: citation.encrypted_index,
+                url: citation.url,
+                title: citation.title
+            };
+        case "search_result_location":
+            return {
+                type: citation.type,
+                citedText: citation.cited_text,
+                searchResultIndex: citation.search_result_index,
+                source: citation.source,
+                title: citation.title,
+                startBlockIndex: citation.start_block_index,
+                endBlockIndex: citation.end_block_index
+            };
+    }
+}
+function textContentFromRawBlocks(blocks) {
+    return blocks.flatMap((block) => {
+        if (block?.type !== "text" || !isString(block.text))
+            return [];
+        const citations = Array.isArray(block.citations)
+            ? block.citations.map(mapCitation)
+            : undefined;
+        const content = {
+            type: "text",
+            text: block.text
+        };
+        if (citations && citations.length > 0) {
+            content.citations = citations;
+        }
+        return [content];
+    });
+}
+function toAnthropicCitation(citation) {
+    switch (citation.type) {
+        case "char_location":
+            return {
+                type: citation.type,
+                cited_text: citation.citedText,
+                document_index: citation.documentIndex,
+                document_title: citation.documentTitle ?? null,
+                file_id: citation.fileId ?? null,
+                start_char_index: citation.startCharIndex,
+                end_char_index: citation.endCharIndex
+            };
+        case "page_location":
+            return {
+                type: citation.type,
+                cited_text: citation.citedText,
+                document_index: citation.documentIndex,
+                document_title: citation.documentTitle ?? null,
+                file_id: citation.fileId ?? null,
+                start_page_number: citation.startPageNumber,
+                end_page_number: citation.endPageNumber
+            };
+        case "content_block_location":
+            return {
+                type: citation.type,
+                cited_text: citation.citedText,
+                document_index: citation.documentIndex,
+                document_title: citation.documentTitle ?? null,
+                file_id: citation.fileId ?? null,
+                start_block_index: citation.startBlockIndex,
+                end_block_index: citation.endBlockIndex
+            };
+        case "web_search_result_location":
+            return {
+                type: citation.type,
+                cited_text: citation.citedText,
+                encrypted_index: citation.encryptedIndex,
+                url: citation.url,
+                title: citation.title ?? null
+            };
+        case "search_result_location":
+            return {
+                type: citation.type,
+                cited_text: citation.citedText,
+                search_result_index: citation.searchResultIndex,
+                source: citation.source,
+                title: citation.title ?? null,
+                start_block_index: citation.startBlockIndex,
+                end_block_index: citation.endBlockIndex
+            };
+    }
+}
+/**
+ * The tool fields Anthropic accepts on every tool form, with each one the
+ * caller left unset omitted.
+ */
+function sharedToolFields(tool) {
+    const fields = {};
+    if (tool.cacheControl) {
+        fields.cache_control = tool.cacheControl;
+    }
+    if (tool.strict !== undefined) {
+        fields.strict = tool.strict;
+    }
+    if (tool.deferLoading !== undefined) {
+        fields.defer_loading = tool.deferLoading;
+    }
+    if (tool.allowedCallers) {
+        fields.allowed_callers = tool.allowedCallers;
+    }
+    return fields;
+}
+function toAnthropicTextBlock(part) {
+    const block = {
+        type: "text",
+        text: part.text
+    };
+    if (part.citations) {
+        block.citations = part.citations.map(toAnthropicCitation);
+    }
+    return block;
+}
+/**
+ * Anthropic requires every `tool_result` block for one assistant turn to live
+ * in a single user message. `convertMessage` emits one user message per
+ * `role: "tool"` message, so parallel tool calls would produce consecutive user
+ * messages and a 400. Merge them back into one.
+ */
+function mergeToolResultMessages(messages) {
+    const isToolResultMessage = (m) => m.role === "user" &&
+        Array.isArray(m.content) &&
+        m.content.length > 0 &&
+        m.content.every((block) => isObjectLike(block) &&
+            block.type === "tool_result");
+    const merged = [];
+    for (const message of messages) {
+        const previous = merged[merged.length - 1];
+        if (previous &&
+            isToolResultMessage(previous) &&
+            isToolResultMessage(message)) {
+            merged[merged.length - 1] = {
+                ...previous,
+                content: [
+                    ...previous.content,
+                    ...message.content
+                ]
+            };
+            continue;
+        }
+        merged.push(message);
+    }
+    return merged;
+}
+function thinkingPolicy(model) {
+    const id = model.toLowerCase();
+    if (id.includes("claude-fable-5") ||
+        id.includes("claude-mythos-5") ||
+        id.includes("claude-mythos-preview")) {
+        return "adaptive_required";
+    }
+    if (id.includes("claude-sonnet-5"))
+        return "adaptive_default";
+    if (id.includes("claude-opus-4-7") || id.includes("claude-opus-4-8")) {
+        return "adaptive_optional";
+    }
+    return "manual";
+}
+function rejectsCustomSampling(model) {
+    return thinkingPolicy(model) !== "manual";
+}
 function isTextContent(content) {
     return content.type === "text";
 }
 function isImageContent(content) {
     return content.type === "image_url";
 }
+function isDocumentContent(content) {
+    return content.type === "document";
+}
 function bytesToBase64(data) {
     if (!data)
         return "";
-    if (typeof data === "string")
+    if (isString(data))
         return data;
     return Buffer.from(data).toString("base64");
 }
+function assertImageSize(base64) {
+    if (Buffer.byteLength(base64, "base64") > MAX_IMAGE_BYTES) {
+        throw new Error("Anthropic image exceeds the 5 MB limit");
+    }
+}
+/**
+ * Anthropic's image block accepts only image/jpeg, image/png, image/gif and
+ * image/webp as `media_type`. Strip any Content-Type parameters, normalize the
+ * common `image/jpg` alias, and reject unsupported media types.
+ */
+function normalizeAnthropicImageMime(mime) {
+    const base = mime.split(";")[0].trim().toLowerCase();
+    if (base === "image/jpg")
+        return "image/jpeg";
+    const supported = ["image/jpeg", "image/png", "image/gif", "image/webp"];
+    if (!supported.includes(base)) {
+        throw new Error(`Anthropic does not support image media type ${base}`);
+    }
+    return base;
+}
 function parseDataUri(uri) {
     const idx = uri.indexOf(",");
     if (idx < 0) {
@@ -33,30 +290,65 @@ function parseDataUri(uri) {
     };
 }
 export class AnthropicProvider extends BaseProvider {
+    /**
+     * Anthropic runs web search server-side via the `web_search_20250305` server
+     * tool. Gate on the provider id so subclasses that reuse the Anthropic SDK
+     * against a different endpoint (gateways that don't implement that server
+     * tool) fall back to the SerpAPI WebSearchTool instead of sending an
+     * unsupported tool that silently breaks web search.
+     */
+    get supportsNativeWebSearch() {
+        return this.provider === "anthropic";
+    }
     static requiredSecrets() {
         return ["ANTHROPIC_API_KEY"];
     }
     apiKey;
+    authToken;
     _client;
     _clientFactory;
     _fetch;
+    _clientOptions;
+    _cacheControl;
+    _betas;
     constructor(secrets, options = {}) {
-        super("anthropic");
-        const apiKey = secrets.ANTHROPIC_API_KEY;
-        if (!apiKey || !apiKey.trim()) {
-            throw new Error("ANTHROPIC_API_KEY is not configured");
+        super(options.providerId ?? "anthropic");
+        const apiKey = secrets.ANTHROPIC_API_KEY?.trim() ?? "";
+        const authToken = secrets.ANTHROPIC_AUTH_TOKEN?.trim() ??
+            options.clientOptions?.authToken?.trim() ??
+            "";
+        const hasStructuredAuth = Boolean(options.clientOptions?.credentials ||
+            options.clientOptions?.config ||
+            options.clientOptions?.profile);
+        if (!apiKey && !authToken && !hasStructuredAuth) {
+            throw new Error("Anthropic authentication is not configured (API key, auth token, credentials, config, or profile required)");
         }
         this.apiKey = apiKey;
+        this.authToken = authToken;
         this._client = options.client ?? null;
+        this._clientOptions = options.clientOptions;
+        this._cacheControl = options.cacheControl;
+        this._betas = options.betas ?? [];
         this._clientFactory =
             options.clientFactory ??
-                ((key) => new Anthropic({
-                    apiKey: key
-                }));
+                ((key) => {
+                    const clientOptions = { ...this._clientOptions };
+                    if (key) {
+                        clientOptions.apiKey = key;
+                    }
+                    if (this.authToken) {
+                        clientOptions.authToken = this.authToken;
+                    }
+                    return new Anthropic(clientOptions);
+                });
         this._fetch = options.fetchFn ?? globalThis.fetch.bind(globalThis);
     }
     getContainerEnv() {
-        return { ANTHROPIC_API_KEY: this.apiKey };
+        if (this.apiKey)
+            return { ANTHROPIC_API_KEY: this.apiKey };
+        if (this.authToken)
+            return { ANTHROPIC_AUTH_TOKEN: this.authToken };
+        return {};
     }
     getClient() {
         if (!this._client) {
@@ -64,217 +356,347 @@ export class AnthropicProvider extends BaseProvider {
         }
         return this._client;
     }
+    requestOptions(signal) {
+        const options = {};
+        if (signal) {
+            options.signal = signal;
+        }
+        if (this._betas.length > 0) {
+            options.headers = { "anthropic-beta": this._betas.join(",") };
+        }
+        return options;
+    }
     async hasToolSupport(_model) {
         return true;
     }
+    /**
+     * `max_input_tokens` from the Models API. The request carries the same
+     * `anthropic-beta` header as Messages, so a 1M-context beta reports the 1M
+     * window. Null when the endpoint fails, as it does on gateways that reuse
+     * this provider without implementing it.
+     */
+    async getContextWindow(model) {
+        try {
+            const info = await this.getClient().models.retrieve(model, null, {
+                ...this.requestOptions(),
+                timeout: 10_000,
+                maxRetries: 0
+            });
+            return info.max_input_tokens ?? null;
+        }
+        catch (error) {
+            log.debug("Anthropic model lookup failed", {
+                model,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return null;
+        }
+    }
     async getAvailableLanguageModels() {
         const maxRetries = 3;
-        const baseDelay = 1000; // ms
-        let lastError = null;
         for (let attempt = 0; attempt < maxRetries; attempt++) {
             try {
-                const controller = new AbortController();
-                const timeout = setTimeout(() => controller.abort(), 10_000); // 10s total timeout
-                const response = await this._fetch("https://api.anthropic.com/v1/models", {
-                    headers: {
-                        "x-api-key": this.apiKey,
-                        "anthropic-version": "2023-06-01"
-                    },
-                    signal: controller.signal
-                });
-                clearTimeout(timeout);
-                // Don't retry on auth errors
-                if (response.status === 401 || response.status === 403) {
-                    log.warn("Anthropic API auth error, not retrying", {
-                        status: response.status
-                    });
-                    return [];
-                }
-                // Retry on rate limit or server errors
-                if ([429, 500, 502, 503, 504].includes(response.status)) {
-                    log.warn("Anthropic API error, retrying", {
-                        status: response.status,
-                        attempt: attempt + 1,
-                        maxRetries
+                const models = [];
+                let afterId;
+                do {
+                    const listParams = {
+                        limit: 1000
+                    };
+                    if (afterId) {
+                        listParams.after_id = afterId;
+                    }
+                    const page = await this.getClient().models.list(listParams, {
+                        ...this.requestOptions(),
+                        timeout: 10_000,
+                        maxRetries: 0
                     });
-                    if (attempt < maxRetries - 1) {
-                        await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
-                        continue;
+                    models.push(...page.data.map((model) => ({
+                        id: model.id,
+                        name: model.display_name,
+                        provider: "anthropic"
+                    })));
+                    if (page.has_more && !page.last_id) {
+                        throw new Error("Anthropic Models API returned has_more without last_id");
                     }
+                    afterId = page.has_more ? (page.last_id ?? undefined) : undefined;
+                } while (afterId);
+                return models;
+            }
+            catch (error) {
+                const status = apiErrorStatus(error);
+                if (status === 401 || status === 403)
                     return [];
-                }
-                if (!response.ok) {
+                if (attempt === maxRetries - 1 ||
+                    (status !== undefined &&
+                        ![429, 500, 502, 503, 504, 529].includes(status))) {
                     log.warn("Failed to fetch Anthropic models", {
-                        status: response.status
+                        error: error instanceof Error ? error.message : String(error),
+                        status
                     });
                     return [];
                 }
-                const payload = (await response.json());
-                return (payload.data ?? [])
-                    .map((m) => m.id ?? m.name)
-                    .filter((id) => typeof id === "string" && id.length > 0)
-                    .map((id) => ({ id, name: id, provider: "anthropic" }));
-            }
-            catch (err) {
-                lastError = err instanceof Error ? err : new Error(String(err));
-                // AbortError means timeout
-                if (lastError.name === "AbortError") {
-                    log.warn("Anthropic API timeout", {
-                        attempt: attempt + 1,
-                        maxRetries
-                    });
-                }
-                else {
-                    log.warn("Anthropic API connection error", {
-                        error: lastError.message,
-                        attempt: attempt + 1,
-                        maxRetries
-                    });
-                }
-                if (attempt < maxRetries - 1) {
-                    await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
-                }
+                const delay = retryAfterMs(apiErrorRetryAfter(error)) ?? 1000 * 2 ** attempt;
+                await new Promise((resolve) => setTimeout(resolve, delay));
             }
         }
-        log.error("Failed to fetch Anthropic models after retries", {
-            error: lastError?.message
-        });
         return [];
     }
     prepareJsonSchema(schema) {
-        if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        if (!isRecord(schema)) {
+            // SAFETY: a schema node that is not an object is carried through as it
+            // stands — a scalar, a list, or an absent schema.
             return schema;
         }
-        const obj = { ...schema };
+        const obj = {
+            // SAFETY: the checks above proved `schema` is a plain object of schema
+            // members.
+            ...schema
+        };
         if (obj.type === "object" && obj.additionalProperties === undefined) {
             obj.additionalProperties = false;
         }
-        if (obj.properties &&
-            typeof obj.properties === "object" &&
-            !Array.isArray(obj.properties)) {
-            obj.properties = Object.fromEntries(Object.entries(obj.properties).map(([k, v]) => [k, this.prepareJsonSchema(v)]));
+        if (isRecord(obj.properties)) {
+            obj.properties = Object.fromEntries(Object.entries(obj.properties).map(([k, v]) => [
+                k,
+                this.prepareJsonSchema(v)
+            ]));
         }
-        if (obj.items && typeof obj.items === "object") {
+        if (isObjectLike(obj.items)) {
             obj.items = this.prepareJsonSchema(obj.items);
         }
         for (const defsKey of ["definitions", "$defs"]) {
             const defs = obj[defsKey];
-            if (defs && typeof defs === "object" && !Array.isArray(defs)) {
-                obj[defsKey] = Object.fromEntries(Object.entries(defs).map(([k, v]) => [
-                    k,
-                    this.prepareJsonSchema(v)
-                ]));
-            }
-        }
-        const unsupported = [
-            "default",
-            "minimum",
-            "maximum",
-            "exclusiveMinimum",
-            "exclusiveMaximum",
-            "multipleOf",
-            "minLength",
-            "maxLength",
-            "minProperties",
-            "maxProperties",
-            "minItems",
-            "maxItems",
-            "uniqueItems"
-        ];
-        for (const key of unsupported) {
-            delete obj[key];
+            if (isRecord(defs)) {
+                obj[defsKey] = Object.fromEntries(Object.entries(defs).map(([k, v]) => [k, this.prepareJsonSchema(v)]));
+            }
         }
         return obj;
     }
-    async convertMessage(message) {
+    /**
+     * Convert a {@link MessageImageContent} part into an Anthropic image block
+     * (`{ type: "image", source: { type: "base64", ... } }`), resolving data
+     * URIs, raw base64, and remote/storage URIs (which are fetched and encoded).
+     */
+    async convertImagePart(part, signal) {
+        const rawData = bytesToBase64(part.image.data);
+        const uri = part.image.uri ?? "";
+        let mediaType = part.image.mimeType ?? "image/png";
+        let base64;
+        if (rawData) {
+            if (rawData.startsWith("data:")) {
+                const parsed = parseDataUri(rawData);
+                if (part.image.mimeType &&
+                    normalizeAnthropicImageMime(part.image.mimeType) !==
+                        normalizeAnthropicImageMime(parsed.mime)) {
+                    throw new Error("Anthropic image data URI MIME mismatch");
+                }
+                base64 = parsed.base64;
+                mediaType = part.image.mimeType ?? parsed.mime;
+            }
+            else {
+                base64 = rawData;
+            }
+        }
+        else if (uri.startsWith("data:")) {
+            const parsed = parseDataUri(uri);
+            if (part.image.mimeType &&
+                normalizeAnthropicImageMime(part.image.mimeType) !==
+                    normalizeAnthropicImageMime(parsed.mime)) {
+                throw new Error("Anthropic image data URI MIME mismatch");
+            }
+            base64 = parsed.base64;
+            mediaType = part.image.mimeType ?? parsed.mime;
+        }
+        else if (uri) {
+            const resolved = await this.resolveUri(uri);
+            if (resolved.startsWith("data:")) {
+                const parsed = parseDataUri(resolved);
+                if (part.image.mimeType &&
+                    normalizeAnthropicImageMime(part.image.mimeType) !==
+                        normalizeAnthropicImageMime(parsed.mime)) {
+                    throw new Error("Anthropic image data URI MIME mismatch");
+                }
+                base64 = parsed.base64;
+                mediaType = part.image.mimeType ?? parsed.mime;
+            }
+            else {
+                const response = await safeFetch(resolved, signal ? { signal } : undefined, 5, this._fetch);
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch URI: ${response.status}`);
+                }
+                const contentLength = Number(response.headers.get("content-length"));
+                if (Number.isFinite(contentLength) && contentLength > MAX_IMAGE_BYTES) {
+                    throw new Error("Anthropic image exceeds the 5 MB limit");
+                }
+                mediaType =
+                    part.image.mimeType ??
+                        response.headers.get("content-type") ??
+                        "image/png";
+                const bytes = new Uint8Array(await response.arrayBuffer());
+                if (bytes.byteLength > MAX_IMAGE_BYTES) {
+                    throw new Error("Anthropic image exceeds the 5 MB limit");
+                }
+                base64 = Buffer.from(bytes).toString("base64");
+            }
+        }
+        else {
+            throw new Error("Invalid image reference with no uri or data");
+        }
+        assertImageSize(base64);
+        return {
+            type: "image",
+            source: {
+                type: "base64",
+                media_type: normalizeAnthropicImageMime(mediaType),
+                data: base64
+            }
+        };
+    }
+    async convertDocumentPart(part) {
+        const { data, uri, mimeType, title } = part.document;
+        let source;
+        if (data !== undefined) {
+            const parsed = isString(data) && data.startsWith("data:")
+                ? parseDataUri(data)
+                : undefined;
+            const effectiveMime = mimeType ?? parsed?.mime ?? "application/pdf";
+            if (parsed && mimeType && parsed.mime !== mimeType) {
+                throw new Error(`Anthropic document MIME mismatch: ${mimeType} vs ${parsed.mime}`);
+            }
+            if (effectiveMime === "text/plain") {
+                const text = parsed
+                    ? Buffer.from(parsed.base64, "base64").toString("utf8")
+                    : isString(data)
+                        ? data
+                        : Buffer.from(data).toString("utf8");
+                source = { type: "text", media_type: "text/plain", data: text };
+            }
+            else if (effectiveMime === "application/pdf") {
+                const encoded = parsed?.base64 ?? bytesToBase64(data);
+                source = {
+                    type: "base64",
+                    media_type: "application/pdf",
+                    data: encoded
+                };
+            }
+            else {
+                throw new Error(`Anthropic does not support document media type ${effectiveMime}`);
+            }
+        }
+        else if (uri) {
+            const resolved = await this.resolveUri(uri);
+            if (/^https:\/\//i.test(resolved)) {
+                source = { type: "url", url: resolved };
+            }
+            else if (!resolved.startsWith("data:")) {
+                throw new Error("Anthropic document URI must resolve to PDF data or an HTTPS URL");
+            }
+            else {
+                const parsed = parseDataUri(resolved);
+                if (parsed.mime !== "application/pdf") {
+                    throw new Error(`Anthropic does not support document media type ${parsed.mime}`);
+                }
+                source = {
+                    type: "base64",
+                    media_type: "application/pdf",
+                    data: parsed.base64
+                };
+            }
+        }
+        else {
+            throw new Error("Anthropic document content requires PDF/text data or an HTTPS PDF URL");
+        }
+        const block = {
+            type: "document",
+            source
+        };
+        if (title) {
+            block.title = title;
+        }
+        if (part.context) {
+            block.context = part.context;
+        }
+        if (part.citations !== undefined) {
+            block.citations = { enabled: part.citations };
+        }
+        return block;
+    }
+    async convertMessage(message, signal) {
         if (message.role === "tool") {
             if (!message.toolCallId) {
                 throw new Error("Tool call ID must not be None");
             }
-            const contentValue = typeof message.content === "string"
-                ? message.content
-                : JSON.stringify(message.content ?? null);
+            // Anthropic tool_result content may be a string or an array of blocks
+            // (text + image). Structured content (e.g. ui_3d_capture_view's
+            // screenshot) is converted to blocks so vision models can see it; plain
+            // results stay stringified as before.
+            let resultContent;
+            if (isString(message.content)) {
+                resultContent = message.content;
+            }
+            else if (Array.isArray(message.content)) {
+                const blocks = [];
+                for (const part of message.content) {
+                    if (isTextContent(part)) {
+                        blocks.push(toAnthropicTextBlock(part));
+                    }
+                    else if (isImageContent(part)) {
+                        blocks.push(await this.convertImagePart(part, signal));
+                    }
+                }
+                resultContent =
+                    blocks.length > 0 ? blocks : JSON.stringify(message.content);
+            }
+            else {
+                resultContent = JSON.stringify(message.content ?? null);
+            }
+            const toolResult = {
+                type: "tool_result",
+                tool_use_id: message.toolCallId,
+                content: resultContent
+            };
+            if (message.isError) {
+                toolResult.is_error = true;
+            }
             return {
                 role: "user",
-                content: [
-                    {
-                        type: "tool_result",
-                        tool_use_id: message.toolCallId,
-                        content: contentValue
-                    }
-                ]
+                content: [toolResult]
             };
         }
         if (message.role === "system") {
-            return {
-                role: "assistant",
-                content: typeof message.content === "string"
-                    ? message.content
-                    : String(message.content ?? "")
-            };
+            // Anthropic has no `system` role in the messages array (the system prompt
+            // is a top-level param). The main generate paths strip system messages
+            // before conversion; if one still reaches here, fold it into a user
+            // message rather than mislabeling it as assistant text (and avoid
+            // String(array) producing "[object Object]").
+            const text = isString(message.content)
+                ? message.content
+                : (message.content ?? [])
+                    .filter(isTextContent)
+                    .map((c) => c.text)
+                    .join("\n");
+            return { role: "user", content: text };
         }
         if (message.role === "user") {
-            if (typeof message.content === "string") {
+            if (isString(message.content)) {
                 return { role: "user", content: message.content };
             }
             const parts = message.content ?? [];
             const content = [];
             for (const part of parts) {
                 if (isTextContent(part)) {
-                    content.push({ type: "text", text: part.text });
+                    content.push(toAnthropicTextBlock(part));
                     continue;
                 }
                 if (isImageContent(part)) {
-                    const rawData = bytesToBase64(part.image.data);
-                    const uri = part.image.uri ?? "";
-                    let mediaType = part.image.mimeType ?? "image/png";
-                    let base64;
-                    if (rawData) {
-                        if (rawData.startsWith("data:")) {
-                            const parsed = parseDataUri(rawData);
-                            base64 = parsed.base64;
-                            mediaType = part.image.mimeType ?? parsed.mime;
-                        }
-                        else {
-                            base64 = rawData;
-                        }
-                    }
-                    else if (uri.startsWith("data:")) {
-                        const parsed = parseDataUri(uri);
-                        base64 = parsed.base64;
-                        mediaType = part.image.mimeType ?? parsed.mime;
-                    }
-                    else if (uri) {
-                        const resolved = await this.resolveUri(uri);
-                        if (resolved.startsWith("data:")) {
-                            const parsed = parseDataUri(resolved);
-                            base64 = parsed.base64;
-                            mediaType = part.image.mimeType ?? parsed.mime;
-                        }
-                        else {
-                            const response = await this._fetch(resolved);
-                            if (!response.ok) {
-                                throw new Error(`Failed to fetch URI: ${response.status}`);
-                            }
-                            mediaType =
-                                part.image.mimeType ??
-                                    response.headers.get("content-type") ??
-                                    "image/png";
-                            base64 = Buffer.from(new Uint8Array(await response.arrayBuffer())).toString("base64");
-                        }
-                    }
-                    else {
-                        throw new Error("Invalid image reference with no uri or data");
-                    }
-                    content.push({
-                        type: "image",
-                        source: {
-                            type: "base64",
-                            media_type: mediaType,
-                            data: base64
-                        }
-                    });
+                    content.push(await this.convertImagePart(part, signal));
+                    continue;
                 }
+                if (isDocumentContent(part)) {
+                    content.push(await this.convertDocumentPart(part));
+                    continue;
+                }
+                throw new Error(`Anthropic does not support ${part.type} message content`);
             }
             return {
                 role: "user",
@@ -289,14 +711,20 @@ export class AnthropicProvider extends BaseProvider {
             return null;
         }
         if (message.toolCalls && message.toolCalls.length > 0) {
-            const contentBlocks = [];
-            if (typeof message.content === "string" && message.content.trim()) {
+            const rawBlocks = message.toolCalls.find((toolCall) => toolCall._anthropicContentBlocks)?._anthropicContentBlocks;
+            if (rawBlocks) {
+                return { role: "assistant", content: rawBlocks };
+            }
+            const contentBlocks = [
+                ...(message._anthropicThinkingBlocks ?? [])
+            ];
+            if (isString(message.content) && message.content.trim()) {
                 contentBlocks.push({ type: "text", text: message.content });
             }
             if (Array.isArray(message.content)) {
                 for (const part of message.content) {
                     if (isTextContent(part) && part.text.trim()) {
-                        contentBlocks.push({ type: "text", text: part.text });
+                        contentBlocks.push(toAnthropicTextBlock(part));
                     }
                 }
             }
@@ -313,7 +741,7 @@ export class AnthropicProvider extends BaseProvider {
                 content: contentBlocks
             };
         }
-        if (typeof message.content === "string") {
+        if (isString(message.content)) {
             return { role: "assistant", content: message.content };
         }
         if (Array.isArray(message.content)) {
@@ -321,236 +749,490 @@ export class AnthropicProvider extends BaseProvider {
                 role: "assistant",
                 content: message.content
                     .filter((part) => isTextContent(part))
-                    .map((part) => ({
-                    type: "text",
-                    text: part.text
-                }))
+                    .map(toAnthropicTextBlock)
             };
         }
         throw new Error(`Unknown message content type ${typeof message.content}`);
     }
     formatTools(tools) {
-        return tools.map((tool) => ({
-            name: tool.name,
-            description: tool.description ?? "",
-            input_schema: this.prepareJsonSchema(tool.inputSchema ?? { type: "object", properties: {} })
-        }));
+        return tools.map((tool) => {
+            // The canonical web-search tool is rendered as Anthropic's built-in
+            // server tool — the search runs server-side and its result blocks stream
+            // back within the same turn (our stream parser ignores them), so the
+            // model answers from live web data without a client round-trip.
+            // Gated on supportsNativeWebSearch: subclasses that reuse the Anthropic
+            // SDK against a different endpoint don't implement this server tool, so
+            // for them the tool falls through to the plain function-tool shape below
+            // and runs client-side via SerpAPI.
+            if (tool.name === WEB_SEARCH_TOOL_NAME && this.supportsNativeWebSearch) {
+                return {
+                    type: "web_search_20250305",
+                    name: WEB_SEARCH_TOOL_NAME,
+                    max_uses: 5,
+                    ...sharedToolFields(tool)
+                };
+            }
+            const base = {
+                name: tool.name,
+                description: tool.description ?? "",
+                input_schema: this.prepareJsonSchema(tool.inputSchema ?? { type: "object", properties: {} })
+            };
+            const withExamples = tool.inputExamples
+                ? { ...base, input_examples: tool.inputExamples }
+                : base;
+            return { ...withExamples, ...sharedToolFields(tool) };
+        });
     }
     extractSystemMessage(messages) {
-        const system = messages.find((m) => m.role === "system");
-        if (!system) {
+        const systemMessages = messages.filter((m) => m.role === "system");
+        if (systemMessages.length === 0) {
             return "You are a helpful assistant.";
         }
-        if (typeof system.content === "string") {
-            return system.content;
-        }
-        if (Array.isArray(system.content)) {
-            return system.content
-                .filter((part) => isTextContent(part))
-                .map((part) => part.text)
-                .join(" ");
-        }
-        return String(system.content ?? "You are a helpful assistant.");
+        const sections = systemMessages
+            .map((message) => {
+            if (isString(message.content))
+                return message.content;
+            if (Array.isArray(message.content)) {
+                return message.content
+                    .filter(isTextContent)
+                    .map((part) => part.text)
+                    .join(" ");
+            }
+            return message.content == null ? "" : String(message.content);
+        })
+            .filter(Boolean);
+        return sections.join("\n\n") || "You are a helpful assistant.";
     }
-    async *generateMessages(args) {
-        const system = this.extractSystemMessage(args.messages);
-        const converted = await Promise.all(args.messages
-            .filter((m) => m.role !== "system")
-            .map((m) => this.convertMessage(m)));
-        const anthropicMessages = converted.filter((m) => m !== null);
+    buildRequest(args) {
         const formattedTools = args.tools && args.tools.length > 0
             ? this.formatTools(args.tools)
             : undefined;
-        let resolvedToolChoice;
+        const policy = thinkingPolicy(args.model);
+        // `thinkingBudget` predates the structured config. A model that only takes
+        // adaptive thinking has no use for the number, so it degrades to a bare
+        // request for thinking.
+        const legacyThinking = args.thinkingBudget === undefined
+            ? undefined
+            : policy === "manual"
+                ? { type: "manual", budgetTokens: args.thinkingBudget }
+                : { type: "adaptive" };
+        const thinking = args.thinking ?? legacyThinking;
+        if (thinking?.type === "manual") {
+            if (policy !== "manual") {
+                throw new Error(`${args.model} requires adaptive thinking; manual budgets are unsupported`);
+            }
+            if (thinking.budgetTokens < 1024) {
+                throw new Error("Anthropic thinking budget must be at least 1024 tokens");
+            }
+        }
+        if (thinking?.type === "disabled" && policy === "adaptive_required") {
+            throw new Error(`${args.model} does not allow thinking to be disabled`);
+        }
+        const explicitThinking = thinking?.type === "adaptive" || thinking?.type === "manual";
+        // Policy-default thinking (no caller-supplied config) is implicit: a forced
+        // tool choice wins over it and thinking is turned off, so callers that
+        // always force a tool can still use adaptive-default models. An explicit
+        // thinking request combined with a forced tool choice is a real conflict.
+        const implicitThinking = !thinking &&
+            (policy === "adaptive_default" || policy === "adaptive_required");
         if (args.toolChoice) {
-            resolvedToolChoice =
-                args.toolChoice === "any"
-                    ? { type: "any" }
-                    : { type: "tool", name: args.toolChoice };
+            if (explicitThinking) {
+                throw new Error("Anthropic does not allow a forced tool choice while thinking is active");
+            }
+            if (implicitThinking && policy === "adaptive_required") {
+                throw new Error(`${args.model} does not allow thinking to be disabled, so a forced tool choice is unsupported`);
+            }
+        }
+        const thinkingSuppressedByToolChoice = Boolean(args.toolChoice && implicitThinking);
+        const thinkingEnabled = explicitThinking || (implicitThinking && !thinkingSuppressedByToolChoice);
+        const toolChoice = args.toolChoice
+            ? args.toolChoice === "any"
+                ? { type: "any" }
+                : { type: "tool", name: args.toolChoice }
+            : undefined;
+        // A manual budget has to fit inside max_tokens, with at least one token
+        // left over for the answer.
+        const requestedMaxTokens = args.maxTokens ?? 8192;
+        const maxTokens = thinking?.type === "manual"
+            ? Math.max(requestedMaxTokens, thinking.budgetTokens + 1)
+            : requestedMaxTokens;
+        // Models on an adaptive thinking policy reject temperature and top_p
+        // outright, and once thinking is on the only value Anthropic still accepts
+        // is a top_p of 0.95 or above under a manual budget.
+        const sampling = {};
+        if (!rejectsCustomSampling(args.model)) {
+            if (!thinkingEnabled) {
+                if (args.temperature != null) {
+                    sampling.temperature = args.temperature;
+                }
+                else if (args.topP != null) {
+                    sampling.top_p = args.topP;
+                }
+            }
+            else if (thinking?.type === "manual" &&
+                args.topP != null &&
+                args.topP >= 0.95) {
+                sampling.top_p = args.topP;
+            }
+        }
+        // The disabled variant carries no `display` field, hence the narrowing.
+        const display = thinking && thinking.type !== "disabled" && thinking.display
+            ? { display: thinking.display }
+            : {};
+        let anthropicThinking;
+        if (thinking?.type === "adaptive") {
+            anthropicThinking = { type: "adaptive", ...display };
+        }
+        else if (thinking?.type === "manual") {
+            anthropicThinking = {
+                type: "enabled",
+                budget_tokens: thinking.budgetTokens,
+                ...display
+            };
+        }
+        else if (thinking?.type === "disabled" ||
+            thinkingSuppressedByToolChoice) {
+            anthropicThinking = { type: "disabled" };
         }
         const request = {
+            model: args.model,
+            messages: args.messages,
+            system: args.system,
+            max_tokens: maxTokens
+        };
+        if (formattedTools) {
+            request.tools = formattedTools;
+        }
+        if (toolChoice) {
+            request.tool_choice = toolChoice;
+        }
+        Object.assign(request, sampling);
+        if (anthropicThinking) {
+            request.thinking = anthropicThinking;
+        }
+        if (args.effort) {
+            request.output_config = { effort: args.effort };
+        }
+        if (this._cacheControl) {
+            request.cache_control = this._cacheControl;
+        }
+        return request;
+    }
+    async *generateMessages(args) {
+        const system = this.extractSystemMessage(args.messages);
+        const converted = await Promise.all(args.messages
+            .filter((m) => m.role !== "system")
+            .map((m) => this.convertMessage(m, args.signal)));
+        const anthropicMessages = mergeToolResultMessages(converted.filter((m) => m !== null));
+        const request = this.buildRequest({
             model: args.model,
             messages: anthropicMessages,
             system,
-            max_tokens: args.maxTokens ?? 8192,
-            ...(formattedTools ? { tools: formattedTools } : {}),
-            ...(resolvedToolChoice ? { tool_choice: resolvedToolChoice } : {}),
-            ...(args.temperature != null ? { temperature: args.temperature } : {}),
-            ...(args.topP != null ? { top_p: args.topP } : {}),
-            ...(args.thinkingBudget != null
-                ? { thinking: { type: "enabled", budget_tokens: args.thinkingBudget } }
-                : {})
-        };
-        log.debug("Anthropic request", { model: args.model });
-        const stream = await this.getClient().messages.create({
-            ...request,
-            stream: true
+            tools: args.tools,
+            toolChoice: args.toolChoice,
+            maxTokens: args.maxTokens,
+            temperature: args.temperature,
+            topP: args.topP,
+            thinking: args.thinking,
+            effort: args.effort,
+            thinkingBudget: args.thinkingBudget
         });
-        let streamInputTokens = 0;
-        let streamOutputTokens = 0;
-        let streamCachedTokens = 0;
-        // Track in-flight tool_use blocks: index → { id, name, accumulated partial_json }
-        const activeToolBlocks = new Map();
-        for await (const event of stream) {
-            if (event.type === "message_start") {
-                const usage = event.message.usage;
-                streamInputTokens += usage.input_tokens ?? 0;
-                streamCachedTokens += usage.cache_read_input_tokens ?? 0;
-            }
-            if (event.type === "message_delta") {
-                streamOutputTokens += event.usage.output_tokens ?? 0;
-            }
-            if (event.type === "message_stop") {
-                this.trackUsage(args.model, {
-                    inputTokens: streamInputTokens,
-                    outputTokens: streamOutputTokens,
-                    cachedTokens: streamCachedTokens
-                });
-            }
-            // Record the start of a tool_use content block so we can accumulate its JSON.
-            if (event.type === "content_block_start") {
-                const block = event.content_block;
-                if (block.type === "tool_use") {
-                    activeToolBlocks.set(event.index, {
-                        id: String(block.id ?? ""),
-                        name: String(block.name ?? ""),
-                        json: ""
-                    });
+        log.debug("Anthropic request", { model: args.model });
+        let currentRequest = request;
+        for (let continuation = 0; continuation <= MAX_PAUSE_TURN_CONTINUATIONS; continuation++) {
+            // SAFETY: the request is assembled field by field as a dictionary, and
+            // the SDK's param interface is closed — it declares no index signature,
+            // so the two do not overlap.
+            const streamRequest = {
+                ...currentRequest,
+                stream: true
+            };
+            this.recordRequestPayload(streamRequest);
+            const stream = await this.getClient().messages.create(streamRequest, this.requestOptions(args.signal));
+            let inputTokens = 0;
+            let outputTokens = 0;
+            let cachedTokens = 0;
+            let cacheWriteTokens = 0;
+            let stopReason = null;
+            const contentBlocks = [];
+            const jsonByIndex = new Map();
+            const thinkingBlocks = [];
+            const toolCalls = [];
+            for await (const event of stream) {
+                if (event.type === "message_start") {
+                    inputTokens = event.message.usage.input_tokens ?? inputTokens;
+                    cachedTokens =
+                        event.message.usage.cache_read_input_tokens ?? cachedTokens;
+                    cacheWriteTokens =
+                        event.message.usage.cache_creation_input_tokens ?? cacheWriteTokens;
+                    continue;
                 }
-                continue;
-            }
-            if (event.type === "content_block_delta") {
-                const delta = event.delta;
-                if ("thinking" in delta && typeof delta.thinking === "string") {
-                    const chunk = {
-                        type: "chunk",
-                        content: delta.thinking,
-                        done: false,
-                        thinking: true
-                    };
-                    yield chunk;
+                if (event.type === "message_delta") {
+                    outputTokens = event.usage.output_tokens;
+                    inputTokens = event.usage.input_tokens ?? inputTokens;
+                    cachedTokens = event.usage.cache_read_input_tokens ?? cachedTokens;
+                    cacheWriteTokens =
+                        event.usage.cache_creation_input_tokens ?? cacheWriteTokens;
+                    stopReason = event.delta?.stop_reason ?? stopReason;
                     continue;
                 }
-                if ("partial_json" in delta &&
-                    typeof delta.partial_json === "string") {
-                    // Regular tool call: accumulate the JSON into the active block.
-                    const block = activeToolBlocks.get(event.index);
-                    if (block) {
-                        block.json += delta.partial_json;
+                if (event.type === "content_block_start") {
+                    const raw = toRawBlock(event.content_block);
+                    contentBlocks[event.index] = raw;
+                    if (event.content_block.type === "tool_use" ||
+                        event.content_block.type === "server_tool_use") {
+                        jsonByIndex.set(event.index, "");
+                    }
+                    if (event.content_block.type === "thinking") {
+                        thinkingBlocks.push({
+                            type: "thinking",
+                            thinking: event.content_block.thinking,
+                            signature: event.content_block.signature
+                        });
+                    }
+                    else if (event.content_block.type === "redacted_thinking") {
+                        thinkingBlocks.push({
+                            type: "redacted_thinking",
+                            data: event.content_block.data
+                        });
                     }
                     continue;
                 }
-                if ("text" in delta &&
-                    typeof delta.text === "string") {
-                    const chunk = {
-                        type: "chunk",
-                        content: delta.text,
-                        done: false
-                    };
-                    yield chunk;
+                if (event.type === "content_block_delta") {
+                    const index = Number(event.index ?? 0);
+                    const raw = contentBlocks[index] ?? {};
+                    contentBlocks[index] = raw;
+                    const delta = event.delta;
+                    if ("thinking" in delta && isString(delta.thinking)) {
+                        const thinkingDelta = delta.thinking;
+                        raw.thinking = String(raw.thinking ?? "") + thinkingDelta;
+                        const thinking = thinkingBlocks.at(-1);
+                        if (thinking?.type === "thinking")
+                            thinking.thinking += thinkingDelta;
+                        yield {
+                            type: "chunk",
+                            content: thinkingDelta,
+                            done: false,
+                            thinking: true
+                        };
+                    }
+                    else if ("signature" in delta && isString(delta.signature)) {
+                        const signatureDelta = delta.signature;
+                        raw.signature = String(raw.signature ?? "") + signatureDelta;
+                        const thinking = thinkingBlocks.at(-1);
+                        if (thinking?.type === "thinking")
+                            thinking.signature += signatureDelta;
+                    }
+                    else if ("partial_json" in delta && isString(delta.partial_json)) {
+                        jsonByIndex.set(index, (jsonByIndex.get(index) ?? "") + delta.partial_json);
+                    }
+                    else if ("text" in delta && isString(delta.text)) {
+                        const textDelta = delta.text;
+                        raw.text = String(raw.text ?? "") + textDelta;
+                        yield { type: "chunk", content: textDelta, done: false };
+                    }
+                    else if (delta.type === "citations_delta") {
+                        const citations = Array.isArray(raw.citations) ? raw.citations : [];
+                        raw.citations = [...citations, delta.citation];
+                    }
+                    continue;
                 }
-                continue;
-            }
-            if (event.type === "content_block_stop") {
-                // content_block_stop does NOT carry the content_block in the raw API event.
-                // Use the block we recorded from content_block_start + accumulated partial_json.
-                const index = event.index;
-                const toolBlock = activeToolBlocks.get(index);
-                if (toolBlock) {
-                    activeToolBlocks.delete(index);
-                    let parsedArgs = {};
-                    try {
-                        const parsed = JSON.parse(toolBlock.json || "{}");
-                        if (parsed &&
-                            typeof parsed === "object" &&
-                            !Array.isArray(parsed)) {
-                            parsedArgs = parsed;
+                if (event.type === "content_block_stop") {
+                    const raw = contentBlocks[event.index];
+                    const json = jsonByIndex.get(event.index);
+                    if (json !== undefined) {
+                        let input;
+                        try {
+                            input = JSON.parse(json || "{}");
+                        }
+                        catch {
+                            throw new Error("Anthropic returned incomplete tool input JSON");
+                        }
+                        raw.input = input;
+                        jsonByIndex.delete(event.index);
+                        if (raw.type === "tool_use") {
+                            if (!isRecord(input)) {
+                                throw new Error("Anthropic returned non-object tool input");
+                            }
+                            const toolCall = {
+                                id: String(raw.id ?? ""),
+                                name: String(raw.name ?? ""),
+                                args: Object.fromEntries(Object.entries(input)),
+                                _anthropicThinkingBlocks: thinkingBlocks.length > 0 ? [...thinkingBlocks] : undefined
+                            };
+                            toolCalls.push(toolCall);
                         }
                     }
-                    catch {
-                        // malformed JSON — emit empty args
-                    }
-                    const toolCall = {
-                        id: toolBlock.id,
-                        name: toolBlock.name,
-                        args: parsedArgs
-                    };
-                    yield toolCall;
                 }
+            }
+            const hasServerToolContent = contentBlocks.some((block) => block?.type === "server_tool_use" ||
+                String(block?.type ?? "").endsWith("_tool_result"));
+            if (hasServerToolContent) {
+                for (const toolCall of toolCalls) {
+                    toolCall._anthropicContentBlocks = contentBlocks;
+                }
+            }
+            this.trackUsage(args.model, {
+                inputTokens: inputTokens + cachedTokens + cacheWriteTokens,
+                outputTokens,
+                cachedTokens,
+                cacheWriteTokens
+            });
+            if (stopReason === "pause_turn") {
+                if (continuation === MAX_PAUSE_TURN_CONTINUATIONS) {
+                    throw new Error("Anthropic pause_turn continuation limit exceeded");
+                }
+                currentRequest = {
+                    ...currentRequest,
+                    messages: [
+                        ...(currentRequest.messages ?? []),
+                        { role: "assistant", content: contentBlocks }
+                    ]
+                };
                 continue;
             }
-            if (event.type === "message_stop") {
-                const chunk = {
-                    type: "chunk",
-                    content: "",
-                    done: true
+            if (stopReason === "max_tokens" ||
+                stopReason === "model_context_window_exceeded") {
+                throw new Error(`Anthropic response was truncated (${stopReason})`);
+            }
+            if (stopReason === "refusal") {
+                throw new Error("Anthropic refused the request");
+            }
+            const textContent = textContentFromRawBlocks(contentBlocks);
+            if (toolCalls.length === 0 &&
+                textContent.some((part) => part.citations?.length)) {
+                yield {
+                    type: "message",
+                    message: { role: "assistant", content: textContent }
                 };
-                yield chunk;
             }
+            for (const toolCall of toolCalls)
+                yield toolCall;
+            yield { type: "chunk", content: "", done: true };
+            return;
         }
     }
     async generateMessage(args) {
         const system = this.extractSystemMessage(args.messages);
         const converted = await Promise.all(args.messages
             .filter((m) => m.role !== "system")
-            .map((m) => this.convertMessage(m)));
-        const anthropicMessages = converted.filter((m) => m !== null);
-        const formattedTools = args.tools && args.tools.length > 0
-            ? this.formatTools(args.tools)
-            : undefined;
-        let resolvedToolChoice;
-        if (args.toolChoice) {
-            resolvedToolChoice =
-                args.toolChoice === "any"
-                    ? { type: "any" }
-                    : { type: "tool", name: args.toolChoice };
-        }
-        const request = {
+            .map((m) => this.convertMessage(m, args.signal)));
+        const anthropicMessages = mergeToolResultMessages(converted.filter((m) => m !== null));
+        const request = this.buildRequest({
             model: args.model,
             messages: anthropicMessages,
             system,
-            max_tokens: args.maxTokens ?? 8192,
-            ...(formattedTools ? { tools: formattedTools } : {}),
-            ...(resolvedToolChoice ? { tool_choice: resolvedToolChoice } : {}),
-            ...(args.temperature != null ? { temperature: args.temperature } : {}),
-            ...(args.topP != null ? { top_p: args.topP } : {}),
-            ...(args.thinkingBudget != null
-                ? { thinking: { type: "enabled", budget_tokens: args.thinkingBudget } }
-                : {})
-        };
+            tools: args.tools,
+            toolChoice: args.toolChoice,
+            maxTokens: args.maxTokens,
+            temperature: args.temperature,
+            topP: args.topP,
+            thinking: args.thinking,
+            effort: args.effort,
+            thinkingBudget: args.thinkingBudget
+        });
         log.debug("Anthropic request", { model: args.model });
-        const response = await this.getClient().messages.create(request);
-        if (response.usage) {
-            this.trackUsage(args.model, {
-                inputTokens: response.usage.input_tokens ?? 0,
-                outputTokens: response.usage.output_tokens ?? 0,
-                cachedTokens: response.usage.cache_read_input_tokens ?? 0
-            });
+        let currentRequest = request;
+        let response;
+        for (let continuation = 0; continuation <= MAX_PAUSE_TURN_CONTINUATIONS; continuation++) {
+            this.recordRequestPayload(currentRequest);
+            // SAFETY: as above — a dictionary request handed to the SDK's closed
+            // non-streaming param interface.
+            response = await this.getClient().messages.create(currentRequest, this.requestOptions(args.signal));
+            if (response.usage) {
+                const cacheRead = response.usage.cache_read_input_tokens ?? 0;
+                const cacheWrite = response.usage.cache_creation_input_tokens ?? 0;
+                this.trackUsage(args.model, {
+                    inputTokens: response.usage.input_tokens + cacheRead + cacheWrite,
+                    outputTokens: response.usage.output_tokens,
+                    cachedTokens: cacheRead,
+                    cacheWriteTokens: cacheWrite
+                });
+            }
+            if (response.stop_reason !== "pause_turn")
+                break;
+            if (continuation === MAX_PAUSE_TURN_CONTINUATIONS) {
+                throw new Error("Anthropic pause_turn continuation limit exceeded");
+            }
+            currentRequest = {
+                ...currentRequest,
+                messages: [
+                    ...(currentRequest.messages ?? []),
+                    {
+                        role: "assistant",
+                        content: response.content.map(toRawBlock)
+                    }
+                ]
+            };
+        }
+        if (!response)
+            throw new Error("Anthropic returned no response");
+        const stopReason = String(response.stop_reason ?? "");
+        if (stopReason === "max_tokens" ||
+            stopReason === "model_context_window_exceeded") {
+            throw new Error(`Anthropic response was truncated (${stopReason})`);
+        }
+        if (stopReason === "refusal") {
+            throw new Error("Anthropic refused the request");
         }
         const textParts = [];
         const toolCalls = [];
-        for (const block of response.content ?? []) {
+        const thinkingBlocks = [];
+        const rawContentBlocks = response.content.map(toRawBlock);
+        for (const block of response.content) {
             if (block.type === "tool_use") {
-                toolCalls.push({
+                const toolCall = {
                     id: String(block.id ?? ""),
                     name: String(block.name ?? ""),
-                    args: (block.input ?? {})
+                    args: Object.fromEntries(Object.entries(block.input ?? {}))
+                };
+                if (rawContentBlocks.some((raw) => raw.type === "server_tool_use" ||
+                    String(raw.type ?? "").endsWith("_tool_result"))) {
+                    toolCall._anthropicContentBlocks = rawContentBlocks;
+                }
+                toolCalls.push(toolCall);
+                continue;
+            }
+            if (block.type === "thinking") {
+                thinkingBlocks.push({
+                    type: "thinking",
+                    thinking: block.thinking,
+                    signature: block.signature
                 });
                 continue;
             }
+            if (block.type === "redacted_thinking") {
+                thinkingBlocks.push({ type: "redacted_thinking", data: block.data });
+                continue;
+            }
             if (block.type === "text") {
-                textParts.push(String(block.text ?? ""));
+                const citations = block.citations?.map(mapCitation);
+                const textPart = {
+                    type: "text",
+                    text: block.text
+                };
+                if (citations && citations.length > 0) {
+                    textPart.citations = citations;
+                }
+                textParts.push(textPart);
             }
         }
+        const hasCitations = textParts.some((part) => part.citations?.length);
         return {
             role: "assistant",
-            content: textParts.join("\n"),
-            toolCalls
+            content: hasCitations
+                ? textParts
+                : textParts.map((part) => part.text).join("\n"),
+            toolCalls,
+            _anthropicThinkingBlocks: thinkingBlocks.length > 0 ? thinkingBlocks : undefined
         };
     }
     asHttpStatusError(error) {
         return new Error(String(error));
     }
+    isContextExceededError(error) {
+        return anthropicContextExceeded(error) !== null;
+    }
     isContextLengthError(error) {
         const msg = String(error).toLowerCase();
         return (msg.includes("context length") ||