@anthropic-ai/sdk 0.119.0 → 0.121.0

package/src/lib/sessions/accumulate.ts

@@ -1,4 +1,5 @@
 import { AnthropicError } from '../../core/error';
+import { checkNever } from '../../internal/utils/values';
 import type {
   BetaManagedAgentsAgentMessageEvent,
   BetaManagedAgentsStreamSessionEvents,
@@ -125,6 +126,3 @@ export function accumulateManagedAgentsEvent(
       return accumulated;
   }
 }
-
-// Compile-time exhaustiveness guard.
-function checkNever(_x: never): void {}

package/src/lib/standard-schema.ts

@@ -0,0 +1,209 @@
+import { AnthropicError } from '../core/error';
+
+// Standard Schema spec types, copied from `@standard-schema/spec@1.1.0` (MIT) as the spec
+// recommends. See https://standardschema.dev
+
+/** The Standard Typed interface. This is a base type extended by other specs. */
+export interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly '~standard': StandardTypedV1.Props<Input, Output>;
+}
+
+export declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema['~standard']['types']>['input'];
+
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (
+      value: unknown,
+      options?: StandardSchemaV1.Options | undefined,
+    ) => Result<Output> | Promise<Result<Output>>;
+  }
+
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+
+/** The Standard JSON Schema interface. */
+export interface StandardJSONSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard JSON Schema properties. */
+  readonly '~standard': StandardJSONSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardJSONSchemaV1 {
+  /** The Standard JSON Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Methods for generating the input/output JSON Schema. */
+    readonly jsonSchema: StandardJSONSchemaV1.Converter;
+  }
+
+  /** The Standard JSON Schema converter interface. */
+  interface Converter {
+    /** Converts the input type to JSON Schema. May throw if conversion is not supported. */
+    readonly input: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
+    /** Converts the output type to JSON Schema. May throw if conversion is not supported. */
+    readonly output: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
+  }
+
+  /**
+   * The target version of the generated JSON Schema.
+   *
+   * It is *strongly recommended* that implementers support `"draft-2020-12"` and `"draft-07"`, as they
+   * are both in wide use. All other targets can be implemented on a best-effort basis. Libraries should
+   * throw if they don't support a specified target.
+   *
+   * The `"openapi-3.0"` target is intended as a standardized specifier for OpenAPI 3.0 which is a
+   * superset of JSON Schema `"draft-04"`.
+   */
+  type Target = 'draft-2020-12' | 'draft-07' | 'openapi-3.0' | ({} & string);
+
+  /** The options for the input/output methods. */
+  interface Options {
+    /** Specifies the target version of the generated JSON Schema. Support for all versions is on a best-effort basis. If a given version is not supported, the library should throw. */
+    readonly target: Target;
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+
+/**
+ * Returns `jsonSchema` if given, otherwise the schema's Standard JSON Schema `input`
+ * representation (the model produces the value that the validator consumes).
+ */
+export function standardSchemaToJSONSchema(
+  schema: StandardSchemaV1,
+  jsonSchema?: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (jsonSchema) {
+    return jsonSchema;
+  }
+
+  const std: StandardSchemaV1.Props & Partial<StandardJSONSchemaV1.Props> = schema['~standard'];
+  if (std.jsonSchema) {
+    return std.jsonSchema.input({ target: 'draft-2020-12' });
+  }
+
+  throw new AnthropicError(
+    `Could not derive a JSON Schema from this ${std.vendor} schema as it does not implement Standard JSON Schema (\`~standard.jsonSchema\`). Pass the \`jsonSchema\` option, or use a library version that implements it (e.g. zod >= 4.2, or valibot via \`toStandardJsonSchema()\`).`,
+  );
+}
+
+/**
+ * Validates `value` with `~standard.validate` and returns the typed output, throwing an
+ * `AnthropicError` on issues. Validation must be synchronous because `parse` hooks are.
+ */
+export function parseWithStandardSchema<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  value: unknown,
+): StandardSchemaV1.InferOutput<Schema> {
+  const result = schema['~standard'].validate(value);
+
+  if (result instanceof Promise) {
+    // avoid an unhandled rejection from the discarded result
+    result.catch(() => {});
+    throw new AnthropicError(
+      `Async validation is not supported: the ${schema['~standard'].vendor} schema's \`~standard.validate()\` returned a Promise.`,
+    );
+  }
+
+  if (result.issues) {
+    const formattedIssues = result.issues.slice(0, 5).map(formatIssue).join('\n');
+    const issueCount = result.issues.length;
+    const suffix = issueCount > 5 ? `\n  ... and ${issueCount - 5} more issue(s)` : '';
+
+    throw new AnthropicError(
+      `Schema validation failed with ${issueCount} issue(s):\n${formattedIssues}${suffix}`,
+    );
+  }
+
+  return result.value;
+}
+
+function formatIssue(issue: StandardSchemaV1.Issue): string {
+  const path = (issue.path ?? [])
+    .map((segment) => String(typeof segment === 'object' ? segment.key : segment))
+    .join('.');
+  return path ? `  - ${path}: ${issue.message}` : `  - ${issue.message}`;
+}

