@anthropic-ai/sdk 0.55.0 → 0.56.0

package/src/internal/utils/path.ts

@@ -12,25 +12,43 @@ export function encodeURIPath(str: string) {
   return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
 }
 
+const EMPTY = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null));
+
 export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
   function path(statics: readonly string[], ...params: readonly unknown[]): string {
     // If there are no params, no processing is needed.
     if (statics.length === 1) return statics[0]!;
 
     let postPath = false;
+    const invalidSegments = [];
     const path = statics.reduce((previousValue, currentValue, index) => {
       if (/[?#]/.test(currentValue)) {
         postPath = true;
       }
-      return (
-        previousValue +
-        currentValue +
-        (index === params.length ? '' : (postPath ? encodeURIComponent : pathEncoder)(String(params[index])))
-      );
+      const value = params[index];
+      let encoded = (postPath ? encodeURIComponent : pathEncoder)('' + value);
+      if (
+        index !== params.length &&
+        (value == null ||
+          (typeof value === 'object' &&
+            // handle values from other realms
+            value.toString ===
+              Object.getPrototypeOf(Object.getPrototypeOf((value as any).hasOwnProperty ?? EMPTY) ?? EMPTY)
+                ?.toString))
+      ) {
+        encoded = value + '';
+        invalidSegments.push({
+          start: previousValue.length + currentValue.length,
+          length: encoded.length,
+          error: `Value of type ${Object.prototype.toString
+            .call(value)
+            .slice(8, -1)} is not a valid path parameter`,
+        });
+      }
+      return previousValue + currentValue + (index === params.length ? '' : encoded);
     }, '');
 
     const pathOnly = path.split(/[?#]/, 1)[0]!;
-    const invalidSegments = [];
     const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
     let match;
 
@@ -39,9 +57,12 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
       invalidSegments.push({
         start: match.index,
         length: match[0].length,
+        error: `Value "${match[0]}" can\'t be safely passed as a path parameter`,
       });
     }
 
+    invalidSegments.sort((a, b) => a.start - b.start);
+
     if (invalidSegments.length > 0) {
       let lastEnd = 0;
       const underline = invalidSegments.reduce((acc, segment) => {
@@ -52,7 +73,9 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
       }, '');
 
       throw new AnthropicError(
-        `Path parameters result in path with invalid segments:\n${path}\n${underline}`,
+        `Path parameters result in path with invalid segments:\n${invalidSegments
+          .map((e) => e.error)
+          .join('\n')}\n${path}\n${underline}`,
       );
     }
 

package/src/lib/BetaMessageStream.ts

@@ -583,14 +583,19 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
         switch (event.delta.type) {
           case 'text_delta': {
             if (snapshotContent?.type === 'text') {
-              snapshotContent.text += event.delta.text;
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                text: (snapshotContent.text || '') + event.delta.text,
+              };
             }
             break;
           }
           case 'citations_delta': {
             if (snapshotContent?.type === 'text') {
-              snapshotContent.citations ??= [];
-              snapshotContent.citations.push(event.delta.citation);
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                citations: [...(snapshotContent.citations ?? []), event.delta.citation],
+              };
             }
             break;
           }
@@ -602,7 +607,8 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
               let jsonBuf = (snapshotContent as any)[JSON_BUF_PROPERTY] || '';
               jsonBuf += event.delta.partial_json;
 
-              Object.defineProperty(snapshotContent, JSON_BUF_PROPERTY, {
+              const newContent = { ...snapshotContent };
+              Object.defineProperty(newContent, JSON_BUF_PROPERTY, {
                 value: jsonBuf,
                 enumerable: false,
                 writable: true,
@@ -610,7 +616,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
 
               if (jsonBuf) {
                 try {
-                  snapshotContent.input = partialParse(jsonBuf);
+                  newContent.input = partialParse(jsonBuf);
                 } catch (err) {
                   const error = new AnthropicError(
                     `Unable to parse tool parameter JSON from model. Please retry your request or adjust your prompt. Error: ${err}. JSON: ${jsonBuf}`,
@@ -618,18 +624,25 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
                   this.#handleError(error);
                 }
               }
+              snapshot.content[event.index] = newContent;
             }
             break;
           }
           case 'thinking_delta': {
             if (snapshotContent?.type === 'thinking') {
-              snapshotContent.thinking += event.delta.thinking;
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                thinking: snapshotContent.thinking + event.delta.thinking,
+              };
             }
             break;
           }
           case 'signature_delta': {
             if (snapshotContent?.type === 'thinking') {
-              snapshotContent.signature = event.delta.signature;
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                signature: event.delta.signature,
+              };
             }
             break;
           }

package/src/lib/MessageStream.ts

@@ -574,7 +574,7 @@ export class MessageStream implements AsyncIterable<MessageStreamEvent> {
 
         return snapshot;
       case 'content_block_start':
-        snapshot.content.push(event.content_block);
+        snapshot.content.push({ ...event.content_block });
         return snapshot;
       case 'content_block_delta': {
         const snapshotContent = snapshot.content.at(event.index);
@@ -582,14 +582,19 @@ export class MessageStream implements AsyncIterable<MessageStreamEvent> {
         switch (event.delta.type) {
           case 'text_delta': {
             if (snapshotContent?.type === 'text') {
-              snapshotContent.text += event.delta.text;
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                text: (snapshotContent.text || '') + event.delta.text,
+              };
             }
             break;
           }
           case 'citations_delta': {
             if (snapshotContent?.type === 'text') {
-              snapshotContent.citations ??= [];
-              snapshotContent.citations.push(event.delta.citation);
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                citations: [...(snapshotContent.citations ?? []), event.delta.citation],
+              };
             }
             break;
           }
@@ -601,27 +606,35 @@ export class MessageStream implements AsyncIterable<MessageStreamEvent> {
               let jsonBuf = (snapshotContent as any)[JSON_BUF_PROPERTY] || '';
               jsonBuf += event.delta.partial_json;
 
-              Object.defineProperty(snapshotContent, JSON_BUF_PROPERTY, {
+              const newContent = { ...snapshotContent };
+              Object.defineProperty(newContent, JSON_BUF_PROPERTY, {
                 value: jsonBuf,
                 enumerable: false,
                 writable: true,
               });
 
               if (jsonBuf) {
-                snapshotContent.input = partialParse(jsonBuf);
+                newContent.input = partialParse(jsonBuf);
               }
+              snapshot.content[event.index] = newContent;
             }
             break;
           }
           case 'thinking_delta': {
             if (snapshotContent?.type === 'thinking') {
-              snapshotContent.thinking += event.delta.thinking;
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                thinking: snapshotContent.thinking + event.delta.thinking,
+              };
             }
             break;
           }
           case 'signature_delta': {
             if (snapshotContent?.type === 'thinking') {
-              snapshotContent.signature = event.delta.signature;
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                signature: event.delta.signature,
+              };
             }
             break;
           }

package/src/resources/beta/beta.ts

@@ -28,6 +28,8 @@ import {
   BetaCitationContentBlockLocationParam,
   BetaCitationPageLocation,
   BetaCitationPageLocationParam,
+  BetaCitationSearchResultLocation,
+  BetaCitationSearchResultLocationParam,
   BetaCitationWebSearchResultLocationParam,
   BetaCitationsConfigParam,
   BetaCitationsDelta,
@@ -78,6 +80,7 @@ import {
   BetaRequestMCPServerToolConfiguration,
   BetaRequestMCPServerURLDefinition,
   BetaRequestMCPToolResultBlockParam,
+  BetaSearchResultBlockParam,
   BetaServerToolUsage,
   BetaServerToolUseBlock,
   BetaServerToolUseBlockParam,
@@ -265,6 +268,8 @@ export declare namespace Beta {
     type BetaCitationContentBlockLocationParam as BetaCitationContentBlockLocationParam,
     type BetaCitationPageLocation as BetaCitationPageLocation,
     type BetaCitationPageLocationParam as BetaCitationPageLocationParam,
+    type BetaCitationSearchResultLocation as BetaCitationSearchResultLocation,
+    type BetaCitationSearchResultLocationParam as BetaCitationSearchResultLocationParam,
     type BetaCitationWebSearchResultLocationParam as BetaCitationWebSearchResultLocationParam,
     type BetaCitationsConfigParam as BetaCitationsConfigParam,
     type BetaCitationsDelta as BetaCitationsDelta,
@@ -315,6 +320,7 @@ export declare namespace Beta {
     type BetaRequestMCPServerToolConfiguration as BetaRequestMCPServerToolConfiguration,
     type BetaRequestMCPServerURLDefinition as BetaRequestMCPServerURLDefinition,
     type BetaRequestMCPToolResultBlockParam as BetaRequestMCPToolResultBlockParam,
+    type BetaSearchResultBlockParam as BetaSearchResultBlockParam,
     type BetaServerToolUsage as BetaServerToolUsage,
     type BetaServerToolUseBlock as BetaServerToolUseBlock,
     type BetaServerToolUseBlockParam as BetaServerToolUseBlockParam,

package/src/resources/beta/index.ts

@@ -38,6 +38,8 @@ export {
   type BetaCitationContentBlockLocationParam,
   type BetaCitationPageLocation,
   type BetaCitationPageLocationParam,
+  type BetaCitationSearchResultLocation,
+  type BetaCitationSearchResultLocationParam,
   type BetaCitationWebSearchResultLocationParam,
   type BetaCitationsConfigParam,
   type BetaCitationsDelta,
@@ -88,6 +90,7 @@ export {
   type BetaRequestMCPServerToolConfiguration,
   type BetaRequestMCPServerURLDefinition,
   type BetaRequestMCPToolResultBlockParam,
+  type BetaSearchResultBlockParam,
   type BetaServerToolUsage,
   type BetaServerToolUseBlock,
   type BetaServerToolUseBlockParam,

package/src/resources/beta/messages/batches.ts

@@ -34,7 +34,7 @@ export class Batches extends APIResource {
    *           messages: [
    *             { content: 'Hello, world', role: 'user' },
    *           ],
-   *           model: 'claude-3-7-sonnet-20250219',
+   *           model: 'claude-sonnet-4-20250514',
    *         },
    *       },
    *     ],

package/src/resources/beta/messages/index.ts

@@ -31,6 +31,8 @@ export {
   type BetaCitationContentBlockLocationParam,
   type BetaCitationPageLocation,
   type BetaCitationPageLocationParam,
+  type BetaCitationSearchResultLocation,
+  type BetaCitationSearchResultLocationParam,
   type BetaCitationWebSearchResultLocationParam,
   type BetaCitationsConfigParam,
   type BetaCitationsDelta,
@@ -81,6 +83,7 @@ export {
   type BetaRequestMCPServerToolConfiguration,
   type BetaRequestMCPServerURLDefinition,
   type BetaRequestMCPToolResultBlockParam,
+  type BetaSearchResultBlockParam,
   type BetaServerToolUsage,
   type BetaServerToolUseBlock,
   type BetaServerToolUseBlockParam,

package/src/resources/beta/messages/messages.ts

@@ -40,6 +40,7 @@ const DEPRECATED_MODELS: {
   'claude-instant-1.1-100k': 'November 6th, 2024',
   'claude-instant-1.2': 'November 6th, 2024',
   'claude-3-sonnet-20240229': 'July 21st, 2025',
+  'claude-3-opus-20240229': 'January 5th, 2026',
   'claude-2.1': 'July 21st, 2025',
   'claude-2.0': 'July 21st, 2025',
 };
@@ -62,7 +63,7 @@ export class Messages extends APIResource {
    * const betaMessage = await client.beta.messages.create({
    *   max_tokens: 1024,
    *   messages: [{ content: 'Hello, world', role: 'user' }],
-   *   model: 'claude-3-7-sonnet-20250219',
+   *   model: 'claude-sonnet-4-20250514',
    * });
    * ```
    */
@@ -277,6 +278,38 @@ export interface BetaCitationPageLocationParam {
   type: 'page_location';
 }
 
+export interface BetaCitationSearchResultLocation {
+  cited_text: string;
+
+  end_block_index: number;
+
+  search_result_index: number;
+
+  source: string;
+
+  start_block_index: number;
+
+  title: string | null;
+
+  type: 'search_result_location';
+}
+
+export interface BetaCitationSearchResultLocationParam {
+  cited_text: string;
+
+  end_block_index: number;
+
+  search_result_index: number;
+
+  source: string;
+
+  start_block_index: number;
+
+  title: string | null;
+
+  type: 'search_result_location';
+}
+
 export interface BetaCitationWebSearchResultLocationParam {
   cited_text: string;
 
@@ -298,7 +331,8 @@ export interface BetaCitationsDelta {
     | BetaCitationCharLocation
     | BetaCitationPageLocation
     | BetaCitationContentBlockLocation
-    | BetaCitationsWebSearchResultLocation;
+    | BetaCitationsWebSearchResultLocation
+    | BetaCitationSearchResultLocation;
 
   type: 'citations_delta';
 }
@@ -459,32 +493,33 @@ export interface BetaContainerUploadBlockParam {
  */
 export type BetaContentBlock =
   | BetaTextBlock
+  | BetaThinkingBlock
+  | BetaRedactedThinkingBlock
   | BetaToolUseBlock
   | BetaServerToolUseBlock
   | BetaWebSearchToolResultBlock
   | BetaCodeExecutionToolResultBlock
   | BetaMCPToolUseBlock
   | BetaMCPToolResultBlock
-  | BetaContainerUploadBlock
-  | BetaThinkingBlock
-  | BetaRedactedThinkingBlock;
+  | BetaContainerUploadBlock;
 
 /**
  * Regular text content.
  */
 export type BetaContentBlockParam =
-  | BetaServerToolUseBlockParam
-  | BetaWebSearchToolResultBlockParam
-  | BetaCodeExecutionToolResultBlockParam
-  | BetaMCPToolUseBlockParam
-  | BetaRequestMCPToolResultBlockParam
   | BetaTextBlockParam
   | BetaImageBlockParam
-  | BetaToolUseBlockParam
-  | BetaToolResultBlockParam
   | BetaRequestDocumentBlock
+  | BetaSearchResultBlockParam
   | BetaThinkingBlockParam
   | BetaRedactedThinkingBlockParam
+  | BetaToolUseBlockParam
+  | BetaToolResultBlockParam
+  | BetaServerToolUseBlockParam
+  | BetaWebSearchToolResultBlockParam
+  | BetaCodeExecutionToolResultBlockParam
+  | BetaMCPToolUseBlockParam
+  | BetaRequestMCPToolResultBlockParam
   | BetaContainerUploadBlockParam;
 
 export interface BetaContentBlockSource {
@@ -645,6 +680,10 @@ export interface BetaMessage {
    * - `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum
    * - `"stop_sequence"`: one of your provided custom `stop_sequences` was generated
    * - `"tool_use"`: the model invoked one or more tools
+   * - `"pause_turn"`: we paused a long-running turn. You may provide the response
+   *   back as-is in a subsequent request to let the model continue.
+   * - `"refusal"`: when streaming classifiers intervene to handle potential policy
+   *   violations
    *
    * In non-streaming mode this value is always non-null. In streaming mode, it is
    * null in the `message_start` event and non-null otherwise.
@@ -767,15 +806,15 @@ export interface BetaRawContentBlockStartEvent {
    */
   content_block:
     | BetaTextBlock
+    | BetaThinkingBlock
+    | BetaRedactedThinkingBlock
     | BetaToolUseBlock
     | BetaServerToolUseBlock
     | BetaWebSearchToolResultBlock
     | BetaCodeExecutionToolResultBlock
     | BetaMCPToolUseBlock
     | BetaMCPToolResultBlock
-    | BetaContainerUploadBlock
-    | BetaThinkingBlock
-    | BetaRedactedThinkingBlock;
+    | BetaContainerUploadBlock;
 
   index: number;
 
@@ -912,6 +951,23 @@ export interface BetaRequestMCPToolResultBlockParam {
   is_error?: boolean;
 }
 
+export interface BetaSearchResultBlockParam {
+  content: Array<BetaTextBlockParam>;
+
+  source: string;
+
+  title: string;
+
+  type: 'search_result';
+
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
+  cache_control?: BetaCacheControlEphemeral | null;
+
+  citations?: BetaCitationsConfigParam;
+}
+
 export interface BetaServerToolUsage {
   /**
    * The number of web search tool requests.
@@ -990,13 +1046,15 @@ export type BetaTextCitation =
   | BetaCitationCharLocation
   | BetaCitationPageLocation
   | BetaCitationContentBlockLocation
-  | BetaCitationsWebSearchResultLocation;
+  | BetaCitationsWebSearchResultLocation
+  | BetaCitationSearchResultLocation;
 
 export type BetaTextCitationParam =
   | BetaCitationCharLocationParam
   | BetaCitationPageLocationParam
   | BetaCitationContentBlockLocationParam
-  | BetaCitationWebSearchResultLocationParam;
+  | BetaCitationWebSearchResultLocationParam
+  | BetaCitationSearchResultLocationParam;
 
 export interface BetaTextDelta {
   text: string;
@@ -1279,7 +1337,7 @@ export interface BetaToolResultBlockParam {
    */
   cache_control?: BetaCacheControlEphemeral | null;
 
-  content?: string | Array<BetaTextBlockParam | BetaImageBlockParam>;
+  content?: string | Array<BetaTextBlockParam | BetaImageBlockParam | BetaSearchResultBlockParam>;
 
   is_error?: boolean;
 }
@@ -1334,15 +1392,15 @@ export interface BetaToolTextEditor20250429 {
 
 export type BetaToolUnion =
   | BetaTool
-  | BetaToolComputerUse20241022
   | BetaToolBash20241022
-  | BetaToolTextEditor20241022
-  | BetaToolComputerUse20250124
   | BetaToolBash20250124
+  | BetaCodeExecutionTool20250522
+  | BetaToolComputerUse20241022
+  | BetaToolComputerUse20250124
+  | BetaToolTextEditor20241022
   | BetaToolTextEditor20250124
   | BetaToolTextEditor20250429
-  | BetaWebSearchTool20250305
-  | BetaCodeExecutionTool20250522;
+  | BetaWebSearchTool20250305;
 
 export interface BetaToolUseBlock {
   id: string;
@@ -1668,7 +1726,7 @@ export interface MessageCreateParamsBase {
    * the top-level `system` parameter — there is no `"system"` role for input
    * messages in the Messages API.
    *
-   * There is a limit of 100000 messages in a single request.
+   * There is a limit of 100,000 messages in a single request.
    */
   messages: Array<BetaMessageParam>;
 
@@ -1773,6 +1831,12 @@ export interface MessageCreateParamsBase {
    * those tools using the tool input generated by the model and then optionally
    * return results back to the model using `tool_result` content blocks.
    *
+   * There are two types of tools: **client tools** and **server tools**. The
+   * behavior described below applies to client tools. For
+   * [server tools](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview#server-tools),
+   * see their individual documentation as each has its own behavior (e.g., the
+   * [web search tool](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool)).
+   *
    * Each tool definition includes:
    *
    * - `name`: Name of the tool.
@@ -1984,7 +2048,7 @@ export interface MessageCountTokensParams {
    * the top-level `system` parameter — there is no `"system"` role for input
    * messages in the Messages API.
    *
-   * There is a limit of 100000 messages in a single request.
+   * There is a limit of 100,000 messages in a single request.
    */
   messages: Array<BetaMessageParam>;
 
@@ -2036,6 +2100,12 @@ export interface MessageCountTokensParams {
    * those tools using the tool input generated by the model and then optionally
    * return results back to the model using `tool_result` content blocks.
    *
+   * There are two types of tools: **client tools** and **server tools**. The
+   * behavior described below applies to client tools. For
+   * [server tools](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview#server-tools),
+   * see their individual documentation as each has its own behavior (e.g., the
+   * [web search tool](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool)).
+   *
    * Each tool definition includes:
    *
    * - `name`: Name of the tool.
@@ -2101,15 +2171,15 @@ export interface MessageCountTokensParams {
    */
   tools?: Array<
     | BetaTool
-    | BetaToolComputerUse20241022
     | BetaToolBash20241022
-    | BetaToolTextEditor20241022
-    | BetaToolComputerUse20250124
     | BetaToolBash20250124
+    | BetaCodeExecutionTool20250522
+    | BetaToolComputerUse20241022
+    | BetaToolComputerUse20250124
+    | BetaToolTextEditor20241022
     | BetaToolTextEditor20250124
     | BetaToolTextEditor20250429
     | BetaWebSearchTool20250305
-    | BetaCodeExecutionTool20250522
   >;
 
   /**
@@ -2132,6 +2202,8 @@ export declare namespace Messages {
     type BetaCitationContentBlockLocationParam as BetaCitationContentBlockLocationParam,
     type BetaCitationPageLocation as BetaCitationPageLocation,
     type BetaCitationPageLocationParam as BetaCitationPageLocationParam,
+    type BetaCitationSearchResultLocation as BetaCitationSearchResultLocation,
+    type BetaCitationSearchResultLocationParam as BetaCitationSearchResultLocationParam,
     type BetaCitationWebSearchResultLocationParam as BetaCitationWebSearchResultLocationParam,
     type BetaCitationsConfigParam as BetaCitationsConfigParam,
     type BetaCitationsDelta as BetaCitationsDelta,
@@ -2182,6 +2254,7 @@ export declare namespace Messages {
     type BetaRequestMCPServerToolConfiguration as BetaRequestMCPServerToolConfiguration,
     type BetaRequestMCPServerURLDefinition as BetaRequestMCPServerURLDefinition,
     type BetaRequestMCPToolResultBlockParam as BetaRequestMCPToolResultBlockParam,
+    type BetaSearchResultBlockParam as BetaSearchResultBlockParam,
     type BetaServerToolUsage as BetaServerToolUsage,
     type BetaServerToolUseBlock as BetaServerToolUseBlock,
     type BetaServerToolUseBlockParam as BetaServerToolUseBlockParam,

package/src/resources/messages/batches.ts

@@ -33,7 +33,7 @@ export class Batches extends APIResource {
    *         messages: [
    *           { content: 'Hello, world', role: 'user' },
    *         ],
-   *         model: 'claude-3-7-sonnet-20250219',
+   *         model: 'claude-sonnet-4-20250514',
    *       },
    *     },
    *   ],