@ai-sdk/anthropic 3.0.18 → 3.0.20

package/src/forward-anthropic-container-id-from-last-step.ts

@@ -0,0 +1,38 @@
+import { JSONObject } from '@ai-sdk/provider';
+import { AnthropicMessageMetadata } from './anthropic-message-metadata';
+
+/**
+ * Sets the Anthropic container ID in the provider options based on
+ * any previous step's provider metadata.
+ *
+ * Searches backwards through steps to find the most recent container ID.
+ * You can use this function in `prepareStep` to forward the container ID between steps.
+ */
+export function forwardAnthropicContainerIdFromLastStep({
+  steps,
+}: {
+  steps: Array<{
+    providerMetadata?: Record<string, JSONObject>;
+  }>;
+}): undefined | { providerOptions?: Record<string, JSONObject> } {
+  // Search backwards through steps to find the most recent container ID
+  for (let i = steps.length - 1; i >= 0; i--) {
+    const containerId = (
+      steps[i].providerMetadata?.anthropic as
+        | AnthropicMessageMetadata
+        | undefined
+    )?.container?.id;
+
+    if (containerId) {
+      return {
+        providerOptions: {
+          anthropic: {
+            container: { id: containerId },
+          },
+        },
+      };
+    }
+  }
+
+  return undefined;
+}

package/src/get-cache-control.ts

@@ -0,0 +1,63 @@
+import { SharedV3Warning, SharedV3ProviderMetadata } from '@ai-sdk/provider';
+import { AnthropicCacheControl } from './anthropic-messages-api';
+
+// Anthropic allows a maximum of 4 cache breakpoints per request
+const MAX_CACHE_BREAKPOINTS = 4;
+
+// Helper function to extract cache_control from provider metadata
+// Allows both cacheControl and cache_control for flexibility
+function getCacheControl(
+  providerMetadata: SharedV3ProviderMetadata | undefined,
+): AnthropicCacheControl | undefined {
+  const anthropic = providerMetadata?.anthropic;
+
+  // allow both cacheControl and cache_control:
+  const cacheControlValue = anthropic?.cacheControl ?? anthropic?.cache_control;
+
+  // Pass through value assuming it is of the correct type.
+  // The Anthropic API will validate the value.
+  return cacheControlValue as AnthropicCacheControl | undefined;
+}
+
+export class CacheControlValidator {
+  private breakpointCount = 0;
+  private warnings: SharedV3Warning[] = [];
+
+  getCacheControl(
+    providerMetadata: SharedV3ProviderMetadata | undefined,
+    context: { type: string; canCache: boolean },
+  ): AnthropicCacheControl | undefined {
+    const cacheControlValue = getCacheControl(providerMetadata);
+
+    if (!cacheControlValue) {
+      return undefined;
+    }
+
+    // Validate that cache_control is allowed in this context
+    if (!context.canCache) {
+      this.warnings.push({
+        type: 'unsupported',
+        feature: 'cache_control on non-cacheable context',
+        details: `cache_control cannot be set on ${context.type}. It will be ignored.`,
+      });
+      return undefined;
+    }
+
+    // Validate cache breakpoint limit
+    this.breakpointCount++;
+    if (this.breakpointCount > MAX_CACHE_BREAKPOINTS) {
+      this.warnings.push({
+        type: 'unsupported',
+        feature: 'cacheControl breakpoint limit',
+        details: `Maximum ${MAX_CACHE_BREAKPOINTS} cache breakpoints exceeded (found ${this.breakpointCount}). This breakpoint will be ignored.`,
+      });
+      return undefined;
+    }
+
+    return cacheControlValue;
+  }
+
+  getWarnings(): SharedV3Warning[] {
+    return this.warnings;
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export type { AnthropicMessageMetadata } from './anthropic-message-metadata';
+export type { AnthropicProviderOptions } from './anthropic-messages-options';
+export type { AnthropicToolOptions } from './anthropic-prepare-tools';
+export { anthropic, createAnthropic } from './anthropic-provider';
+export type {
+  AnthropicProvider,
+  AnthropicProviderSettings,
+} from './anthropic-provider';
+export { forwardAnthropicContainerIdFromLastStep } from './forward-anthropic-container-id-from-last-step';
+export { VERSION } from './version';

package/src/internal/index.ts

@@ -0,0 +1,4 @@
+export { AnthropicMessagesLanguageModel } from '../anthropic-messages-language-model';
+export { anthropicTools } from '../anthropic-tools';
+export type { AnthropicMessagesModelId } from '../anthropic-messages-options';
+export { prepareTools } from '../anthropic-prepare-tools';

package/src/map-anthropic-stop-reason.ts

@@ -0,0 +1,28 @@
+import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+
+/**
+ * @see https://docs.anthropic.com/en/api/messages#response-stop-reason
+ */
+export function mapAnthropicStopReason({
+  finishReason,
+  isJsonResponseFromTool,
+}: {
+  finishReason: string | null | undefined;
+  isJsonResponseFromTool?: boolean;
+}): LanguageModelV3FinishReason['unified'] {
+  switch (finishReason) {
+    case 'pause_turn':
+    case 'end_turn':
+    case 'stop_sequence':
+      return 'stop';
+    case 'refusal':
+      return 'content-filter';
+    case 'tool_use':
+      return isJsonResponseFromTool ? 'stop' : 'tool-calls';
+    case 'max_tokens':
+    case 'model_context_window_exceeded':
+      return 'length';
+    default:
+      return 'other';
+  }
+}

package/src/tool/bash_20241022.ts

@@ -0,0 +1,33 @@
+import {
+  createProviderToolFactory,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+const bash_20241022InputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      command: z.string(),
+      restart: z.boolean().optional(),
+    }),
+  ),
+);
+
+export const bash_20241022 = createProviderToolFactory<
+  {
+    /**
+     * The bash command to run. Required unless the tool is being restarted.
+     */
+    command: string;
+
+    /**
+     * Specifying true will restart this tool. Otherwise, leave this unspecified.
+     */
+    restart?: boolean;
+  },
+  {}
+>({
+  id: 'anthropic.bash_20241022',
+  inputSchema: bash_20241022InputSchema,
+});

