@puku-ai/sdk 4.0.0 → 4.0.2

package/dist/vendor/lib/environments/poller.d.ts

@@ -0,0 +1,94 @@
+import type { PukuAI } from '../../client';
+import type { BetaSelfHostedWork } from '../../resources/beta/environments/work';
+import type { BetaToolRunnerRequestOptions } from '../tools/BetaToolRunner';
+export { is4xx, isFatal4xx, isStatus, jitter } from '../../internal/utils/backoff';
+export declare const POLL_BLOCK_MS = 999;
+export interface WorkPollerOptions {
+    client: PukuAI;
+    environmentId: string;
+    /**
+     * The environment key — the single credential for the self-hosted runner. It
+     * authenticates the work-poll calls here and every per-session call the
+     * consumer makes afterwards.
+     */
+    environmentKey: string;
+    workerId?: string;
+    /** External abort signal. Aborting it ends the iteration. */
+    signal?: AbortSignal;
+    /**
+     * Whether the poller posts `work.stop` itself after the consumer's loop body
+     * returns. Defaults to `true`. Set `false` when the consumer already owns the
+     * stop (e.g. {@link EnvironmentWorker} force-stops every item) so the work
+     * item is not stopped twice.
+     *
+     * Orthogonal to {@link WorkPollerOptions.drain}: `autoStop` is a per-item
+     * lifecycle flag (does the poller `work.stop` each item), `drain` controls
+     * loop termination (does the poller return when the queue is empty). They are
+     * not two names for the same thing — `EnvironmentWorker.run` uses
+     * `autoStop: false` with `drain` defaulting `false`.
+     */
+    autoStop?: boolean;
+    /**
+     * When `true`, the poller returns (ends iteration) as soon as the work queue
+     * is empty instead of long-polling forever. Defaults to `false` (long-poll
+     * until aborted). Pair with `blockMs: null` for a single non-blocking pass
+     * over whatever is already queued.
+     */
+    drain?: boolean;
+    /**
+     * Block timeout in milliseconds passed through to `work.poll` — the server
+     * long-polls up to this long for an item before returning empty. Defaults to
+     * {@link POLL_BLOCK_MS} (the API cap, 999). Pass `null` to omit it entirely
+     * for a non-blocking single poll (useful with {@link WorkPollerOptions.drain}).
+     */
+    blockMs?: number | null;
+    /**
+     * Reclaim unacknowledged work items older than this many milliseconds, passed
+     * through to `work.poll`'s `reclaim_older_than_ms`. Defaults to `undefined`
+     * (omitted — the server applies its own default).
+     */
+    reclaimOlderThanMs?: number | null;
+    /**
+     * Extra per-request options merged into the poll/ack/stop calls. Custom
+     * `headers` (e.g. a proxy's auth/routing headers) are layered on top of the
+     * environment-key auth + helper telemetry headers; the poller owns the abort
+     * signal, so a `signal` here is ignored.
+     */
+    requestOptions?: BetaToolRunnerRequestOptions;
+}
+/**
+ * Async-iterable that long-polls a self-hosted environment for work, ack's
+ * each item, yields the {@link BetaSelfHostedWork} item, and posts `stop` after
+ * the consumer's loop body returns (or when the consumer `break`s).
+ *
+ * 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...
+ * }
+ * ```
+ */
+export declare class WorkPoller implements AsyncIterable<BetaSelfHostedWork> {
+    #private;
+    readonly client: PukuAI;
+    readonly environmentId: string;
+    readonly environmentKey: string;
+    readonly workerId: string;
+    constructor(opts: WorkPollerOptions);
+    /** Read-only view of this iterator's abort signal. */
+    get signal(): AbortSignal;
+    /** Abort the iterator. The current `for await` will exit cleanly. */
+    abort(): void;
+    [Symbol.asyncIterator](): AsyncIterator<BetaSelfHostedWork>;
+}
+/** Exponential poll backoff: 1s, 2s, 4s … clamped to a 60s cap. */
+export declare function backoff(attempt: number): number;

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

