@ai-sdk/anthropic 4.0.0-beta.5 → 4.0.0-beta.67

package/src/{anthropic-messages-api.ts → anthropic-api.ts}

@@ -1,25 +1,38 @@
-import { JSONSchema7 } from '@ai-sdk/provider';
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import type { JSONSchema7 } from '@ai-sdk/provider';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
-export type AnthropicMessagesPrompt = {
+export type AnthropicPrompt = {
   system: Array<AnthropicTextContent> | undefined;
   messages: AnthropicMessage[];
 };
 
-export type AnthropicMessage = AnthropicUserMessage | AnthropicAssistantMessage;
+export type AnthropicMessage =
+  | AnthropicUserMessage
+  | AnthropicAssistantMessage
+  | AnthropicSystemMessage;
 
 export type AnthropicCacheControl = {
   type: 'ephemeral';
   ttl?: '5m' | '1h';
 };
 
+export interface AnthropicSystemMessage {
+  role: 'system';
+  content: Array<AnthropicTextContent>;
+}
+
 export interface AnthropicUserMessage {
   role: 'user';
   content: Array<
     | AnthropicTextContent
     | AnthropicImageContent
     | AnthropicDocumentContent
+    | AnthropicContainerUploadContent
     | AnthropicToolResultContent
   >;
 }
@@ -38,6 +51,7 @@ export interface AnthropicAssistantMessage {
     | AnthropicToolSearchToolResultContent
     | AnthropicBashCodeExecutionToolResultContent
     | AnthropicTextEditorCodeExecutionToolResultContent
+    | AnthropicAdvisorToolResultContent
     | AnthropicMcpToolUseContent
     | AnthropicMcpToolResultContent
     | AnthropicCompactionContent
@@ -87,6 +101,10 @@ type AnthropicContentSource =
       type: 'text';
       media_type: 'text/plain';
       data: string;
+    }
+  | {
+      type: 'file';
+      file_id: string;
     };
 
 export interface AnthropicImageContent {
@@ -104,6 +122,12 @@ export interface AnthropicDocumentContent {
   cache_control: AnthropicCacheControl | undefined;
 }
 
+export interface AnthropicContainerUploadContent {
+  type: 'container_upload';
+  file_id: string;
+  cache_control?: never;
+}
+
 /**
  * The caller information for programmatic tool calling.
  * Present when a tool is called from within code execution.
@@ -147,7 +171,9 @@ export interface AnthropicServerToolUseContent {
     | 'text_editor_code_execution'
     // tool search:
     | 'tool_search_tool_regex'
-    | 'tool_search_tool_bm25';
+    | 'tool_search_tool_bm25'
+    // advisor:
+    | 'advisor';
   input: unknown;
   cache_control: AnthropicCacheControl | undefined;
 }
@@ -198,13 +224,18 @@ export interface AnthropicToolResultContent {
 export interface AnthropicWebSearchToolResultContent {
   type: 'web_search_tool_result';
   tool_use_id: string;
-  content: Array<{
-    url: string;
-    title: string | null;
-    page_age: string | null;
-    encrypted_content: string;
-    type: string;
-  }>;
+  content:
+    | Array<{
+        url: string;
+        title: string | null;
+        page_age: string | null;
+        encrypted_content: string;
+        type: string;
+      }>
+    | {
+        type: 'web_search_tool_result_error';
+        error_code: string;
+      };
   cache_control: AnthropicCacheControl | undefined;
 }
 
@@ -306,6 +337,30 @@ export interface AnthropicBashCodeExecutionToolResultContent {
   cache_control: AnthropicCacheControl | undefined;
 }
 
+export interface AnthropicAdvisorToolResultContent {
+  type: 'advisor_tool_result';
+  tool_use_id: string;
+  content:
+    | {
+        type: 'advisor_result';
+        text: string;
+      }
+    | {
+        type: 'advisor_redacted_result';
+        encrypted_content: string;
+      }
+    | {
+        type: 'advisor_tool_result_error';
+        /**
+         * Available options: `max_uses_exceeded`, `too_many_requests`,
+         * `overloaded`, `prompt_too_long`, `execution_time_exceeded`,
+         * `unavailable`.
+         */
+        error_code: string;
+      };
+  cache_control: AnthropicCacheControl | undefined;
+}
+
 export interface AnthropicWebFetchToolResultContent {
   type: 'web_fetch_tool_result';
   tool_use_id: string;
@@ -455,6 +510,16 @@ export type AnthropicTool =
   | {
       type: 'tool_search_tool_bm25_20251119';
       name: string;
+    }
+  | {
+      type: 'advisor_20260301';
+      name: 'advisor';
+      model: string;
+      max_uses?: number;
+      caching?: {
+        type: 'ephemeral';
+        ttl: '5m' | '1h';
+      };
     };
 
 export type AnthropicSpeed = 'fast' | 'standard';
@@ -547,9 +612,18 @@ export type AnthropicResponseContextManagement = {
   applied_edits: AnthropicResponseContextManagementEdit[];
 };
 
+const anthropicStopDetailsSchema = z.object({
+  type: z.string(),
+  category: z.string().nullish(),
+  explanation: z.string().nullish(),
+  recommended_model: z.string().nullish(),
+});
+
+export type AnthropicStopDetails = z.infer<typeof anthropicStopDetailsSchema>;
+
 // limited version of the schema, focussed on what is needed for the implementation
 // this approach limits breakages when the API changes and increases efficiency
-export const anthropicMessagesResponseSchema = lazySchema(() =>
+export const anthropicResponseSchema = lazySchema(() =>
   zodSchema(
     z.object({
       type: z.literal('message'),
@@ -828,10 +902,36 @@ export const anthropicMessagesResponseSchema = lazySchema(() =>
               }),
             ]),
           }),
+          // advisor results for advisor_20260301:
+          z.object({
+            type: z.literal('advisor_tool_result'),
+            tool_use_id: z.string(),
+            content: z.discriminatedUnion('type', [
+              z.object({
+                type: z.literal('advisor_result'),
+                text: z.string(),
+              }),
+              z.object({
+                type: z.literal('advisor_redacted_result'),
+                encrypted_content: z.string(),
+              }),
+              z.object({
+                type: z.literal('advisor_tool_result_error'),
+                error_code: z.string(),
+              }),
+            ]),
+          }),
+          // Server-side fallback marker. Parsed so the response validates, but
+          // dropped from the content output (the AI SDK has no model-hop
+          // primitive). The hop remains observable via usage.iterations.
+          z.object({
+            type: z.literal('fallback'),
+          }),
         ]),
       ),
       stop_reason: z.string().nullish(),
       stop_sequence: z.string().nullish(),
