@anthropic-ai/sdk 0.100.1 → 0.102.0

package/src/core/middleware.ts

@@ -0,0 +1,293 @@
+import type { Fetch } from '../internal/builtin-types';
+import { castToError, isAbortError } from '../internal/errors';
+import { addRequestID } from '../internal/parse';
+import type { FinalRequestOptions } from '../internal/request-options';
+import type { APIRequest } from './api';
+import { AnthropicError, APIConnectionError, RetryableError } from './error';
+import { Stream } from './streaming';
+
+/**
+ * Invokes the rest of the middleware chain, ending with the underlying `fetch`.
+ *
+ * This function can be invoked multiple times.
+ */
+export type MiddlewareNext = (request: APIRequest) => Promise<Response>;
+
+/**
+ * Helpers passed to each middleware alongside `next`, scoped to the request
+ * in flight (one context is shared by every middleware in the chain).
+ */
+export interface MiddlewareContext {
+  /**
+   * The SDK request options the API call in flight was made with: `method`,
+   * `path`, the pre-encoded `body`, `stream`, etc.
+   *
+   * `undefined` when the chain isn't running for an SDK API request, i.e.
+   * for credential token-exchange requests.
+   */
+  readonly options?: FinalRequestOptions | undefined;
+
+  /**
+   * Parse a response body the way the SDK would for the request in flight:
+   *
+   * - JSON responses are decoded, with the non-enumerable `_request_id`
+   *   property attached like SDK return values, and anything else resolves
+   *   to the body text.
+   * - For streaming requests ({@link options}`.stream`), resolves immediately
+   *   with a {@link Stream} reading an independent copy of the response body —
+   *   iterating it doesn't consume the client's events, and aborting or
+   *   `break`ing out of it doesn't cancel the underlying request. Each call
+   *   returns a fresh `Stream` (streams are single-consumer, so they aren't
+   *   cached). Error (non-2xx) responses parse as JSON/text rather than as a
+   *   stream, mirroring the SDK's own handling.
+   * - For binary requests, resolves with the `Response` itself, unconsumed.
+   *
+   * Reads through an internal `response.clone()`, so the response stays
+   * readable: the client (and any other middleware) can still consume the
+   * body afterwards. Non-stream results are cached per `Response` and shared
+   * across the middleware chain, so repeated calls cost a single read.
+   *
+   * @example
+   * ```ts
+   * const mw: Middleware = async (request, next, ctx) => {
+   *   const response = await next(request);
+   *   const data = await ctx.parse<Message>(response);
+   *   if (data.type === 'message') console.log(data.usage);
+   *   return response;
+   * };
+   * ```
+   */
+  parse<T = unknown>(response: Response): Promise<T>;
+}
+
+/**
+ * A function that wraps each HTTP request made by the client.
+ *
+ * Middleware may observe or modify the request before calling `next`, observe
+ * or replace the response, short-circuit by returning a `Response` without
+ * calling `next`, or call `next` multiple times to implement custom retries.
+ *
+ * Middleware must not consume the body of the `Response` it returns - the
+ * client still needs to read it. To inspect the body, use
+ * `await ctx.parse(response)` (cached, leaves the body readable) or read a
+ * clone (`await response.clone().text()`); to transform it, return a
+ * replacement, e.g. `new Response(body, response)`.
+ *
+ * Middleware runs per HTTP attempt, inside the SDK's retry loop; the attempt
+ * number is available via the `X-Stainless-Retry-Count` request header. An
+ * error thrown from middleware propagates to the caller as-is.
+ *
+ * Middleware errors are **not** retried apart from connection-level errors:
+ * timeout/abort errors, errors thrown by `fetch()`, and `APIConnectionError`s
+ * or `RetryableError`s — thrown directly or present anywhere in an error's
+ * `cause` chain. Retryable middleware errors still propagate to the caller
+ * as-is once retries are exhausted.
+ *
+ * @example
+ * ```ts
+ * const logger: Middleware = async (request, next) => {
+ *   console.log('->', request.method, request.url);
+ *   const response = await next(request);
+ *   console.log('<-', response.status, request.url);
+ *   return response;
+ * };
+ *
+ * const client = new Anthropic({ middleware: [logger] });
+ * ```
+ */
+export type Middleware = (
+  request: APIRequest,
+  next: MiddlewareNext,
+  ctx: MiddlewareContext,
+) => Promise<Response>;
+
+/**
+ * Errors thrown by the underlying `fetch`, as opposed to by a middleware.
+ *
+ * Tracked so the client can apply its connection-error retry policy to
+ * transport failures while letting errors thrown by middleware propagate to
+ * the caller untouched.
+ */
+const fetchOriginErrors = new WeakSet<object>();
+
+/** Whether `err` was thrown by the underlying `fetch` rather than by a middleware. */
+export function isFetchOriginError(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && fetchOriginErrors.has(err);
+}
+
+/**
+ * Whether an error thrown by middleware should stay on the SDK's
+ * connection-error retry policy: fetch-origin, abort, `APIConnectionError`, or
+ * `RetryableError` — checked through the error's `cause` chain.
+ */
+export function isRetryableError(err: unknown): boolean {
+  const seen = new Set<unknown>(); // guard against `cause` cycles
+  while (typeof err === 'object' && err !== null && !seen.has(err)) {
+    seen.add(err);
+    if (
+      isFetchOriginError(err) ||
+      isAbortError(err) ||
+      err instanceof APIConnectionError ||
+      err instanceof RetryableError
+    ) {
+      return true;
+    }
+    err = (err as { cause?: unknown }).cause;
+  }
+  return false;
+}
+
+/**
+ * Wraps `fetchFn` so each call runs through `middleware`, keeping the same
+ * call signature as `fetch` itself.
+ *
+ * With no middleware, calls are passed straight through to `fetchFn`.
+ * Otherwise the arguments are normalized into an {@link APIRequest} (headers
+ * coerced to a `Headers` instance, URL stringified) before entering the
+ * chain. The chain is composed per call, so mutations of a `middleware`
+ * array are picked up by later requests.
+ *
+ * `options` — the SDK request options behind this call, when there are any —
+ * is surfaced to middleware as `ctx.options` and drives `ctx.parse`.
+ */
+export function wrapFetchWithMiddleware(
+  fetchFn: Fetch,
+  middleware: readonly Middleware[],
+  options?: FinalRequestOptions | undefined,
+): Fetch {
+  return async (url, init = {}) => {
+    if (middleware.length === 0) {
+      // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
+      return fetchFn.call(undefined, url, init);
+    }
+    const headers = init.headers instanceof Headers ? init.headers : new Headers(init.headers);
+    const response = await applyMiddleware(
+      fetchFn,
+      middleware,
+      options,
+    )({
+      ...init,
+      headers,
+      url:
+        typeof url === 'string' ? url
+        : url instanceof URL ? url.href
+        : url.url,
+    });
+    // Catch a footgun before the client tries to read the body itself and
+    // fails with a confusing low-level stream error.
+    if (response.bodyUsed || response.body?.locked) {
+      throw new AnthropicError(
+        'middleware consumed the response body; use response.clone() to inspect it, ' +
+          'or return new Response(body, response) to consume and replace it',
+      );
+    }
+    return response;
+  };
+}
+
+/**
+ * Creates the {@link MiddlewareContext} shared by every middleware in one chain.
+ */
+function createMiddlewareContext(options: FinalRequestOptions | undefined): MiddlewareContext {
+  // Keyed on the Response so each `next()` call's response (e.g. with custom
+  // retries, or a middleware swapping in a replacement) parses independently,
+  // while several middleware parsing the same response share a single read.
+  const cache = new WeakMap<Response, Promise<unknown>>();
+  return {
+    options,
+    parse<T>(response: Response): Promise<T> {
+      // Streams are single-consumer, so caching one would hand later callers
+      // an already-consumed stream; every call gets a fresh clone-backed one.
+      if (options?.stream && response.ok) {
+        return parseMiddlewareResponse(response, options) as Promise<T>;
+      }
+      let parsed = cache.get(response);
+      if (!parsed) {
+        parsed = parseMiddlewareResponse(response, options);
+        cache.set(response, parsed);
+      }
+      return parsed as Promise<T>;
+    },
+  };
+}
+
+/**
+ * Mirrors the client's own response parsing (`defaultParseResponse` in
+ * `internal/parse.ts`), reading through a clone so the body stays available
+ * to the rest of the chain and the client itself.
+ */
+async function parseMiddlewareResponse(
+  response: Response,
+  options: FinalRequestOptions | undefined,
+): Promise<unknown> {
+  if (response.bodyUsed || response.body?.locked) {
+    throw new AnthropicError(
+      'cannot ctx.parse() a response whose body was already consumed; ' +
+        'call ctx.parse() instead of reading the body, or read via response.clone()',
+    );
+  }
+
+  // Error responses parse as JSON/text below — the SDK only stream-parses
+  // successful responses, and middleware typically wants the error body.
+  if (options?.stream && response.ok) {
+    // A fresh controller rather than the request's own: aborting (or
+    // `break`ing out of) the middleware's stream must not cancel the
+    // in-flight request the client is still reading.
+    const streamClass = options.__streamClass ?? Stream;
+    return streamClass.fromSSEResponse(response.clone(), new AbortController());
+  }
+
+  // fetch refuses to read the body when the status code is 204.
+  if (response.status === 204) {
+    return null;
+  }
+
+  if (options?.__binaryResponse) {
+    return response;
+  }
+
+  const contentType = response.headers.get('content-type');
+  const mediaType = contentType?.split(';')[0]?.trim();
+  const isJSON = mediaType?.includes('application/json') || mediaType?.endsWith('+json');
+  if (isJSON) {
+    if (response.headers.get('content-length') === '0') {
+      // if there is no content we can't do anything
+      return undefined;
+    }
+    return addRequestID(await response.clone().json(), response);
+  }
+
+  return await response.clone().text();
+}
+
+/**
+ * Composes `middleware` around `fetchFn` and returns the entry point of the chain.
+ */
+export function applyMiddleware(
+  fetchFn: Fetch,
+  middleware: readonly Middleware[],
+  options?: FinalRequestOptions | undefined,
+): MiddlewareNext {
+  // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
+  let next: MiddlewareNext = async ({ url, ...init }) => {
+    try {
+      return await fetchFn.call(undefined, url, init);
+    } catch (err) {
+      // Brand the error as fetch-origin, normalizing with `castToError` first since a
+      // WeakSet can't hold primitives and the brand must be on the same object the
+      // client's own `castToError` will later pass through.
+      const error = castToError(err);
+      fetchOriginErrors.add(error);
+      throw error;
+    }
+  };
+
+  const ctx = createMiddlewareContext(options);
+  for (let i = middleware.length - 1; i >= 0; i--) {
+    const mw = middleware[i]!;
+    const nextInner = next;
+    next = async (request) => mw(request, nextInner, ctx);
+  }
+
+  return next;
+}