@@ -0,0 +1,218 @@
+import { PukuError } from '../../core/error.js';
+import { loggerFor } from '../../internal/utils/log.js';
+import { sleep } from '../../internal/utils/sleep.js';
+import { uuid4 } from '../../internal/utils/uuid.js';
+import { linkAbort } from '../../internal/utils/abort.js';
+import { buildHeaders } from '../../internal/headers.js';
+import { applyJitter, backoff as expBackoff, isFatal4xx, isStatus, jitter, } from '../../internal/utils/backoff.js';
+import { copyClientForHelper } from '../helper-client.js';
+export { is4xx, isFatal4xx, isStatus, jitter } from '../../internal/utils/backoff.js';
+// API caps block_ms at 999; rely on client-side jitter between empty polls.
+export const POLL_BLOCK_MS = 999;
+const POLL_BACKOFF_BASE_MS = 1000;
+const POLL_BACKOFF_CAP_MS = 60_000;
+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...
+ * }
+ * ```
+ */
+export 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 = copyClientForHelper(opts.client, {
+            authToken: opts.environmentKey,
+            helper: 'environments-work-poller',
+        });
+        this.#autoStop = opts.autoStop ?? true;
+        this.#drain = opts.drain ?? false;
+        // `undefined` => default to the API cap; an explicit `null` => omit
+        // `block_ms` for a non-blocking poll.
+        this.#blockMs = opts.blockMs === undefined ? POLL_BLOCK_MS : opts.blockMs;
+        this.#reclaimOlderThanMs = opts.reclaimOlderThanMs ?? null;
+        this.#requestOpts = opts.requestOptions;
+        this.#controller = new AbortController();
+        this.#detachExternal = linkAbort(opts.signal, this.#controller);
+    }
+    /** Read-only view of this iterator's abort signal. */
+    get signal() {
+        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 PukuError('Cannot iterate over a consumed WorkPoller');
+        }
+        this.#consumed = true;
+        const log = loggerFor(this.client);
+        log.info('poller starting', {
+            component: 'work-poller',
+            environment_id: this.environmentId,
+        });
+        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: buildHeaders([this.#requestOpts?.headers]), signal: this.#controller.signal });
+                }
+                catch (e) {
+                    if (this.#controller.signal.aborted)
+                        return;
+                    // A bad environment key / missing environment never recovers — surface
+                    // it instead of spinning forever at the backoff cap.
+                    if (isFatal4xx(e)) {
+                        log.error('poll failed permanently, stopping poller', { error: String(e) });
+                        throw e;
+                    }
+                    // Jittered exponential backoff so a fleet of pollers doesn't retry in
+                    // lockstep after a shared outage.
+                    const wait = applyJitter(backoff(attempt));
+                    log.warn('poll failed, backing off', { error: String(e), backoff_ms: wait });
+                    attempt++;
+                    await sleep(wait, this.#controller.signal);
+                    continue;
+                }
+                attempt = 0;
+                if (work == null) {
+                    // Queue empty: either return now (drain) or wait and poll again.
+                    if (this.#drain)
+                        return;
+                    idle.onEmptyPoll();
+                    await sleep(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: buildHeaders([this.#requestOpts?.headers]), signal: this.#controller.signal });
+                }
+                catch (e) {
+                    log.error('ack failed', { work_id: work.id, error: String(e) });
+                    continue;
+                }
+                try {
+                    yield work;
+                }
+                finally {
+                    // Post-handler stop. Runs whether the consumer body returned
+                    // normally, threw, or `break`d out of the loop — unless the consumer
+                    // owns the stop itself (`autoStop: false`).
+                    if (this.#autoStop) {
+                        try {
+                            await this.#runnerClient.beta.environments.work.stop(work.id, { environment_id: work.environment_id }, { headers: buildHeaders([this.#requestOpts?.headers]) });
+                        }
+                        catch (e) {
+                            if (!isStatus(e, 409))
+                                log.warn('stop failed', { work_id: work.id, error: String(e) });
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            // Detach from the external signal so the consumer can drop their
+            // signal reference without leaking this iterator instance.
+            this.#detachExternal();
+        }
+    }
+}
+/** Exponential poll backoff: 1s, 2s, 4s … clamped to a 60s cap. */
+export function backoff(attempt) {
+    return expBackoff(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}-${uuid4()}` : uuid4();
+}
+//# sourceMappingURL=poller.js.map