package/src/tool/bash_20250124.ts

@@ -0,0 +1,33 @@
+import {
+  createProviderToolFactory,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+const bash_20250124InputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      command: z.string(),
+      restart: z.boolean().optional(),
+    }),
+  ),
+);
+
+export const bash_20250124 = createProviderToolFactory<
+  {
+    /**
+     * The bash command to run. Required unless the tool is being restarted.
+     */
+    command: string;
+
+    /**
+     * Specifying true will restart this tool. Otherwise, leave this unspecified.
+     */
+    restart?: boolean;
+  },
+  {}
+>({
+  id: 'anthropic.bash_20250124',
+  inputSchema: bash_20250124InputSchema,
+});

package/src/tool/code-execution_20250522.ts

@@ -0,0 +1,61 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const codeExecution_20250522OutputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      type: z.literal('code_execution_result'),
+      stdout: z.string(),
+      stderr: z.string(),
+      return_code: z.number(),
+      content: z
+        .array(
+          z.object({
+            type: z.literal('code_execution_output'),
+            file_id: z.string(),
+          }),
+        )
+        .optional()
+        .default([]),
+    }),
+  ),
+);
+
+const codeExecution_20250522InputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      code: z.string(),
+    }),
+  ),
+);
+
+const factory = createProviderToolFactoryWithOutputSchema<
+  {
+    /**
+     * The Python code to execute.
+     */
+    code: string;
+  },
+  {
+    type: 'code_execution_result';
+    stdout: string;
+    stderr: string;
+    return_code: number;
+    content: Array<{ type: 'code_execution_output'; file_id: string }>;
+  },
+  {}
+>({
+  id: 'anthropic.code_execution_20250522',
+  inputSchema: codeExecution_20250522InputSchema,
+  outputSchema: codeExecution_20250522OutputSchema,
+});
+
+export const codeExecution_20250522 = (
+  args: Parameters<typeof factory>[0] = {},
+) => {
+  return factory(args);
+};

package/src/tool/code-execution_20250825.ts

