@tetral-ai/sdk 0.110.0-alpha.1

package/lib/environments/worker.mjs

@@ -0,0 +1,267 @@
+var _EnvironmentWorker_instances, _EnvironmentWorker_signal, _EnvironmentWorker_handleItem;
+import { __classPrivateFieldGet, __classPrivateFieldSet } from "../../internal/tslib.mjs";
+import { AnthropicError } from "../../core/error.mjs";
+import { loggerFor } from "../../internal/utils/log.mjs";
+import { readEnv } from "../../internal/utils/env.mjs";
+import { sleep } from "../../internal/utils/sleep.mjs";
+import { isFatal4xx, isStatus } from "../../internal/utils/backoff.mjs";
+import { linkAbort } from "../../internal/utils/abort.mjs";
+import { buildHeaders } from "../../internal/headers.mjs";
+import { SessionToolRunner } from "../tools/SessionToolRunner.mjs";
+import { WorkPoller } from "./poller.mjs";
+import { copyClientForHelper } from "../helper-client.mjs";
+const HEARTBEAT_DEFAULT_MS = 30000;
+const NO_HEARTBEAT_SENTINEL = 'NO_HEARTBEAT';
+/**
+ * The self-hosted environment runner, composed from the control-plane
+ * {@link WorkPoller} and the per-session {@link SessionToolRunner}.
+ *
+ * For each claimed `session` work item it: builds the per-session
+ * {@link AgentToolContext}, downloads the session agent's skills
+ * (`setupSkills`), then runs a {@link SessionToolRunner} for the session
+ * *while* heartbeating the work-item lease in parallel; on exit it force-stops
+ * the work item, cleans up the downloaded skills, and loops to the next one. The
+ * lease heartbeat reports `state === "stopping"` / a lost lease back into the run
+ * by aborting the session runner.
+ *
+ * Use {@link EnvironmentWorker.handleItem} if you already hold a claimed work
+ * item (e.g. a `worker poll --on-work` script handed one to a fresh process) and
+ * just want the per-item flow without the poll loop — with no arguments it reads
+ * the `ANTHROPIC_*` env vars that command sets.
+ *
+ * Construct it via `client.beta.environments.work.worker({ ... })` (or
+ * `new EnvironmentWorker({ client, ... })` directly).
+ *
+ * Retained self-hosted compatibility helper. Tetral Cloud-hosted Environments
+ * do not use the work queue in this stage; generated work API calls remain
+ * normal request paths and Tetral backend admission rejects them fail-closed.
+ *
+ * @example
+ * ```ts
+ * // Long-running daemon: poll for work, serve each session, loop.
+ * await client.beta.environments.work
+ *   .worker({ environmentId, environmentKey, workdir: '/workspace' })
+ *   .run(AbortSignal.timeout(60 * 60_000));
+ *
+ * // Already-claimed item (e.g. inside `ant worker poll --on-work ...`):
+ * await client.beta.environments.work.worker({ workdir: '/workspace' }).handleItem();
+ * ```
+ */
+export class EnvironmentWorker {
+    constructor(opts) {
+        _EnvironmentWorker_instances.add(this);
+        _EnvironmentWorker_signal.set(this, void 0);
+        this.client = opts.client;
+        this.environmentId = opts.environmentId;
+        this.environmentKey = opts.environmentKey;
+        this.tools = opts.tools;
+        this.workdir = opts.workdir ?? process.cwd();
+        this.unrestrictedPaths = opts.unrestrictedPaths;
+        this.maxFileBytes = opts.maxFileBytes;
+        this.maxIdleMs = opts.maxIdleMs;
+        this.workerId = opts.workerId;
+        this.requestOptions = opts.requestOptions;
+        __classPrivateFieldSet(this, _EnvironmentWorker_signal, opts.signal, "f");
+    }
+    /**
+     * Poll the environment and service each claimed session until the supplied
+     * signal (or the one passed to the constructor) aborts. Throws if
+     * `environmentId` / `environmentKey` were not provided to the constructor.
+     */
+    async run(signal) {
+        const { environmentId, environmentKey } = this;
+        if (environmentId === undefined || environmentKey === undefined) {
+            throw new AnthropicError('EnvironmentWorker.run: environmentId and environmentKey are required to poll for work');
+        }
+        const externalSignal = signal ?? __classPrivateFieldGet(this, _EnvironmentWorker_signal, "f");
+        const poller = new WorkPoller({
+            client: this.client,
+            environmentId,
+            environmentKey,
+            ...(this.workerId !== undefined ? { workerId: this.workerId } : {}),
+            ...(externalSignal ? { signal: externalSignal } : {}),
+            ...(this.requestOptions !== undefined ? { requestOptions: this.requestOptions } : {}),
+            // The per-item handler force-stops every work item on exit; let it be the
+            // single owner of `work.stop` rather than double-posting from the poller.
+            autoStop: false,
+        });
+        for await (const work of poller) {
+            await __classPrivateFieldGet(this, _EnvironmentWorker_instances, "m", _EnvironmentWorker_handleItem).call(this, work, environmentKey, poller.signal);
+        }
+    }
+    /**
+     * Service a single, already-claimed work item without the poll loop: build the
+     * per-session {@link AgentToolContext} (workdir from this worker's options),
+     * download the session agent's skills (`setupSkills`), run a
+     * {@link SessionToolRunner} for the session while heartbeating the work-item
+     * lease in parallel, and force-stop the work item on exit (whether the runner
+     * finishes normally, throws, or the heartbeat loop signals shutdown).
+     *
+     * Use this when something else does the claiming — e.g. a `worker poll
+     * --on-work` script that hands an already-claimed item to a fresh process. The
+     * work id / environment id / session id each fall back to `ANTHROPIC_WORK_ID` /
+     * `ANTHROPIC_ENVIRONMENT_ID` / `ANTHROPIC_SESSION_ID` (the env vars that
+     * command sets) when not passed; the environment key resolves from this
+     * option, then the worker's own `environmentKey`, then
+     * `ANTHROPIC_ENVIRONMENT_KEY`. With no arguments inside that command it just
+     * works. Throws a clear error naming the first of the four required values
+     * still missing after resolution.
+     */
+    async handleItem(opts) {
+        const workId = opts?.workId ?? readEnv('ANTHROPIC_WORK_ID');
+        const environmentId = opts?.environmentId ?? readEnv('ANTHROPIC_ENVIRONMENT_ID');
+        const sessionId = opts?.sessionId ?? readEnv('ANTHROPIC_SESSION_ID');
+        const environmentKey = opts?.environmentKey ?? this.environmentKey ?? readEnv('ANTHROPIC_ENVIRONMENT_KEY');
+        if (!workId) {
+            throw new AnthropicError('handleItem: workId is required — pass it or set ANTHROPIC_WORK_ID');
+        }
+        if (!environmentId) {
+            throw new AnthropicError('handleItem: environmentId is required — pass it or set ANTHROPIC_ENVIRONMENT_ID');
+        }
+        if (!sessionId) {
+            throw new AnthropicError('handleItem: sessionId is required — pass it or set ANTHROPIC_SESSION_ID');
+        }
+        if (!environmentKey) {
+            throw new AnthropicError('handleItem: environmentKey is required — pass it, construct the worker with it, or set ANTHROPIC_ENVIRONMENT_KEY');
+        }
+        const work = {
+            id: workId,
+            environment_id: environmentId,
+            data: { type: 'session', id: sessionId },
+        };
+        await __classPrivateFieldGet(this, _EnvironmentWorker_instances, "m", _EnvironmentWorker_handleItem).call(this, work, environmentKey, opts?.signal ?? __classPrivateFieldGet(this, _EnvironmentWorker_signal, "f"));
+    }
+}
+_EnvironmentWorker_signal = new WeakMap(), _EnvironmentWorker_instances = new WeakSet(), _EnvironmentWorker_handleItem = 
+/**
+ * The per-item body shared by {@link EnvironmentWorker.run}'s poll loop and
+ * {@link EnvironmentWorker.handleItem}: run a {@link SessionToolRunner} for the
+ * work item's session while heartbeating its lease, force-stopping on exit.
+ * Non-session work items are ignored.
+ */
+async function _EnvironmentWorker_handleItem(work, environmentKey, externalSignal) {
+    const log = loggerFor(this.client);
+    // Every per-session call — the SessionToolRunner event stream/list/send, the
+    // lease heartbeat, and the work force-stop — authenticates with the
+    // environment key. Scope a client to it once and thread that through.
+    // `copyClientForHelper` also clears the parent's `apiKey`, so the sub-client
+    // emits *only* the bearer credential on the wire (a plain
+    // `withOptions({authToken})` would leave `X-Api-Key` set as well).
+    const sessionClient = copyClientForHelper(this.client, {
+        authToken: environmentKey,
+        helper: 'environments-worker',
+    });
+    // The poller runs with `autoStop: false`, so the per-item handler is the
+    // single owner of `work.stop` for every claimed item.
+    const sessionId = work.data.id;
+    const ctx = {
+        workdir: this.workdir,
+        client: this.client,
+        sessionId,
+        ...(this.unrestrictedPaths !== undefined ? { unrestrictedPaths: this.unrestrictedPaths } : {}),
+        ...(this.maxFileBytes !== undefined ? { maxFileBytes: this.maxFileBytes } : {}),
+    };
+    // Lazily load the Node-only toolset module — see the import note at the top.
+    const agentToolset = await import("../../tools/agent-toolset/node.mjs");
+    let cleanupSkills = async () => { };
+    try {
+        cleanupSkills = await agentToolset.setupSkills(ctx);
+    }
+    catch (e) {
+        log.warn('skill setup failed', { session_id: sessionId, work_id: work.id, error: String(e) });
+    }
+    const tools = typeof this.tools === 'function' ?
+        this.tools(ctx)
+        : this.tools ?? agentToolset.betaAgentToolset20260401(ctx);
+    // A per-session controller: aborts when the supplied signal aborts, when the
+    // session runner finishes, or when the lease heartbeat says to stop.
+    const ctrl = new AbortController();
+    const detachExternal = linkAbort(externalSignal, ctrl);
+    const heartbeatPromise = heartbeatLoop(sessionClient, work, ctrl, log, this.requestOptions).catch((e) => {
+        if (!ctrl.signal.aborted)
+            log.error('heartbeat loop failed', { work_id: work.id, error: String(e) });
+        ctrl.abort();
+    });
+    try {
+        const runner = new SessionToolRunner(sessionId, {
+            client: sessionClient,
+            tools,
+            ...(this.maxIdleMs !== undefined ? { maxIdleMs: this.maxIdleMs } : {}),
+            ...(this.requestOptions !== undefined ? { requestOptions: this.requestOptions } : {}),
+            signal: ctrl.signal,
+        });
+        for await (const _ of runner) {
+            // Drive the runner to completion; per-call observability is not part
+            // of this composition's surface — use `SessionToolRunner` directly
+            // (via `client.beta.sessions.events.toolRunner`) if you want it.
+        }
+    }
+    finally {
+        ctrl.abort();
+        detachExternal();
+        await heartbeatPromise;
+        await cleanupSkills().catch((e) => {
+            log.warn('skill cleanup failed', { session_id: sessionId, work_id: work.id, error: String(e) });
+        });
+        await forceStop(sessionClient, work, log, this.requestOptions);
+    }
+};
+/** Force-stop a claimed work item, swallowing the 409 that means it's already stopped. */
+async function forceStop(client, work, log, requestOptions) {
+    try {
+        await client.beta.environments.work.stop(work.id, { environment_id: work.environment_id, force: true }, 
+        // Caller's headers pass through; the helper-tag header is on the scoped
+        // sub-client's default_headers via copyClientForHelper, so no per-call
+        // re-stamping needed.
+        { ...requestOptions, headers: buildHeaders([requestOptions?.headers]) });
+    }
+    catch (e) {
+        if (!isStatus(e, 409)) {
+            log.error('force-stop on exit failed', { work_id: work.id, error: String(e) });
+        }
+    }
+}
+/**
+ * Keep the work-item lease alive while a session is being served. Aborts `ctrl`
+ * when the control plane reports the work is `stopping`/`stopped`, when the
+ * lease is no longer extended, or on a permanent heartbeat failure.
+ */
+async function heartbeatLoop(client, work, ctrl, logger, requestOptions) {
+    let intervalMs = HEARTBEAT_DEFAULT_MS;
+    let last = NO_HEARTBEAT_SENTINEL;
+    const beat = async () => {
+        try {
+            const resp = await client.beta.environments.work.heartbeat(work.id, { environment_id: work.environment_id, expected_last_heartbeat: last }, { ...requestOptions, headers: buildHeaders([requestOptions?.headers]), signal: ctrl.signal });
+            last = resp.last_heartbeat;
+            if (resp.ttl_seconds > 0) {
+                intervalMs = Math.max(1000, Math.min((resp.ttl_seconds * 1000) / 2, HEARTBEAT_DEFAULT_MS));
+            }
+            if (resp.state === 'stopping' || resp.state === 'stopped') {
+                logger.info('heartbeat signals shutdown', { work_id: work.id, state: resp.state });
+                ctrl.abort();
+            }
+            if (!resp.lease_extended) {
+                logger.warn('lease not extended, shutting down', { work_id: work.id });
+                ctrl.abort();
+            }
+        }
+        catch (e) {
+            // An abort throws to unwind the caller (the `heartbeatLoop(...).catch`
+            // in `#handleItem`) rather than returning early.
+            ctrl.signal.throwIfAborted();
+            if (isFatal4xx(e)) {
+                logger.error('permanent heartbeat failure', { work_id: work.id, error: String(e) });
+                ctrl.abort();
+                throw e;
+            }
+            logger.warn('transient heartbeat failure', { work_id: work.id, error: String(e) });
+        }
+    };
+    await beat();
+    while (!ctrl.signal.aborted) {
+        await sleep(intervalMs, ctrl.signal);
+        ctrl.signal.throwIfAborted();
+        await beat();
+    }
+}
+//# sourceMappingURL=worker.mjs.map

