@ai-sdk/anthropic 3.0.75 → 3.0.77

package/src/convert-anthropic-messages-usage.ts

@@ -2,14 +2,29 @@ import type { JSONObject, LanguageModelV3Usage } 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).
+ *
+ * - `compaction` / `message`: executor iterations, billed at executor rates.
+ * - `advisor_message`: advisor sub-inference, billed at the advisor model's
+ *   rates. The `model` field carries the advisor model ID. Advisor tokens
+ *   are NOT rolled into the top-level totals because they bill at a
+ *   different rate; inspect this array for advisor cost tracking.
  */
-export type AnthropicUsageIteration = {
-  type: 'compaction' | 'message';
-  input_tokens: number;
-  output_tokens: number;
-};
+export type AnthropicUsageIteration =
+  | {
+      type: 'compaction' | 'message';
+      input_tokens: number;
+      output_tokens: number;
+      cache_creation_input_tokens?: number | null;
+      cache_read_input_tokens?: number | null;
+    }
+  | {
+      type: 'advisor_message';
+      model: string;
+      input_tokens: number;
+      output_tokens: number;
+      cache_creation_input_tokens?: number | null;
+      cache_read_input_tokens?: number | null;
+    };
 
 export type AnthropicMessagesUsage = {
   input_tokens: number;
@@ -17,10 +32,12 @@ export type AnthropicMessagesUsage = {
   cache_creation_input_tokens?: number | null;
   cache_read_input_tokens?: number | null;
   /**
-   * When compaction is triggered, this array contains usage for each
-   * sampling iteration. The top-level input_tokens and output_tokens
-   * do NOT include compaction iteration usage - to get total tokens
-   * consumed and billed, sum across all entries in this array.
+   * 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;
 };
@@ -35,22 +52,33 @@ export function convertAnthropicMessagesUsage({
   const cacheCreationTokens = usage.cache_creation_input_tokens ?? 0;
   const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
 
-  // When iterations is present (compaction occurred), sum across all iterations
-  // to get the true total tokens consumed/billed. The top-level input_tokens
-  // and output_tokens exclude compaction iteration usage.
+  // 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.
   let inputTokens: number;
   let outputTokens: number;
 
   if (usage.iterations && usage.iterations.length > 0) {
-    const totals = usage.iterations.reduce(
-      (acc, iter) => ({
-        input: acc.input + iter.input_tokens,
-        output: acc.output + iter.output_tokens,
-      }),
-      { input: 0, output: 0 },
+    const executorIterations = usage.iterations.filter(
+      iter => iter.type === 'compaction' || iter.type === 'message',
     );
-    inputTokens = totals.input;
-    outputTokens = totals.output;
+
+    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;

package/src/convert-to-anthropic-messages-prompt.ts

@@ -24,6 +24,7 @@ import {
 } from './anthropic-messages-api';
 import { anthropicFilePartProviderOptions } from './anthropic-messages-options';
 import { CacheControlValidator } from './get-cache-control';
+import { advisor_20260301OutputSchema } from './tool/advisor_20260301';
 import { codeExecution_20250522OutputSchema } from './tool/code-execution_20250522';
 import { codeExecution_20250825OutputSchema } from './tool/code-execution_20250825';
 import { codeExecution_20260120OutputSchema } from './tool/code-execution_20260120';
@@ -634,6 +635,15 @@ export async function convertToAnthropicMessagesPrompt({
                         input: part.input,
                         cache_control: cacheControl,
                       });
+                    } else if (providerToolName === 'advisor') {
+                      // The advisor server_tool_use.input is always {}.
+                      anthropicContent.push({
+                        type: 'server_tool_use',
+                        id: part.toolCallId,
+                        name: 'advisor',
+                        input: {},
+                        cache_control: cacheControl,
+                      });
                     } else {
                       warnings.push({
                         type: 'other',
@@ -1020,6 +1030,58 @@ export async function convertToAnthropicMessagesPrompt({
                   break;
                 }
 
+                if (providerToolName === 'advisor') {
+                  const output = part.output;
+
+                  if (output.type !== 'json' && output.type !== 'error-json') {
+                    warnings.push({
+                      type: 'other',
+                      message: `provider executed tool result output type ${output.type} for tool ${part.toolName} is not supported`,
+                    });
+
+                    break;
+                  }
+
+                  const advisorOutput = await validateTypes({
+                    value: output.value,
+                    schema: advisor_20260301OutputSchema,
+                  });
+
+                  if (advisorOutput.type === 'advisor_result') {
+                    anthropicContent.push({
+                      type: 'advisor_tool_result',
+                      tool_use_id: part.toolCallId,
+                      content: {
+                        type: 'advisor_result',
+                        text: advisorOutput.text,
+                      },
+                      cache_control: cacheControl,
+                    });
+                  } else if (advisorOutput.type === 'advisor_redacted_result') {
+                    anthropicContent.push({
+                      type: 'advisor_tool_result',
+                      tool_use_id: part.toolCallId,
+                      content: {
+                        type: 'advisor_redacted_result',
+                        encrypted_content: advisorOutput.encryptedContent,
+                      },
+                      cache_control: cacheControl,
+                    });
+                  } else {
+                    anthropicContent.push({
+                      type: 'advisor_tool_result',
+                      tool_use_id: part.toolCallId,
+                      content: {
+                        type: 'advisor_tool_result_error',
+                        error_code: advisorOutput.errorCode,
+                      },
+                      cache_control: cacheControl,
+                    });
+                  }
+
+                  break;
+                }
+
                 warnings.push({
                   type: 'other',
                   message: `provider executed tool result for tool ${part.toolName} is not supported`,

package/src/tool/advisor_20260301.ts

@@ -0,0 +1,128 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const advisor_20260301ArgsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      model: z.string(),
+      maxUses: z.number().optional(),
+      caching: z
+        .object({
+          type: z.literal('ephemeral'),
+          ttl: z.union([z.literal('5m'), z.literal('1h')]),
+        })
+        .optional(),
+    }),
+  ),
+);
+
+export const advisor_20260301OutputSchema = lazySchema(() =>
+  zodSchema(
+    z.discriminatedUnion('type', [
+      z.object({
+        type: z.literal('advisor_result'),
+        text: z.string(),
+      }),
+      z.object({
+        type: z.literal('advisor_redacted_result'),
+        encryptedContent: z.string(),
+      }),
+      z.object({
+        type: z.literal('advisor_tool_result_error'),
+        errorCode: z.string(),
+      }),
+    ]),
+  ),
+);
+
+const advisor_20260301InputSchema = lazySchema(() =>
+  zodSchema(z.object({}).strict()),
+);
+
+const factory = createProviderToolFactoryWithOutputSchema<
+  // Input is always empty: the executor emits server_tool_use with empty input
+  // and the server constructs the advisor's view from the full transcript.
+  {},
+  | {
+      type: 'advisor_result';
+
+      /**
+       * Plaintext advice from the advisor model.
+       */
+      text: string;
+    }
+  | {
+      type: 'advisor_redacted_result';
+
+      /**
+       * Opaque, encrypted advice. Must be round-tripped verbatim on subsequent
+       * turns; the server decrypts it server-side when rendering the advisor's
+       * advice into the executor's prompt.
+       */
+      encryptedContent: string;
+    }
+  | {
+      type: 'advisor_tool_result_error';
+
+      /**
+       * Available options: `max_uses_exceeded`, `too_many_requests`,
+       * `overloaded`, `prompt_too_long`, `execution_time_exceeded`,
+       * `unavailable`.
+       */
+      errorCode: string;
+    },
+  {
+    /**
+     * The advisor model ID, such as `"claude-opus-4-7"`. Billed at this
+     * model's rates for the sub-inference.
+     *
+     * The advisor must be at least as capable as the executor; an invalid
+     * pair returns a `400 invalid_request_error` from the API.
+     */
+    model: string;
+
+    /**
+     * Maximum number of advisor calls allowed in a single request. Once the
+     * executor reaches this cap, further advisor calls return an
+     * `advisor_tool_result_error` with `error_code: "max_uses_exceeded"` and
+     * the executor continues without further advice.
+     *
+     * This is a per-request cap, not a per-conversation cap. To enforce
+     * conversation-level limits, count advisor calls client-side; when you
+     * hit your cap, remove the advisor tool from `tools` AND strip all
+     * `advisor_tool_result` blocks from your message history (otherwise the
+     * API returns `400 invalid_request_error`).
+     */
+    maxUses?: number;
+
+    /**
+     * Enables prompt caching for the advisor's own transcript across calls
+     * within a conversation. Unlike `cache_control` on content blocks, this
+     * is not a breakpoint marker; it is an on/off switch. The server decides
+     * where cache boundaries go.
+     *
+     * The cache write costs more than the reads save when the advisor is
+     * called two or fewer times per conversation; caching breaks even at
+     * roughly three advisor calls. Enable it for long agent loops; keep it
+     * off for short tasks. Keep it consistent across a conversation —
+     * toggling causes cache misses.
+     */
+    caching?: {
+      type: 'ephemeral';
+      ttl: '5m' | '1h';
+    };
+  }
+>({
+  id: 'anthropic.advisor_20260301',
+  inputSchema: advisor_20260301InputSchema,
+  outputSchema: advisor_20260301OutputSchema,
+  supportsDeferredResults: true,
+});
+
+export const advisor_20260301 = (args: Parameters<typeof factory>[0]) => {
+  return factory(args);
+};