@tetral-ai/sdk 0.110.0-alpha.1

package/lib/environments/poller.js

@@ -0,0 +1,185 @@
+"use strict";
+var _WorkPoller_runnerClient, _WorkPoller_consumed, _WorkPoller_controller, _WorkPoller_detachExternal, _WorkPoller_autoStop, _WorkPoller_drain, _WorkPoller_blockMs, _WorkPoller_reclaimOlderThanMs, _WorkPoller_requestOpts;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkPoller = exports.POLL_BLOCK_MS = exports.jitter = exports.isStatus = exports.isFatal4xx = exports.is4xx = void 0;
+exports.backoff = backoff;
+const tslib_1 = require("../../internal/tslib.js");
+const error_1 = require("../../core/error.js");
+const log_1 = require("../../internal/utils/log.js");
+const sleep_1 = require("../../internal/utils/sleep.js");
+const uuid_1 = require("../../internal/utils/uuid.js");
+const abort_1 = require("../../internal/utils/abort.js");
+const headers_1 = require("../../internal/headers.js");
+const backoff_1 = require("../../internal/utils/backoff.js");
+const helper_client_1 = require("../helper-client.js");
+var backoff_2 = require("../../internal/utils/backoff.js");
+Object.defineProperty(exports, "is4xx", { enumerable: true, get: function () { return backoff_2.is4xx; } });
+Object.defineProperty(exports, "isFatal4xx", { enumerable: true, get: function () { return backoff_2.isFatal4xx; } });
+Object.defineProperty(exports, "isStatus", { enumerable: true, get: function () { return backoff_2.isStatus; } });
+Object.defineProperty(exports, "jitter", { enumerable: true, get: function () { return backoff_2.jitter; } });
+// API caps block_ms at 999; rely on client-side jitter between empty polls.
+exports.POLL_BLOCK_MS = 999;
+const POLL_BACKOFF_BASE_MS = 1000;
+const POLL_BACKOFF_CAP_MS = 60000;
+/**
+ * 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).
+ *
+ * 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
+ * for await (const work of client.beta.environments.work.poller({
+ *   environmentId,
+ *   environmentKey,
+ * })) {
+ *   // ...service the work...
+ * }
+ * ```
+ */
+class WorkPoller {
+    constructor(opts) {
+        // 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.
+        _WorkPoller_runnerClient.set(this, void 0);
+        _WorkPoller_consumed.set(this, false);
+        _WorkPoller_controller.set(this, void 0);
+        _WorkPoller_detachExternal.set(this, void 0);
+        _WorkPoller_autoStop.set(this, void 0);
+        _WorkPoller_drain.set(this, void 0);
+        _WorkPoller_blockMs.set(this, void 0);
+        _WorkPoller_reclaimOlderThanMs.set(this, void 0);
+        _WorkPoller_requestOpts.set(this, void 0);
+        this.client = opts.client;
+        this.environmentId = opts.environmentId;
+        this.environmentKey = opts.environmentKey;
+        this.workerId = opts.workerId ?? defaultWorkerId();
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_runnerClient, (0, helper_client_1.copyClientForHelper)(opts.client, {
+            authToken: opts.environmentKey,
+            helper: 'environments-work-poller',
+        }), "f");
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_autoStop, opts.autoStop ?? true, "f");
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_drain, opts.drain ?? false, "f");
+        // `undefined` => default to the API cap; an explicit `null` => omit
+        // `block_ms` for a non-blocking poll.
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_blockMs, opts.blockMs === undefined ? exports.POLL_BLOCK_MS : opts.blockMs, "f");
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_reclaimOlderThanMs, opts.reclaimOlderThanMs ?? null, "f");
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_requestOpts, opts.requestOptions, "f");
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_controller, new AbortController(), "f");
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_detachExternal, (0, abort_1.linkAbort)(opts.signal, tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f")), "f");
+    }
+    /** Read-only view of this iterator's abort signal. */
+    get signal() {
+        return tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f").signal;
+    }
+    /** Abort the iterator. The current `for await` will exit cleanly. */
+    abort() {
+        tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f").abort();
+    }
+    async *[(_WorkPoller_runnerClient = new WeakMap(), _WorkPoller_consumed = new WeakMap(), _WorkPoller_controller = new WeakMap(), _WorkPoller_detachExternal = new WeakMap(), _WorkPoller_autoStop = new WeakMap(), _WorkPoller_drain = new WeakMap(), _WorkPoller_blockMs = new WeakMap(), _WorkPoller_reclaimOlderThanMs = new WeakMap(), _WorkPoller_requestOpts = new WeakMap(), Symbol.asyncIterator)]() {
+        if (tslib_1.__classPrivateFieldGet(this, _WorkPoller_consumed, "f")) {
+            throw new error_1.AnthropicError('Cannot iterate over a consumed WorkPoller');
+        }
+        tslib_1.__classPrivateFieldSet(this, _WorkPoller_consumed, true, "f");
+        const log = (0, log_1.loggerFor)(this.client);
+        log.info('poller starting', {
+            component: 'work-poller',
+            environment_id: this.environmentId,
+        });
+        try {
+            let attempt = 0;
+            while (!tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f").signal.aborted) {
+                let work;
+                try {
+                    work = await tslib_1.__classPrivateFieldGet(this, _WorkPoller_runnerClient, "f").beta.environments.work.poll(this.environmentId, {
+                        'Anthropic-Worker-ID': this.workerId,
+                        ...(tslib_1.__classPrivateFieldGet(this, _WorkPoller_blockMs, "f") !== null ? { block_ms: tslib_1.__classPrivateFieldGet(this, _WorkPoller_blockMs, "f") } : {}),
+                        ...(tslib_1.__classPrivateFieldGet(this, _WorkPoller_reclaimOlderThanMs, "f") !== null ?
+                            { reclaim_older_than_ms: tslib_1.__classPrivateFieldGet(this, _WorkPoller_reclaimOlderThanMs, "f") }
+                            : {}),
+                    }, { headers: (0, headers_1.buildHeaders)([tslib_1.__classPrivateFieldGet(this, _WorkPoller_requestOpts, "f")?.headers]), signal: tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f").signal });
+                }
+                catch (e) {
+                    if (tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f").signal.aborted)
+                        return;
+                    // A bad environment key / missing environment never recovers — surface
+                    // it instead of spinning forever at the backoff cap.
+                    if ((0, backoff_1.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 = (0, backoff_1.applyJitter)(backoff(attempt));
+                    log.warn('poll failed, backing off', { error: String(e), backoff_ms: wait });
+                    attempt++;
+                    await (0, sleep_1.sleep)(wait, tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f").signal);
+                    continue;
+                }
+                attempt = 0;
+                if (work == null) {
+                    // Queue empty: either return now (drain) or wait and poll again.
+                    if (tslib_1.__classPrivateFieldGet(this, _WorkPoller_drain, "f"))
+                        return;
+                    await (0, sleep_1.sleep)((0, backoff_1.jitter)(1000, 3000), tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f").signal);
+                    continue;
+                }
+                log.info('claimed work', {
+                    component: 'work-poller',
+                    environment_id: this.environmentId,
+                    work_id: work.id,
+                    work_type: work.data.type,
+                });
+                try {
+                    await tslib_1.__classPrivateFieldGet(this, _WorkPoller_runnerClient, "f").beta.environments.work.ack(work.id, { environment_id: work.environment_id }, { headers: (0, headers_1.buildHeaders)([tslib_1.__classPrivateFieldGet(this, _WorkPoller_requestOpts, "f")?.headers]), signal: tslib_1.__classPrivateFieldGet(this, _WorkPoller_controller, "f").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 (tslib_1.__classPrivateFieldGet(this, _WorkPoller_autoStop, "f")) {
+                        try {
+                            await tslib_1.__classPrivateFieldGet(this, _WorkPoller_runnerClient, "f").beta.environments.work.stop(work.id, { environment_id: work.environment_id }, { headers: (0, headers_1.buildHeaders)([tslib_1.__classPrivateFieldGet(this, _WorkPoller_requestOpts, "f")?.headers]) });
+                        }
+                        catch (e) {
+                            if (!(0, backoff_1.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.
+            tslib_1.__classPrivateFieldGet(this, _WorkPoller_detachExternal, "f").call(this);
+        }
+    }
+}
+exports.WorkPoller = WorkPoller;
+/** Exponential poll backoff: 1s, 2s, 4s … clamped to a 60s cap. */
+function backoff(attempt) {
+    return (0, backoff_1.backoff)(attempt, POLL_BACKOFF_BASE_MS, POLL_BACKOFF_CAP_MS);
+}
+function defaultWorkerId() {
+    // 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.process?.env;
+    const host = env?.['HOSTNAME'];
+    return host ? `${host}-${(0, uuid_1.uuid4)()}` : (0, uuid_1.uuid4)();
+}
+//# sourceMappingURL=poller.js.map

package/lib/environments/poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.js","sourceRoot":"","sources":["../../src/lib/environments/poller.ts"],"names":[],"mappings":";;;;AAoPA,0BAEC;;AAtPD,+CAAkD;AAGlD,qDAAqD;AACrD,yDAAmD;AACnD,uDAAkD;AAClD,yDAAuD;AACvD,uDAAsD;AAEtD,6DAMsC;AACtC,uDAAuD;AAEvD,2DAAmF;AAA1E,gGAAA,KAAK,OAAA;AAAE,qGAAA,UAAU,OAAA;AAAE,mGAAA,QAAQ,OAAA;AAAE,iGAAA,MAAM,OAAA;AAE5C,4EAA4E;AAC/D,QAAA,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAClC,MAAM,mBAAmB,GAAG,KAAM,CAAC;AAwDnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,UAAU;IAoBrB,YAAY,IAAuB;QAdnC,yEAAyE;QACzE,wEAAwE;QACxE,uEAAuE;QACvE,0EAA0E;QACjE,2CAAyB;QAClC,+BAAY,KAAK,EAAC;QACT,yCAA6B;QAC7B,6CAA4B;QAC5B,uCAAmB;QACnB,oCAAgB;QAChB,sCAAwB;QACxB,iDAAmC;QACnC,0CAAuD;QAG9D,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,eAAe,EAAE,CAAC;QACnD,+BAAA,IAAI,4BAAiB,IAAA,mCAAmB,EAAC,IAAI,CAAC,MAAM,EAAE;YACpD,SAAS,EAAE,IAAI,CAAC,cAAc;YAC9B,MAAM,EAAE,0BAA0B;SACnC,CAAC,MAAA,CAAC;QACH,+BAAA,IAAI,wBAAa,IAAI,CAAC,QAAQ,IAAI,IAAI,MAAA,CAAC;QACvC,+BAAA,IAAI,qBAAU,IAAI,CAAC,KAAK,IAAI,KAAK,MAAA,CAAC;QAClC,oEAAoE;QACpE,sCAAsC;QACtC,+BAAA,IAAI,uBAAY,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAa,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,MAAA,CAAC;QAC1E,+BAAA,IAAI,kCAAuB,IAAI,CAAC,kBAAkB,IAAI,IAAI,MAAA,CAAC;QAC3D,+BAAA,IAAI,2BAAgB,IAAI,CAAC,cAAc,MAAA,CAAC;QACxC,+BAAA,IAAI,0BAAe,IAAI,eAAe,EAAE,MAAA,CAAC;QACzC,+BAAA,IAAI,8BAAmB,IAAA,iBAAS,EAAC,IAAI,CAAC,MAAM,EAAE,+BAAA,IAAI,8BAAY,CAAC,MAAA,CAAC;IAClE,CAAC;IAED,sDAAsD;IACtD,IAAI,MAAM;QACR,OAAO,+BAAA,IAAI,8BAAY,CAAC,MAAM,CAAC;IACjC,CAAC;IAED,qEAAqE;IACrE,KAAK;QACH,+BAAA,IAAI,8BAAY,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,CAAC,6WAAC,MAAM,CAAC,aAAa,EAAC;QAC3B,IAAI,+BAAA,IAAI,4BAAU,EAAE,CAAC;YACnB,MAAM,IAAI,sBAAc,CAAC,2CAA2C,CAAC,CAAC;QACxE,CAAC;QACD,+BAAA,IAAI,wBAAa,IAAI,MAAA,CAAC;QACtB,MAAM,GAAG,GAAG,IAAA,eAAS,EAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE;YAC1B,SAAS,EAAE,aAAa;YACxB,cAAc,EAAE,IAAI,CAAC,aAAa;SACnC,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,OAAO,CAAC,+BAAA,IAAI,8BAAY,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACxC,IAAI,IAA+B,CAAC;gBACpC,IAAI,CAAC;oBACH,IAAI,GAAG,MAAM,+BAAA,IAAI,gCAAc,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CACzD,IAAI,CAAC,aAAa,EAClB;wBACE,qBAAqB,EAAE,IAAI,CAAC,QAAQ;wBACpC,GAAG,CAAC,+BAAA,IAAI,2BAAS,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,+BAAA,IAAI,2BAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC9D,GAAG,CAAC,+BAAA,IAAI,sCAAoB,KAAK,IAAI,CAAC,CAAC;4BACrC,EAAE,qBAAqB,EAAE,+BAAA,IAAI,sCAAoB,EAAE;4BACrD,CAAC,CAAC,EAAE,CAAC;qBACN,EACD,EAAE,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,+BAAA,IAAI,+BAAa,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,+BAAA,IAAI,8BAAY,CAAC,MAAM,EAAE,CACzF,CAAC;gBACJ,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,IAAI,+BAAA,IAAI,8BAAY,CAAC,MAAM,CAAC,OAAO;wBAAE,OAAO;oBAC5C,uEAAuE;oBACvE,qDAAqD;oBACrD,IAAI,IAAA,oBAAU,EAAC,CAAC,CAAC,EAAE,CAAC;wBAClB,GAAG,CAAC,KAAK,CAAC,0CAA0C,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;wBAC5E,MAAM,CAAC,CAAC;oBACV,CAAC;oBACD,sEAAsE;oBACtE,kCAAkC;oBAClC,MAAM,IAAI,GAAG,IAAA,qBAAW,EAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;oBAC3C,GAAG,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC7E,OAAO,EAAE,CAAC;oBACV,MAAM,IAAA,aAAK,EAAC,IAAI,EAAE,+BAAA,IAAI,8BAAY,CAAC,MAAM,CAAC,CAAC;oBAC3C,SAAS;gBACX,CAAC;gBACD,OAAO,GAAG,CAAC,CAAC;gBACZ,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;oBACjB,iEAAiE;oBACjE,IAAI,+BAAA,IAAI,yBAAO;wBAAE,OAAO;oBACxB,MAAM,IAAA,aAAK,EAAC,IAAA,gBAAM,EAAC,IAAI,EAAE,IAAI,CAAC,EAAE,+BAAA,IAAI,8BAAY,CAAC,MAAM,CAAC,CAAC;oBACzD,SAAS;gBACX,CAAC;gBACD,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE;oBACvB,SAAS,EAAE,aAAa;oBACxB,cAAc,EAAE,IAAI,CAAC,aAAa;oBAClC,OAAO,EAAE,IAAI,CAAC,EAAE;oBAChB,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI;iBAC1B,CAAC,CAAC;gBAEH,IAAI,CAAC;oBACH,MAAM,+BAAA,IAAI,gCAAc,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CACjD,IAAI,CAAC,EAAE,EACP,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,EACvC,EAAE,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,+BAAA,IAAI,+BAAa,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,+BAAA,IAAI,8BAAY,CAAC,MAAM,EAAE,CACzF,CAAC;gBACJ,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;oBAChE,SAAS;gBACX,CAAC;gBAED,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC;gBACb,CAAC;wBAAS,CAAC;oBACT,6DAA6D;oBAC7D,qEAAqE;oBACrE,4CAA4C;oBAC5C,IAAI,+BAAA,IAAI,4BAAU,EAAE,CAAC;wBACnB,IAAI,CAAC;4BACH,MAAM,+BAAA,IAAI,gCAAc,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAClD,IAAI,CAAC,EAAE,EACP,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,EACvC,EAAE,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,+BAAA,IAAI,+BAAa,EAAE,OAAO,CAAC,CAAC,EAAE,CACxD,CAAC;wBACJ,CAAC;wBAAC,OAAO,CAAC,EAAE,CAAC;4BACX,IAAI,CAAC,IAAA,kBAAQ,EAAC,CAAC,EAAE,GAAG,CAAC;gCAAE,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;wBACzF,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,iEAAiE;YACjE,2DAA2D;YAC3D,+BAAA,IAAI,kCAAgB,MAApB,IAAI,CAAkB,CAAC;QACzB,CAAC;IACH,CAAC;CACF;AA/ID,gCA+IC;AAED,mEAAmE;AACnE,SAAgB,OAAO,CAAC,OAAe;IACrC,OAAO,IAAA,iBAAU,EAAC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,eAAe;IACtB,8EAA8E;IAC9E,2EAA2E;IAC3E,+EAA+E;IAC/E,8BAA8B;IAC9B,MAAM,GAAG,GAAI,UAAyE,CAAC,OAAO,EAAE,GAAG,CAAC;IACpG,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC;IAC/B,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAA,YAAK,GAAE,EAAE,CAAC,CAAC,CAAC,IAAA,YAAK,GAAE,CAAC;AAC/C,CAAC"}

package/lib/environments/poller.mjs

@@ -0,0 +1,176 @@
+var _WorkPoller_runnerClient, _WorkPoller_consumed, _WorkPoller_controller, _WorkPoller_detachExternal, _WorkPoller_autoStop, _WorkPoller_drain, _WorkPoller_blockMs, _WorkPoller_reclaimOlderThanMs, _WorkPoller_requestOpts;
+import { __classPrivateFieldGet, __classPrivateFieldSet } from "../../internal/tslib.mjs";
+import { AnthropicError } from "../../core/error.mjs";
+import { loggerFor } from "../../internal/utils/log.mjs";
+import { sleep } from "../../internal/utils/sleep.mjs";
+import { uuid4 } from "../../internal/utils/uuid.mjs";
+import { linkAbort } from "../../internal/utils/abort.mjs";
+import { buildHeaders } from "../../internal/headers.mjs";
+import { applyJitter, backoff as expBackoff, isFatal4xx, isStatus, jitter, } from "../../internal/utils/backoff.mjs";
+import { copyClientForHelper } from "../helper-client.mjs";
+export { is4xx, isFatal4xx, isStatus, jitter } from "../../internal/utils/backoff.mjs";
+// 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 = 60000;
+/**
+ * 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).
+ *
+ * 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
+ * for await (const work of client.beta.environments.work.poller({
+ *   environmentId,
+ *   environmentKey,
+ * })) {
+ *   // ...service the work...
+ * }
+ * ```
+ */
+export class WorkPoller {
+    constructor(opts) {
+        // 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.
+        _WorkPoller_runnerClient.set(this, void 0);
+        _WorkPoller_consumed.set(this, false);
+        _WorkPoller_controller.set(this, void 0);
+        _WorkPoller_detachExternal.set(this, void 0);
+        _WorkPoller_autoStop.set(this, void 0);
+        _WorkPoller_drain.set(this, void 0);
+        _WorkPoller_blockMs.set(this, void 0);
+        _WorkPoller_reclaimOlderThanMs.set(this, void 0);
+        _WorkPoller_requestOpts.set(this, void 0);
+        this.client = opts.client;
+        this.environmentId = opts.environmentId;
+        this.environmentKey = opts.environmentKey;
+        this.workerId = opts.workerId ?? defaultWorkerId();
+        __classPrivateFieldSet(this, _WorkPoller_runnerClient, copyClientForHelper(opts.client, {
+            authToken: opts.environmentKey,
+            helper: 'environments-work-poller',
+        }), "f");
+        __classPrivateFieldSet(this, _WorkPoller_autoStop, opts.autoStop ?? true, "f");
+        __classPrivateFieldSet(this, _WorkPoller_drain, opts.drain ?? false, "f");
+        // `undefined` => default to the API cap; an explicit `null` => omit
+        // `block_ms` for a non-blocking poll.
+        __classPrivateFieldSet(this, _WorkPoller_blockMs, opts.blockMs === undefined ? POLL_BLOCK_MS : opts.blockMs, "f");
+        __classPrivateFieldSet(this, _WorkPoller_reclaimOlderThanMs, opts.reclaimOlderThanMs ?? null, "f");
+        __classPrivateFieldSet(this, _WorkPoller_requestOpts, opts.requestOptions, "f");
+        __classPrivateFieldSet(this, _WorkPoller_controller, new AbortController(), "f");
+        __classPrivateFieldSet(this, _WorkPoller_detachExternal, linkAbort(opts.signal, __classPrivateFieldGet(this, _WorkPoller_controller, "f")), "f");
+    }
+    /** Read-only view of this iterator's abort signal. */
+    get signal() {
+        return __classPrivateFieldGet(this, _WorkPoller_controller, "f").signal;
+    }
+    /** Abort the iterator. The current `for await` will exit cleanly. */
+    abort() {
+        __classPrivateFieldGet(this, _WorkPoller_controller, "f").abort();
+    }
+    async *[(_WorkPoller_runnerClient = new WeakMap(), _WorkPoller_consumed = new WeakMap(), _WorkPoller_controller = new WeakMap(), _WorkPoller_detachExternal = new WeakMap(), _WorkPoller_autoStop = new WeakMap(), _WorkPoller_drain = new WeakMap(), _WorkPoller_blockMs = new WeakMap(), _WorkPoller_reclaimOlderThanMs = new WeakMap(), _WorkPoller_requestOpts = new WeakMap(), Symbol.asyncIterator)]() {
+        if (__classPrivateFieldGet(this, _WorkPoller_consumed, "f")) {
+            throw new AnthropicError('Cannot iterate over a consumed WorkPoller');
+        }
+        __classPrivateFieldSet(this, _WorkPoller_consumed, true, "f");
+        const log = loggerFor(this.client);
+        log.info('poller starting', {
+            component: 'work-poller',
+            environment_id: this.environmentId,
+        });
+        try {
+            let attempt = 0;
+            while (!__classPrivateFieldGet(this, _WorkPoller_controller, "f").signal.aborted) {
+                let work;
+                try {
+                    work = await __classPrivateFieldGet(this, _WorkPoller_runnerClient, "f").beta.environments.work.poll(this.environmentId, {
+                        'Anthropic-Worker-ID': this.workerId,
+                        ...(__classPrivateFieldGet(this, _WorkPoller_blockMs, "f") !== null ? { block_ms: __classPrivateFieldGet(this, _WorkPoller_blockMs, "f") } : {}),
+                        ...(__classPrivateFieldGet(this, _WorkPoller_reclaimOlderThanMs, "f") !== null ?
+                            { reclaim_older_than_ms: __classPrivateFieldGet(this, _WorkPoller_reclaimOlderThanMs, "f") }
+                            : {}),
+                    }, { headers: buildHeaders([__classPrivateFieldGet(this, _WorkPoller_requestOpts, "f")?.headers]), signal: __classPrivateFieldGet(this, _WorkPoller_controller, "f").signal });
+                }
+                catch (e) {
+                    if (__classPrivateFieldGet(this, _WorkPoller_controller, "f").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, __classPrivateFieldGet(this, _WorkPoller_controller, "f").signal);
+                    continue;
+                }
+                attempt = 0;
+                if (work == null) {
+                    // Queue empty: either return now (drain) or wait and poll again.
+                    if (__classPrivateFieldGet(this, _WorkPoller_drain, "f"))
+                        return;
+                    await sleep(jitter(1000, 3000), __classPrivateFieldGet(this, _WorkPoller_controller, "f").signal);
+                    continue;
+                }
+                log.info('claimed work', {
+                    component: 'work-poller',
+                    environment_id: this.environmentId,
+                    work_id: work.id,
+                    work_type: work.data.type,
+                });
+                try {
+                    await __classPrivateFieldGet(this, _WorkPoller_runnerClient, "f").beta.environments.work.ack(work.id, { environment_id: work.environment_id }, { headers: buildHeaders([__classPrivateFieldGet(this, _WorkPoller_requestOpts, "f")?.headers]), signal: __classPrivateFieldGet(this, _WorkPoller_controller, "f").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 (__classPrivateFieldGet(this, _WorkPoller_autoStop, "f")) {
+                        try {
+                            await __classPrivateFieldGet(this, _WorkPoller_runnerClient, "f").beta.environments.work.stop(work.id, { environment_id: work.environment_id }, { headers: buildHeaders([__classPrivateFieldGet(this, _WorkPoller_requestOpts, "f")?.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.
+            __classPrivateFieldGet(this, _WorkPoller_detachExternal, "f").call(this);
+        }
+    }
+}
+/** Exponential poll backoff: 1s, 2s, 4s … clamped to a 60s cap. */
+export function backoff(attempt) {
+    return expBackoff(attempt, POLL_BACKOFF_BASE_MS, POLL_BACKOFF_CAP_MS);
+}
+function defaultWorkerId() {
+    // 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.process?.env;
+    const host = env?.['HOSTNAME'];
+    return host ? `${host}-${uuid4()}` : uuid4();
+}
+//# sourceMappingURL=poller.mjs.map

package/lib/environments/poller.mjs.map

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

package/lib/environments/worker.d.mts

@@ -0,0 +1,150 @@
+import type { Anthropic } from "../../client.mjs";
+import type { BetaRunnableTool } from "../tools/BetaRunnableTool.mjs";
+import type { BetaToolRunnerRequestOptions } from "../tools/BetaToolRunner.mjs";
+import type { AgentToolContext } from "../../tools/agent-toolset/node.mjs";
+/**
+ * Either a fixed tool array or a factory invoked once per claimed session with
+ * that session's {@link AgentToolContext} — use the factory form to bind
+ * `betaAgentToolset20260401` (or any tool that needs the workdir / session
+ * id) to the right session.
+ */
+export type EnvironmentWorkerTools = Array<BetaRunnableTool> | ((ctx: AgentToolContext) => Array<BetaRunnableTool>);
+export interface EnvironmentWorkerOptions {
+    client: Anthropic;
+    /**
+     * The self-hosted environment to poll for work. Required by
+     * {@link EnvironmentWorker.run}; not used by {@link EnvironmentWorker.handleItem}.
+     */
+    environmentId?: string;
+    /**
+     * The environment key — the single credential for the runner. It authenticates
+     * the work-poll calls and every per-session call (event stream, lease
+     * heartbeat, force-stop). Required by {@link EnvironmentWorker.run}; falls back
+     * to `ANTHROPIC_ENVIRONMENT_KEY` in {@link EnvironmentWorker.handleItem}.
+     */
+    environmentKey?: string;
+    /**
+     * Tools to expose to each claimed session. Defaults to
+     * `betaAgentToolset20260401(ctx)` (the standard `agent_toolset_20260401` set
+     * bound to the per-session {@link AgentToolContext}).
+     */
+    tools?: EnvironmentWorkerTools;
+    /** Base directory for the per-session {@link AgentToolContext}. Defaults to `process.cwd()`. */
+    workdir?: string;
+    /** Forwarded to the per-session {@link AgentToolContext}. */
+    unrestrictedPaths?: boolean;
+    /** Forwarded to the per-session {@link AgentToolContext} (`maxFileBytes`). */
+    maxFileBytes?: number | null;
+    /** Forwarded to {@link SessionToolRunner} (`maxIdleMs`). */
+    maxIdleMs?: number;
+    /** Forwarded to the {@link WorkPoller}. */
+    workerId?: string;
+    /** External abort signal; aborting it ends the run. */
+    signal?: AbortSignal;
+    /**
+     * Extra per-request options merged into every call this worker issues — the
+     * work poll/ack/heartbeat/stop control-plane calls and the per-session
+     * SessionToolRunner's stream/list/send. Mirrors what
+     * `client.beta.messages.toolRunner` accepts: custom `headers` (e.g. a proxy's
+     * auth/routing headers) reach all of them. The worker owns the abort signals,
+     * so a `signal` here is ignored — use {@link EnvironmentWorkerOptions.signal}.
+     */
+    requestOptions?: BetaToolRunnerRequestOptions;
+}
+/**
+ * Options for {@link EnvironmentWorker.handleItem}. Every field falls back to the
+ * matching `ANTHROPIC_*` environment variable — the ones the
+ * `ant worker poll --on-work` command sets for the process it spawns — when not
+ * passed explicitly.
+ */
+export interface HandleItemOptions {
+    /** Work item id. Falls back to `ANTHROPIC_WORK_ID`. */
+    workId?: string;
+    /** Self-hosted environment id. Falls back to `ANTHROPIC_ENVIRONMENT_ID`. */
+    environmentId?: string;
+    /** Session id. Falls back to `ANTHROPIC_SESSION_ID`. */
+    sessionId?: string;
+    /**
+     * The environment key used to authenticate every per-session call. Resolution
+     * order: this option, then the worker's own `environmentKey`, then
+     * `ANTHROPIC_ENVIRONMENT_KEY`.
+     */
+    environmentKey?: string;
+    /** External abort signal; aborting it ends the run. Defaults to the constructor's signal. */
+    signal?: AbortSignal;
+}
+/**
+ * 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 declare class EnvironmentWorker {
+    #private;
+    readonly client: Anthropic;
+    readonly environmentId: string | undefined;
+    readonly environmentKey: string | undefined;
+    readonly tools: EnvironmentWorkerTools | undefined;
+    readonly workdir: string;
+    readonly unrestrictedPaths: boolean | undefined;
+    readonly maxFileBytes: number | null | undefined;
+    readonly maxIdleMs: number | undefined;
+    readonly workerId: string | undefined;
+    readonly requestOptions: BetaToolRunnerRequestOptions | undefined;
+    constructor(opts: EnvironmentWorkerOptions);
+    /**
+     * 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.
+     */
+    run(signal?: AbortSignal): Promise<void>;
+    /**
+     * 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.
+     */
+    handleItem(opts?: HandleItemOptions): Promise<void>;
+}
+//# sourceMappingURL=worker.d.mts.map

package/lib/environments/worker.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.mts","sourceRoot":"","sources":["../../src/lib/environments/worker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAqB;AAQ9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,sCAAkC;AAClE,OAAO,KAAK,EAAE,4BAA4B,EAAE,oCAAgC;AAU5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,2CAAuC;AAKvE;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC9B,KAAK,CAAC,gBAAgB,CAAC,GACvB,CAAC,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAEzD,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,4BAA4B,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,iBAAiB;;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,4BAA4B,GAAG,SAAS,CAAC;gBAGtD,IAAI,EAAE,wBAAwB;IAc1C;;;;OAIG;IACG,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB9C;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAgH1D"}