package/lib/environments/worker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.mjs","sourceRoot":"","sources":["../../src/lib/environments/worker.ts"],"names":[],"mappings":"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"}

package/lib/helper-client.d.mts

@@ -0,0 +1,34 @@
+import type { Anthropic } from "../client.mjs";
+import { type StainlessHelperHeaderValue } from "../internal/stainless-helper-header.mjs";
+/**
+ * Return a `withOptions()` clone of `client` set up for use *by* one of the
+ * runner helpers: authenticated with `authToken` as Bearer credentials, with
+ * the parent's `X-Api-Key` cleared, and tagged with the helper's
+ * `x-stainless-helper` value on every outgoing request.
+ *
+ * The returned sub-client inherits the parent's full configuration
+ * (`baseURL`, `timeout`, `maxRetries`, `fetch`, `fetchOptions`, custom
+ * `defaultHeaders`, `defaultQuery`). Overrides applied:
+ *
+ * - `authToken: authToken` — the new credential.
+ * - `apiKey: null` — the parent's `X-Api-Key` is cleared. `withOptions`
+ *   inherits the parent's `apiKey` by default; without this, both
+ *   `X-Api-Key` *and* `Authorization: Bearer …` would land on the wire.
+ *   `client.ts` only triggers the env-var fallback when `apiKey === undefined`,
+ *   so explicit `null` is honored.
+ * - `credentials: undefined` — opts the clone out of any inherited
+ *   credentials/config/profile so the explicit bearer is the unambiguous auth.
+ * - `baseURL: client.baseURL` — pins the parent's resolved host (auth override otherwise resets it).
+ * - `defaultHeaders` is rebuilt as `safe(parent._authState.extraHeaders) ⊕
+ *   safe(parent.defaultHeaders) ⊕ {'x-stainless-helper': helper}`. Auth
+ *   headers are stripped from inherited header sources because the helper's
+ *   bearer token is the only auth that should reach the helper request.
+ *   `withOptions` *replaces* (does not merge) `defaultHeaders`, so we merge
+ *   here so any non-auth custom headers the caller set on the parent client
+ *   survive on the sub-client.
+ */
+export declare function copyClientForHelper<T extends Anthropic>(client: T, { authToken, helper }: {
+    authToken: string;
+    helper: StainlessHelperHeaderValue;
+}): T;
+//# sourceMappingURL=helper-client.d.mts.map