+      stop_details: anthropicStopDetailsSchema.nullish(),
       usage: z.looseObject({
         input_tokens: z.number(),
         output_tokens: z.number(),
@@ -840,9 +940,17 @@ export const anthropicMessagesResponseSchema = lazySchema(() =>
         iterations: z
           .array(
             z.object({
-              type: z.union([z.literal('compaction'), z.literal('message')]),
+              type: z.union([
+                z.literal('compaction'),
+                z.literal('message'),
+                z.literal('advisor_message'),
+                z.literal('fallback_message'),
+              ]),
+              model: z.string().nullish(),
               input_tokens: z.number(),
               output_tokens: z.number(),
+              cache_creation_input_tokens: z.number().nullish(),
+              cache_read_input_tokens: z.number().nullish(),
             }),
           )
           .nullish(),
@@ -889,7 +997,7 @@ export const anthropicMessagesResponseSchema = lazySchema(() =>
 
 // limited version of the schema, focused on what is needed for the implementation
 // this approach limits breakages when the API changes and increases efficiency
-export const anthropicMessagesChunkSchema = lazySchema(() =>
+export const anthropicChunkSchema = lazySchema(() =>
   zodSchema(
     z.discriminatedUnion('type', [
       z.object({
@@ -1186,6 +1294,30 @@ export const anthropicMessagesChunkSchema = lazySchema(() =>
               }),
             ]),
           }),
+          // advisor results for advisor_20260301:
+          z.object({
+            type: z.literal('advisor_tool_result'),
+            tool_use_id: z.string(),
+            content: z.discriminatedUnion('type', [
+              z.object({
+                type: z.literal('advisor_result'),
+                text: z.string(),
+              }),
+              z.object({
+                type: z.literal('advisor_redacted_result'),
+                encrypted_content: z.string(),
+              }),
+              z.object({
+                type: z.literal('advisor_tool_result_error'),
+                error_code: z.string(),
+              }),
+            ]),
+          }),
+          // Server-side fallback marker; dropped from content output (see the
+          // response schema). The hop remains observable via usage.iterations.
+          z.object({
+            type: z.literal('fallback'),
+          }),
         ]),
       }),
       z.object({
@@ -1258,6 +1390,7 @@ export const anthropicMessagesChunkSchema = lazySchema(() =>
         delta: z.object({
           stop_reason: z.string().nullish(),
           stop_sequence: z.string().nullish(),
+          stop_details: anthropicStopDetailsSchema.nullish(),
           container: z
             .object({
               expires_at: z.string(),
@@ -1285,9 +1418,17 @@ export const anthropicMessagesChunkSchema = lazySchema(() =>
           iterations: z
             .array(
               z.object({
-                type: z.union([z.literal('compaction'), z.literal('message')]),
+                type: z.union([
+                  z.literal('compaction'),
+                  z.literal('message'),
+                  z.literal('advisor_message'),
+                  z.literal('fallback_message'),
+                ]),
+                model: z.string().nullish(),
                 input_tokens: z.number(),
                 output_tokens: z.number(),
+                cache_creation_input_tokens: z.number().nullish(),
+                cache_read_input_tokens: z.number().nullish(),
               }),
             )
             .nullish(),
@@ -1338,7 +1479,7 @@ export type AnthropicReasoningMetadata = InferSchema<
 >;
 
 export type Citation = NonNullable<
-  (InferSchema<typeof anthropicMessagesResponseSchema>['content'][number] & {
+  (InferSchema<typeof anthropicResponseSchema>['content'][number] & {
     type: 'text';
   })['citations']
 >[number];

package/src/anthropic-error.ts

@@ -1,8 +1,8 @@
 import {
   createJsonErrorResponseHandler,
-  InferSchema,
   lazySchema,
   zodSchema,
+  type InferSchema,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 

package/src/anthropic-files.ts

@@ -0,0 +1,95 @@
+import type {
+  FilesV4,
+  FilesV4UploadFileCallOptions,
+  FilesV4UploadFileResult,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertInlineFileDataToUint8Array,
+  createJsonResponseHandler,
+  lazySchema,
+  postFormDataToApi,
+  zodSchema,
+  type FetchFunction,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { anthropicFailedResponseHandler } from './anthropic-error';
+
+const anthropicUploadFileResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      id: z.string(),
+      type: z.literal('file'),
+      filename: z.string(),
+      mime_type: z.string(),
+      size_bytes: z.number(),
+      created_at: z.string(),
+      downloadable: z.boolean().nullish(),
+    }),
+  ),
+);
+
+interface AnthropicFilesConfig {
+  provider: string;
+  baseURL: string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+}
+
+export class AnthropicFiles implements FilesV4 {
+  readonly specificationVersion = 'v4';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(private readonly config: AnthropicFilesConfig) {}
+
+  async uploadFile({
+    data,
+    mediaType,
+    filename,
+  }: FilesV4UploadFileCallOptions): Promise<FilesV4UploadFileResult> {
+    const fileBytes = convertInlineFileDataToUint8Array(data);
+
+    const blob = new Blob([fileBytes], { type: mediaType });
+
+    const formData = new FormData();
+    if (filename != null) {
+      formData.append('file', blob, filename);
+    } else {
+      formData.append('file', blob);
+    }
+
+    const { value: response } = await postFormDataToApi({
+      url: `${this.config.baseURL}/files`,
+      headers: combineHeaders(this.config.headers(), {
+        'anthropic-beta': 'files-api-2025-04-14',
+      }),
+      formData,
+      failedResponseHandler: anthropicFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        anthropicUploadFileResponseSchema,
+      ),
+      fetch: this.config.fetch,
+    });
+
+    return {
+      warnings: [],
+      providerReference: { anthropic: response.id },
+      mediaType: response.mime_type ?? mediaType,
+      filename: response.filename ?? filename,
+      providerMetadata: {
+        anthropic: {
+          filename: response.filename,
+          mimeType: response.mime_type,
+          sizeBytes: response.size_bytes,
+          createdAt: response.created_at,
+          ...(response.downloadable != null
+            ? { downloadable: response.downloadable }
+            : {}),
+        },
+      },
+    };
+  }
+}

package/src/{anthropic-messages-options.ts → anthropic-language-model-options.ts}

@@ -1,7 +1,7 @@
 import { z } from 'zod/v4';
 
 // https://docs.claude.com/en/docs/about-claude/models/overview
-export type AnthropicMessagesModelId =
+export type AnthropicModelId =
   | 'claude-3-haiku-20240307'
   | 'claude-haiku-4-5-20251001'
   | 'claude-haiku-4-5'
@@ -17,6 +17,9 @@ export type AnthropicMessagesModelId =
   | 'claude-sonnet-4-5'
   | 'claude-sonnet-4-6'
   | 'claude-opus-4-6'
+  | 'claude-opus-4-7'
+  | 'claude-opus-4-8'
+  | 'claude-fable-5'
   | (string & {});
 
 /**
@@ -24,6 +27,12 @@ export type AnthropicMessagesModelId =
  * These options apply to individual file parts (documents).
  */
 export const anthropicFilePartProviderOptions = z.object({
+  /**
+   * Upload this file into the code execution container instead of sending it as
+   * a normal document or image content block.
+   */
+  containerUpload: z.boolean().optional(),
+
   /**
    * Citation configuration for this document.
    * When enabled, this document will generate citations in the response.
@@ -83,6 +92,12 @@ export const anthropicLanguageModelOptions = z.object({
       z.object({
         /** for Sonnet 4.6, Opus 4.6, and newer models */
         type: z.literal('adaptive'),
+        /**
+         * Controls whether thinking content is included in the response.
+         * - `"omitted"`: Thinking blocks are present but text is empty (default for Opus 4.7+).
+         * - `"summarized"`: Thinking content is returned. Required to see reasoning output.
+         */
+        display: z.enum(['omitted', 'summarized']).optional(),
       }),
       z.object({
         /** for models before Opus 4.6, except Sonnet 4.6 still supports it */
@@ -112,6 +127,23 @@ export const anthropicLanguageModelOptions = z.object({
     })
     .optional(),
 
+  /**
+   * Metadata to include with the request.
+   *
+   * See https://platform.claude.com/docs/en/api/messages/create for details.
+   */
+  metadata: z
+    .object({
+      /**
+       * An external identifier for the user associated with the request.
+       *
+       * Should be a UUID, hash value, or other opaque identifier.
+       * Must not contain PII (name, email, phone number, etc.).
+       */
+      userId: z.string().optional(),
+    })
+    .optional(),
+
   /**
    * MCP servers to be utilized in this request.
    */
@@ -142,21 +174,29 @@ export const anthropicLanguageModelOptions = z.object({
       id: z.string().optional(),
       skills: z
         .array(
-          z.object({
-            type: z.union([z.literal('anthropic'), z.literal('custom')]),
-            skillId: z.string(),
-            version: z.string().optional(),
-          }),
+          z.discriminatedUnion('type', [
+            z.object({
+              type: z.literal('anthropic'),
+              skillId: z.string(),
+              version: z.string().optional(),
+            }),
+            z.object({
+              type: z.literal('custom'),
+              providerReference: z.record(z.string(), z.string()),
+              version: z.string().optional(),
+            }),
+          ]),
         )
         .optional(),
     })
     .optional(),
 
   /**
-   * Whether to enable tool streaming (and structured output streaming).
-   *
-   * When set to false, the model will return all tool calls and results
-   * at once after a delay.
+   * Whether to enable fine-grained (eager) streaming of tool call inputs
+   * and structured outputs for every function tool in the request. When
+   * true (the default), each function tool receives a default of
+   * `eager_input_streaming: true` unless it explicitly sets
+   * `providerOptions.anthropic.eagerInputStreaming`.
    *
    * @default true
    */
@@ -165,7 +205,22 @@ export const anthropicLanguageModelOptions = z.object({
   /**
    * @default 'high'
    */
-  effort: z.enum(['low', 'medium', 'high', 'max']).optional(),
+  effort: z.enum(['low', 'medium', 'high', 'xhigh', 'max']).optional(),
+
+  /**
+   * Task budget for agentic turns. Informs the model of the total token budget
+   * available for the current task, allowing it to prioritize work and wind down
+   * gracefully as the budget is consumed.
+   *
+   * Advisory only — does not enforce a hard token limit.
+   */
+  taskBudget: z
+    .object({
+      type: z.literal('tokens'),
+      total: z.number().int().min(20000),
+      remaining: z.number().int().min(0).optional(),
+    })
+    .optional(),
 
   /**
    * Enable fast mode for faster inference (2.5x faster output token speeds).
@@ -173,6 +228,44 @@ export const anthropicLanguageModelOptions = z.object({
    */
   speed: z.enum(['fast', 'standard']).optional(),
 
+  /**
+   * Controls where model inference runs for this request.
+   *
+   * - `"global"`: Inference may run in any available geography (default).
+   * - `"us"`: Inference runs only in US-based infrastructure.
+   *
+   * See https://platform.claude.com/docs/en/build-with-claude/data-residency
+   */
+  inferenceGeo: z.enum(['us', 'global']).optional(),
+
+  /**
+   * Server-side fallback chain.
+   *
+   * When the primary model's safety classifiers block a turn, the API
+   * automatically retries it on the next model in the chain, server-side. A
+   * `content-filter` finish reason means the entire chain refused.
+   *
+   * Each entry is merged into the request as a direct request to that entry's
+   * model, so it must be formatted accordingly: `model` is required, and an
+   * entry may additionally override `max_tokens`, `thinking`, `output_config`,
+   * and `speed` for that attempt only (`speed` additionally requires the speed
+   * beta). The value is passed through to the API as-is.
+   *
+   * The required `server-side-fallback-2026-06-01` beta is added automatically
+   * when this option is set.
+   */
+  fallbacks: z
+    .array(
+      z.object({
+        model: z.string(),
+        max_tokens: z.number().int().optional(),
+        thinking: z.record(z.string(), z.unknown()).optional(),
+        output_config: z.record(z.string(), z.unknown()).optional(),
+        speed: z.enum(['fast', 'standard']).optional(),
+      }),
+    )
+    .optional(),
+
   /**
    * A set of beta features to enable.
    * Allow a provider to receive the full `betas` set if it needs it.