package/dist/vendor/lib/environments/poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.js","sourceRoot":"","sources":["../../../../src/vendor/lib/environments/poller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAE,SAAS,EAAe,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EACL,WAAW,EACX,OAAO,IAAI,UAAU,EACrB,UAAU,EACV,QAAQ,EACR,MAAM,GACP,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAEnF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAClC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AACnC,MAAM,uBAAuB,GAAG,OAAO,CAAC;AAwDxC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,UAAU;IACZ,MAAM,CAAS;IACf,aAAa,CAAS;IACtB,cAAc,CAAS;IACvB,QAAQ,CAAS;IAE1B,yEAAyE;IACzE,wEAAwE;IACxE,uEAAuE;IACvE,0EAA0E;IACjE,aAAa,CAAS;IAC/B,SAAS,GAAG,KAAK,CAAC;IACT,WAAW,CAAkB;IAC7B,eAAe,CAAa;IAC5B,SAAS,CAAU;IACnB,MAAM,CAAU;IAChB,QAAQ,CAAgB;IACxB,mBAAmB,CAAgB;IACnC,YAAY,CAA2C;IAEhE,YAAY,IAAuB;QACjC,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,IAAI,CAAC,aAAa,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE;YACpD,SAAS,EAAE,IAAI,CAAC,cAAc;YAC9B,MAAM,EAAE,0BAA0B;SACnC,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;QAClC,oEAAoE;QACpE,sCAAsC;QACtC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QAC1E,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC;QAC3D,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAClE,CAAC;IAED,sDAAsD;IACtD,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;IACjC,CAAC;IAED,qEAAqE;IACrE,KAAK;QACH,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,MAAM,GAAG,GAAG,SAAS,CAAC,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;QACH,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAElD,IAAI,CAAC;YACH,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACxC,IAAI,IAA+B,CAAC;gBACpC,IAAI,CAAC;oBACH,IAAI,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CACzD,IAAI,CAAC,aAAa,EAClB;wBACE,kBAAkB,EAAE,IAAI,CAAC,QAAQ;wBACjC,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC9D,GAAG,CAAC,IAAI,CAAC,mBAAmB,KAAK,IAAI,CAAC,CAAC;4BACrC,EAAE,qBAAqB,EAAE,IAAI,CAAC,mBAAmB,EAAE;4BACrD,CAAC,CAAC,EAAE,CAAC;qBACN,EACD,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CACzF,CAAC;gBACJ,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO;wBAAE,OAAO;oBAC5C,uEAAuE;oBACvE,qDAAqD;oBACrD,IAAI,UAAU,CAAC,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,WAAW,CAAC,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,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;oBAC3C,SAAS;gBACX,CAAC;gBACD,OAAO,GAAG,CAAC,CAAC;gBACZ,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;oBACjB,iEAAiE;oBACjE,IAAI,IAAI,CAAC,MAAM;wBAAE,OAAO;oBACxB,IAAI,CAAC,WAAW,EAAE,CAAC;oBACnB,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;oBACzD,SAAS;gBACX,CAAC;gBACD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,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,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CACjD,IAAI,CAAC,EAAE,EACP,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,EACvC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,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,IAAI,CAAC,SAAS,EAAE,CAAC;wBACnB,IAAI,CAAC;4BACH,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAClD,IAAI,CAAC,EAAE,EACP,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,EACvC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,EAAE,CACxD,CAAC;wBACJ,CAAC;wBAAC,OAAO,CAAC,EAAE,CAAC;4BACX,IAAI,CAAC,QAAQ,CAAC,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,IAAI,CAAC,eAAe,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,UAAU,CAAC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO;IACF,IAAI,CAAS;IACb,cAAc,CAAS;IAChC,UAAU,CAAqB;IAC/B,WAAW,GAAG,CAAC,CAAC;IAEhB,YAAY,GAAW,EAAE,aAAqB;QAC5C,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;IACtC,CAAC;IAED,WAAW;QACT,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;QACjF,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;YACzC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC;QACnD,CAAC;aAAM,IAAI,GAAG,GAAG,IAAI,CAAC,WAAW,IAAI,uBAAuB,EAAE,CAAC;YAC7D,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACnG,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;CACF;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,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;AAC/C,CAAC"}