package/lib/helper-client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-client.d.mts","sourceRoot":"","sources":["../src/lib/helper-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAkB;AAE3C,OAAO,EAEL,KAAK,0BAA0B,EAChC,gDAA4C;AA4C7C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,SAAS,EACrD,MAAM,EAAE,CAAC,EACT,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,GAC/E,CAAC,CAqBH"}

package/lib/helper-client.d.ts

@@ -0,0 +1,34 @@
+import type { Anthropic } from "../client.js";
+import { type StainlessHelperHeaderValue } from "../internal/stainless-helper-header.js";
+/**
+ * Return a `withOptions()` clone of `client` set up for use *by* one of the
+ * runner helpers: authenticated with `authToken` as Bearer credentials, with
+ * the parent's `X-Api-Key` cleared, and tagged with the helper's
+ * `x-stainless-helper` value on every outgoing request.
+ *
+ * The returned sub-client inherits the parent's full configuration
+ * (`baseURL`, `timeout`, `maxRetries`, `fetch`, `fetchOptions`, custom
+ * `defaultHeaders`, `defaultQuery`). Overrides applied:
+ *
+ * - `authToken: authToken` — the new credential.
+ * - `apiKey: null` — the parent's `X-Api-Key` is cleared. `withOptions`
+ *   inherits the parent's `apiKey` by default; without this, both
+ *   `X-Api-Key` *and* `Authorization: Bearer …` would land on the wire.
+ *   `client.ts` only triggers the env-var fallback when `apiKey === undefined`,
+ *   so explicit `null` is honored.
+ * - `credentials: undefined` — opts the clone out of any inherited
+ *   credentials/config/profile so the explicit bearer is the unambiguous auth.
+ * - `baseURL: client.baseURL` — pins the parent's resolved host (auth override otherwise resets it).
+ * - `defaultHeaders` is rebuilt as `safe(parent._authState.extraHeaders) ⊕
+ *   safe(parent.defaultHeaders) ⊕ {'x-stainless-helper': helper}`. Auth
+ *   headers are stripped from inherited header sources because the helper's
+ *   bearer token is the only auth that should reach the helper request.
+ *   `withOptions` *replaces* (does not merge) `defaultHeaders`, so we merge
+ *   here so any non-auth custom headers the caller set on the parent client
+ *   survive on the sub-client.
+ */
+export declare function copyClientForHelper<T extends Anthropic>(client: T, { authToken, helper }: {
+    authToken: string;
+    helper: StainlessHelperHeaderValue;
+}): T;
+//# sourceMappingURL=helper-client.d.ts.map

