@anthropic-ai/sdk 0.95.2 → 0.97.0

package/src/helpers/beta/zod.ts

@@ -1,5 +1,4 @@
 import { transformJSONSchema } from '../..//lib/transform-json-schema';
-import type { infer as zodInfer, ZodType } from 'zod';
 import * as z from 'zod/v4';
 import { AnthropicError } from '../../core/error';
 import { AutoParseableBetaOutputFormat } from '../../lib/beta-parser';
@@ -14,9 +13,9 @@ import { BetaToolResultContentBlockParam } from '../../resources/beta';
  * This can be passed directly to the `.create()` method but will not
  * result in any automatic parsing, you'll have to parse the response yourself.
  */
-export function betaZodOutputFormat<ZodInput extends ZodType>(
+export function betaZodOutputFormat<ZodInput extends z.ZodType>(
   zodObject: ZodInput,
-): AutoParseableBetaOutputFormat<zodInfer<ZodInput>> {
+): AutoParseableBetaOutputFormat<z.infer<ZodInput>> {
   let jsonSchema = z.toJSONSchema(zodObject, { reused: 'ref' });
 
   jsonSchema = transformJSONSchema(jsonSchema);
@@ -46,15 +45,21 @@ export function betaZodOutputFormat<ZodInput extends ZodType>(
  * converted into JSON Schema when passed to the API. The provided function's
  * input arguments will also be validated against the provided schema.
  */
-export function betaZodTool<InputSchema extends ZodType>(options: {
+export function betaZodTool<InputSchema extends z.ZodType>(options: {
   name: string;
   inputSchema: InputSchema;
   description: string;
   run: (
-    args: zodInfer<InputSchema>,
+    args: z.infer<InputSchema>,
     context?: BetaToolRunContext,
   ) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
-}): BetaRunnableTool<zodInfer<InputSchema>> {
+  /**
+   * Optional cleanup hook for tools that hold process-level resources (e.g. a
+   * persistent shell). `client.beta.sessions.events.toolRunner` calls it once
+   * when iteration ends.
+   */
+  close?: () => void | Promise<void>;
+}): BetaRunnableTool<z.infer<InputSchema>> {
   const jsonSchema = z.toJSONSchema(options.inputSchema, { reused: 'ref' });
 
   if (jsonSchema.type !== 'object') {
@@ -70,6 +75,7 @@ export function betaZodTool<InputSchema extends ZodType>(options: {
     input_schema: objectSchema,
     description: options.description,
     run: options.run,
-    parse: (args: unknown) => options.inputSchema.parse(args) as zodInfer<InputSchema>,
+    parse: (args: unknown) => options.inputSchema.parse(args) as z.infer<InputSchema>,
+    ...(options.close ? { close: options.close } : {}),
   };
 }

package/src/helpers/zod.ts

@@ -1,5 +1,4 @@
 import { transformJSONSchema } from '../lib/transform-json-schema';
-import type { infer as zodInfer, ZodType } from 'zod';
 import * as z from 'zod/v4';
 import { AnthropicError } from '../core/error';
 import { AutoParseableOutputFormat } from '../lib/parser';
@@ -13,9 +12,9 @@ import { AutoParseableOutputFormat } from '../lib/parser';
  * This can be passed directly to the `.create()` method but will not
  * result in any automatic parsing, you'll have to parse the response yourself.
  */
-export function zodOutputFormat<ZodInput extends ZodType>(
+export function zodOutputFormat<ZodInput extends z.ZodType>(
   zodObject: ZodInput,
-): AutoParseableOutputFormat<zodInfer<ZodInput>> {
+): AutoParseableOutputFormat<z.infer<ZodInput>> {
   let jsonSchema = z.toJSONSchema(zodObject, { reused: 'ref' });
 
   jsonSchema = transformJSONSchema(jsonSchema);

package/src/internal/utils/abort.ts

@@ -0,0 +1,21 @@
+/**
+ * Chain an external {@link AbortSignal} into a local {@link AbortController}:
+ * the controller aborts whenever `external` aborts (synchronously if it is
+ * already aborted).
+ *
+ * Returns a cleanup function that detaches the listener. Callers MUST invoke it
+ * on their normal teardown path — `{ once: true }` only removes the listener if
+ * abort actually fires, so a long-lived `external` signal (e.g. a daemon-wide
+ * signal reused across many short-lived controllers) would otherwise leak one
+ * listener per controller.
+ */
+export function linkAbort(external: AbortSignal | null | undefined, controller: AbortController): () => void {
+  if (!external) return () => {};
+  if (external.aborted) {
+    controller.abort();
+    return () => {};
+  }
+  const onAbort = () => controller.abort();
+  external.addEventListener('abort', onAbort);
+  return () => external.removeEventListener('abort', onAbort);
+}

package/src/internal/utils/async-queue.ts

@@ -0,0 +1,66 @@
+export type AsyncQueueResult<T> = { done: false; value: T } | { done: true; value: undefined };
+
+/**
+ * Single-consumer async queue that bridges background producers to an
+ * `AsyncIterator`-style reader. Producers `push()` items; the consumer awaits
+ * `next()`. `close()` is idempotent and wakes any pending `next()` with
+ * `done: true`. `tryShift()` synchronously drains remaining items after
+ * iteration has been signalled to stop.
+ */
+export class AsyncQueue<T> {
+  #items: T[] = [];
+  #waiters: Array<(r: AsyncQueueResult<T>) => void> = [];
+  #closed = false;
+
+  /** Enqueue an item, or hand it directly to a waiting reader. Returns `false` once closed. */
+  push(item: T): boolean {
+    if (this.#closed) return false;
+    const w = this.#waiters.shift();
+    if (w) w({ done: false, value: item });
+    else this.#items.push(item);
+    return true;
+  }
+
+  /** Mark the queue done. Idempotent; wakes every pending reader with `done: true`. */
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    while (this.#waiters.length > 0) {
+      const w = this.#waiters.shift()!;
+      w({ done: true, value: undefined });
+    }
+  }
+
+  /**
+   * Resolve with the next item, or `done: true` once the queue is closed and
+   * drained. When `signal` is supplied, aborting it resolves a pending read
+   * with `done: true` (cancellation is pushed down here rather than handled by
+   * an outer `Promise.race`).
+   */
+  next(signal?: AbortSignal): Promise<AsyncQueueResult<T>> {
+    if (this.#items.length > 0) {
+      return Promise.resolve({ done: false, value: this.#items.shift()! });
+    }
+    if (this.#closed || signal?.aborted) {
+      return Promise.resolve({ done: true, value: undefined });
+    }
+    return new Promise<AsyncQueueResult<T>>((resolve) => {
+      const waiter = (r: AsyncQueueResult<T>) => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve(r);
+      };
+      const onAbort = () => {
+        const idx = this.#waiters.indexOf(waiter);
+        if (idx >= 0) this.#waiters.splice(idx, 1);
+        resolve({ done: true, value: undefined });
+      };
+      this.#waiters.push(waiter);
+      signal?.addEventListener('abort', onAbort, { once: true });
+    });
+  }
+
+  /** Synchronously remove and return the next buffered item, or `undefined` if empty. */
+  tryShift(): T | undefined {
+    return this.#items.shift();
+  }
+}

package/src/internal/utils/backoff.ts

@@ -0,0 +1,41 @@
+import { APIError } from '../../core/error';
+
+/** True when `e` is an {@link APIError} whose HTTP status equals `code`. */
+export function isStatus(e: unknown, code: number): boolean {
+  return e instanceof APIError && e.status === code;
+}
+
+/** True when `e` is an {@link APIError} with a 4xx status. */
+export function is4xx(e: unknown): boolean {
+  return e instanceof APIError && typeof e.status === 'number' && e.status >= 400 && e.status < 500;
+}
+
+/**
+ * True for a 4xx that the core client's retry policy would *not* retry, i.e. a
+ * permanent client error. 408 (request timeout), 409 (lock timeout) and 429
+ * (rate limit) are retryable for the base client (`Anthropic.shouldRetry`), so
+ * they are not treated as fatal here — keeping helper retry behaviour aligned
+ * with the rest of the SDK.
+ */
+export function isFatal4xx(e: unknown): boolean {
+  return is4xx(e) && !isStatus(e, 408) && !isStatus(e, 409) && !isStatus(e, 429);
+}
+
+/** Exponential backoff: `baseMs * 2 ** attempt`, clamped to `capMs`. */
+export function backoff(attempt: number, baseMs: number, capMs: number): number {
+  return Math.min(baseMs * 2 ** attempt, capMs);
+}
+
+/** Uniform random delay in the half-open interval `[lowMs, highMs)`. */
+export function jitter(lowMs: number, highMs: number): number {
+  return lowMs + Math.random() * (highMs - lowMs);
+}
+
+/**
+ * Trim up to 25% off `ms` at random so a fleet of clients backing off after a
+ * shared outage does not retry in lockstep — mirrors the jitter the core client
+ * applies to its own retry timeout.
+ */
+export function applyJitter(ms: number): number {
+  return ms * (1 - Math.random() * 0.25);
+}

package/src/internal/utils/promise.ts

@@ -0,0 +1,18 @@
+/**
+ * A deferred: a `Promise` together with its `resolve` / `reject` functions.
+ * This is `Promise.withResolvers()`, which is not available in all supported
+ * runtimes.
+ */
+export function promiseWithResolvers<T>(): {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+} {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}

package/src/internal/utils/sleep.ts

@@ -1,3 +1,26 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+/**
+ * Resolve after `ms`, or immediately when `signal` aborts.
+ *
+ * When a `signal` is passed the abort listener is always removed so repeated
+ * calls do not accumulate listeners on a long-lived signal. Resolves (rather
+ * than rejects) on abort — callers treat abort as "wake up early," not as a
+ * failure; callers that want to unwind should check the signal themselves.
+ */
+export const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+  new Promise<void>((resolve) => {
+    if (signal?.aborted) return resolve();
 
-export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+
+    // `{ once: true }` auto-removes the listener if abort fires first,
+    // so we only need an explicit remove on the timer-wins path above.
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });

package/src/lib/environments/index.ts

@@ -0,0 +1,23 @@
+export {
+  WorkPoller,
+  type WorkPollerOptions,
+  POLL_BLOCK_MS,
+  backoff,
+  jitter,
+  isStatus,
+  is4xx,
+  isFatal4xx,
+} from './poller';
+export {
+  EnvironmentWorker,
+  type EnvironmentWorkerOptions,
+  type EnvironmentWorkerTools,
+  type HandleItemOptions,
+} from './worker';
+export {
+  SessionToolRunner,
+  type SessionToolRunnerOptions,
+  type DispatchedToolCall,
+  MANAGED_AGENTS_BETA,
+  DEFAULT_MAX_IDLE_MS,
+} from '../tools/SessionToolRunner';

package/src/lib/environments/poller.ts

@@ -0,0 +1,253 @@
+import { AnthropicError } from '../../core/error';
+import type { Anthropic } from '../../client';
+import type { BetaSelfHostedWork } from '../../resources/beta/environments/work';
+import { loggerFor } from '../../internal/utils/log';
+import { sleep } from '../../internal/utils/sleep';
+import { uuid4 } from '../../internal/utils/uuid';
+import { linkAbort } from '../../internal/utils/abort';
+import { buildHeaders } from '../../internal/headers';
+import type { BetaToolRunnerRequestOptions } from '../tools/BetaToolRunner';
+import {
+  applyJitter,
+  backoff as expBackoff,
+  isFatal4xx,
+  isStatus,
+  jitter,
+} from '../../internal/utils/backoff';
+import { copyClientForHelper } from '../helper-client';
+
+export { is4xx, isFatal4xx, isStatus, jitter } from '../../internal/utils/backoff';
+
+// API caps block_ms at 999; rely on client-side jitter between empty polls.
+export const POLL_BLOCK_MS = 999;
+const POLL_BACKOFF_BASE_MS = 1000;
+const POLL_BACKOFF_CAP_MS = 60_000;
+
+export interface WorkPollerOptions {
+  client: Anthropic;
+  environmentId: string;
+  /**
+   * The environment key — the single credential for the self-hosted runner. It
+   * authenticates the work-poll calls here and every per-session call the
+   * consumer makes afterwards.
+   */
+  environmentKey: string;
+  workerId?: string;
+  /** External abort signal. Aborting it ends the iteration. */
+  signal?: AbortSignal;
+  /**
+   * Whether the poller posts `work.stop` itself after the consumer's loop body
+   * returns. Defaults to `true`. Set `false` when the consumer already owns the
+   * stop (e.g. {@link EnvironmentWorker} force-stops every item) so the work
+   * item is not stopped twice.
+   *
+   * Orthogonal to {@link WorkPollerOptions.drain}: `autoStop` is a per-item
+   * lifecycle flag (does the poller `work.stop` each item), `drain` controls
+   * loop termination (does the poller return when the queue is empty). They are
+   * not two names for the same thing — `EnvironmentWorker.run` uses
+   * `autoStop: false` with `drain` defaulting `false`.
+   */
+  autoStop?: boolean;
+  /**
+   * When `true`, the poller returns (ends iteration) as soon as the work queue
+   * is empty instead of long-polling forever. Defaults to `false` (long-poll
+   * until aborted). Pair with `blockMs: null` for a single non-blocking pass
+   * over whatever is already queued.
+   */
+  drain?: boolean;
+  /**
+   * Block timeout in milliseconds passed through to `work.poll` — the server
+   * long-polls up to this long for an item before returning empty. Defaults to
+   * {@link POLL_BLOCK_MS} (the API cap, 999). Pass `null` to omit it entirely
+   * for a non-blocking single poll (useful with {@link WorkPollerOptions.drain}).
+   */
+  blockMs?: number | null;
+  /**
+   * Reclaim unacknowledged work items older than this many milliseconds, passed
+   * through to `work.poll`'s `reclaim_older_than_ms`. Defaults to `undefined`
+   * (omitted — the server applies its own default).
+   */
+  reclaimOlderThanMs?: number | null;
+  /**
+   * Extra per-request options merged into the poll/ack/stop calls. Custom
+   * `headers` (e.g. a proxy's auth/routing headers) are layered on top of the
+   * environment-key auth + helper telemetry headers; the poller owns the abort
+   * signal, so a `signal` here is ignored.
+   */
+  requestOptions?: BetaToolRunnerRequestOptions;
+}
+
+/**
+ * Async-iterable that long-polls a self-hosted environment for work, ack's
+ * each item, yields the {@link BetaSelfHostedWork} item, and posts `stop` after
+ * the consumer's loop body returns (or when the consumer `break`s).
+ *
+ * @example
+ * ```ts
+ * for await (const work of client.beta.environments.work.poller({
+ *   environmentId,
+ *   environmentKey,
+ * })) {
+ *   // ...service the work...
+ * }
+ * ```
+ */
+export class WorkPoller implements AsyncIterable<BetaSelfHostedWork> {
+  readonly client: Anthropic;
+  readonly environmentId: string;
+  readonly environmentKey: string;
+  readonly workerId: string;
+
+  // Sub-client scoped to the environment key. Every poll / ack / stop call
+  // is routed through this so the parent's `X-Api-Key` never lands on the
+  // wire alongside the bearer credential. The helper-telemetry header is
+  // attached as a default on this client; per-call plumbing is unnecessary.
+  readonly #runnerClient: Anthropic;
+  #consumed = false;
+  readonly #controller: AbortController;
+  readonly #detachExternal: () => void;
+  readonly #autoStop: boolean;
+  readonly #drain: boolean;
+  readonly #blockMs: number | null;
+  readonly #reclaimOlderThanMs: number | null;
+  readonly #requestOpts: BetaToolRunnerRequestOptions | undefined;
+
+  constructor(opts: WorkPollerOptions) {
+    this.client = opts.client;
+    this.environmentId = opts.environmentId;
+    this.environmentKey = opts.environmentKey;
+    this.workerId = opts.workerId ?? defaultWorkerId();
+    this.#runnerClient = copyClientForHelper(opts.client, {
+      authToken: opts.environmentKey,
+      helper: 'environments-work-poller',
+    });
+    this.#autoStop = opts.autoStop ?? true;
+    this.#drain = opts.drain ?? false;
+    // `undefined` => default to the API cap; an explicit `null` => omit
+    // `block_ms` for a non-blocking poll.
+    this.#blockMs = opts.blockMs === undefined ? POLL_BLOCK_MS : opts.blockMs;
+    this.#reclaimOlderThanMs = opts.reclaimOlderThanMs ?? null;
+    this.#requestOpts = opts.requestOptions;
+    this.#controller = new AbortController();
+    this.#detachExternal = linkAbort(opts.signal, this.#controller);
+  }
+
+  /** Read-only view of this iterator's abort signal. */
+  get signal(): AbortSignal {
+    return this.#controller.signal;
+  }
+
+  /** Abort the iterator. The current `for await` will exit cleanly. */
+  abort(): void {
+    this.#controller.abort();
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<BetaSelfHostedWork> {
+    if (this.#consumed) {
+      throw new AnthropicError('Cannot iterate over a consumed WorkPoller');
+    }
+    this.#consumed = true;
+    const log = loggerFor(this.client);
+    log.info('poller starting', {
+      component: 'work-poller',
+      environment_id: this.environmentId,
+    });
+
+    try {
+      let attempt = 0;
+      while (!this.#controller.signal.aborted) {
+        let work: BetaSelfHostedWork | null;
+        try {
+          work = await this.#runnerClient.beta.environments.work.poll(
+            this.environmentId,
+            {
+              'Anthropic-Worker-ID': this.workerId,
+              ...(this.#blockMs !== null ? { block_ms: this.#blockMs } : {}),
+              ...(this.#reclaimOlderThanMs !== null ?
+                { reclaim_older_than_ms: this.#reclaimOlderThanMs }
+              : {}),
+            },
+            { headers: buildHeaders([this.#requestOpts?.headers]), signal: this.#controller.signal },
+          );
+        } catch (e) {
+          if (this.#controller.signal.aborted) return;
+          // A bad environment key / missing environment never recovers — surface
+          // it instead of spinning forever at the backoff cap.
+          if (isFatal4xx(e)) {
+            log.error('poll failed permanently, stopping poller', { error: String(e) });
+            throw e;
+          }
+          // Jittered exponential backoff so a fleet of pollers doesn't retry in
+          // lockstep after a shared outage.
+          const wait = applyJitter(backoff(attempt));
+          log.warn('poll failed, backing off', { error: String(e), backoff_ms: wait });
+          attempt++;
+          await sleep(wait, this.#controller.signal);
+          continue;
+        }
+        attempt = 0;
+        if (work == null) {
+          // Queue empty: either return now (drain) or wait and poll again.
+          if (this.#drain) return;
+          await sleep(jitter(1000, 3000), this.#controller.signal);
+          continue;
+        }
+        log.info('claimed work', {
+          component: 'work-poller',
+          environment_id: this.environmentId,
+          work_id: work.id,
+          work_type: work.data.type,
+        });
+
+        try {
+          await this.#runnerClient.beta.environments.work.ack(
+            work.id,
+            { environment_id: work.environment_id },
+            { headers: buildHeaders([this.#requestOpts?.headers]), signal: this.#controller.signal },
+          );
+        } catch (e) {
+          log.error('ack failed', { work_id: work.id, error: String(e) });
+          continue;
+        }
+
+        try {
+          yield work;
+        } finally {
+          // Post-handler stop. Runs whether the consumer body returned
+          // normally, threw, or `break`d out of the loop — unless the consumer
+          // owns the stop itself (`autoStop: false`).
+          if (this.#autoStop) {
+            try {
+              await this.#runnerClient.beta.environments.work.stop(
+                work.id,
+                { environment_id: work.environment_id },
+                { headers: buildHeaders([this.#requestOpts?.headers]) },
+              );
+            } catch (e) {
+              if (!isStatus(e, 409)) log.warn('stop failed', { work_id: work.id, error: String(e) });
+            }
+          }
+        }
+      }
+    } finally {
+      // Detach from the external signal so the consumer can drop their
+      // signal reference without leaking this iterator instance.
+      this.#detachExternal();
+    }
+  }
+}
+
+/** Exponential poll backoff: 1s, 2s, 4s … clamped to a 60s cap. */
+export function backoff(attempt: number): number {
+  return expBackoff(attempt, POLL_BACKOFF_BASE_MS, POLL_BACKOFF_CAP_MS);
+}
+
+function defaultWorkerId(): string {
+  // The API documents the worker id as a *unique* identifier for Redis consumer
+  // groups, so the fallback must be unique even when several pollers share a
+  // host. Prefix with the hostname when one is exposed for readability, but rely
+  // on the uuid for uniqueness.
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+  const host = env?.['HOSTNAME'];
+  return host ? `${host}-${uuid4()}` : uuid4();
+}