package/src/index.ts

@@ -4,7 +4,15 @@ export { Anthropic as default } from './client';
 
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
-export { BaseAnthropic, Anthropic, type ClientOptions, HUMAN_PROMPT, AI_PROMPT } from './client';
+export { type Middleware, type MiddlewareContext, type MiddlewareNext } from './core/middleware';
+export {
+  BaseAnthropic,
+  Anthropic,
+  type APIRequest,
+  type ClientOptions,
+  HUMAN_PROMPT,
+  AI_PROMPT,
+} from './client';
 export { PagePromise } from './core/pagination';
 export {
   AnthropicError,
@@ -12,6 +20,7 @@ export {
   APIConnectionError,
   APIConnectionTimeoutError,
   APIUserAbortError,
+  RetryableError,
   NotFoundError,
   ConflictError,
   RateLimitError,

package/src/internal/request-options.ts

@@ -4,6 +4,7 @@ import { NullableHeaders } from './headers';
 
 import type { BodyInit } from './builtin-types';
 import { Stream } from '../core/streaming';
+import type { Middleware } from '../core/middleware';
 import type { HTTPMethod, MergedRequestInit } from './types';
 import { type HeadersLike } from './headers';
 
@@ -66,6 +67,13 @@ export type RequestOptions = {
    */
   signal?: AbortSignal | undefined | null;
 
+  /**
+   * Additional {@link Middleware} to wrap this request's HTTP attempts.
+   *
+   * These run after any client-level middleware and apply to every attempt of this request, including retries.
+   */
+  middleware?: ReadonlyArray<Middleware> | undefined;
+
   /**
    * A unique key for this request to enable idempotency.
    */

package/src/lib/BetaMessageStream.ts

@@ -578,6 +578,9 @@ export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMess
         snapshot.container = event.delta.container;
         snapshot.stop_reason = event.delta.stop_reason;
         snapshot.stop_sequence = event.delta.stop_sequence;
+        if (event.delta.stop_details != null) {
+          snapshot.stop_details = event.delta.stop_details;
+        }
         snapshot.usage.output_tokens = event.usage.output_tokens;
         snapshot.context_management = event.context_management;
 

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

@@ -519,20 +519,13 @@ export interface BetaManagedAgentsCustomTool {
  * JSON Schema for custom tool input parameters.
  */
 export interface BetaManagedAgentsCustomToolInputSchema {
-  /**
-   * JSON Schema properties defining the tool's input parameters.
-   */
+  type: 'object';
+
   properties?: { [key: string]: unknown } | null;
 
-  /**
-   * List of required property names.
-   */
-  required?: Array<string>;
+  required?: Array<string> | null;
 
-  /**
-   * Must be 'object' for tool input schemas.
-   */
-  type?: 'object';
+  [k: string]: unknown;
 }
 
 /**
@@ -835,12 +828,12 @@ export interface AgentCreateParams {
   model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams;
 
   /**
-   * Body param: Human-readable name for the agent. 1-256 characters.
+   * Body param: Human-readable name for the agent.
    */
   name: string;
 
   /**
-   * Body param: Description of what the agent does. Up to 2048 characters.
+   * Body param: Description of what the agent does.
    */
   description?: string | null;
 
@@ -864,12 +857,12 @@ export interface AgentCreateParams {
   multiagent?: SessionsAPI.BetaManagedAgentsMultiagentParams | null;
 
   /**
-   * Body param: Skills available to the agent. Maximum 20.
+   * Body param: Skills available to the agent.
    */
   skills?: Array<BetaManagedAgentsSkillParams>;
 
   /**
-   * Body param: System prompt for the agent. Up to 100,000 characters.
+   * Body param: System prompt for the agent.
    */
   system?: string | null;
 
@@ -911,8 +904,7 @@ export interface AgentUpdateParams {
   version: number;
 
   /**
-   * Body param: Description. Up to 2048 characters. Omit to preserve; send empty
-   * string or null to clear.
+   * Body param: Description. Omit to preserve; send empty string or null to clear.
    */
   description?: string | null;
 
@@ -945,20 +937,19 @@ export interface AgentUpdateParams {
   multiagent?: SessionsAPI.BetaManagedAgentsMultiagentParams | null;
 
   /**
-   * Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be
+   * Body param: Human-readable name. Must be non-empty. Omit to preserve. Cannot be
    * cleared.
    */
   name?: string;
 
   /**
    * Body param: Skills. Full replacement. Omit to preserve; send empty array or null
-   * to clear. Maximum 20.
+   * to clear.
    */
   skills?: Array<BetaManagedAgentsSkillParams> | null;
 
   /**
-   * Body param: System prompt. Up to 100,000 characters. Omit to preserve; send
-   * empty string or null to clear.
+   * Body param: System prompt. Omit to preserve; send empty string or null to clear.
    */
   system?: string | null;
 

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

@@ -60,6 +60,8 @@ const DEPRECATED_MODELS: {
   'claude-2.0': 'July 21st, 2025',
   'claude-3-7-sonnet-latest': 'February 19th, 2026',
   'claude-3-7-sonnet-20250219': 'February 19th, 2026',
+  'claude-opus-4-1': 'August 5th, 2026',
+  'claude-opus-4-1-20250805': 'August 5th, 2026',
 };
 
 const MODELS_TO_WARN_WITH_THINKING_ENABLED: Model[] = ['claude-mythos-preview', 'claude-opus-4-6'];
@@ -393,6 +395,17 @@ export interface BetaAdvisorTool20260301 {
    */
   defer_loading?: boolean;
 
+  /**
+   * Bounds the advisor's total output (thinking + text) per call. When the advisor
+   * hits this cap, the returned advisor_result or advisor_redacted_result block
+   * carries stop_reason='max_tokens', and a truncation note is appended to the
+   * advice text the worker model sees (inside the encrypted blob in redacted mode).
+   * When set, the server also emits a remaining-tokens budget block in the advisor's
+   * prompt so the advisor self-shapes toward the cap. When omitted, the advisor
+   * model's default output cap applies and no budget block is emitted.
+   */
+  max_tokens?: number | null;
+
   /**
    * Maximum number of times the tool can be used in the API request.
    */
@@ -435,7 +448,8 @@ export interface BetaAdvisorToolResultError {
     | 'too_many_requests'
     | 'overloaded'
     | 'unavailable'
-    | 'execution_time_exceeded';
+    | 'execution_time_exceeded'
+    | 'model_not_found';
 
   type: 'advisor_tool_result_error';
 }
@@ -447,7 +461,8 @@ export interface BetaAdvisorToolResultErrorParam {
     | 'too_many_requests'
     | 'overloaded'
     | 'unavailable'
-    | 'execution_time_exceeded';
+    | 'execution_time_exceeded'
+    | 'model_not_found';
 
   type: 'advisor_tool_result_error';
 }
@@ -3228,6 +3243,8 @@ export interface BetaToolSearchToolResultErrorParam {
   error_code: 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded';
 
   type: 'tool_search_tool_result_error';
+
+  error_message?: string | null;
 }
 
 export interface BetaToolSearchToolSearchResultBlock {

package/src/resources/beta/webhooks.ts

@@ -63,7 +63,7 @@ export type BetaWebhookEventData =
 
 export interface BetaWebhookSessionArchivedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -76,7 +76,7 @@ export interface BetaWebhookSessionArchivedEventData {
 
 export interface BetaWebhookSessionCreatedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -89,7 +89,7 @@ export interface BetaWebhookSessionCreatedEventData {
 
 export interface BetaWebhookSessionDeletedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -102,7 +102,7 @@ export interface BetaWebhookSessionDeletedEventData {
 
 export interface BetaWebhookSessionIdledEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -115,7 +115,7 @@ export interface BetaWebhookSessionIdledEventData {
 
 export interface BetaWebhookSessionOutcomeEvaluationEndedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -128,7 +128,7 @@ export interface BetaWebhookSessionOutcomeEvaluationEndedEventData {
 
 export interface BetaWebhookSessionPendingEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -141,7 +141,7 @@ export interface BetaWebhookSessionPendingEventData {
 
 export interface BetaWebhookSessionRequiresActionEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -154,7 +154,7 @@ export interface BetaWebhookSessionRequiresActionEventData {
 
 export interface BetaWebhookSessionRunningEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -167,7 +167,7 @@ export interface BetaWebhookSessionRunningEventData {
 
 export interface BetaWebhookSessionStatusIdledEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -180,7 +180,7 @@ export interface BetaWebhookSessionStatusIdledEventData {
 
 export interface BetaWebhookSessionStatusRescheduledEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -193,7 +193,7 @@ export interface BetaWebhookSessionStatusRescheduledEventData {
 
 export interface BetaWebhookSessionStatusRunStartedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -206,7 +206,7 @@ export interface BetaWebhookSessionStatusRunStartedEventData {
 
 export interface BetaWebhookSessionStatusTerminatedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -219,7 +219,7 @@ export interface BetaWebhookSessionStatusTerminatedEventData {
 
 export interface BetaWebhookSessionThreadCreatedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -232,7 +232,7 @@ export interface BetaWebhookSessionThreadCreatedEventData {
 
 export interface BetaWebhookSessionThreadIdledEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -245,7 +245,7 @@ export interface BetaWebhookSessionThreadIdledEventData {
 
 export interface BetaWebhookSessionThreadTerminatedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the session that triggered the event.
    */
   id: string;
 
@@ -258,7 +258,7 @@ export interface BetaWebhookSessionThreadTerminatedEventData {
 
 export interface BetaWebhookVaultArchivedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the vault that triggered the event.
    */
   id: string;
 
@@ -271,7 +271,7 @@ export interface BetaWebhookVaultArchivedEventData {
 
 export interface BetaWebhookVaultCreatedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the vault that triggered the event.
    */
   id: string;
 
@@ -284,7 +284,7 @@ export interface BetaWebhookVaultCreatedEventData {
 
 export interface BetaWebhookVaultCredentialArchivedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the vault credential that triggered the event.
    */
   id: string;
 
@@ -302,7 +302,7 @@ export interface BetaWebhookVaultCredentialArchivedEventData {
 
 export interface BetaWebhookVaultCredentialCreatedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the vault credential that triggered the event.
    */
   id: string;
 
@@ -320,7 +320,7 @@ export interface BetaWebhookVaultCredentialCreatedEventData {
 
 export interface BetaWebhookVaultCredentialDeletedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the vault credential that triggered the event.
    */
   id: string;
 
@@ -338,7 +338,7 @@ export interface BetaWebhookVaultCredentialDeletedEventData {
 
 export interface BetaWebhookVaultCredentialRefreshFailedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the vault credential that triggered the event.
    */
   id: string;
 
@@ -356,7 +356,7 @@ export interface BetaWebhookVaultCredentialRefreshFailedEventData {
 
 export interface BetaWebhookVaultDeletedEventData {
   /**
-   * ID of the resource that triggered the event.
+   * ID of the vault that triggered the event.
    */
   id: string;