package/lib/helper-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-client.d.ts","sourceRoot":"","sources":["../src/lib/helper-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAkB;AAE3C,OAAO,EAEL,KAAK,0BAA0B,EAChC,+CAA4C;AA4C7C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,SAAS,EACrD,MAAM,EAAE,CAAC,EACT,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,GAC/E,CAAC,CAqBH"}

package/lib/helper-client.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyClientForHelper = copyClientForHelper;
+const error_1 = require("../core/error.js");
+const headers_1 = require("../internal/headers.js");
+const stainless_helper_header_1 = require("../internal/stainless-helper-header.js");
+const HELPER_AUTH_HEADER_NAMES = new Set(['authorization', 'x-api-key']);
+function stripAuthHeaders(headers) {
+    if (!headers)
+        return undefined;
+    const parsed = (0, headers_1.buildHeaders)([headers]);
+    const safeValues = new Headers();
+    for (const [name, value] of parsed.values.entries()) {
+        if (!HELPER_AUTH_HEADER_NAMES.has(name.toLowerCase())) {
+            safeValues.append(name, value);
+        }
+    }
+    const safeNulls = {};
+    for (const name of parsed.nulls) {
+        if (!HELPER_AUTH_HEADER_NAMES.has(name.toLowerCase())) {
+            safeNulls[name] = null;
+        }
+    }
+    return (0, headers_1.buildHeaders)([safeValues, safeNulls]);
+}
+/**
+ * Return a `withOptions()` clone of `client` set up for use *by* one of the
+ * runner helpers: authenticated with `authToken` as Bearer credentials, with
+ * the parent's `X-Api-Key` cleared, and tagged with the helper's
+ * `x-stainless-helper` value on every outgoing request.
+ *
+ * The returned sub-client inherits the parent's full configuration
+ * (`baseURL`, `timeout`, `maxRetries`, `fetch`, `fetchOptions`, custom
+ * `defaultHeaders`, `defaultQuery`). Overrides applied:
+ *
+ * - `authToken: authToken` — the new credential.
+ * - `apiKey: null` — the parent's `X-Api-Key` is cleared. `withOptions`
+ *   inherits the parent's `apiKey` by default; without this, both
+ *   `X-Api-Key` *and* `Authorization: Bearer …` would land on the wire.
+ *   `client.ts` only triggers the env-var fallback when `apiKey === undefined`,
+ *   so explicit `null` is honored.
+ * - `credentials: undefined` — opts the clone out of any inherited
+ *   credentials/config/profile so the explicit bearer is the unambiguous auth.
+ * - `baseURL: client.baseURL` — pins the parent's resolved host (auth override otherwise resets it).
+ * - `defaultHeaders` is rebuilt as `safe(parent._authState.extraHeaders) ⊕
+ *   safe(parent.defaultHeaders) ⊕ {'x-stainless-helper': helper}`. Auth
+ *   headers are stripped from inherited header sources because the helper's
+ *   bearer token is the only auth that should reach the helper request.
+ *   `withOptions` *replaces* (does not merge) `defaultHeaders`, so we merge
+ *   here so any non-auth custom headers the caller set on the parent client
+ *   survive on the sub-client.
+ */
+function copyClientForHelper(client, { authToken, helper }) {
+    if (!authToken) {
+        throw new error_1.AnthropicError(`copyClientForHelper: expected a non-empty authToken but received ${JSON.stringify(authToken)}`);
+    }
+    const internal = client;
+    const parentDefaults = stripAuthHeaders(internal._options.defaultHeaders);
+    const parentAuthExtraHeaders = stripAuthHeaders(internal._authState?.extraHeaders);
+    const defaultHeaders = (0, headers_1.buildHeaders)([
+        parentAuthExtraHeaders,
+        parentDefaults,
+        { [stainless_helper_header_1.STAINLESS_HELPER_HEADER]: helper },
+    ]);
+    return client.withOptions({
+        apiKey: null,
+        authToken,
+        baseURL: client.baseURL,
+        credentials: undefined,
+        defaultHeaders,
+    });
+}
+//# sourceMappingURL=helper-client.js.map

