@puku-ai/sdk 4.0.0 → 4.0.2

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

@@ -0,0 +1,572 @@
+import { PukuError, APIError } from '../../core/error.js';
+import { loggerFor } from '../../internal/utils/log.js';
+import { fromBase64 } from '../../internal/utils/base64.js';
+import { decodeUTF8 } from '../../internal/utils/bytes.js';
+import { readEnv } from '../../internal/utils/env.js';
+import { sleep } from '../../internal/utils/sleep.js';
+import { isFatal4xx, isStatus } from '../../internal/utils/backoff.js';
+import { linkAbort } from '../../internal/utils/abort.js';
+import { isObj } from '../../internal/utils/values.js';
+import { buildHeaders } from '../../internal/headers.js';
+import { SessionToolRunner } from '../tools/SessionToolRunner.js';
+import { WorkPoller } from './poller.js';
+import { copyClientForHelper } from '../helper-client.js';
+import { checkMemorySyncInterval } from '../../tools/agent-toolset/sync-interval.js';
+const HEARTBEAT_DEFAULT_MS = 30_000;
+const HEARTBEAT_TTL_DEFAULT_MS = 90_000;
+const NO_HEARTBEAT_SENTINEL = 'NO_HEARTBEAT';
+/** True when the session has at least one memory store attached. */
+function hasMemoryStore(session) {
+    return session.resources.some((r) => r.type === 'memory_store');
+}
+/**
+ * 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 function sessionsTokenFromSecret(secret) {
+    if (!secret)
+        return null;
+    let parsed;
+    try {
+        // The payload may arrive URL-safe and without base64 padding; normalize
+        // both before decoding.
+        const normalized = secret.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+        parsed = JSON.parse(decodeUTF8(fromBase64(padded)));
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    // The payload is untrusted input, so the token is still checked at runtime
+    // rather than trusted to match the schema.
+    const token = parsed.sessions_token;
+    return typeof token === 'string' && token !== '' ? token : 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 class EnvironmentWorker {
+    client;
+    environmentId;
+    environmentKey;
+    tools;
+    workdir;
+    /** @deprecated Never set; see {@link EnvironmentWorkerOptions.unrestrictedPaths}. */
+    unrestrictedPaths;
+    maxFileBytes;
+    maxIdleMs;
+    memorySyncIntervalMs;
+    memorySyncDeletions;
+    workerId;
+    requestOptions;
+    #signal;
+    constructor(opts) {
+        if (opts.unrestrictedPaths !== undefined) {
+            throw new PukuError('The `unrestrictedPaths` option you passed to EnvironmentWorker (or ' +
+                'client.beta.environments.work.worker()) is no longer supported. ' +
+                "The worker's file tools (read, write, edit, glob, grep) are now always confined to `workdir` " +
+                "plus the session's memory folders. Remove `unrestrictedPaths` from your options; to let the " +
+                'file tools reach any other directory, add it to `AgentToolContext.allowedRoots` from a ' +
+                '`tools` factory.');
+        }
+        this.client = opts.client;
+        this.environmentId = opts.environmentId;
+        this.environmentKey = opts.environmentKey;
+        this.tools = opts.tools;
+        this.workdir = opts.workdir ?? process.cwd();
+        this.maxFileBytes = opts.maxFileBytes;
+        this.maxIdleMs = opts.maxIdleMs;
+        if (opts.memorySyncIntervalMs != null) {
+            checkMemorySyncInterval(opts.memorySyncIntervalMs, 'memorySyncIntervalMs');
+        }
+        this.memorySyncIntervalMs = opts.memorySyncIntervalMs;
+        this.memorySyncDeletions = opts.memorySyncDeletions ?? 'enabled';
+        this.workerId = opts.workerId;
+        this.requestOptions = opts.requestOptions;
+        this.#signal = opts.signal;
+    }
+    /**
+     * Poll the environment and service each claimed session until the supplied
+     * signal (or the one passed to the constructor) aborts. Throws if
+     * `environmentId` / `environmentKey` were not provided to the constructor.
+     */
+    async run(signal) {
+        const { environmentId, environmentKey } = this;
+        if (environmentId === undefined || environmentKey === undefined) {
+            throw new PukuError('EnvironmentWorker.run: environmentId and environmentKey are required to poll for work');
+        }
+        const externalSignal = signal ?? this.#signal;
+        const poller = new WorkPoller({
+            client: this.client,
+            environmentId,
+            environmentKey,
+            ...(this.workerId !== undefined ? { workerId: this.workerId } : {}),
+            ...(externalSignal ? { signal: externalSignal } : {}),
+            ...(this.requestOptions !== undefined ? { requestOptions: this.requestOptions } : {}),
+            // The per-item handler stops or releases every work item on exit; let it
+            // be the single owner of `work.stop` rather than double-posting from the
+            // poller.
+            autoStop: false,
+        });
+        for await (const work of poller) {
+            try {
+                await this.#handleItem(work, environmentKey, poller.signal);
+            }
+            catch (e) {
+                // One bad item fails that item, not the worker: the handler's teardown
+                // already stopped or released it, so the next poll claims the next
+                // item. A store directory left behind by a killed worker would
+                // otherwise crashloop this process forever.
+                if (poller.signal?.aborted)
+                    throw e;
+                loggerFor(this.client).error('work item failed', { work_id: work.id, error: String(e) });
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async handleItem(opts) {
+        const workId = opts?.workId ?? readEnv('PUKU_WORK_ID');
+        const environmentId = opts?.environmentId ?? readEnv('PUKU_ENVIRONMENT_ID');
+        const sessionId = opts?.sessionId ?? readEnv('PUKU_SESSION_ID');
+        const environmentKey = opts?.environmentKey ?? this.environmentKey ?? readEnv('PUKU_ENVIRONMENT_KEY');
+        // `||` rather than `??` so an empty option still falls through to the env
+        // var and then to null (matching how `readEnv` treats empty values).
+        const workSecret = opts?.workSecret || readEnv('PUKU_WORK_SECRET') || null;
+        if (!workId) {
+            throw new PukuError('handleItem: workId is required — pass it or set PUKU_WORK_ID');
+        }
+        if (!environmentId) {
+            throw new PukuError('handleItem: environmentId is required — pass it or set PUKU_ENVIRONMENT_ID');
+        }
+        if (!sessionId) {
+            throw new PukuError('handleItem: sessionId is required — pass it or set PUKU_SESSION_ID');
+        }
+        if (!environmentKey) {
+            throw new PukuError('handleItem: environmentKey is required — pass it, construct the worker with it, or set PUKU_ENVIRONMENT_KEY');
+        }
+        const work = {
+            id: workId,
+            environment_id: environmentId,
+            secret: workSecret,
+            data: { type: 'session', id: sessionId },
+        };
+        await this.#handleItem(work, environmentKey, opts?.signal ?? this.#signal);
+    }
+    /**
+     * The per-item body shared by {@link EnvironmentWorker.run}'s poll loop and
+     * {@link EnvironmentWorker.handleItem}: run a {@link SessionToolRunner} for the
+     * work item's session while heartbeating its lease, force-stopping on exit
+     * unless the lease was lost. Non-session work items are ignored.
+     *
+     * When the poll response carried a per-item `secret` (a short-lived payload
+     * scoped to this work item), the sessions token extracted from it is
+     * preferred over `environmentKey` as the Bearer credential for those
+     * per-item calls; a missing/undecodable secret falls back to
+     * `environmentKey` unchanged.
+     */
+    async #handleItem(work, environmentKey, externalSignal) {
+        const log = loggerFor(this.client);
+        // The per-item credential: the sessions token carried inside the work
+        // item's secret payload when the server issued one, otherwise the
+        // environment key. Never log this value.
+        const sessionsToken = sessionsTokenFromSecret(work.secret);
+        if (work.secret && sessionsToken === null) {
+            log.warn('work item carried a secret payload but no sessions token could be extracted; ' +
+                'falling back to the environment key', { work_id: work.id });
+        }
+        const itemCredential = sessionsToken ?? environmentKey;
+        // Every per-session call — the SessionToolRunner event stream/list/send, the
+        // lease heartbeat, the skill download, and the work force-stop —
+        // authenticates with the per-item credential. Scope a client to it once and
+        // thread that through. `copyClientForHelper` also clears the parent's
+        // `apiKey`, so the sub-client emits *only* the bearer credential on the
+        // wire (a plain `withOptions({authToken})` would leave `X-Api-Key` set as
+        // well).
+        const sessionClient = copyClientForHelper(this.client, {
+            authToken: itemCredential,
+            helper: 'environments-worker',
+        });
+        // The poller runs with `autoStop: false`, so the per-item handler is the
+        // single owner of `work.stop` for every claimed item.
+        const sessionId = work.data.id;
+        // A per-session controller: aborts when the supplied signal aborts, when the
+        // session runner finishes, or when the lease heartbeat says to stop.
+        const ctrl = new AbortController();
+        const detachExternal = linkAbort(externalSignal, ctrl);
+        const lease = new Lease(ctrl);
+        // Lazily load the Node-only toolset module — see the import note at the top.
+        const agentToolset = await import('../../tools/agent-toolset/node.js');
+        // Start the lease heartbeat BEFORE the session fetch and the skill /
+        // memory downloads: those can take longer than the lease TTL, and an
+        // unheartbeated lease lapsing mid-download would let another worker
+        // reclaim the item and serve the same session (split-brain).
+        //
+        // Each heartbeat reports the lease TTL the server is enforcing; it becomes
+        // the runner's tool-result send retry window so a send keeps retrying
+        // exactly as long as the lease could still be live. The runner is only
+        // built after the downloads, so hold the latest TTL until then.
+        let leaseTtlMs;
+        let runner;
+        const heartbeatPromise = heartbeatLoop(sessionClient, work, lease, log, this.requestOptions, (ttlMs) => {
+            leaseTtlMs = ttlMs;
+            runner?._setSendRetryWindow(ttlMs);
+        }).catch((e) => {
+            if (!ctrl.signal.aborted)
+                log.error('heartbeat loop failed', { work_id: work.id, error: String(e) });
+            ctrl.abort();
+        });
+        let cleanupSkills = async () => { };
+        let stores;
+        let cleanEnd = false;
+        try {
+            if (work.data.type !== 'session') {
+                log.debug('skipping non-session work item', { work_id: work.id, type: work.data.type });
+                return;
+            }
+            // One session fetch, shared by the skills download and the memory-store
+            // download — two fetches could disagree about the attached resources.
+            // A failed fetch fails the work item (the teardown below still stops
+            // or releases it).
+            const session = await sessionClient.beta.sessions.retrieve(sessionId);
+            // Only with the session in hand can we tell one that simply has no
+            // memory from one whose memory we cannot mount. Turning memory off
+            // with the interval knob is a deliberate opt-out and stays quiet.
+            if (sessionsToken === null && this.memorySyncIntervalMs !== null && hasMemoryStore(session)) {
+                throw new agentToolset.SessionMemoryError(`cannot mount the session's memories: the work item carried no sessions token ` +
+                    `(work_id=${work.id}, session_id=${sessionId}); ` +
+                    'the memory endpoints reject the environment key, so the poller must issue a per-item ' +
+                    '`secret` carrying `sessions_token`, or set `memorySyncIntervalMs: null` to run without memory');
+            }
+            const ctx = {
+                workdir: this.workdir,
+                // The scoped sub-client, not the parent: the skill download
+                // `setupSkills` performs for this session rides the same per-item
+                // credential as every other per-item call.
+                client: sessionClient,
+                session,
+                ...(this.maxFileBytes !== undefined ? { maxFileBytes: this.maxFileBytes } : {}),
+            };
+            try {
+                cleanupSkills = await agentToolset.setupSkills(ctx);
+            }
+            catch (e) {
+                log.warn('skill setup failed', { session_id: sessionId, work_id: work.id, error: String(e) });
+            }
+            // Memory stores: the memory_stores endpoints accept the per-item sessions
+            // token but reject the environment key, so download and sync only run when
+            // the item carried a usable secret (and the interval is set).
+            // `sessionClient` is already scoped to that token then, so the memory
+            // calls ride the same sub-client. A store that cannot be materialised
+            // throws `SessionMemoryError` out of `download` and fails the item.
+            if (sessionsToken !== null && this.memorySyncIntervalMs !== null) {
+                stores = new agentToolset.SessionMemoryStores(sessionClient, {
+                    workdir: this.workdir,
+                    ...(this.memorySyncIntervalMs !== undefined ? { syncIntervalMs: this.memorySyncIntervalMs } : {}),
+                    syncDeletions: this.memorySyncDeletions,
+                });
+                await stores.download(session);
+                // A store mounted outside the workdir must stay reachable by the file
+                // tools; read-only stores still refuse writes.
+                ctx.allowedRoots = stores.roots;
+                ctx.readOnlyRoots = stores.readOnlyRoots;
+            }
+            else {
+                log.debug('memory stores disabled for this item', { work_id: work.id });
+            }
+            const tools = typeof this.tools === 'function' ?
+                this.tools(ctx)
+                : this.tools ?? agentToolset.betaAgentToolset20260401(ctx);
+            runner = new SessionToolRunner(sessionId, {
+                client: sessionClient,
+                tools,
+                ...(this.maxIdleMs !== undefined ? { maxIdleMs: this.maxIdleMs } : {}),
+                ...(this.requestOptions !== undefined ? { requestOptions: this.requestOptions } : {}),
+                signal: ctrl.signal,
+            });
+            if (leaseTtlMs !== undefined)
+                runner._setSendRetryWindow(leaseTtlMs);
+            for await (const _ of runner) {
+                // Drive the runner to completion; per-call observability is not part
+                // of this composition's surface — use `SessionToolRunner` directly
+                // (via `client.beta.sessions.events.toolRunner`) if you want it.
+                if (stores)
+                    await stores.syncIfDue();
+            }
+            // Only a clean stream end earns the last full sync; it runs in the
+            // teardown below.
+            cleanEnd = !ctrl.signal.aborted;
+        }
+        finally {
+            // The heartbeat keeps the lease alive until this teardown is done.
+            try {
+                // cleanupSkills first, so its failure cannot skip the memory flush.
+                await cleanupSkills().catch((e) => {
+                    log.warn('skill cleanup failed', { session_id: sessionId, work_id: work.id, error: String(e) });
+                });
+            }
+            finally {
+                if (stores) {
+                    const boundMs = agentToolset.MEMORY_FLUSH_TIMEOUT_MS;
+                    if (cleanEnd) {
+                        const finishCutOff = await withTimeout(stores.finish(), boundMs);
+                        if (finishCutOff) {
+                            log.warn(`final memory sync cut off after ${boundMs}ms; the flush that follows still uploads changed files`, { session_id: sessionId, work_id: work.id });
+                        }
+                    }
+                    // Also after finish(): it swallows its own failures, and a
+                    // clean flush is a no-op.
+                    const flushBound = new AbortController();
+                    const flushCutOff = await withTimeout(stores.flushWrites(flushBound.signal), boundMs);
+                    if (flushCutOff) {
+                        flushBound.abort();
+                        log.warn(`memory flush cut off after ${boundMs}ms; changed files it had not uploaded yet are not saved`, { session_id: sessionId, work_id: work.id });
+                    }
+                    await stores.dispose().catch((e) => {
+                        log.warn('memory store cleanup failed', {
+                            session_id: sessionId,
+                            work_id: work.id,
+                            error: String(e),
+                        });
+                    });
+                }
+            }
+            lease.finish('runner_done');
+            detachExternal();
+            await heartbeatPromise;
+            // Stop only an item this worker still holds — after a lost lease it
+            // belongs to the queue or another worker.
+            if (lease.lost) {
+                log.info('lease lost; released without stopping it', { session_id: sessionId, work_id: work.id });
+            }
+            else {
+                await forceStop(sessionClient, work, log, this.requestOptions);
+            }
+        }
+    }
+}
+/**
+ * Resolve when `p` settles or `ms` elapses — `true` when `ms` elapsed
+ * first. A timed-out `p` keeps running — JS cannot cancel a promise.
+ */
+async function withTimeout(p, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            p.then(() => false, () => false),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(true), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** Force-stop a claimed work item, swallowing the 409 that means it's already stopped. */
+async function forceStop(client, work, log, requestOptions) {
+    try {
+        await client.beta.environments.work.stop(work.id, { environment_id: work.environment_id, force: true }, 
+        // Caller's headers pass through; the helper-tag header is on the scoped
+        // sub-client's default_headers via copyClientForHelper, so no per-call
+        // re-stamping needed.
+        { ...requestOptions, headers: buildHeaders([requestOptions?.headers]) });
+    }
+    catch (e) {
+        if (!isStatus(e, 409)) {
+            log.error('force-stop on exit failed', { work_id: work.id, error: String(e) });
+        }
+    }
+}
+/**
+ * This worker's view of one work-item lease: the per-item abort signal plus
+ * why heartbeating ended. The first recorded reason wins, so a run aborted
+ * *because* the lease was lost still reads as lost afterwards; an abort with
+ * no recorded reason (the external signal) is not lost.
+ */
+class Lease {
+    #ctrl;
+    #endReason;
+    constructor(ctrl) {
+        this.#ctrl = ctrl;
+    }
+    get signal() {
+        return this.#ctrl.signal;
+    }
+    finish(reason) {
+        this.#endReason ??= reason;
+        this.#ctrl.abort();
+    }
+    /** True once the item belongs to the queue or another worker. */
+    get lost() {
+        return this.#endReason === 'lease_lost' || this.#endReason === 'assumed_lost';
+    }
+}
+/** The server's view of the lease carried by a 412 heartbeat response, or empty if absent. */
+function serverLeaseState(e) {
+    let node = e instanceof APIError ? e.error : undefined;
+    for (const key of ['error', 'details', 'current_state']) {
+        if (!isObj(node))
+            return {};
+        node = node[key];
+    }
+    return isObj(node) ? node : {};
+}
+/**
+ * Keep the work-item lease alive while a session is being served. Runs until
+ * `lease` ends, and ends it itself when the control plane reports the work is
+ * `stopping`/`stopped` or no longer extends the lease, when a heartbeat is
+ * rejected (a 412 means the lease already belongs to someone else), or when no
+ * heartbeat has succeeded for longer than the lease ttl (the lease is assumed
+ * lost, so two runners don't end up serving the same work). Each heartbeat
+ * call is cut off after the current beat interval so a hung request cannot
+ * outlive the lease it is meant to renew.
+ */
+async function heartbeatLoop(client, work, lease, logger, requestOptions, 
+/** Called with the server-reported lease TTL after every successful beat. */
+onLeaseTtl) {
+    let intervalMs = HEARTBEAT_DEFAULT_MS;
+    let ttlMs = HEARTBEAT_TTL_DEFAULT_MS;
+    let lastSuccessMs = Date.now();
+    let last = NO_HEARTBEAT_SENTINEL;
+    const beat = async () => {
+        // Not the request `timeout` option: the core client retries timeouts, so
+        // it would not bound the call as a whole.
+        const beatCtrl = new AbortController();
+        const detach = linkAbort(lease.signal, beatCtrl);
+        const cutoff = setTimeout(() => beatCtrl.abort(), intervalMs);
+        try {
+            const resp = await client.beta.environments.work.heartbeat(work.id, { environment_id: work.environment_id, expected_last_heartbeat: last }, { ...requestOptions, headers: buildHeaders([requestOptions?.headers]), signal: beatCtrl.signal });
+            lastSuccessMs = Date.now();
+            last = resp.last_heartbeat;
+            if (resp.ttl_seconds > 0) {
+                ttlMs = resp.ttl_seconds * 1000;
+                intervalMs = Math.max(1_000, Math.min(ttlMs / 2, HEARTBEAT_DEFAULT_MS));
+                onLeaseTtl?.(ttlMs);
+            }
+            if (resp.state === 'stopping' || resp.state === 'stopped') {
+                logger.info('heartbeat signals shutdown', { work_id: work.id, state: resp.state });
+                lease.finish('control_plane_stop');
+            }
+            if (!resp.lease_extended) {
+                logger.warn('lease not extended, shutting down', { work_id: work.id });
+                lease.finish('control_plane_stop');
+            }
+        }
+        catch (e) {
+            // An abort throws to unwind the caller (the `heartbeatLoop(...).catch`
+            // in `#handleItem`) rather than returning early.
+            lease.signal.throwIfAborted();
+            if (isStatus(e, 412)) {
+                const server = serverLeaseState(e);
+                logger.error('lease lost: heartbeat precondition failed', {
+                    work_id: work.id,
+                    server_state: server['state'],
+                    server_ttl_seconds: server['ttl_seconds'],
+                    server_last_heartbeat: server['last_heartbeat'],
+                });
+                lease.finish('lease_lost');
+                return;
+            }
+            if (isFatal4xx(e)) {
+                logger.error('permanent heartbeat failure', { work_id: work.id, error: String(e) });
+                lease.finish('heartbeat_rejected');
+                throw e;
+            }
+            if (Date.now() - lastSuccessMs > ttlMs) {
+                logger.error('lease assumed lost: no successful heartbeat in ttl', {
+                    work_id: work.id,
+                    ttl_ms: ttlMs,
+                    error: String(e),
+                });
+                lease.finish('assumed_lost');
+                return;
+            }
+            logger.warn('transient heartbeat failure', { work_id: work.id, error: String(e) });
+        }
+        finally {
+            clearTimeout(cutoff);
+            detach();
+        }
+    };
+    await beat();
+    while (!lease.signal.aborted) {
+        await sleep(intervalMs, lease.signal);
+        lease.signal.throwIfAborted();
+        await beat();
+    }
+}
+//# sourceMappingURL=worker.js.map

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

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

package/dist/vendor/lib/helper-client.d.ts

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