package/src/lib/tools/BetaToolRunner.ts

@@ -8,6 +8,7 @@ import {
   BetaMessageParam,
   BetaRequestToolAdditionBlock,
   BetaRequestToolRemovalBlock,
+  BetaStopReason,
   BetaToolChangeMCPToolReference,
   BetaToolChangeMCPToolsetReference,
   BetaToolChangeToolReference,
@@ -18,6 +19,7 @@ import { BetaMessageStream } from '../BetaMessageStream';
 import { RequestOptions } from '../../internal/request-options';
 import { buildHeaders } from '../../internal/headers';
 import { promiseWithResolvers } from '../../internal/utils/promise';
+import { checkNever } from '../../internal/utils/values';
 import { CompactionControl, DEFAULT_SUMMARY_PROMPT, DEFAULT_TOKEN_THRESHOLD } from './CompactionControl';
 import {
   collectStainlessHelpers,
@@ -220,6 +222,7 @@ export class BetaToolRunner<Stream extends boolean> {
           if (!isCompacted) {
             if (!this.#mutated) {
               const message = await this.#message;
+              const nextStep = determineNextStepFromStopReason(message.stop_reason);
               this.#state.params.messages.push({ role: message.role, content: message.content });
 
               // Container-bound server tools reject a follow-up request that omits the container the
@@ -233,14 +236,12 @@ export class BetaToolRunner<Stream extends boolean> {
                 }
               }
 
-              // Refusal-terminated turns are terminal: the refusal may have cut a tool_use off
-              // with partial input, so executing this turn's tools would fire side effects the
-              // model never confirmed — and once middleware strips the refusal turn, their
-              // tool_results could never be replayed coherently. Surface the refusal as the
-              // final message instead.
-              if (message.stop_reason === 'refusal') {
+              if (nextStep === 'stop') {
                 break;
               }
+              if (nextStep === 'resume') {
+                continue;
+              }
             }
 
             const toolMessage = await this.#generateToolResponse(this.#state.params.messages.at(-1)!);
@@ -612,6 +613,37 @@ function referencedToolName(
   }
 }
 
+type NextStep = 'run_tools' | 'resume' | 'stop';
+
+/**
+ * Sorts every stop reason into one of three buckets: `run_tools` turns run their client tool
+ * calls and continue the loop; `resume` turns are sent back unchanged so the server continues
+ * them; `stop` turns end the loop without running any tool calls.
+ */
+function determineNextStepFromStopReason(stopReason: BetaStopReason | null): NextStep {
+  if (stopReason === null) return 'stop';
+  switch (stopReason) {
+    case 'tool_use':
+      return 'run_tools';
+    case 'pause_turn':
+    // pause_after_compaction hands the turn back before the model answers; sending it back
+    // unchanged continues it.
+    case 'compaction':
+      return 'resume';
+    case 'end_turn':
+    case 'stop_sequence':
+    case 'max_tokens':
+    case 'model_context_window_exceeded':
+    case 'refusal':
+      return 'stop';
+    default:
+      // The union is forward-compatible, so a stop reason this SDK doesn't know yet ends the
+      // loop rather than throwing; the `never` check makes tsc reject an unclassified member.
+      checkNever(stopReason);
+      return 'stop';
+  }
+}
+
 // vendored from typefest just to make things look a bit nicer on hover
 type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};