package/lib/helper-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-client.js","sourceRoot":"","sources":["../src/lib/helper-client.ts"],"names":[],"mappings":";;AA6EA,kDAwBC;AArGD,4CAA+C;AAE/C,oDAA2F;AAC3F,oFAG6C;AAqB7C,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,CAAC;AAEzE,SAAS,gBAAgB,CAAC,OAAoB;IAC5C,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAE/B,MAAM,MAAM,GAAG,IAAA,sBAAY,EAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,OAAO,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACtD,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAyB,EAAE,CAAC;IAC3C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACtD,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO,IAAA,sBAAY,EAAC,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,mBAAmB,CACjC,MAAS,EACT,EAAE,SAAS,EAAE,MAAM,EAA6D;IAEhF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,sBAAc,CACtB,oEAAoE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAChG,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAyC,CAAC;IAC3D,MAAM,cAAc,GAAG,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC1E,MAAM,sBAAsB,GAAG,gBAAgB,CAAC,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACnF,MAAM,cAAc,GAAoB,IAAA,sBAAY,EAAC;QACnD,sBAAsB;QACtB,cAAc;QACd,EAAE,CAAC,iDAAuB,CAAC,EAAE,MAAM,EAAE;KACtC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,WAAW,CAAC;QACxB,MAAM,EAAE,IAAI;QACZ,SAAS;QACT,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,SAAS;QACtB,cAAc;KACf,CAAM,CAAC;AACV,CAAC"}

