@anthropic-ai/sdk 0.105.0 → 0.107.0

package/src/lib/helper-client.ts

@@ -1,6 +1,10 @@
 import { AnthropicError } from '../core/error';
 import type { Anthropic } from '../client';
 import { buildHeaders, type HeadersLike, type NullableHeaders } from '../internal/headers';
+import {
+  STAINLESS_HELPER_HEADER,
+  type StainlessHelperHeaderValue,
+} from '../internal/stainless-helper-header';
 
 /**
  * Shared util for building a runner-helper-bound sub-client.
@@ -16,13 +20,6 @@ import { buildHeaders, type HeadersLike, type NullableHeaders } from '../interna
  * {@link copyClientForHelper} is the one shared construction.
  */
 
-/**
- * The closed set of `x-stainless-helper` telemetry tags the runner helpers
- * stamp on outgoing requests. Constrained as a string union so a typo at any
- * call site is a type error rather than silently mistagged telemetry.
- */
-export type HelperTag = 'environments-work-poller' | 'environments-worker' | 'session-tool-runner';
-
 interface ClientInternalAccess {
   _options: { defaultHeaders?: HeadersLike };
   _authState?: { extraHeaders?: Record<string, string> };
@@ -54,7 +51,7 @@ interface ClientInternalAccess {
  */
 export function copyClientForHelper<T extends Anthropic>(
   client: T,
-  { authToken, helper }: { authToken: string; helper: HelperTag },
+  { authToken, helper }: { authToken: string; helper: StainlessHelperHeaderValue },
 ): T {
   if (!authToken) {
     throw new AnthropicError(
@@ -77,7 +74,7 @@ export function copyClientForHelper<T extends Anthropic>(
   const defaultHeaders: NullableHeaders = buildHeaders([
     inheritedAuthExtraHeaders,
     parentDefaults,
-    { 'x-stainless-helper': helper },
+    { [STAINLESS_HELPER_HEADER]: helper },
   ]);
   return client.withOptions({
     apiKey: null,

package/src/lib/middleware.ts

@@ -3,6 +3,8 @@ import { AnthropicError } from '../core/error';
 import type { Middleware, MiddlewareContext, MiddlewareNext } from '../core/middleware';
 import { Stream, type ServerSentEvent } from '../core/streaming';
 import { isAbortError } from '../internal/errors';
+import { appendHeaderValue } from '../internal/headers';
+import { STAINLESS_HELPER_HEADER } from '../internal/stainless-helper-header';
 import { safeJSON } from '../internal/utils/values';
 import type { AnthropicBeta } from '../resources/beta/beta';
 import type {
@@ -179,8 +181,9 @@ export function betaRefusalFallbackMiddleware(
       ((error: BetaRefusalFallbackError) =>
         ctx.logger.error(`anthropic-sdk: betaRefusalFallbackMiddleware: ${error.message}`));
 
-    // Send the configured betas on this and every hop request derived from it.
-    request = appendBetas(request, options.betas ?? DEFAULT_BETAS);
+    // Send the configured betas on this and every hop request derived from it,
+    // and tag this and every hop with the middleware's helper telemetry.
+    request = withMiddlewareHeaders(request, options.betas ?? DEFAULT_BETAS);
 
     const body = stripFallbackBlocks(ctx.options.body as MessageCreateParams);
     const state = ctx.options.fallbackState;
@@ -851,8 +854,7 @@ function toPrefillBlocks(responseBlocks: any[]): BetaContentBlockParam[] {
  * A copy of `request` with `betas` appended to its `anthropic-beta` header,
  * skipping values already present (set by the caller or another middleware).
  */
-function appendBetas(request: APIRequest, betas: readonly AnthropicBeta[]): APIRequest {
-  if (!betas.length) return request;
+function withMiddlewareHeaders(request: APIRequest, betas: readonly AnthropicBeta[]): APIRequest {
   const headers = new Headers(request.headers);
   const existing = new Set(
     headers
@@ -866,6 +868,10 @@ function appendBetas(request: APIRequest, betas: readonly AnthropicBeta[]): APIR
       existing.add(beta);
     }
   }
+  headers.set(
+    STAINLESS_HELPER_HEADER,
+    appendHeaderValue(headers.get(STAINLESS_HELPER_HEADER), 'fallback-refusal-middleware'),
+  );
   return { ...request, headers };
 }
 

package/src/lib/tools/BetaToolRunner.ts

@@ -8,7 +8,11 @@ import { RequestOptions } from '../../internal/request-options';
 import { buildHeaders } from '../../internal/headers';
 import { promiseWithResolvers } from '../../internal/utils/promise';
 import { CompactionControl, DEFAULT_SUMMARY_PROMPT, DEFAULT_TOKEN_THRESHOLD } from './CompactionControl';
-import { collectStainlessHelpers } from '../stainless-helper-header';
+import {
+  collectStainlessHelpers,
+  helperHeader,
+  STAINLESS_HELPER_HEADER,
+} from '../../internal/stainless-helper-header';
 
 /**
  * A ToolRunner handles the automatic conversation loop between the assistant and tools.
@@ -52,12 +56,17 @@ export class BetaToolRunner<Stream extends boolean> {
       },
     };
 
-    const helpers = collectStainlessHelpers(params.tools, params.messages);
-    const helperValue = ['BetaToolRunner', ...helpers].join(', ');
-
+    // structuredClone drops symbol-keyed properties, so collect helper marks
+    // from the original params here — the create()-side collector won't see
+    // them on the cloned messages.
+    const collected = collectStainlessHelpers(params.tools, params.messages);
     this.#options = {
       ...options,
-      headers: buildHeaders([{ 'x-stainless-helper': helperValue }, options?.headers]),
+      headers: buildHeaders([
+        helperHeader('BetaToolRunner'),
+        collected.length ? { [STAINLESS_HELPER_HEADER]: collected.join(', ') } : undefined,
+        options?.headers,
+      ]),
     };
     this.#completion = promiseWithResolvers();
 
@@ -137,7 +146,7 @@ export class BetaToolRunner<Stream extends boolean> {
       },
       {
         signal: this.#options.signal,
-        headers: buildHeaders([this.#options.headers, { 'x-stainless-helper': 'compaction' }]),
+        headers: buildHeaders([this.#options.headers, helperHeader('compaction')]),
       },
     );
 

package/src/lib/tools/SessionToolRunner.ts

@@ -15,6 +15,7 @@ import { isFatal4xx } from '../../internal/utils/backoff';
 import { linkAbort } from '../../internal/utils/abort';
 import { AsyncQueue } from '../../internal/utils/async-queue';
 import { buildHeaders } from '../../internal/headers';
+import { helperHeader } from '../../internal/stainless-helper-header';
 import type { RequestOptions } from '../../internal/request-options';
 import { runRunnableTool, toolName, type BetaRunnableTool } from './BetaRunnableTool';
 import type { BetaToolRunnerRequestOptions } from './BetaToolRunner';
@@ -22,9 +23,6 @@ import type { BetaToolRunnerRequestOptions } from './BetaToolRunner';
 /** Beta header for the managed-agents API. */
 export const MANAGED_AGENTS_BETA = 'managed-agents-2026-04-01';
 
-/** `x-stainless-helper` value identifying this helper in SDK telemetry. */
-const HELPER_NAME = 'SessionToolRunner';
-
 const STREAM_BACKOFF_START_MS = 500;
 const STREAM_BACKOFF_CAP_MS = 10_000;
 const TOOL_TIMEOUT_MS = 120_000;
@@ -287,7 +285,7 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
   #requestOptions(): RequestOptions {
     return {
       ...this.#requestOpts,
-      headers: buildHeaders([{ 'x-stainless-helper': HELPER_NAME }, this.#requestOpts?.headers]),
+      headers: buildHeaders([helperHeader('session-tool-runner'), this.#requestOpts?.headers]),
       signal: this.#controller.signal,
     };
   }

package/src/resources/beta/agents/agents.ts

@@ -840,7 +840,9 @@ export interface AgentCreateParams {
 
   /**
    * Body param: MCP servers this agent connects to. Maximum 20. Names must be unique
-   * within the array.
+   * within the array. Every server must be referenced by an `mcp_toolset` in
+   * `tools`; unreferenced servers are rejected. See the
+   * [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector).
    */
   mcp_servers?: Array<BetaManagedAgentsURLMCPServerParams>;
 
@@ -911,7 +913,10 @@ export interface AgentUpdateParams {
 
   /**
    * Body param: MCP servers. Full replacement. Omit to preserve; send empty array or
-   * null to clear. Names must be unique. Maximum 20.
+   * `null` to clear. Names must be unique. Maximum 20. Every server must be
+   * referenced by an `mcp_toolset` in the agent's resulting `tools`; unreferenced
+   * servers are rejected. See the
+   * [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector).
    */
   mcp_servers?: Array<BetaManagedAgentsURLMCPServerParams> | null;
 

package/src/resources/beta/beta.ts

@@ -432,6 +432,7 @@ import {
   BetaWebFetchTool20250910,
   BetaWebFetchTool20260209,
   BetaWebFetchTool20260309,
+  BetaWebFetchTool20260318,
   BetaWebFetchToolResultBlock,
   BetaWebFetchToolResultBlockParam,
   BetaWebFetchToolResultErrorBlock,
@@ -441,6 +442,7 @@ import {
   BetaWebSearchResultBlockParam,
   BetaWebSearchTool20250305,
   BetaWebSearchTool20260209,
+  BetaWebSearchTool20260318,
   BetaWebSearchToolRequestError,
   BetaWebSearchToolResultBlock,
   BetaWebSearchToolResultBlockContent,
@@ -884,6 +886,7 @@ export declare namespace Beta {
     type BetaWebFetchTool20250910 as BetaWebFetchTool20250910,
     type BetaWebFetchTool20260209 as BetaWebFetchTool20260209,
     type BetaWebFetchTool20260309 as BetaWebFetchTool20260309,
+    type BetaWebFetchTool20260318 as BetaWebFetchTool20260318,
     type BetaWebFetchToolResultBlock as BetaWebFetchToolResultBlock,
     type BetaWebFetchToolResultBlockParam as BetaWebFetchToolResultBlockParam,
     type BetaWebFetchToolResultErrorBlock as BetaWebFetchToolResultErrorBlock,
@@ -893,6 +896,7 @@ export declare namespace Beta {
     type BetaWebSearchResultBlockParam as BetaWebSearchResultBlockParam,
     type BetaWebSearchTool20250305 as BetaWebSearchTool20250305,
     type BetaWebSearchTool20260209 as BetaWebSearchTool20260209,
+    type BetaWebSearchTool20260318 as BetaWebSearchTool20260318,
     type BetaWebSearchToolRequestError as BetaWebSearchToolRequestError,
     type BetaWebSearchToolResultBlock as BetaWebSearchToolResultBlock,
     type BetaWebSearchToolResultBlockContent as BetaWebSearchToolResultBlockContent,

package/src/resources/beta/deployments.ts

@@ -55,7 +55,9 @@ export class Deployments extends APIResource {
    * @example
    * ```ts
    * const betaManagedAgentsDeployment =
-   *   await client.beta.deployments.retrieve('deployment_id');
+   *   await client.beta.deployments.retrieve(
+   *     'depl_011CZkZcDH3vPqd7xnEfwTai',
+   *   );
    * ```
    */
   retrieve(
@@ -79,7 +81,9 @@ export class Deployments extends APIResource {
    * @example
    * ```ts
    * const betaManagedAgentsDeployment =
-   *   await client.beta.deployments.update('deployment_id');
+   *   await client.beta.deployments.update(
+   *     'depl_011CZkZcDH3vPqd7xnEfwTai',
+   *   );
    * ```
    */
   update(
@@ -130,7 +134,9 @@ export class Deployments extends APIResource {
    * @example
    * ```ts
    * const betaManagedAgentsDeployment =
-   *   await client.beta.deployments.archive('deployment_id');
+   *   await client.beta.deployments.archive(
+   *     'depl_011CZkZcDH3vPqd7xnEfwTai',
+   *   );
    * ```
    */
   archive(
@@ -154,7 +160,9 @@ export class Deployments extends APIResource {
    * @example
    * ```ts
    * const betaManagedAgentsDeployment =
-   *   await client.beta.deployments.pause('deployment_id');
+   *   await client.beta.deployments.pause(
+   *     'depl_011CZkZcDH3vPqd7xnEfwTai',
+   *   );
    * ```
    */
   pause(
@@ -178,7 +186,9 @@ export class Deployments extends APIResource {
    * @example
    * ```ts
    * const betaManagedAgentsDeploymentRun =
-   *   await client.beta.deployments.run('deployment_id');
+   *   await client.beta.deployments.run(
+   *     'depl_011CZkZcDH3vPqd7xnEfwTai',
+   *   );
    * ```
    */
   run(
@@ -202,7 +212,9 @@ export class Deployments extends APIResource {
    * @example
    * ```ts
    * const betaManagedAgentsDeployment =
-   *   await client.beta.deployments.unpause('deployment_id');
+   *   await client.beta.deployments.unpause(
+   *     'depl_011CZkZcDH3vPqd7xnEfwTai',
+   *   );
    * ```
    */
   unpause(

package/src/resources/beta/files.ts

@@ -7,7 +7,7 @@ import { Page, type PageParams, PagePromise } from '../../core/pagination';
 import { type Uploadable } from '../../core/uploads';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
-import { stainlessHelperHeaderFromFile } from '../../lib/stainless-helper-header';
+import { stainlessHelperHeaderFromFile } from '../../internal/stainless-helper-header';
 import { multipartFormRequestOptions } from '../../internal/uploads';
 import { path } from '../../internal/utils/path';
 

package/src/resources/beta/index.ts

@@ -393,6 +393,7 @@ export {
   type BetaWebFetchTool20250910,
   type BetaWebFetchTool20260209,
   type BetaWebFetchTool20260309,
+  type BetaWebFetchTool20260318,
   type BetaWebFetchToolResultBlock,
   type BetaWebFetchToolResultBlockParam,
   type BetaWebFetchToolResultErrorBlock,
@@ -402,6 +403,7 @@ export {
   type BetaWebSearchResultBlockParam,
   type BetaWebSearchTool20250305,
   type BetaWebSearchTool20260209,
+  type BetaWebSearchTool20260318,
   type BetaWebSearchToolRequestError,
   type BetaWebSearchToolResultBlock,
   type BetaWebSearchToolResultBlockContent,

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

@@ -21,7 +21,7 @@ export class Batches extends APIResource {
    * can take up to 24 hours to complete.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -43,12 +43,15 @@ export class Batches extends APIResource {
    * ```
    */
   create(params: BatchCreateParams, options?: RequestOptions): APIPromise<BetaMessageBatch> {
-    const { betas, ...body } = params;
+    const { betas, user_profile_id, ...body } = params;
     return this._client.post('/v1/messages/batches?beta=true', {
       body,
       ...options,
       headers: buildHeaders([
-        { 'anthropic-beta': [...(betas ?? []), 'message-batches-2024-09-24'].toString() },
+        {
+          'anthropic-beta': [...(betas ?? []), 'message-batches-2024-09-24'].toString(),
+          ...(user_profile_id != null ? { 'anthropic-user-profile-id': user_profile_id } : undefined),
+        },
         options?.headers,
       ]),
     });
@@ -60,7 +63,7 @@ export class Batches extends APIResource {
    * `results_url` field in the response.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -90,7 +93,7 @@ export class Batches extends APIResource {
    * returned first.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -122,7 +125,7 @@ export class Batches extends APIResource {
    * like to delete an in-progress batch, you must first cancel it.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -159,7 +162,7 @@ export class Batches extends APIResource {
    * non-interruptible.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -192,7 +195,7 @@ export class Batches extends APIResource {
    * requests. Use the `custom_id` field to match results to requests.
    *
    * Learn more about the Message Batches API in our
-   * [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing)
+   * [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
    *
    * @example
    * ```ts
@@ -424,6 +427,15 @@ export interface BatchCreateParams {
    * Header param: Optional header to specify the beta version(s) you want to use.
    */
   betas?: Array<BetaAPI.AnthropicBeta>;
+
+  /**
+   * Header param: The user profile ID to attribute the requests in this batch to.
+   * Use when acting on behalf of a party other than your organization. Requires the
+   * `user-profiles` beta header. Applies to every request in the batch; an
+   * individual request whose `user_profile_id` body field conflicts with this header
+   * is errored.
+   */
+  user_profile_id?: string;
 }
 
 export namespace BatchCreateParams {
@@ -439,7 +451,8 @@ export namespace BatchCreateParams {
     /**
      * Messages API creation parameters for the individual request.
      *
-     * See the [Messages API reference](https://docs.claude.com/en/api/messages) for
+     * See the
+     * [Messages API reference](https://platform.claude.com/docs/en/api/messages) for
      * full documentation on available parameters.
      */
     params: Request.Params;
@@ -449,7 +462,8 @@ export namespace BatchCreateParams {
     /**
      * Messages API creation parameters for the individual request.
      *
-     * See the [Messages API reference](https://docs.claude.com/en/api/messages) for
+     * See the
+     * [Messages API reference](https://platform.claude.com/docs/en/api/messages) for
      * full documentation on available parameters.
      */
     export interface Params {
@@ -460,11 +474,12 @@ export namespace BatchCreateParams {
        * only specifies the absolute maximum number of tokens to generate.
        *
        * Set to `0` to populate the
-       * [prompt cache](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#pre-warming-the-cache)
+       * [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache)
        * without generating a response.
        *
        * Different models have different maximum values for this parameter. See
-       * [models](https://docs.claude.com/en/docs/models-overview) for details.
+       * [models](https://platform.claude.com/docs/en/about-claude/models/overview) for
+       * details.
        */
       max_tokens: number;
 
@@ -526,12 +541,13 @@ export namespace BatchCreateParams {
        * { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] }
        * ```
        *
-       * See [input examples](https://docs.claude.com/en/api/messages-examples).
+       * See
+       * [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
        *
        * Note that if you want to include a
-       * [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the
-       * top-level `system` parameter — there is no `"system"` role for input messages in
-       * the Messages API.
+       * [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role),
+       * you can use the top-level `system` parameter — there is no `"system"` role for
+       * input messages in the Messages API.
        *
        * There is a limit of 100,000 messages in a single request.
        */
@@ -635,7 +651,8 @@ export namespace BatchCreateParams {
        * for this request.
        *
        * Anthropic offers different levels of service for your API requests. See
-       * [service-tiers](https://docs.claude.com/en/api/service-tiers) for details.
+       * [service-tiers](https://platform.claude.com/docs/en/api/service-tiers) for
+       * details.
        */
       service_tier?: 'auto' | 'standard_only';
 
@@ -661,7 +678,8 @@ export namespace BatchCreateParams {
       /**
        * Whether to incrementally stream the response using server-sent events.
        *
-       * See [streaming](https://docs.claude.com/en/api/messages-streaming) for details.
+       * See [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming)
+       * for details.
        */
       stream?: boolean;
 
@@ -670,7 +688,7 @@ export namespace BatchCreateParams {
        *
        * A system prompt is a way of providing context and instructions to Claude, such
        * as specifying a particular goal or role. See our
-       * [guide to system prompts](https://docs.claude.com/en/docs/system-prompts).
+       * [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).
        */
       system?: string | Array<BetaMessagesAPI.BetaTextBlockParam>;
 
@@ -689,7 +707,7 @@ export namespace BatchCreateParams {
        * tokens and counts towards your `max_tokens` limit.
        *
        * See
-       * [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking)
+       * [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
        * for details.
        */
       thinking?: BetaMessagesAPI.BetaThinkingConfigParam;
@@ -710,9 +728,9 @@ export namespace BatchCreateParams {
        *
        * There are two types of tools: **client tools** and **server tools**. The
        * behavior described below applies to client tools. For
-       * [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools),
+       * [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools),
        * see their individual documentation as each has its own behavior (e.g., the
-       * [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)).
+       * [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)).
        *
        * Each tool definition includes:
        *
@@ -775,7 +793,9 @@ export namespace BatchCreateParams {
        * functions, or more generally whenever you want the model to produce a particular
        * JSON structure of output.
        *
-       * See our [guide](https://docs.claude.com/en/docs/tool-use) for more details.
+       * See our
+       * [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)
+       * for more details.
        */
       tools?: Array<BetaMessagesAPI.BetaToolUnion>;
 
@@ -791,12 +811,6 @@ export namespace BatchCreateParams {
        * other values will be rejected with a 400 error.
        */
       top_p?: number;
-
-      /**
-       * The user profile ID to attribute this request to. Use when acting on behalf of a
-       * party other than your organization.
-       */
-      user_profile_id?: string | null;
     }
   }
 }

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

@@ -222,6 +222,7 @@ export {
   type BetaWebFetchTool20250910,
   type BetaWebFetchTool20260209,
   type BetaWebFetchTool20260309,
+  type BetaWebFetchTool20260318,
   type BetaWebFetchToolResultBlock,
   type BetaWebFetchToolResultBlockParam,
   type BetaWebFetchToolResultErrorBlock,
@@ -231,6 +232,7 @@ export {
   type BetaWebSearchResultBlockParam,
   type BetaWebSearchTool20250305,
   type BetaWebSearchTool20260209,
+  type BetaWebSearchTool20260318,
   type BetaWebSearchToolRequestError,
   type BetaWebSearchToolResultBlock,
   type BetaWebSearchToolResultBlockContent,