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

package/src/anthropic-message-metadata.ts

@@ -1,12 +1,29 @@
-import { JSONObject } from '@ai-sdk/provider';
+import type { JSONObject } from '@ai-sdk/provider';
 
 /**
  * Represents a single iteration in the usage breakdown.
- * When compaction occurs, the API returns an iterations array showing
- * usage for each sampling iteration (compaction + message).
+ *
+ * The API returns an iterations array showing usage for each sampling
+ * iteration. Iterations can be:
+ * - `compaction`: a context compaction step (billed at executor rates).
+ * - `message`: an executor sampling iteration (billed at executor rates).
+ * - `advisor_message`: an advisor sub-inference (billed at the advisor
+ *   model's rates). Advisor token usage is NOT rolled into the top-level
+ *   usage totals because it bills at a different rate; inspect this array
+ *   directly for advisor billing.
+ * - `fallback_message`: a server-side fallback attempt that served the turn.
+ *   Inspect this array for exact per-model attribution on a turn that fell
+ *   back.
  */
-export interface AnthropicUsageIteration {
-  type: 'compaction' | 'message';
+export type AnthropicUsageIteration = {
+  type: 'compaction' | 'message' | 'advisor_message' | 'fallback_message';
+
+  /**
+   * The model that produced this iteration. Populated for the per-model
+   * attribution cases (the fallback chain and advisor sub-inferences) and
+   * absent otherwise.
+   */
+  model?: string;
 
   /**
    * Number of input tokens consumed in this iteration.
@@ -17,15 +34,58 @@ export interface AnthropicUsageIteration {
    * Number of output tokens generated in this iteration.
    */
   outputTokens: number;
-}
+
+  /**
+   * Number of cache-creation input tokens consumed in this iteration.
+   */
+  cacheCreationInputTokens?: number;
+
+  /**
+   * Number of cache-read input tokens consumed in this iteration.
+   */
+  cacheReadInputTokens?: number;
+};
 
 export interface AnthropicMessageMetadata {
   usage: JSONObject;
-  // TODO remove cacheCreationInputTokens in AI SDK 6
-  // (use value in usage object instead)
-  cacheCreationInputTokens: number | null;
   stopSequence: string | null;
 
+  /**
+   * Details about why the request stopped. Present only when the API returns
+   * a `refusal` stop reason together with a `stop_details` object (a
+   * classifier block or a model refusal).
+   *
+   * Branch on the finish reason (`content-filter`), not on this object: the
+   * API may return a refusal with no details at all, so this field can be
+   * absent even on a refusal and should not be relied upon being present.
+   */
+  stopDetails?: {
+    /**
+     * The kind of stop detail. `'refusal'` for classifier blocks and model
+     * refusals.
+     */
+    type: string;
+
+    /**
+     * The classifier category that triggered the block, e.g. `'cyber'` or
+     * `'bio'`. Absent for model refusals and other cases.
+     */
+    category?: string;
+
+    /**
+     * Human-readable explanation of why the request was blocked. May be
+     * absent even on a refusal.
+     */
+    explanation?: string;
+
+    /**
+     * The canonical id of a model to retry directly. Populated only when the
+     * request included fallbacks and the fallback attempt could not be made
+     * (e.g. the fallback model was rate limited or overloaded).
+     */
+    recommendedModel?: string;
+  };
+
   /**
    * Usage breakdown by iteration when compaction is triggered.
    *

package/src/anthropic-prepare-tools.ts

@@ -1,10 +1,11 @@
 import {
-  LanguageModelV4CallOptions,
-  SharedV4Warning,
   UnsupportedFunctionalityError,
+  type LanguageModelV4CallOptions,
+  type SharedV4Warning,
 } from '@ai-sdk/provider';
-import { AnthropicTool, AnthropicToolChoice } from './anthropic-messages-api';
+import type { AnthropicTool, AnthropicToolChoice } from './anthropic-api';
 import { CacheControlValidator } from './get-cache-control';
+import { advisor_20260301ArgsSchema } from './tool/advisor_20260301';
 import { textEditor_20250728ArgsSchema } from './tool/text-editor_20250728';
 import { webSearch_20260209ArgsSchema } from './tool/web-search_20260209';
 import { webSearch_20250305ArgsSchema } from './tool/web-search_20250305';
@@ -27,6 +28,7 @@ export async function prepareTools({
   cacheControlValidator,
   supportsStructuredOutput,
   supportsStrictTools,
+  defaultEagerInputStreaming = false,
 }: {
   tools: LanguageModelV4CallOptions['tools'];
   toolChoice: LanguageModelV4CallOptions['toolChoice'] | undefined;
@@ -42,6 +44,12 @@ export async function prepareTools({
    * Whether the model supports strict mode on tool definitions.
    */
   supportsStrictTools: boolean;
+
+  /**
+   * Default for `eager_input_streaming` on function tools that do not set
+   * it explicitly. Driven by the model-level `toolStreaming` option.
+   */
+  defaultEagerInputStreaming?: boolean;
 }): Promise<{
   tools: Array<AnthropicTool> | undefined;
   toolChoice: AnthropicToolChoice | undefined;
@@ -73,8 +81,10 @@ export async function prepareTools({
         const anthropicOptions = tool.providerOptions?.anthropic as
           | AnthropicToolOptions
           | undefined;
-        // eager_input_streaming is only supported on custom (function) tools
-        const eagerInputStreaming = anthropicOptions?.eagerInputStreaming;
+        // eager_input_streaming is only supported on custom (function) tools.
+        // Fall back to the model-level default when the tool doesn't set it.
+        const eagerInputStreaming =
+          anthropicOptions?.eagerInputStreaming ?? defaultEagerInputStreaming;
         const deferLoading = anthropicOptions?.deferLoading;
         const allowedCallers = anthropicOptions?.allowedCallers;
 
@@ -322,7 +332,6 @@ export async function prepareTools({
           }
 
           case 'anthropic.tool_search_regex_20251119': {
-            betas.add('advanced-tool-use-2025-11-20');
             anthropicTools.push({
               type: 'tool_search_tool_regex_20251119',
               name: 'tool_search_tool_regex',
@@ -331,7 +340,6 @@ export async function prepareTools({
           }
 
           case 'anthropic.tool_search_bm25_20251119': {
-            betas.add('advanced-tool-use-2025-11-20');
             anthropicTools.push({
               type: 'tool_search_tool_bm25_20251119',
               name: 'tool_search_tool_bm25',
@@ -339,6 +347,22 @@ export async function prepareTools({
             break;
           }
 
+          case 'anthropic.advisor_20260301': {
+            betas.add('advisor-tool-2026-03-01');
+            const args = await validateTypes({
+              value: tool.args,
+              schema: advisor_20260301ArgsSchema,
+            });
+            anthropicTools.push({
+              type: 'advisor_20260301',
+              name: 'advisor',
+              model: args.model,
+              ...(args.maxUses !== undefined && { max_uses: args.maxUses }),
+              ...(args.caching !== undefined && { caching: args.caching }),
+            });
+            break;
+          }
+
           default: {
             toolWarnings.push({
               type: 'unsupported',

package/src/anthropic-provider.ts

@@ -1,42 +1,53 @@
 import {
   InvalidArgumentError,
-  LanguageModelV4,
   NoSuchModelError,
-  ProviderV4,
+  type FilesV4,
+  type LanguageModelV4,
+  type ProviderV4,
+  type SkillsV4,
 } from '@ai-sdk/provider';
 import {
-  FetchFunction,
   generateId,
   loadApiKey,
   loadOptionalSetting,
   withoutTrailingSlash,
   withUserAgentSuffix,
+  type FetchFunction,
 } from '@ai-sdk/provider-utils';
-import { VERSION } from './version';
-import { AnthropicMessagesLanguageModel } from './anthropic-messages-language-model';
-import { AnthropicMessagesModelId } from './anthropic-messages-options';
+import { AnthropicFiles } from './anthropic-files';
+import { AnthropicLanguageModel } from './anthropic-language-model';
+import type { AnthropicModelId } from './anthropic-language-model-options';
 import { anthropicTools } from './anthropic-tools';
+import { AnthropicSkills } from './skills/anthropic-skills';
+import { VERSION } from './version';
 
 export interface AnthropicProvider extends ProviderV4 {
   /**
    * Creates a model for text generation.
    */
-  (modelId: AnthropicMessagesModelId): LanguageModelV4;
+  (modelId: AnthropicModelId): LanguageModelV4;
 
   /**
    * Creates a model for text generation.
    */
-  languageModel(modelId: AnthropicMessagesModelId): LanguageModelV4;
+  languageModel(modelId: AnthropicModelId): LanguageModelV4;
 
-  chat(modelId: AnthropicMessagesModelId): LanguageModelV4;
+  chat(modelId: AnthropicModelId): LanguageModelV4;
 
-  messages(modelId: AnthropicMessagesModelId): LanguageModelV4;
+  messages(modelId: AnthropicModelId): LanguageModelV4;
 
   /**
    * @deprecated Use `embeddingModel` instead.
    */
   textEmbeddingModel(modelId: string): never;
 
+  files(): FilesV4;
+
+  /**
+   * Returns a SkillsV4 interface for uploading skills to Anthropic.
+   */
+  skills(): SkillsV4;
+
   /**
    * Anthropic-specific computer use tool.
    */
@@ -130,8 +141,8 @@ export function createAnthropic(
     );
   };
 
-  const createChatModel = (modelId: AnthropicMessagesModelId) =>
-    new AnthropicMessagesLanguageModel(modelId, {
+  const createChatModel = (modelId: AnthropicModelId) =>
+    new AnthropicLanguageModel(modelId, {
       provider: providerName,
       baseURL,
       headers: getHeaders,
@@ -143,7 +154,15 @@ export function createAnthropic(
       }),
     });
 
-  const provider = function (modelId: AnthropicMessagesModelId) {
+  const createSkills = () =>
+    new AnthropicSkills({
+      provider: `${providerName.replace('.messages', '')}.skills`,
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const provider = function (modelId: AnthropicModelId) {
     if (new.target) {
       throw new Error(
         'The Anthropic model function cannot be called with the new keyword.',
@@ -166,6 +185,16 @@ export function createAnthropic(
     throw new NoSuchModelError({ modelId, modelType: 'imageModel' });
   };
 
+  provider.files = () =>
+    new AnthropicFiles({
+      provider: providerName,
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  provider.skills = createSkills;
+
   provider.tools = anthropicTools;
 
   return provider;

package/src/anthropic-tools.ts

@@ -1,3 +1,4 @@
+import { advisor_20260301 } from './tool/advisor_20260301';
 import { bash_20241022 } from './tool/bash_20241022';
 import { bash_20250124 } from './tool/bash_20250124';
 import { codeExecution_20250522 } from './tool/code-execution_20250522';
@@ -19,6 +20,36 @@ import { webSearch_20260209 } from './tool/web-search_20260209';
 import { webSearch_20250305 } from './tool/web-search_20250305';
 
 export const anthropicTools = {
+  /**
+   * Pairs a faster executor model with a higher-intelligence advisor model
+   * that provides strategic guidance mid-generation.
+   *
+   * The advisor lets a faster, lower-cost executor model consult a
+   * higher-intelligence advisor model server-side. The advisor reads the
+   * executor's full transcript and produces a plan or course correction;
+   * the executor continues with the task, informed by the advice. All of
+   * this happens inside a single `/v1/messages` request.
+   *
+   * Beta header `advisor-tool-2026-03-01` is added automatically when this
+   * tool is included.
+   *
+   * Multi-turn conversations: pass the full assistant content (including
+   * `advisor_tool_result` blocks) back to the API on subsequent turns. If
+   * you omit the advisor tool from `tools` on a follow-up turn while the
+   * message history still contains `advisor_tool_result` blocks, the API
+   * returns a `400 invalid_request_error`.
+   *
+   * Supported executor models: Claude Haiku 4.5, Sonnet 4.6, Opus 4.6,
+   * Opus 4.7. The advisor must be at least as capable as the executor.
+   *
+   * @param model - The advisor model ID (required), e.g. `"claude-opus-4-8"`.
+   * @param maxUses - Maximum advisor calls per request (per-request cap).
+   * @param caching - Enables prompt caching for the advisor's transcript
+   * across calls within a conversation. Worthwhile from ~3 advisor calls
+   * per conversation.
+   */
+  advisor_20260301,
+
   /**
    * The bash tool enables Claude to execute shell commands in a persistent bash session,
    * allowing system operations, script execution, and command-line automation.

package/src/convert-anthropic-usage.ts

@@ -0,0 +1,109 @@
+import type { JSONObject, LanguageModelV4Usage } from '@ai-sdk/provider';
+
+/**
+ * Represents a single iteration in the usage breakdown.
+ *
+ * - `compaction` / `message`: executor iterations, billed at executor rates.
+ * - `advisor_message`: advisor sub-inference, billed at the advisor model's
+ *   rates. Advisor tokens are NOT rolled into the top-level totals because
+ *   they bill at a different rate; inspect this array for advisor cost
+ *   tracking.
+ * - `fallback_message`: a server-side fallback attempt that served the turn.
+ *   When present, the top-level usage already reflects the served answer, so
+ *   it is used as-is.
+ *
+ * The `model` field carries the model that produced the iteration. The API
+ * populates it for the per-model attribution cases (the fallback chain and
+ * advisor sub-inferences) and omits it otherwise.
+ */
+export type AnthropicUsageIteration = {
+  type: 'compaction' | 'message' | 'advisor_message' | 'fallback_message';
+  model?: string | null;
+  input_tokens: number;
+  output_tokens: number;
+  cache_creation_input_tokens?: number | null;
+  cache_read_input_tokens?: number | null;
+};
+
+export type AnthropicUsage = {
+  input_tokens: number;
+  output_tokens: number;
+  cache_creation_input_tokens?: number | null;
+  cache_read_input_tokens?: number | null;
+  /**
+   * When compaction is triggered or the advisor tool is invoked, this
+   * array contains usage for each sampling iteration. Top-level
+   * input_tokens and output_tokens exclude compaction iteration usage,
+   * and the advisor sub-inference is also not rolled into the top-level
+   * totals because it bills at a different rate. Use this array for
+   * per-iteration cost tracking.
+   */
+  iterations?: AnthropicUsageIteration[] | null;
+};
+
+export function convertAnthropicUsage({
+  usage,
+  rawUsage,
+}: {
+  usage: AnthropicUsage;
+  rawUsage?: JSONObject;
+}): LanguageModelV4Usage {
+  const cacheCreationTokens = usage.cache_creation_input_tokens ?? 0;
+  const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
+
+  // When iterations is present (compaction or advisor), sum across executor
+  // iterations to get the true executor totals. The top-level input_tokens
+  // and output_tokens exclude compaction usage. Advisor (`advisor_message`)
+  // iterations are filtered out: they bill at the advisor model's rates,
+  // not the executor's, so they don't belong in the top-level totals.
+  //
+  // A turn served by a server-side fallback is the exception: the served
+  // answer comes from the fallback model, so the executor `message` iteration
+  // is the blocked primary attempt (zero output). The top-level totals already
+  // reflect the fallback answer, so they are used directly.
+  let inputTokens: number;
+  let outputTokens: number;
+
+  const servedByFallback = usage.iterations?.some(
+    iter => iter.type === 'fallback_message',
+  );
+
+  if (usage.iterations && usage.iterations.length > 0 && !servedByFallback) {
+    const executorIterations = usage.iterations.filter(
+      iter => iter.type === 'compaction' || iter.type === 'message',
+    );
+
+    if (executorIterations.length > 0) {
+      const totals = executorIterations.reduce(
+        (acc, iter) => ({
+          input: acc.input + iter.input_tokens,
+          output: acc.output + iter.output_tokens,
+        }),
+        { input: 0, output: 0 },
+      );
+      inputTokens = totals.input;
+      outputTokens = totals.output;
+    } else {
+      inputTokens = usage.input_tokens;
+      outputTokens = usage.output_tokens;
+    }
+  } else {
+    inputTokens = usage.input_tokens;
+    outputTokens = usage.output_tokens;
+  }
+
+  return {
+    inputTokens: {
+      total: inputTokens + cacheCreationTokens + cacheReadTokens,
+      noCache: inputTokens,
+      cacheRead: cacheReadTokens,
+      cacheWrite: cacheCreationTokens,
+    },
+    outputTokens: {
+      total: outputTokens,
+      text: undefined,
+      reasoning: undefined,
+    },
+    raw: rawUsage ?? usage,
+  };
+}