package/lib/helper-client.mjs

@@ -0,0 +1,70 @@
+import { AnthropicError } from "../core/error.mjs";
+import { buildHeaders } from "../internal/headers.mjs";
+import { STAINLESS_HELPER_HEADER, } from "../internal/stainless-helper-header.mjs";
+const HELPER_AUTH_HEADER_NAMES = new Set(['authorization', 'x-api-key']);
+function stripAuthHeaders(headers) {
+    if (!headers)
+        return undefined;
+    const parsed = buildHeaders([headers]);
+    const safeValues = new Headers();
+    for (const [name, value] of parsed.values.entries()) {
+        if (!HELPER_AUTH_HEADER_NAMES.has(name.toLowerCase())) {
+            safeValues.append(name, value);
+        }
+    }
+    const safeNulls = {};
+    for (const name of parsed.nulls) {
+        if (!HELPER_AUTH_HEADER_NAMES.has(name.toLowerCase())) {
+            safeNulls[name] = null;
+        }
+    }
+    return buildHeaders([safeValues, safeNulls]);
+}
+/**
+ * Return a `withOptions()` clone of `client` set up for use *by* one of the
+ * runner helpers: authenticated with `authToken` as Bearer credentials, with
+ * the parent's `X-Api-Key` cleared, and tagged with the helper's
+ * `x-stainless-helper` value on every outgoing request.
+ *
+ * The returned sub-client inherits the parent's full configuration
+ * (`baseURL`, `timeout`, `maxRetries`, `fetch`, `fetchOptions`, custom
+ * `defaultHeaders`, `defaultQuery`). Overrides applied:
+ *
+ * - `authToken: authToken` — the new credential.
+ * - `apiKey: null` — the parent's `X-Api-Key` is cleared. `withOptions`
+ *   inherits the parent's `apiKey` by default; without this, both
+ *   `X-Api-Key` *and* `Authorization: Bearer …` would land on the wire.
+ *   `client.ts` only triggers the env-var fallback when `apiKey === undefined`,
+ *   so explicit `null` is honored.
+ * - `credentials: undefined` — opts the clone out of any inherited
+ *   credentials/config/profile so the explicit bearer is the unambiguous auth.
+ * - `baseURL: client.baseURL` — pins the parent's resolved host (auth override otherwise resets it).
+ * - `defaultHeaders` is rebuilt as `safe(parent._authState.extraHeaders) ⊕
+ *   safe(parent.defaultHeaders) ⊕ {'x-stainless-helper': helper}`. Auth
+ *   headers are stripped from inherited header sources because the helper's
+ *   bearer token is the only auth that should reach the helper request.
+ *   `withOptions` *replaces* (does not merge) `defaultHeaders`, so we merge
+ *   here so any non-auth custom headers the caller set on the parent client
+ *   survive on the sub-client.
+ */
+export function copyClientForHelper(client, { authToken, helper }) {
+    if (!authToken) {
+        throw new AnthropicError(`copyClientForHelper: expected a non-empty authToken but received ${JSON.stringify(authToken)}`);
+    }
+    const internal = client;
+    const parentDefaults = stripAuthHeaders(internal._options.defaultHeaders);
+    const parentAuthExtraHeaders = stripAuthHeaders(internal._authState?.extraHeaders);
+    const defaultHeaders = buildHeaders([
+        parentAuthExtraHeaders,
+        parentDefaults,
+        { [STAINLESS_HELPER_HEADER]: helper },
+    ]);
+    return client.withOptions({
+        apiKey: null,
+        authToken,
+        baseURL: client.baseURL,
+        credentials: undefined,
+        defaultHeaders,
+    });
+}
+//# sourceMappingURL=helper-client.mjs.map