package/dist/vendor/lib/environments/worker.d.ts

@@ -0,0 +1,226 @@
+import type { PukuAI } from '../../client';
+import type { BetaRunnableTool } from '../tools/BetaRunnableTool';
+import type { BetaToolRunnerRequestOptions } from '../tools/BetaToolRunner';
+import type { AgentToolContext, MemoryDeleteMode } from '../../tools/agent-toolset/node';
+/**
+ * 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: PukuAI;
+    /**
+     * 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 worker's standing credential: polling always
+     * uses it, and per-session calls fall back to it when a claimed item's
+     * `secret` doesn't yield a sessions token. Required by
+     * {@link EnvironmentWorker.run}; falls back to `PUKU_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}).
+     *
+     * A `run` that blocks the event loop synchronously also stalls the lease
+     * heartbeat, and the worker can lose the lease; keep tools non-blocking (see
+     * {@link BetaRunnableTool.run}).
+     */
+    tools?: EnvironmentWorkerTools;
+    /** Base directory for the per-session {@link AgentToolContext}. Defaults to `process.cwd()`. */
+    workdir?: string;
+    /**
+     * @deprecated No longer accepted: the file tools are always confined to
+     * `workdir` plus `allowedRoots`, which is neither behavior this flag used to
+     * select, so passing either value throws. Remove it; list extra directories
+     * in {@link AgentToolContext.allowedRoots}. The property is removed in a
+     * future release.
+     */
+    unrestrictedPaths?: boolean;
+    /** Forwarded to the per-session {@link AgentToolContext} (`maxFileBytes`). */
+    maxFileBytes?: number | null;
+    /** Forwarded to {@link SessionToolRunner} (`maxIdleMs`). */
+    maxIdleMs?: number;
+    /**
+     * How often (milliseconds) to sync the session's attached memory stores back
+     * while it runs — checked after each dispatched tool call, plus one final
+     * sync when the session ends cleanly. Defaults to
+     * `DEFAULT_MEMORY_SYNC_INTERVAL_MS` (15s); the constructor throws for
+     * values below `MIN_MEMORY_SYNC_INTERVAL_MS` (5s). Every teardown also runs
+     * a push-only flush of changed files; that flush and the final sync are
+     * each bounded by `MEMORY_FLUSH_TIMEOUT_MS`, and a warning is logged when
+     * either bound cuts work off. `null` disables memory download and sync
+     * entirely. Memory stores are only touched for work items whose `secret`
+     * carries a `sessions_token`; while sync is enabled, an item without one
+     * fails when its session has memory stores attached, because those stores
+     * cannot be mounted without the token. With `null` the same item runs,
+     * without memory, and nothing is logged — turning sync off is the
+     * operator's explicit choice.
+     */
+    memorySyncIntervalMs?: number | null;
+    /**
+     * Whether local file deletions may delete on the server — see
+     * {@link MemoryDeleteMode}. Uploads and pulls are unaffected.
+     * Defaults to `"enabled"`.
+     */
+    memorySyncDeletions?: MemoryDeleteMode;
+    /** 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 `PUKU_*` 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 `PUKU_WORK_ID`. */
+    workId?: string;
+    /** Self-hosted environment id. Falls back to `PUKU_ENVIRONMENT_ID`. */
+    environmentId?: string;
+    /** Session id. Falls back to `PUKU_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
+     * `PUKU_ENVIRONMENT_KEY`.
+     */
+    environmentKey?: string;
+    /**
+     * The work item's per-item `secret` payload from the poll response. Falls
+     * back to `PUKU_WORK_SECRET`. Unlike the others it is optional — when
+     * present, the sessions token extracted from it is preferred as the Bearer
+     * credential for this item's heartbeat / force-stop / skill-download /
+     * session calls; when absent (or undecodable) those calls use the
+     * environment key.
+     */
+    workSecret?: string;
+    /** External abort signal; aborting it ends the run. Defaults to the constructor's signal. */
+    signal?: AbortSignal;
+}
+/**
+ * Extract the per-item sessions token from a work item's `secret` payload.
+ *
+ * The `secret` the poll response populates is not itself a credential: it is a
+ * URL-safe base64 JSON payload matching {@link BetaWorkSecret} — the
+ * `sessions_token` (the bearer for this item's work lifecycle and
+ * session-level calls) plus fields this worker does not consume. Returns the
+ * sessions token, or `null` (meaning: fall back to the environment key) when
+ * the payload is missing, doesn't decode, or carries no token. Never log the
+ * payload or anything extracted from it.
+ */
+export declare function sessionsTokenFromSecret(secret: string | null | undefined): string | null;
+/**
+ * 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 on the same event loop; on exit it
+ * force-stops the work item (unless the lease was lost, in which case the item
+ * is left to whoever holds it now), 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.
+ *
+ * The `environmentKey` is the worker's standing credential. When a claimed
+ * work item carries a per-item `secret` (a short-lived payload the poll
+ * response may populate), the sessions token extracted from it is preferred
+ * over the environment key for that item's heartbeat / force-stop /
+ * skill-download / session calls; polling itself always uses the environment
+ * key, and items without a usable secret fall back to it entirely.
+ *
+ * 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 `PUKU_*` env vars that command sets.
+ *
+ * Construct it via `client.beta.environments.work.worker({ ... })` (or
+ * `new EnvironmentWorker({ client, ... })` directly).
+ *
+ * @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: PukuAI;
+    readonly environmentId: string | undefined;
+    readonly environmentKey: string | undefined;
+    readonly tools: EnvironmentWorkerTools | undefined;
+    readonly workdir: string;
+    /** @deprecated Never set; see {@link EnvironmentWorkerOptions.unrestrictedPaths}. */
+    readonly unrestrictedPaths: boolean | undefined;
+    readonly maxFileBytes: number | null | undefined;
+    readonly maxIdleMs: number | undefined;
+    readonly memorySyncIntervalMs: number | null | undefined;
+    readonly memorySyncDeletions: MemoryDeleteMode;
+    readonly workerId: string | undefined;
+    readonly requestOptions: BetaToolRunnerRequestOptions | undefined;
+    constructor(opts: Omit<EnvironmentWorkerOptions, 'unrestrictedPaths'>);
+    /** @deprecated `unrestrictedPaths` is no longer accepted — see {@link EnvironmentWorkerOptions.unrestrictedPaths}. */
+    constructor(opts: Omit<EnvironmentWorkerOptions, 'unrestrictedPaths'> & {
+        unrestrictedPaths: boolean;
+    });
+    /**
+     * 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, and force-stop the work item on exit (whether the runner finishes
+     * normally, throws, or the control plane signals shutdown). The one
+     * exception is a lost lease: the item then belongs to the queue or another
+     * worker and is left alone.
+     *
+     * 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 `PUKU_WORK_ID` /
+     * `PUKU_ENVIRONMENT_ID` / `PUKU_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
+     * `PUKU_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. Throws `SessionMemoryError` when the
+     * session has memory stores attached but they cannot be mounted — the work
+     * item carried no sessions token (unless `memorySyncIntervalMs` turned
+     * memory off), or a store failed to download.
+     *
+     * `workSecret` is the work item's per-item `secret` payload from the poll
+     * response, falling back to `PUKU_WORK_SECRET`; unlike the others it is
+     * optional — when present, the sessions token extracted from it is preferred
+     * as the Bearer credential for this item's heartbeat / force-stop / session
+     * calls; when absent (or undecodable) those calls use the environment key.
+     */
+    handleItem(opts?: HandleItemOptions): Promise<void>;
+}