@ai-sdk/anthropic 3.0.75 → 3.0.77

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @ai-sdk/anthropic
 
+## 3.0.77
+
+### Patch Changes
+
+- d53314d: feat(anthropic): add the new advisor tool
+
+## 3.0.76
+
+### Patch Changes
+
+- Updated dependencies [f591416]
+  - @ai-sdk/provider-utils@4.0.27
+
 ## 3.0.75
 
 ### Patch Changes

package/dist/index.d.mts

@@ -5,10 +5,17 @@ import { FetchFunction } from '@ai-sdk/provider-utils';
 
 /**
  * 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; `model` carries the advisor model ID). 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.
  */
-interface AnthropicUsageIteration {
+type AnthropicUsageIteration = {
     type: 'compaction' | 'message';
     /**
      * Number of input tokens consumed in this iteration.
@@ -18,7 +25,41 @@ 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;
+} | {
+    type: 'advisor_message';
+    /**
+     * The advisor model that produced this iteration.
+     */
+    model: string;
+    /**
+     * Number of input tokens consumed in this iteration.
+     */
+    inputTokens: number;
+    /**
+     * Number of output tokens generated in this iteration.
+     */
+    outputTokens: number;
+    /**
+     * Number of cache-creation input tokens consumed by this advisor
+     * sub-inference. Nonzero when advisor-side caching is enabled and
+     * the advisor writes a fresh cache entry.
+     */
+    cacheCreationInputTokens?: number;
+    /**
+     * Number of cache-read input tokens consumed by this advisor
+     * sub-inference. Nonzero on the second and later advisor calls
+     * when advisor-side caching is enabled.
+     */
+    cacheReadInputTokens?: number;
+};
 interface AnthropicMessageMetadata {
     usage: JSONObject;
     cacheCreationInputTokens: number | null;
@@ -242,6 +283,60 @@ interface AnthropicToolOptions {
 }
 
 declare 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-7"`.
+     * @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: (args: Parameters<_ai_sdk_provider_utils.ProviderToolFactoryWithOutputSchema<{}, {
+        type: "advisor_result";
+        text: string;
+    } | {
+        type: "advisor_redacted_result";
+        encryptedContent: string;
+    } | {
+        type: "advisor_tool_result_error";
+        errorCode: string;
+    }, {
+        model: string;
+        maxUses?: number;
+        caching?: {
+            type: "ephemeral";
+            ttl: "5m" | "1h";
+        };
+    }>>[0]) => _ai_sdk_provider_utils.Tool<{}, {
+        type: "advisor_result";
+        text: string;
+    } | {
+        type: "advisor_redacted_result";
+        encryptedContent: string;
+    } | {
+        type: "advisor_tool_result_error";
+        errorCode: string;
+    }>;
     /**
      * The bash tool enables Claude to execute shell commands in a persistent bash session,
      * allowing system operations, script execution, and command-line automation.

package/dist/index.d.ts

@@ -5,10 +5,17 @@ import { FetchFunction } from '@ai-sdk/provider-utils';
 
 /**
  * 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; `model` carries the advisor model ID). 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.
  */
-interface AnthropicUsageIteration {
+type AnthropicUsageIteration = {
     type: 'compaction' | 'message';
     /**
      * Number of input tokens consumed in this iteration.
@@ -18,7 +25,41 @@ 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;
+} | {
+    type: 'advisor_message';
+    /**
+     * The advisor model that produced this iteration.
+     */
+    model: string;
+    /**
+     * Number of input tokens consumed in this iteration.
+     */
+    inputTokens: number;
+    /**
+     * Number of output tokens generated in this iteration.
+     */
+    outputTokens: number;
+    /**
+     * Number of cache-creation input tokens consumed by this advisor
+     * sub-inference. Nonzero when advisor-side caching is enabled and
+     * the advisor writes a fresh cache entry.
+     */
+    cacheCreationInputTokens?: number;
+    /**
+     * Number of cache-read input tokens consumed by this advisor
+     * sub-inference. Nonzero on the second and later advisor calls
+     * when advisor-side caching is enabled.
+     */
+    cacheReadInputTokens?: number;
+};
 interface AnthropicMessageMetadata {
     usage: JSONObject;
     cacheCreationInputTokens: number | null;
@@ -242,6 +283,60 @@ interface AnthropicToolOptions {
 }
 
 declare 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-7"`.
+     * @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: (args: Parameters<_ai_sdk_provider_utils.ProviderToolFactoryWithOutputSchema<{}, {
+        type: "advisor_result";
+        text: string;
+    } | {
+        type: "advisor_redacted_result";
+        encryptedContent: string;
+    } | {
+        type: "advisor_tool_result_error";
+        errorCode: string;
+    }, {
+        model: string;
+        maxUses?: number;
+        caching?: {
+            type: "ephemeral";
+            ttl: "5m" | "1h";
+        };
+    }>>[0]) => _ai_sdk_provider_utils.Tool<{}, {
+        type: "advisor_result";
+        text: string;
+    } | {
+        type: "advisor_redacted_result";
+        encryptedContent: string;
+    } | {
+        type: "advisor_tool_result_error";
+        errorCode: string;
+    }>;
     /**
      * The bash tool enables Claude to execute shell commands in a persistent bash session,
      * allowing system operations, script execution, and command-line automation.