package/lib/helper-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-client.mjs","sourceRoot":"","sources":["../src/lib/helper-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,0BAAsB;AAE/C,OAAO,EAAE,YAAY,EAA0C,gCAA4B;AAC3F,OAAO,EACL,uBAAuB,GAExB,gDAA4C;AAqB7C,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,CAAC;AAEzE,SAAS,gBAAgB,CAAC,OAAoB;IAC5C,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAE/B,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,OAAO,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACtD,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAyB,EAAE,CAAC;IAC3C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACtD,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAC,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAS,EACT,EAAE,SAAS,EAAE,MAAM,EAA6D;IAEhF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,cAAc,CACtB,oEAAoE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAChG,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAyC,CAAC;IAC3D,MAAM,cAAc,GAAG,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC1E,MAAM,sBAAsB,GAAG,gBAAgB,CAAC,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACnF,MAAM,cAAc,GAAoB,YAAY,CAAC;QACnD,sBAAsB;QACtB,cAAc;QACd,EAAE,CAAC,uBAAuB,CAAC,EAAE,MAAM,EAAE;KACtC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,WAAW,CAAC;QACxB,MAAM,EAAE,IAAI;QACZ,SAAS;QACT,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,SAAS;QACtB,cAAc;KACf,CAAM,CAAC;AACV,CAAC"}

package/lib/middleware.d.mts