@@ -0,0 +1,281 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const codeExecution_20250825OutputSchema = lazySchema(() =>
+  zodSchema(
+    z.discriminatedUnion('type', [
+      z.object({
+        type: z.literal('code_execution_result'),
+        stdout: z.string(),
+        stderr: z.string(),
+        return_code: z.number(),
+        content: z
+          .array(
+            z.object({
+              type: z.literal('code_execution_output'),
+              file_id: z.string(),
+            }),
+          )
+          .optional()
+          .default([]),
+      }),
+      z.object({
+        type: z.literal('bash_code_execution_result'),
+        content: z.array(
+          z.object({
+            type: z.literal('bash_code_execution_output'),
+            file_id: z.string(),
+          }),
+        ),
+        stdout: z.string(),
+        stderr: z.string(),
+        return_code: z.number(),
+      }),
+      z.object({
+        type: z.literal('bash_code_execution_tool_result_error'),
+        error_code: z.string(),
+      }),
+      z.object({
+        type: z.literal('text_editor_code_execution_tool_result_error'),
+        error_code: z.string(),
+      }),
+      z.object({
+        type: z.literal('text_editor_code_execution_view_result'),
+        content: z.string(),
+        file_type: z.string(),
+        num_lines: z.number().nullable(),
+        start_line: z.number().nullable(),
+        total_lines: z.number().nullable(),
+      }),
+      z.object({
+        type: z.literal('text_editor_code_execution_create_result'),
+        is_file_update: z.boolean(),
+      }),
+      z.object({
+        type: z.literal('text_editor_code_execution_str_replace_result'),
+        lines: z.array(z.string()).nullable(),
+        new_lines: z.number().nullable(),
+        new_start: z.number().nullable(),
+        old_lines: z.number().nullable(),
+        old_start: z.number().nullable(),
+      }),
+    ]),
+  ),
+);
+
+export const codeExecution_20250825InputSchema = lazySchema(() =>
+  zodSchema(
+    z.discriminatedUnion('type', [
+      // Programmatic tool calling format (mapped from { code } by AI SDK)
+      z.object({
+        type: z.literal('programmatic-tool-call'),
+        code: z.string(),
+      }),
+      z.object({
+        type: z.literal('bash_code_execution'),
+        command: z.string(),
+      }),
+      z.discriminatedUnion('command', [
+        z.object({
+          type: z.literal('text_editor_code_execution'),
+          command: z.literal('view'),
+          path: z.string(),
+        }),
+        z.object({
+          type: z.literal('text_editor_code_execution'),
+          command: z.literal('create'),
+          path: z.string(),
+          file_text: z.string().nullish(),
+        }),
+        z.object({
+          type: z.literal('text_editor_code_execution'),
+          command: z.literal('str_replace'),
+          path: z.string(),
+          old_str: z.string(),
+          new_str: z.string(),
+        }),
+      ]),
+    ]),
+  ),
+);
+
+const factory = createProviderToolFactoryWithOutputSchema<
+  | {
+      type: 'programmatic-tool-call';
+      /**
+       * Programmatic tool calling: Python code to execute when code_execution
+       * is used with allowedCallers to trigger client-executed tools.
+       */
+      code: string;
+    }
+  | {
+      type: 'bash_code_execution';
+
+      /**
+       * Shell command to execute.
+       */
+      command: string;
+    }
+  | {
+      type: 'text_editor_code_execution';
+      command: 'view';
+
+      /**
+       * The path to the file to view.
+       */
+      path: string;
+    }
+  | {
+      type: 'text_editor_code_execution';
+      command: 'create';
+
+      /**
+       * The path to the file to edit.
+       */
+      path: string;
+
+      /**
+       * The text of the file to edit.
+       */
+      file_text?: string | null;
+    }
+  | {
+      type: 'text_editor_code_execution';
+      command: 'str_replace';
+
+      /**
+       * The path to the file to edit.
+       */
+      path: string;
+
+      /**
+       * The string to replace.
+       */
+      old_str: string;
+
+      /**
+       * The new string to replace the old string with.
+       */
+      new_str: string;
+    },
+  | {
+      /**
+       * Programmatic tool calling result: returned when code_execution runs code
+       * that calls client-executed tools via allowedCallers.
+       */
+      type: 'code_execution_result';
+
+      /**
+       * Output from successful execution
+       */
+      stdout: string;
+
+      /**
+       * Error messages if execution fails
+       */
+      stderr: string;
+
+      /**
+       * 0 for success, non-zero for failure
+       */
+      return_code: number;
+
+      /**
+       * Output file Id list
+       */
+      content: Array<{ type: 'code_execution_output'; file_id: string }>;
+    }
+  | {
+      type: 'bash_code_execution_result';
+
+      /**
+       * Output file Id list
+       */
+      content: Array<{
+        type: 'bash_code_execution_output';
+        file_id: string;
+      }>;
+
+      /**
+       * Output from successful execution
+       */
+      stdout: string;
+
+      /**
+       * Error messages if execution fails
+       */
+      stderr: string;
+
+      /**
+       * 0 for success, non-zero for failure
+       */
+      return_code: number;
+    }
+  | {
+      type: 'bash_code_execution_tool_result_error';
+
+      /**
+       * Available options: invalid_tool_input, unavailable, too_many_requests,
+       * execution_time_exceeded, output_file_too_large.
+       */
+      error_code: string;
+    }
+  | {
+      type: 'text_editor_code_execution_tool_result_error';
+
+      /**
+       * Available options: invalid_tool_input, unavailable, too_many_requests,
+       * execution_time_exceeded, file_not_found.
+       */
+      error_code: string;
+    }
+  | {
+      type: 'text_editor_code_execution_view_result';
+
+      content: string;
+
+      /**
+       * The type of the file. Available options: text, image, pdf.
+       */
+      file_type: string;
+
+      num_lines: number | null;
+      start_line: number | null;
+      total_lines: number | null;
+    }
+  | {
+      type: 'text_editor_code_execution_create_result';
+
+      is_file_update: boolean;
+    }
+  | {
+      type: 'text_editor_code_execution_str_replace_result';
+
+      lines: string[] | null;
+      new_lines: number | null;
+      new_start: number | null;
+      old_lines: number | null;
+      old_start: number | null;
+    },
+  {
+    // no arguments
+  }
+>({
+  id: 'anthropic.code_execution_20250825',
+  inputSchema: codeExecution_20250825InputSchema,
+  outputSchema: codeExecution_20250825OutputSchema,
+  // Programmatic tool calling: tool results may be deferred to a later turn
+  // when code execution triggers a client-executed tool that needs to be
+  // resolved before the code execution result can be returned.
+  supportsDeferredResults: true,
+});
+
+export const codeExecution_20250825 = (
+  args: Parameters<typeof factory>[0] = {},
+) => {
+  return factory(args);
+};

