@anthropic-ai/sdk 0.105.0 → 0.106.0

package/src/internal/stainless-helper-header.ts

@@ -0,0 +1,122 @@
+/**
+ * Single source of truth for the `x-stainless-helper` telemetry header — the
+ * key, the closed value vocabulary, and per-object helper tagging. The
+ * append-don't-clobber merge for the header itself lives in
+ * {@link import('../internal/headers').buildHeaders} via `APPEND_HEADERS`.
+ */
+
+/**
+ * Telemetry header naming the SDK helper(s) a request came from. Always this
+ * lowercase form; `buildHeaders` matches it case-insensitively for its append
+ * semantics, but a single canonical casing keeps every call site greppable.
+ */
+export const STAINLESS_HELPER_HEADER = 'x-stainless-helper';
+
+/** Telemetry header naming the SDK method (e.g. `stream`) in use. */
+export const STAINLESS_HELPER_METHOD_HEADER = 'x-stainless-helper-method';
+
+/**
+ * The closed set of helper telemetry tags, shared verbatim across SDKs. A
+ * typo at any call site is a type error rather than silently mistagged
+ * telemetry. Existing values keep their original spellings — telemetry
+ * consumers match on them, so renames lose history. New tags are hyphenated
+ * lowercase.
+ */
+export type StainlessHelperHeaderValue =
+  | 'BetaToolRunner'
+  | 'betaZodTool'
+  | 'compaction'
+  | 'environments-work-poller'
+  | 'environments-worker'
+  | 'fallback-refusal-middleware'
+  | 'mcpContent'
+  | 'mcpMessage'
+  | 'mcpResourceToContent'
+  | 'mcpResourceToFile'
+  | 'mcpTool'
+  | 'session-tool-runner';
+
+/**
+ * The `{ 'x-stainless-helper': value }` header dict, for passing into
+ * `buildHeaders` (which comma-appends `x-stainless-helper` across sources)
+ * or as `defaultHeaders`/per-request `headers`.
+ */
+export function helperHeader(value: StainlessHelperHeaderValue): { [STAINLESS_HELPER_HEADER]: string } {
+  return { [STAINLESS_HELPER_HEADER]: value };
+}
+
+/**
+ * Symbol used to mark objects created by SDK helpers for tracking.
+ * The value is the helper name (e.g., 'mcpTool', 'betaZodTool').
+ */
+export const SDK_HELPER_SYMBOL = Symbol('anthropic.sdk.stainlessHelper');
+
+type StainlessHelperObject = { [SDK_HELPER_SYMBOL]: string };
+
+export function wasCreatedByStainlessHelper(value: unknown): value is StainlessHelperObject {
+  return typeof value === 'object' && value !== null && SDK_HELPER_SYMBOL in value;
+}
+
+/**
+ * Collects helper names from tools and messages arrays.
+ * Returns a deduplicated array of helper names found.
+ */
+export function collectStainlessHelpers(
+  tools: readonly unknown[] | undefined,
+  messages: readonly unknown[] | undefined,
+): string[] {
+  const helpers = new Set<string>();
+
+  // Collect from tools
+  if (tools) {
+    for (const tool of tools) {
+      if (wasCreatedByStainlessHelper(tool)) {
+        helpers.add(tool[SDK_HELPER_SYMBOL]);
+      }
+    }
+  }
+
+  // Collect from messages and their content blocks
+  if (messages) {
+    for (const message of messages) {
+      if (wasCreatedByStainlessHelper(message)) {
+        helpers.add(message[SDK_HELPER_SYMBOL]);
+      }
+
+      const content = (message as { content?: unknown }).content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (wasCreatedByStainlessHelper(block)) {
+            helpers.add(block[SDK_HELPER_SYMBOL]);
+          }
+        }
+      }
+    }
+  }
+
+  return Array.from(helpers);
+}
+
+/**
+ * Builds x-stainless-helper header value from tools and messages.
+ * Returns an empty object if no helpers are found.
+ */
+export function stainlessHelperHeader(
+  tools: readonly unknown[] | undefined,
+  messages: readonly unknown[] | undefined,
+): { 'x-stainless-helper'?: string } {
+  const helpers = collectStainlessHelpers(tools, messages);
+  if (helpers.length === 0) return {};
+  return { [STAINLESS_HELPER_HEADER]: helpers.join(', ') };
+}
+
+/**
+ * Builds x-stainless-helper header value from a file object.
+ * Returns an empty object if the file is not marked with a helper.
+ */
+export function stainlessHelperHeaderFromFile(file: unknown): { 'x-stainless-helper'?: string } {
+  if (wasCreatedByStainlessHelper(file)) {
+    return { [STAINLESS_HELPER_HEADER]: file[SDK_HELPER_SYMBOL] };
+  }
+  return {};
+}

package/src/lib/BetaMessageStream.ts

@@ -1,3 +1,4 @@
+import { STAINLESS_HELPER_METHOD_HEADER } from '../internal/stainless-helper-header';
 import type { Logger } from '../client';
 import { AnthropicError, APIUserAbortError } from '../error';
 import { isAbortError } from '../internal/errors';
@@ -162,7 +163,7 @@ export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMess
       runner._createMessage(
         messages,
         { ...params, stream: true },
-        { ...options, headers: { ...options?.headers, 'X-Stainless-Helper-Method': 'stream' } },
+        { ...options, headers: { ...options?.headers, [STAINLESS_HELPER_METHOD_HEADER]: 'stream' } },
       ),
     );
     return runner;