@@ -0,0 +1,96 @@
+import type { Middleware } from "../core/middleware.mjs";
+import type { AnthropicBeta } from "../resources/beta/beta.mjs";
+import type { BetaFallbackParam, BetaRawMessageDeltaEvent } from "../resources/beta/messages/messages.mjs";
+export { BetaFallbackState } from "../internal/request-options.mjs";
+/** Why {@link BetaRefusalFallbackOptions.onError} fired. */
+export type BetaRefusalFallbackError = {
+    /** The refusal carries no `fallback_credit_token`, so it can't be retried. */
+    kind: 'no_credit_token';
+    message: string;
+    /** The refusal `message_delta` event, verbatim. */
+    event: BetaRawMessageDeltaEvent;
+} | {
+    /** The stream refused but every fallback entry has been used up. */
+    kind: 'chain_exhausted';
+    message: string;
+    /** The refusal `message_delta` event, verbatim. */
+    event: BetaRawMessageDeltaEvent;
+} | {
+    /** A streaming fallback request failed; the hop was skipped. */
+    kind: 'request_failed';
+    message: string;
+    /** The fallback model whose request failed. */
+    model: string;
+    /** The HTTP status, or `null` when the request threw instead of resolving. */
+    status: number | null;
+    /** The parsed error body, or the thrown error when `status` is `null`. */
+    detail: unknown;
+};
+export interface BetaRefusalFallbackOptions {
+    /**
+     * Betas added to the `anthropic-beta` header of every `/v1/messages`
+     * request this middleware handles — the original request included, since
+     * refusals only carry a `fallback_credit_token` when the beta is enabled.
+     * Defaults to `['fallback-credit-2026-06-01']`; pass `[]` to send none.
+     */
+    betas?: readonly AnthropicBeta[] | undefined;
+    /**
+     * Called when a refusal is surfaced to the client rather than retried —
+     * it carries no `fallback_credit_token`, no fallback entries remain, or a
+     * streaming fallback request failed. Discriminate on `error.kind`.
+     * Defaults to logging through the client logger.
+     */
+    onError?: ((error: BetaRefusalFallbackError) => void) | undefined;
+}
+/**
+ * Middleware that retries refused `/v1/messages` requests down a fallback chain.
+ *
+ * Non-streaming: when a response comes back with `stop_reason: 'refusal'`, the
+ * request is retried with each entry of `fallbacks` merged over the original
+ * params — passing along the refusal's `fallback_credit_token` — until a model
+ * accepts or the chain is exhausted. A message served by a fallback carries a
+ * `fallback` content block prepended at each model boundary — the same seam
+ * block shape the server-side `fallbacks` param places in `content`, though
+ * the rest of the envelope is the serving hop's as returned (see the
+ * known-divergences note below); an exhausted chain surfaces the final
+ * refusal verbatim.
+ *
+ * Streaming: when the stream ends in `stop_reason: 'refusal'`, a second
+ * request is issued to the fallback model — carrying the refused model's
+ * partial output as a trailing assistant prefill when the refusal grants one
+ * (`fallback_has_prefill_claim`), plus the refusal's `fallback_credit_token`
+ * — and the fallback's events are spliced onto the
+ * still-open stream, so the client sees one continuous message in the
+ * server-side `fallbacks` wire shape: a `fallback` content block at each model
+ * boundary, monotonic block indices, and per-hop `usage.iterations` on the
+ * final `message_delta`. Only `model` is honored from each entry on this path:
+ * the credit token is redeemable only against the refused request's body, so
+ * the other per-entry overrides (`max_tokens`, `thinking`, ...) would be
+ * rejected.
+ *
+ * The fallback-credit beta the credit tokens require is sent by default on
+ * every request the middleware handles; the `betas` option controls this.
+ *
+ * In both modes a fallback that itself refuses with a fresh credit token
+ * continues down the chain. A streaming fallback whose prefill the server
+ * rejects (HTTP 400) is retried once without it; a fallback whose request
+ * fails outright is skipped — its token was never redeemed, so it carries to
+ * the next entry.
+ *
+ * To keep later requests on the model that accepted, pass a
+ * {@link BetaFallbackState} via the `fallbackState` request option; requests
+ * sharing that state start directly at the pinned fallback. Reuse one state
+ * across whatever scope the pin should apply to — typically a conversation.
+ *
+ * @example
+ * ```ts
+ * const client = new Anthropic({
+ *   middleware: [betaRefusalFallbackMiddleware([{ model: 'claude-opus-4-8' }])],
+ * });
+ *
+ * const fallbackState = new BetaFallbackState();
+ * const message = await client.beta.messages.create(params, { fallbackState });
+ * ```
+ */
+export declare function betaRefusalFallbackMiddleware(fallbacks: readonly BetaFallbackParam[], options?: BetaRefusalFallbackOptions): Middleware;
+//# sourceMappingURL=middleware.d.mts.map

package/lib/middleware.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.mts","sourceRoot":"","sources":["../src/lib/middleware.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAqC,+BAA2B;AAMxF,OAAO,KAAK,EAAE,aAAa,EAAE,mCAA+B;AAC5D,OAAO,KAAK,EAIV,iBAAiB,EAOjB,wBAAwB,EAMzB,gDAA4C;AAE7C,OAAO,EAAE,iBAAiB,EAAE,wCAAoC;AAwBhE,4DAA4D;AAC5D,MAAM,MAAM,wBAAwB,GAChC;IACE,8EAA8E;IAC9E,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,wBAAwB,CAAC;CACjC,GACD;IACE,oEAAoE;IACpE,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,wBAAwB,CAAC;CACjC,GACD;IACE,gEAAgE;IAChE,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEN,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAAC;IAE7C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,iBAAiB,EAAE,EACvC,OAAO,GAAE,0BAA+B,GACvC,UAAU,CA4JZ"}