@puku-ai/sdk 4.0.3 → 4.0.4

package/dist/vendor/lib/credentials/types.cjs

@@ -0,0 +1,267 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkloadIdentityError = exports.ADVISORY_REFRESH_BACKOFF_IN_SECONDS = exports.MANDATORY_REFRESH_THRESHOLD_IN_SECONDS = exports.ADVISORY_REFRESH_THRESHOLD_IN_SECONDS = exports.FEDERATION_BETA_HEADER = exports.OAUTH_API_BETA_HEADER = exports.TOKEN_ENDPOINT = exports.GRANT_TYPE_REFRESH_TOKEN = exports.GRANT_TYPE_JWT_BEARER = void 0;
+exports.requireSecureTokenEndpoint = requireSecureTokenEndpoint;
+exports.parseTokenResponse = parseTokenResponse;
+exports.redactSensitive = redactSensitive;
+exports.checkCredentialsFileSafety = checkCredentialsFileSafety;
+exports.writeCredentialsFileAtomic = writeCredentialsFileAtomic;
+const error_1 = require("../../core/error");
+exports.GRANT_TYPE_JWT_BEARER = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
+exports.GRANT_TYPE_REFRESH_TOKEN = 'refresh_token';
+exports.TOKEN_ENDPOINT = '/v1/oauth/token';
+/**
+ * `puku-beta` value required on authenticated API requests using an
+ * OAuth bearer token, and on `refresh_token` grants against the token endpoint.
+ */
+exports.OAUTH_API_BETA_HEADER = 'oauth-2025-04-20';
+/**
+ * `puku-beta` value required on jwt-bearer exchanges against the token
+ * endpoint. It routes the request to the federation service; it must NOT be
+ * sent on `refresh_token` grants, which are handled by a different backend.
+ */
+exports.FEDERATION_BETA_HEADER = 'oidc-federation-2026-04-01';
+exports.ADVISORY_REFRESH_THRESHOLD_IN_SECONDS = 120;
+exports.MANDATORY_REFRESH_THRESHOLD_IN_SECONDS = 30;
+exports.ADVISORY_REFRESH_BACKOFF_IN_SECONDS = 5;
+const MAX_TOKEN_RESPONSE_BYTES = 1 << 20;
+/**
+ * Rejects base URLs that would cause a JWT assertion or refresh token to be
+ * sent over cleartext HTTP. Loopback hosts are allowed for local development.
+ */
+function requireSecureTokenEndpoint(baseURL) {
+    if (!baseURL)
+        return;
+    let u;
+    try {
+        u = new URL(baseURL);
+    }
+    catch (err) {
+        throw new WorkloadIdentityError(`Invalid token endpoint base URL "${baseURL}": ${err}`);
+    }
+    if (u.protocol === 'https:')
+        return;
+    // WHATWG URL.hostname returns bracketed IPv6 ("[::1]"); Go's net/url strips them.
+    const host = u.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (u.protocol === 'http:' && (host === 'localhost' || host === '127.0.0.1' || host === '::1')) {
+        return;
+    }
+    throw new WorkloadIdentityError(`Refusing to send credential over non-https token endpoint "${baseURL}"`);
+}
+/**
+ * Reads the response body as text, parses it as a token-endpoint JSON
+ * response, validates `access_token` is present, and rejects a non-Bearer
+ * `token_type` when one is provided. Reads at most
+ * {@link MAX_TOKEN_RESPONSE_BYTES} from the body stream.
+ */
+async function parseTokenResponse(resp, requestId) {
+    const text = await readLimitedText(resp);
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new WorkloadIdentityError(`Token endpoint returned non-JSON response (status ${resp.status})`, resp.status, redactSensitive(text), requestId);
+    }
+    if (!data.access_token) {
+        throw new WorkloadIdentityError(`Token endpoint response missing access_token: ${JSON.stringify(redactSensitive(data))}`, resp.status, redactSensitive(data), requestId);
+    }
+    if (data.token_type && data.token_type.toLowerCase() !== 'bearer') {
+        throw new WorkloadIdentityError(`Token endpoint response: unsupported token_type "${data.token_type}" (want Bearer)`, resp.status, redactSensitive(data), requestId);
+    }
+    return data;
+}
+const MAX_ERROR_BODY_CHARS = 2000;
+// RFC 6749 §5.2 standard error-response fields. Anything else in a token
+// endpoint error body is potentially echoed input (assertion, refresh_token,
+// access_token, …) and is dropped rather than allowlisted-with-exceptions.
+const SAFE_ERROR_KEYS = new Set(['error', 'error_description', 'error_uri']);
+/**
+ * Returns a redacted copy of a token-endpoint error body for safe inclusion
+ * in an exception. Strings are truncated; objects keep only the RFC 6749
+ * §5.2 error fields.
+ */
+function redactSensitive(body) {
+    if (body == null)
+        return body;
+    if (typeof body === 'string') {
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            if (body.length <= MAX_ERROR_BODY_CHARS)
+                return body;
+            return body.slice(0, MAX_ERROR_BODY_CHARS) + `... <${body.length - MAX_ERROR_BODY_CHARS} more chars>`;
+        }
+        return JSON.stringify(redactSensitive(parsed));
+    }
+    if (typeof body === 'object' && !Array.isArray(body)) {
+        const out = {};
+        for (const [k, v] of Object.entries(body)) {
+            if (SAFE_ERROR_KEYS.has(k))
+                out[k] = v;
+        }
+        return out;
+    }
+    return null;
+}
+/**
+ * Best-effort safety check on a credentials file before reading it.
+ *
+ * On POSIX: resolves symlinks (so containerized deployments that mount the
+ * credential as a symlink to a tmpfs-backed file keep working), then rejects
+ * the resolved target if it is group- or world- readable or writable. A uid
+ * mismatch on the resolved target is surfaced via `onWarn` since
+ * root-written/app-read is common in init-container setups. No-op on Windows.
+ */
+async function checkCredentialsFileSafety(path, onWarn = (m) => console.warn(`puku-ai/sdk: ${m}`)) {
+    if (typeof process === 'undefined' || process.platform === 'win32')
+        return;
+    const { fs } = await Promise.resolve().then(() => __importStar(require('../../internal/node')));
+    let resolved = path;
+    let st;
+    try {
+        resolved = await fs.promises.realpath(path);
+        st = await fs.promises.stat(resolved);
+    }
+    catch {
+        return; // ENOENT etc — let the subsequent read surface a precise error
+    }
+    const mode = st.mode & 0o777;
+    // 0o022 = group/world write; 0o044 = group/world read.
+    if (mode & 0o022) {
+        throw new WorkloadIdentityError(`Credentials file at ${resolved} is group/world-writable (mode 0o${mode.toString(8)}); ` +
+            `this allows other local users to plant tokens. Run \`chmod 600 ${resolved}\`.`);
+    }
+    if (mode & 0o044) {
+        throw new WorkloadIdentityError(`Credentials file at ${resolved} is group/world-readable (mode 0o${mode.toString(8)}); ` +
+            `run \`chmod 600 ${resolved}\` before retrying.`);
+    }
+    if (typeof process.getuid === 'function' && st.uid !== process.getuid()) {
+        onWarn(`credentials file at ${resolved} is owned by uid ${st.uid} (current process uid ${process.getuid()}); ` + `verify this is intentional.`);
+    }
+}
+/**
+ * Atomically writes JSON to `targetPath` via a `.tmp` sibling + rename,
+ * with fsync on the file and (best-effort) on the parent directory.
+ * Creates the parent directory with mode 0700 and the file with mode 0600.
+ */
+async function writeCredentialsFileAtomic(targetPath, data) {
+    const { fs, path } = await Promise.resolve().then(() => __importStar(require('../../internal/node')));
+    const dir = path.dirname(targetPath);
+    await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+    // Unique temp name avoids two concurrent writers (different processes or
+    // SDK instances) racing on the same '.tmp' sibling and corrupting each
+    // other's bytes mid-write before the rename.
+    const tmpPath = `${targetPath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        const fh = await fs.promises.open(tmpPath, 'w', 0o600);
+        try {
+            await fh.writeFile(JSON.stringify(data, null, 2));
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+        await fs.promises.rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        // Don't leak the temp file if anything between create and rename failed.
+        await fs.promises.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+    // fsync the parent directory so the rename survives a crash.
+    try {
+        const dirFh = await fs.promises.open(dir, 'r');
+        try {
+            await dirFh.sync();
+        }
+        finally {
+            await dirFh.close();
+        }
+    }
+    catch {
+        // Directory fsync is best-effort (unsupported on some platforms, e.g. Windows).
+    }
+}
+async function readLimitedText(resp) {
+    if (!resp.body) {
+        return '';
+    }
+    const reader = resp.body.getReader();
+    const chunks = [];
+    let received = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (received + value.length > MAX_TOKEN_RESPONSE_BYTES) {
+            const remaining = MAX_TOKEN_RESPONSE_BYTES - received;
+            if (remaining > 0)
+                chunks.push(value.subarray(0, remaining));
+            await reader.cancel();
+            break;
+        }
+        chunks.push(value);
+        received += value.length;
+    }
+    let merged;
+    if (chunks.length === 1) {
+        merged = chunks[0];
+    }
+    else {
+        merged = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+        let offset = 0;
+        for (const c of chunks) {
+            merged.set(c, offset);
+            offset += c.length;
+        }
+    }
+    return new TextDecoder('utf-8').decode(merged);
+}
+class WorkloadIdentityError extends error_1.PukuError {
+    statusCode;
+    body;
+    requestId;
+    constructor(message, statusCode = null, body = null, requestId = null) {
+        super(message);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.requestId = requestId;
+    }
+}
+exports.WorkloadIdentityError = WorkloadIdentityError;

package/dist/vendor/lib/credentials/user-oauth.cjs

@@ -0,0 +1,129 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userOAuthProvider = userOAuthProvider;
+const credentials_1 = require("../../core/credentials");
+const types_1 = require("./types");
+const time_1 = require("../../internal/utils/time");
+const version_1 = require("../../version");
+/**
+ * Reads a user-oauth credential file. Returns the cached access token while
+ * fresh; on expiry performs a `refresh_token` grant and writes the new
+ * tokens back to the credentials file (atomic replace, fsync'd).
+ *
+ * If `clientId` is empty, the access token is treated as static — the
+ * credentials file is read on every call but no refresh is attempted, and
+ * an expired token without a `refresh_token` raises.
+ */
+function userOAuthProvider(config) {
+    return async (opts) => {
+        const { fs } = await Promise.resolve().then(() => __importStar(require('../../internal/node')));
+        await (0, types_1.checkCredentialsFileSafety)(config.credentialsPath, config.onSafetyWarning);
+        let raw;
+        try {
+            raw = await fs.promises.readFile(config.credentialsPath, 'utf-8');
+        }
+        catch (err) {
+            throw new types_1.WorkloadIdentityError(`Credentials file not found at ${config.credentialsPath}: ${err}`);
+        }
+        let creds;
+        try {
+            creds = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new types_1.WorkloadIdentityError(`Credentials file at ${config.credentialsPath} is not valid JSON: ${err}`);
+        }
+        const accessToken = creds.access_token;
+        if (!accessToken) {
+            throw new types_1.WorkloadIdentityError(`Credentials file at ${config.credentialsPath} must include 'access_token'`);
+        }
+        // Return cached token if still fresh (or no expiry info), unless the
+        // caller is forcing a refresh after a 401 — then go straight to refresh
+        // even if the file's expires_at still looks valid.
+        const expiresAt = creds.expires_at;
+        if (!opts?.forceRefresh &&
+            (expiresAt == null || (0, time_1.nowAsSeconds)() < expiresAt - types_1.MANDATORY_REFRESH_THRESHOLD_IN_SECONDS)) {
+            return { token: accessToken, expiresAt: expiresAt ?? null };
+        }
+        const refreshToken = creds.refresh_token;
+        if (!config.clientId || !refreshToken) {
+            throw new types_1.WorkloadIdentityError(`Access token at ${config.credentialsPath} has expired and no refresh is available ` +
+                `(client_id ${config.clientId ? 'set' : 'empty'}, refresh_token ${refreshToken ? 'set' : 'empty'})`);
+        }
+        (0, types_1.requireSecureTokenEndpoint)(config.baseURL);
+        const body = {
+            grant_type: types_1.GRANT_TYPE_REFRESH_TOKEN,
+            refresh_token: refreshToken,
+            client_id: config.clientId,
+        };
+        const url = `${config.baseURL}${types_1.TOKEN_ENDPOINT}`;
+        let resp;
+        try {
+            resp = await config.fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'puku-beta': types_1.OAUTH_API_BETA_HEADER,
+                    'User-Agent': config.userAgent || `puku-ai-sdk-typescript/${version_1.VERSION} userOAuthProvider`,
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new types_1.WorkloadIdentityError(`User OAuth refresh failed to reach token endpoint: ${err}`);
+        }
+        const requestId = resp.headers.get('Request-Id');
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            throw new types_1.WorkloadIdentityError(`User OAuth refresh failed (HTTP ${resp.status}): ${(0, types_1.redactSensitive)(text)}`, resp.status, (0, types_1.redactSensitive)(text), requestId);
+        }
+        const data = await (0, types_1.parseTokenResponse)(resp, requestId);
+        const expiresIn = Number(data.expires_in);
+        if (!Number.isFinite(expiresIn)) {
+            throw new types_1.WorkloadIdentityError(`User OAuth refresh response missing or invalid expires_in: ${JSON.stringify((0, types_1.redactSensitive)(data))}`, resp.status, (0, types_1.redactSensitive)(data), requestId);
+        }
+        const newExpiresAt = (0, time_1.nowAsSeconds)() + expiresIn;
+        const newRefreshToken = data.refresh_token || refreshToken;
+        await (0, types_1.writeCredentialsFileAtomic)(config.credentialsPath, {
+            ...creds,
+            version: credentials_1.CREDENTIALS_FILE_VERSION,
+            type: 'oauth_token',
+            access_token: data.access_token,
+            expires_at: newExpiresAt,
+            refresh_token: newRefreshToken,
+        });
+        return { token: data.access_token, expiresAt: newExpiresAt };
+    };
+}

package/dist/vendor/lib/credentials.cjs

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCredentialsFromConfig = exports.loadConfig = void 0;
+var credentials_1 = require("../core/credentials");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return credentials_1.loadConfig; } });
+var credential_chain_1 = require("./credentials/credential-chain");
+Object.defineProperty(exports, "resolveCredentialsFromConfig", { enumerable: true, get: function () { return credential_chain_1.resolveCredentialsFromConfig; } });

package/dist/vendor/lib/environments/index.cjs

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_IDLE_MS = exports.MANAGED_AGENTS_BETA = exports.SessionToolRunner = exports.EnvironmentWorker = exports.isFatal4xx = exports.is4xx = exports.isStatus = exports.jitter = exports.backoff = exports.POLL_BLOCK_MS = exports.WorkPoller = void 0;
+var poller_1 = require("./poller");
+Object.defineProperty(exports, "WorkPoller", { enumerable: true, get: function () { return poller_1.WorkPoller; } });
+Object.defineProperty(exports, "POLL_BLOCK_MS", { enumerable: true, get: function () { return poller_1.POLL_BLOCK_MS; } });
+Object.defineProperty(exports, "backoff", { enumerable: true, get: function () { return poller_1.backoff; } });
+Object.defineProperty(exports, "jitter", { enumerable: true, get: function () { return poller_1.jitter; } });
+Object.defineProperty(exports, "isStatus", { enumerable: true, get: function () { return poller_1.isStatus; } });
+Object.defineProperty(exports, "is4xx", { enumerable: true, get: function () { return poller_1.is4xx; } });
+Object.defineProperty(exports, "isFatal4xx", { enumerable: true, get: function () { return poller_1.isFatal4xx; } });
+var worker_1 = require("./worker");
+Object.defineProperty(exports, "EnvironmentWorker", { enumerable: true, get: function () { return worker_1.EnvironmentWorker; } });
+var SessionToolRunner_1 = require("../tools/SessionToolRunner");
+Object.defineProperty(exports, "SessionToolRunner", { enumerable: true, get: function () { return SessionToolRunner_1.SessionToolRunner; } });
+Object.defineProperty(exports, "MANAGED_AGENTS_BETA", { enumerable: true, get: function () { return SessionToolRunner_1.MANAGED_AGENTS_BETA; } });
+Object.defineProperty(exports, "DEFAULT_MAX_IDLE_MS", { enumerable: true, get: function () { return SessionToolRunner_1.DEFAULT_MAX_IDLE_MS; } });

package/dist/vendor/lib/environments/poller.cjs

@@ -0,0 +1,226 @@
+"use strict";
+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 error_1 = require("../../core/error");
+const log_1 = require("../../internal/utils/log");
+const sleep_1 = require("../../internal/utils/sleep");
+const uuid_1 = require("../../internal/utils/uuid");
+const abort_1 = require("../../internal/utils/abort");
+const headers_1 = require("../../internal/headers");
+const backoff_1 = require("../../internal/utils/backoff");
+const helper_client_1 = require("../helper-client");
+var backoff_2 = require("../../internal/utils/backoff");
+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 = 60_000;
+const IDLE_REPORT_INTERVAL_MS = 300_000;
+/**
+ * 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).
+ *
+ * A yielded item may carry a per-item `secret` payload (populated only by the
+ * poll response); the poller passes it through untouched — consumers such as
+ * {@link EnvironmentWorker} extract the sessions token it carries and prefer
+ * that over the environment key for the item's downstream calls. Treat it as
+ * opaque and never log it.
+ *
+ * @example
+ * ```ts
+ * for await (const work of client.beta.environments.work.poller({
+ *   environmentId,
+ *   environmentKey,
+ * })) {
+ *   // ...service the work...
+ * }
+ * ```
+ */
+class WorkPoller {
+    client;
+    environmentId;
+    environmentKey;
+    workerId;
+    // 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.
+    #runnerClient;
+    #consumed = false;
+    #controller;
+    #detachExternal;
+    #autoStop;
+    #drain;
+    #blockMs;
+    #reclaimOlderThanMs;
+    #requestOpts;
+    constructor(opts) {
+        this.client = opts.client;
+        this.environmentId = opts.environmentId;
+        this.environmentKey = opts.environmentKey;
+        this.workerId = opts.workerId ?? defaultWorkerId();
+        this.#runnerClient = (0, helper_client_1.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 ? exports.POLL_BLOCK_MS : opts.blockMs;
+        this.#reclaimOlderThanMs = opts.reclaimOlderThanMs ?? null;
+        this.#requestOpts = opts.requestOptions;
+        this.#controller = new AbortController();
+        this.#detachExternal = (0, abort_1.linkAbort)(opts.signal, this.#controller);
+    }
+    /** Read-only view of this iterator's abort signal. */
+    get signal() {
+        return this.#controller.signal;
+    }
+    /** Abort the iterator. The current `for await` will exit cleanly. */
+    abort() {
+        this.#controller.abort();
+    }
+    async *[Symbol.asyncIterator]() {
+        if (this.#consumed) {
+            throw new error_1.PukuError('Cannot iterate over a consumed WorkPoller');
+        }
+        this.#consumed = true;
+        const log = (0, log_1.loggerFor)(this.client);
+        log.info('poller starting', {
+            component: 'work-poller',
+            environment_id: this.environmentId,
+        });
+        const idle = new IdleLog(log, this.environmentId);
+        try {
+            let attempt = 0;
+            while (!this.#controller.signal.aborted) {
+                let work;
+                try {
+                    work = await this.#runnerClient.beta.environments.work.poll(this.environmentId, {
+                        'PukuAI-Worker-ID': this.workerId,
+                        ...(this.#blockMs !== null ? { block_ms: this.#blockMs } : {}),
+                        ...(this.#reclaimOlderThanMs !== null ?
+                            { reclaim_older_than_ms: this.#reclaimOlderThanMs }
+                            : {}),
+                    }, { headers: (0, headers_1.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 ((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, this.#controller.signal);
+                    continue;
+                }
+                attempt = 0;
+                if (work == null) {
+                    // Queue empty: either return now (drain) or wait and poll again.
+                    if (this.#drain)
+                        return;
+                    idle.onEmptyPoll();
+                    await (0, sleep_1.sleep)((0, backoff_1.jitter)(1000, 3000), this.#controller.signal);
+                    continue;
+                }
+                idle.onClaim();
+                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: (0, headers_1.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: (0, headers_1.buildHeaders)([this.#requestOpts?.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.
+            this.#detachExternal();
+        }
+    }
+}
+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);
+}
+/**
+ * Keeps an idle poll loop visible in the logs without an INFO line per poll:
+ * the first empty poll after start-up or after a claim logs at INFO and later
+ * ones at DEBUG, with an INFO reminder every `IDLE_REPORT_INTERVAL_MS` while
+ * the loop stays idle.
+ */
+class IdleLog {
+    #log;
+    #environmentId;
+    #idleSince;
+    #lastReport = 0;
+    constructor(log, environmentId) {
+        this.#log = log;
+        this.#environmentId = environmentId;
+    }
+    onEmptyPoll() {
+        const now = Date.now();
+        const fields = { component: 'work-poller', environment_id: this.#environmentId };
+        if (this.#idleSince === undefined) {
+            this.#idleSince = this.#lastReport = now;
+            this.#log.info('idle; polling for work', fields);
+        }
+        else if (now - this.#lastReport >= IDLE_REPORT_INTERVAL_MS) {
+            this.#lastReport = now;
+            this.#log.info(`still polling; idle for ${Math.round((now - this.#idleSince) / 1000)}s`, fields);
+        }
+        else {
+            this.#log.debug('poll returned no work', fields);
+        }
+    }
+    onClaim() {
+        this.#idleSince = undefined;
+    }
+}
+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)();
+}