package/src/lib/MessageStream.ts

@@ -1,3 +1,4 @@
+import { STAINLESS_HELPER_METHOD_HEADER } from '../internal/stainless-helper-header';
 import { isAbortError } from '../internal/errors';
 import { AnthropicError, APIUserAbortError } from '../error';
 import {
@@ -161,7 +162,7 @@ export class MessageStream<ParsedT = null> implements AsyncIterable<MessageStrea
       runner._createMessage(
         messages,
         { ...params, stream: true },
-        { ...options, headers: { ...options?.headers, 'X-Stainless-Helper-Method': 'stream' } },
+        { ...options, headers: { ...options?.headers, [STAINLESS_HELPER_METHOD_HEADER]: 'stream' } },
       ),
     );
     return runner;

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/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/messages/batches.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,
       ]),
     });
@@ -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 {
@@ -791,12 +803,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/messages.ts

@@ -9,7 +9,7 @@ import { Stream } from '../../../core/streaming';
 import { MODEL_NONSTREAMING_TOKENS } from '../../../internal/constants';
 import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
-import { stainlessHelperHeader } from '../../../lib/stainless-helper-header';
+import { stainlessHelperHeader } from '../../../internal/stainless-helper-header';
 import {
   parseBetaMessage,
   type ExtractParsedContentFromBetaParams,
@@ -111,7 +111,7 @@ export class Messages extends APIResource {
     // Transform deprecated output_format to output_config.format
     const modifiedParams = transformOutputFormat(params);
 
-    const { betas, ...body } = modifiedParams;
+    const { betas, user_profile_id, ...body } = modifiedParams;
 
     if (body.model in DEPRECATED_MODELS) {
       console.warn(
@@ -145,7 +145,10 @@ export class Messages extends APIResource {
       timeout: timeout ?? 600000,
       ...options,
       headers: buildHeaders([
-        { ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined) },
+        {
+          ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined),
+          ...(user_profile_id != null ? { 'anthropic-user-profile-id': user_profile_id } : undefined),
+        },
         helperHeader,
         options?.headers,
       ]),
@@ -588,7 +591,9 @@ export interface BetaCacheControlEphemeral {
    * - `5m`: 5 minutes
    * - `1h`: 1 hour
    *
-   * Defaults to `5m`.
+   * Defaults to `5m`. See
+   * [prompt caching pricing](https://docs.claude.com/en/docs/build-with-claude/prompt-caching)
+   * for details.
    */
   ttl?: '5m' | '1h';
 }
@@ -1732,7 +1737,7 @@ export interface BetaFallbackRefusalTrigger {
   /**
    * The policy category that triggered a refusal.
    */
-  category: 'cyber' | 'bio' | 'frontier_llm' | 'reasoning_extraction' | null;
+  category: 'cyber' | 'bio' | 'frontier_llm' | 'reasoning_extraction' | 'military_weapons' | null;
 
   type: 'refusal';
 }
@@ -2504,7 +2509,7 @@ export interface BetaRefusalStopDetails {
   /**
    * The policy category that triggered a refusal.
    */
-  category: 'cyber' | 'bio' | 'frontier_llm' | 'reasoning_extraction' | null;
+  category: 'cyber' | 'bio' | 'frontier_llm' | 'reasoning_extraction' | 'military_weapons' | null;
 
   /**
    * Human-readable explanation of the refusal.
@@ -4710,15 +4715,16 @@ export interface MessageCreateParamsBase {
   top_p?: number;
 
   /**
-   * Body param: The user profile ID to attribute this request to. Use when acting on
-   * behalf of a party other than your organization.
+   * Header param: Optional header to specify the beta version(s) you want to use.
    */
-  user_profile_id?: string | null;
+  betas?: Array<BetaAPI.AnthropicBeta>;
 
   /**
-   * Header param: Optional header to specify the beta version(s) you want to use.
+   * Header param: The user profile ID to attribute this request to. Use when acting
+   * on behalf of a party other than your organization. Requires the `user-profiles`
+   * beta header.
    */
-  betas?: Array<BetaAPI.AnthropicBeta>;
+  user_profile_id?: string;
 }
 
 export namespace MessageCreateParams {

package/src/resources/messages/batches.ts

@@ -40,8 +40,16 @@ export class Batches extends APIResource {
    * });
    * ```
    */
-  create(body: BatchCreateParams, options?: RequestOptions): APIPromise<MessageBatch> {
-    return this._client.post('/v1/messages/batches', { body, ...options });
+  create(params: BatchCreateParams, options?: RequestOptions): APIPromise<MessageBatch> {
+    const { user_profile_id, ...body } = params;
+    return this._client.post('/v1/messages/batches', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(user_profile_id != null ? { 'anthropic-user-profile-id': user_profile_id } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -350,10 +358,19 @@ export interface MessageBatchSucceededResult {
 
 export interface BatchCreateParams {
   /**
-   * List of requests for prompt completion. Each is an individual request to create
-   * a Message.
+   * Body param: List of requests for prompt completion. Each is an individual
+   * request to create a Message.
    */
   requests: Array<BatchCreateParams.Request>;
+
+  /**
+   * 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 {