package/src/tool/computer_20241022.ts

@@ -0,0 +1,87 @@
+import {
+  createProviderToolFactory,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+const computer_20241022InputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      action: z.enum([
+        'key',
+        'type',
+        'mouse_move',
+        'left_click',
+        'left_click_drag',
+        'right_click',
+        'middle_click',
+        'double_click',
+        'screenshot',
+        'cursor_position',
+      ]),
+      coordinate: z.array(z.number().int()).optional(),
+      text: z.string().optional(),
+    }),
+  ),
+);
+
+export const computer_20241022 = createProviderToolFactory<
+  {
+    /**
+     * The action to perform. The available actions are:
+     * - `key`: Press a key or key-combination on the keyboard.
+     *   - This supports xdotool's `key` syntax.
+     *   - Examples: "a", "Return", "alt+Tab", "ctrl+s", "Up", "KP_0" (for the numpad 0 key).
+     * - `type`: Type a string of text on the keyboard.
+     * - `cursor_position`: Get the current (x, y) pixel coordinate of the cursor on the screen.
+     * - `mouse_move`: Move the cursor to a specified (x, y) pixel coordinate on the screen.
+     * - `left_click`: Click the left mouse button.
+     * - `left_click_drag`: Click and drag the cursor to a specified (x, y) pixel coordinate on the screen.
+     * - `right_click`: Click the right mouse button.
+     * - `middle_click`: Click the middle mouse button.
+     * - `double_click`: Double-click the left mouse button.
+     * - `screenshot`: Take a screenshot of the screen.
+     */
+    action:
+      | 'key'
+      | 'type'
+      | 'mouse_move'
+      | 'left_click'
+      | 'left_click_drag'
+      | 'right_click'
+      | 'middle_click'
+      | 'double_click'
+      | 'screenshot'
+      | 'cursor_position';
+
+    /**
+     * (x, y): The x (pixels from the left edge) and y (pixels from the top edge) coordinates to move the mouse to. Required only by `action=mouse_move` and `action=left_click_drag`.
+     */
+    coordinate?: number[];
+
+    /**
+     * Required only by `action=type` and `action=key`.
+     */
+    text?: string;
+  },
+  {
+    /**
+     * The width of the display being controlled by the model in pixels.
+     */
+    displayWidthPx: number;
+
+    /**
+     * The height of the display being controlled by the model in pixels.
+     */
+    displayHeightPx: number;
+
+    /**
+     * The display number to control (only relevant for X11 environments). If specified, the tool will be provided a display number in the tool definition.
+     */
+    displayNumber?: number;
+  }
+>({
+  id: 'anthropic.computer_20241022',
+  inputSchema: computer_20241022InputSchema,
+});