@oneie/claude 0.9.0 → 0.10.0

package/scripts/node_modules/@anthropic-ai/sdk/src/lib/environments/poller.ts

@@ -1,253 +0,0 @@
-import { AnthropicError } from '../../core/error';
-import type { Anthropic } from '../../client';
-import type { BetaSelfHostedWork } from '../../resources/beta/environments/work';
-import { loggerFor } from '../../internal/utils/log';
-import { sleep } from '../../internal/utils/sleep';
-import { uuid4 } from '../../internal/utils/uuid';
-import { linkAbort } from '../../internal/utils/abort';
-import { buildHeaders } from '../../internal/headers';
-import type { BetaToolRunnerRequestOptions } from '../tools/BetaToolRunner';
-import {
-  applyJitter,
-  backoff as expBackoff,
-  isFatal4xx,
-  isStatus,
-  jitter,
-} from '../../internal/utils/backoff';
-import { copyClientForHelper } from '../helper-client';
-
-export { is4xx, isFatal4xx, isStatus, jitter } from '../../internal/utils/backoff';
-
-// 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;
-
-export interface WorkPollerOptions {
-  client: Anthropic;
-  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).
- *
- * @example
- * ```ts
- * for await (const work of client.beta.environments.work.poller({
- *   environmentId,
- *   environmentKey,
- * })) {
- *   // ...service the work...
- * }
- * ```
- */
-export class WorkPoller implements AsyncIterable<BetaSelfHostedWork> {
-  readonly client: Anthropic;
-  readonly environmentId: string;
-  readonly environmentKey: string;
-  readonly workerId: string;
-
-  // 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.
-  readonly #runnerClient: Anthropic;
-  #consumed = false;
-  readonly #controller: AbortController;
-  readonly #detachExternal: () => void;
-  readonly #autoStop: boolean;
-  readonly #drain: boolean;
-  readonly #blockMs: number | null;
-  readonly #reclaimOlderThanMs: number | null;
-  readonly #requestOpts: BetaToolRunnerRequestOptions | undefined;
-
-  constructor(opts: WorkPollerOptions) {
-    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(): AbortSignal {
-    return this.#controller.signal;
-  }
-
-  /** Abort the iterator. The current `for await` will exit cleanly. */
-  abort(): void {
-    this.#controller.abort();
-  }
-
-  async *[Symbol.asyncIterator](): AsyncIterator<BetaSelfHostedWork> {
-    if (this.#consumed) {
-      throw new AnthropicError('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,
-    });
-
-    try {
-      let attempt = 0;
-      while (!this.#controller.signal.aborted) {
-        let work: BetaSelfHostedWork | null;
-        try {
-          work = await this.#runnerClient.beta.environments.work.poll(
-            this.environmentId,
-            {
-              'Anthropic-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;
-          await sleep(jitter(1000, 3000), this.#controller.signal);
-          continue;
-        }
-        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: number): number {
-  return expBackoff(attempt, POLL_BACKOFF_BASE_MS, POLL_BACKOFF_CAP_MS);
-}
-
-function defaultWorkerId(): string {
-  // 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 as { process?: { env?: Record<string, string | undefined> } }).process?.env;
-  const host = env?.['HOSTNAME'];
-  return host ? `${host}-${uuid4()}` : uuid4();
-}

package/scripts/node_modules/@anthropic-ai/sdk/src/lib/environments/worker.ts

@@ -1,400 +0,0 @@
-import { AnthropicError } from '../../core/error';
-import type { Anthropic } from '../../client';
-import type { BetaSelfHostedWork } from '../../resources/beta/environments/work';
-import { loggerFor, type Logger } from '../../internal/utils/log';
-import { readEnv } from '../../internal/utils/env';
-import { sleep } from '../../internal/utils/sleep';
-import { isFatal4xx, isStatus } from '../../internal/utils/backoff';
-import { linkAbort } from '../../internal/utils/abort';
-import { buildHeaders } from '../../internal/headers';
-import type { BetaRunnableTool } from '../tools/BetaRunnableTool';
-import type { BetaToolRunnerRequestOptions } from '../tools/BetaToolRunner';
-import { SessionToolRunner } from '../tools/SessionToolRunner';
-import { WorkPoller } from './poller';
-import { copyClientForHelper } from '../helper-client';
-// `tools/agent-toolset/node` is Node-only (node:child_process, node:fs, …).
-// Only the type is imported statically (erased at build); the module's values
-// (`setupSkills`, `betaAgentToolset20260401`) are loaded lazily inside the
-// per-item handler. That keeps this file free of Node-only deps in the static
-// import graph, which is what lets `client.beta.environments.work.worker()`
-// exist as a resource method without pulling Node built-ins into the SDK core.
-import type { AgentToolContext } from '../../tools/agent-toolset/node';
-
-const HEARTBEAT_DEFAULT_MS = 30_000;
-const NO_HEARTBEAT_SENTINEL = 'NO_HEARTBEAT';
-
-/**
- * Either a fixed tool array or a factory invoked once per claimed session with
- * that session's {@link AgentToolContext} — use the factory form to bind
- * `betaAgentToolset20260401` (or any tool that needs the workdir / session
- * id) to the right session.
- */
-export type EnvironmentWorkerTools =
-  | Array<BetaRunnableTool>
-  | ((ctx: AgentToolContext) => Array<BetaRunnableTool>);
-
-export interface EnvironmentWorkerOptions {
-  client: Anthropic;
-  /**
-   * The self-hosted environment to poll for work. Required by
-   * {@link EnvironmentWorker.run}; not used by {@link EnvironmentWorker.handleItem}.
-   */
-  environmentId?: string;
-  /**
-   * The environment key — the single credential for the runner. It authenticates
-   * the work-poll calls and every per-session call (event stream, lease
-   * heartbeat, force-stop). Required by {@link EnvironmentWorker.run}; falls back
-   * to `ANTHROPIC_ENVIRONMENT_KEY` in {@link EnvironmentWorker.handleItem}.
-   */
-  environmentKey?: string;
-  /**
-   * Tools to expose to each claimed session. Defaults to
-   * `betaAgentToolset20260401(ctx)` (the standard `agent_toolset_20260401` set
-   * bound to the per-session {@link AgentToolContext}).
-   */
-  tools?: EnvironmentWorkerTools;
-  /** Base directory for the per-session {@link AgentToolContext}. Defaults to `process.cwd()`. */
-  workdir?: string;
-  /** Forwarded to the per-session {@link AgentToolContext}. */
-  unrestrictedPaths?: boolean;
-  /** Forwarded to the per-session {@link AgentToolContext} (`maxFileBytes`). */
-  maxFileBytes?: number | null;
-  /** Forwarded to {@link SessionToolRunner} (`maxIdleMs`). */
-  maxIdleMs?: number;
-  /** Forwarded to the {@link WorkPoller}. */
-  workerId?: string;
-  /** External abort signal; aborting it ends the run. */
-  signal?: AbortSignal;
-  /**
-   * Extra per-request options merged into every call this worker issues — the
-   * work poll/ack/heartbeat/stop control-plane calls and the per-session
-   * SessionToolRunner's stream/list/send. Mirrors what
-   * `client.beta.messages.toolRunner` accepts: custom `headers` (e.g. a proxy's
-   * auth/routing headers) reach all of them. The worker owns the abort signals,
-   * so a `signal` here is ignored — use {@link EnvironmentWorkerOptions.signal}.
-   */
-  requestOptions?: BetaToolRunnerRequestOptions;
-}
-
-/**
- * Options for {@link EnvironmentWorker.handleItem}. Every field falls back to the
- * matching `ANTHROPIC_*` environment variable — the ones the
- * `ant worker poll --on-work` command sets for the process it spawns — when not
- * passed explicitly.
- */
-export interface HandleItemOptions {
-  /** Work item id. Falls back to `ANTHROPIC_WORK_ID`. */
-  workId?: string;
-  /** Self-hosted environment id. Falls back to `ANTHROPIC_ENVIRONMENT_ID`. */
-  environmentId?: string;
-  /** Session id. Falls back to `ANTHROPIC_SESSION_ID`. */
-  sessionId?: string;
-  /**
-   * The environment key used to authenticate every per-session call. Resolution
-   * order: this option, then the worker's own `environmentKey`, then
-   * `ANTHROPIC_ENVIRONMENT_KEY`.
-   */
-  environmentKey?: string;
-  /** External abort signal; aborting it ends the run. Defaults to the constructor's signal. */
-  signal?: AbortSignal;
-}
-
-/** The fields of {@link BetaSelfHostedWork} the per-item flow reads. */
-type ClaimedWork = Pick<BetaSelfHostedWork, 'id' | 'environment_id' | 'data'>;
-
-/**
- * The self-hosted environment runner, composed from the control-plane
- * {@link WorkPoller} and the per-session {@link SessionToolRunner}.
- *
- * For each claimed `session` work item it: builds the per-session
- * {@link AgentToolContext}, downloads the session agent's skills
- * (`setupSkills`), then runs a {@link SessionToolRunner} for the session
- * *while* heartbeating the work-item lease in parallel; on exit it force-stops
- * the work item, cleans up the downloaded skills, and loops to the next one. The
- * lease heartbeat reports `state === "stopping"` / a lost lease back into the run
- * by aborting the session runner.
- *
- * Use {@link EnvironmentWorker.handleItem} if you already hold a claimed work
- * item (e.g. a `worker poll --on-work` script handed one to a fresh process) and
- * just want the per-item flow without the poll loop — with no arguments it reads
- * the `ANTHROPIC_*` env vars that command sets.
- *
- * Construct it via `client.beta.environments.work.worker({ ... })` (or
- * `new EnvironmentWorker({ client, ... })` directly).
- *
- * @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 {
-  readonly client: Anthropic;
-  readonly environmentId: string | undefined;
-  readonly environmentKey: string | undefined;
-  readonly tools: EnvironmentWorkerTools | undefined;
-  readonly workdir: string;
-  readonly unrestrictedPaths: boolean | undefined;
-  readonly maxFileBytes: number | null | undefined;
-  readonly maxIdleMs: number | undefined;
-  readonly workerId: string | undefined;
-  readonly requestOptions: BetaToolRunnerRequestOptions | undefined;
-  readonly #signal: AbortSignal | undefined;
-
-  constructor(opts: EnvironmentWorkerOptions) {
-    this.client = opts.client;
-    this.environmentId = opts.environmentId;
-    this.environmentKey = opts.environmentKey;
-    this.tools = opts.tools;
-    this.workdir = opts.workdir ?? process.cwd();
-    this.unrestrictedPaths = opts.unrestrictedPaths;
-    this.maxFileBytes = opts.maxFileBytes;
-    this.maxIdleMs = opts.maxIdleMs;
-    this.workerId = opts.workerId;
-    this.requestOptions = opts.requestOptions;
-    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?: AbortSignal): Promise<void> {
-    const { environmentId, environmentKey } = this;
-    if (environmentId === undefined || environmentKey === undefined) {
-      throw new AnthropicError(
-        'EnvironmentWorker.run: environmentId and environmentKey are required to poll for work',
-      );
-    }
-    const externalSignal = signal ?? 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 force-stops every work item on exit; let it be the
-      // single owner of `work.stop` rather than double-posting from the poller.
-      autoStop: false,
-    });
-
-    for await (const work of poller) {
-      await this.#handleItem(work, environmentKey, poller.signal);
-    }
-  }
-
-  /**
-   * Service a single, already-claimed work item without the poll loop: build the
-   * per-session {@link AgentToolContext} (workdir from this worker's options),
-   * download the session agent's skills (`setupSkills`), run a
-   * {@link SessionToolRunner} for the session while heartbeating the work-item
-   * lease in parallel, and force-stop the work item on exit (whether the runner
-   * finishes normally, throws, or the heartbeat loop signals shutdown).
-   *
-   * Use this when something else does the claiming — e.g. a `worker poll
-   * --on-work` script that hands an already-claimed item to a fresh process. The
-   * work id / environment id / session id each fall back to `ANTHROPIC_WORK_ID` /
-   * `ANTHROPIC_ENVIRONMENT_ID` / `ANTHROPIC_SESSION_ID` (the env vars that
-   * command sets) when not passed; the environment key resolves from this
-   * option, then the worker's own `environmentKey`, then
-   * `ANTHROPIC_ENVIRONMENT_KEY`. With no arguments inside that command it just
-   * works. Throws a clear error naming the first of the four required values
-   * still missing after resolution.
-   */
-  async handleItem(opts?: HandleItemOptions): Promise<void> {
-    const workId = opts?.workId ?? readEnv('ANTHROPIC_WORK_ID');
-    const environmentId = opts?.environmentId ?? readEnv('ANTHROPIC_ENVIRONMENT_ID');
-    const sessionId = opts?.sessionId ?? readEnv('ANTHROPIC_SESSION_ID');
-    const environmentKey =
-      opts?.environmentKey ?? this.environmentKey ?? readEnv('ANTHROPIC_ENVIRONMENT_KEY');
-
-    if (!workId) {
-      throw new AnthropicError('handleItem: workId is required — pass it or set ANTHROPIC_WORK_ID');
-    }
-    if (!environmentId) {
-      throw new AnthropicError(
-        'handleItem: environmentId is required — pass it or set ANTHROPIC_ENVIRONMENT_ID',
-      );
-    }
-    if (!sessionId) {
-      throw new AnthropicError('handleItem: sessionId is required — pass it or set ANTHROPIC_SESSION_ID');
-    }
-    if (!environmentKey) {
-      throw new AnthropicError(
-        'handleItem: environmentKey is required — pass it, construct the worker with it, or set ANTHROPIC_ENVIRONMENT_KEY',
-      );
-    }
-
-    const work: ClaimedWork = {
-      id: workId,
-      environment_id: environmentId,
-      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.
-   * Non-session work items are ignored.
-   */
-  async #handleItem(
-    work: ClaimedWork,
-    environmentKey: string,
-    externalSignal: AbortSignal | undefined,
-  ): Promise<void> {
-    const log = loggerFor(this.client);
-    // Every per-session call — the SessionToolRunner event stream/list/send, the
-    // lease heartbeat, and the work force-stop — authenticates with the
-    // environment key. Scope a client to it once and thread that through.
-    // `copyClientForHelper` also clears the parent's `apiKey`, so the sub-client
-    // emits *only* the bearer credential on the wire (a plain
-    // `withOptions({authToken})` would leave `X-Api-Key` set as well).
-    const sessionClient = copyClientForHelper(this.client, {
-      authToken: environmentKey,
-      helper: 'environments-worker',
-    });
-
-    // The poller runs with `autoStop: false`, so the per-item handler is the
-    // single owner of `work.stop` for every claimed item.
-    const sessionId = work.data.id;
-
-    const ctx: AgentToolContext = {
-      workdir: this.workdir,
-      client: this.client,
-      sessionId,
-      ...(this.unrestrictedPaths !== undefined ? { unrestrictedPaths: this.unrestrictedPaths } : {}),
-      ...(this.maxFileBytes !== undefined ? { maxFileBytes: this.maxFileBytes } : {}),
-    };
-    // Lazily load the Node-only toolset module — see the import note at the top.
-    const agentToolset = await import('../../tools/agent-toolset/node');
-    let cleanupSkills: () => Promise<void> = async () => {};
-    try {
-      cleanupSkills = await agentToolset.setupSkills(ctx);
-    } catch (e) {
-      log.warn('skill setup failed', { session_id: sessionId, work_id: work.id, error: String(e) });
-    }
-    const tools =
-      typeof this.tools === 'function' ?
-        this.tools(ctx)
-      : this.tools ?? agentToolset.betaAgentToolset20260401(ctx);
-
-    // A per-session controller: aborts when the supplied signal aborts, when the
-    // session runner finishes, or when the lease heartbeat says to stop.
-    const ctrl = new AbortController();
-    const detachExternal = linkAbort(externalSignal, ctrl);
-
-    const heartbeatPromise = heartbeatLoop(sessionClient, work, ctrl, log, this.requestOptions).catch((e) => {
-      if (!ctrl.signal.aborted) log.error('heartbeat loop failed', { work_id: work.id, error: String(e) });
-      ctrl.abort();
-    });
-
-    try {
-      const runner = new SessionToolRunner(sessionId, {
-        client: sessionClient,
-        tools,
-        ...(this.maxIdleMs !== undefined ? { maxIdleMs: this.maxIdleMs } : {}),
-        ...(this.requestOptions !== undefined ? { requestOptions: this.requestOptions } : {}),
-        signal: ctrl.signal,
-      });
-      for await (const _ of runner) {
-        // Drive the runner to completion; per-call observability is not part
-        // of this composition's surface — use `SessionToolRunner` directly
-        // (via `client.beta.sessions.events.toolRunner`) if you want it.
-      }
-    } finally {
-      ctrl.abort();
-      detachExternal();
-      await heartbeatPromise;
-      await cleanupSkills().catch((e) => {
-        log.warn('skill cleanup failed', { session_id: sessionId, work_id: work.id, error: String(e) });
-      });
-      await forceStop(sessionClient, work, log, this.requestOptions);
-    }
-  }
-}
-
-/** Force-stop a claimed work item, swallowing the 409 that means it's already stopped. */
-async function forceStop(
-  client: Anthropic,
-  work: Pick<BetaSelfHostedWork, 'id' | 'environment_id'>,
-  log: Logger,
-  requestOptions?: BetaToolRunnerRequestOptions,
-): Promise<void> {
-  try {
-    await client.beta.environments.work.stop(
-      work.id,
-      { environment_id: work.environment_id, force: true },
-      // Caller's headers pass through; the helper-tag header is on the scoped
-      // sub-client's default_headers via copyClientForHelper, so no per-call
-      // re-stamping needed.
-      { ...requestOptions, headers: buildHeaders([requestOptions?.headers]) },
-    );
-  } catch (e) {
-    if (!isStatus(e, 409)) {
-      log.error('force-stop on exit failed', { work_id: work.id, error: String(e) });
-    }
-  }
-}
-
-/**
- * Keep the work-item lease alive while a session is being served. Aborts `ctrl`
- * when the control plane reports the work is `stopping`/`stopped`, when the
- * lease is no longer extended, or on a permanent heartbeat failure.
- */
-async function heartbeatLoop(
-  client: Anthropic,
-  work: Pick<BetaSelfHostedWork, 'id' | 'environment_id'>,
-  ctrl: AbortController,
-  logger: Logger,
-  requestOptions?: BetaToolRunnerRequestOptions,
-): Promise<void> {
-  let intervalMs = HEARTBEAT_DEFAULT_MS;
-  let last = NO_HEARTBEAT_SENTINEL;
-  const beat = async (): Promise<void> => {
-    try {
-      const resp = await client.beta.environments.work.heartbeat(
-        work.id,
-        { environment_id: work.environment_id, expected_last_heartbeat: last },
-        { ...requestOptions, headers: buildHeaders([requestOptions?.headers]), signal: ctrl.signal },
-      );
-      last = resp.last_heartbeat;
-      if (resp.ttl_seconds > 0) {
-        intervalMs = Math.max(1_000, Math.min((resp.ttl_seconds * 1000) / 2, HEARTBEAT_DEFAULT_MS));
-      }
-      if (resp.state === 'stopping' || resp.state === 'stopped') {
-        logger.info('heartbeat signals shutdown', { work_id: work.id, state: resp.state });
-        ctrl.abort();
-      }
-      if (!resp.lease_extended) {
-        logger.warn('lease not extended, shutting down', { work_id: work.id });
-        ctrl.abort();
-      }
-    } catch (e) {
-      // An abort throws to unwind the caller (the `heartbeatLoop(...).catch`
-      // in `#handleItem`) rather than returning early.
-      ctrl.signal.throwIfAborted();
-      if (isFatal4xx(e)) {
-        logger.error('permanent heartbeat failure', { work_id: work.id, error: String(e) });
-        ctrl.abort();
-        throw e;
-      }
-      logger.warn('transient heartbeat failure', { work_id: work.id, error: String(e) });
-    }
-  };
-
-  await beat();
-  while (!ctrl.signal.aborted) {
-    await sleep(intervalMs, ctrl.signal);
-    ctrl.signal.throwIfAborted();
-    await beat();
-  }
-}