@anthropic-ai/sdk 0.117.1 → 0.119.0

package/src/client.ts

@@ -53,6 +53,14 @@ import {
   CompletionCreateParamsStreaming,
   Completions,
 } from './resources/completions';
+import {
+  DeletedFile,
+  FileListParams,
+  FileMetadata,
+  FileMetadataPageCursor,
+  FileUploadParams,
+  Files,
+} from './resources/files';
 import {
   CapabilitySupport,
   ContextManagementCapability,
@@ -95,6 +103,46 @@ import {
   BashCodeExecutionToolResultError,
   BashCodeExecutionToolResultErrorCode,
   BashCodeExecutionToolResultErrorParam,
+  BrowserCloseTabConfig,
+  BrowserDoubleClickConfig,
+  BrowserFileUploadConfig,
+  BrowserFindConfig,
+  BrowserFormInputConfig,
+  BrowserGetPageTextConfig,
+  BrowserHoldKeyConfig,
+  BrowserHoverConfig,
+  BrowserJavascriptExecConfig,
+  BrowserKeyConfig,
+  BrowserLeftClickConfig,
+  BrowserLeftClickDragConfig,
+  BrowserLeftMouseDownConfig,
+  BrowserLeftMouseUpConfig,
+  BrowserListTabsConfig,
+  BrowserMiddleClickConfig,
+  BrowserMouseMoveConfig,
+  BrowserNavigateConfig,
+  BrowserNewTabConfig,
+  BrowserReadConsoleConfig,
+  BrowserReadNetworkConfig,
+  BrowserReadPageConfig,
+  BrowserRightClickConfig,
+  BrowserScreenshotConfig,
+  BrowserScrollConfig,
+  BrowserScrollToConfig,
+  BrowserStateBlockParam,
+  BrowserStateChange,
+  BrowserStateChangeDownloadCompleted,
+  BrowserStateChangeDownloadFailed,
+  BrowserStateChangeDownloadStarted,
+  BrowserStateChangeTabOpened,
+  BrowserStateTabEntry,
+  BrowserSwitchTabConfig,
+  BrowserToolset20260801,
+  BrowserToolsetConfigs,
+  BrowserTripleClickConfig,
+  BrowserTypeConfig,
+  BrowserWaitConfig,
+  BrowserZoomConfig,
   CacheControlEphemeral,
   CacheCreation,
   CitationCharLocation,
@@ -125,7 +173,28 @@ import {
   CodeExecutionToolResultError,
   CodeExecutionToolResultErrorCode,
   CodeExecutionToolResultErrorParam,
+  ComputerCursorPositionConfig,
+  ComputerDoubleClickConfig,
+  ComputerHoldKeyConfig,
+  ComputerKeyConfig,
+  ComputerLeftClickConfig,
+  ComputerLeftClickDragConfig,
+  ComputerLeftMouseDownConfig,
+  ComputerLeftMouseUpConfig,
+  ComputerMiddleClickConfig,
+  ComputerMouseMoveConfig,
+  ComputerRightClickConfig,
+  ComputerScreenshotConfig,
+  ComputerScrollConfig,
+  ComputerToolset20260801,
+  ComputerToolsetConfigs,
+  ComputerTripleClickConfig,
+  ComputerTypeConfig,
+  ComputerWaitConfig,
+  ComputerZoomConfig,
   Container,
+  ContainerParams,
+  ContainerSkill,
   ContainerUploadBlock,
   ContainerUploadBlockParam,
   ContentBlock,
@@ -140,7 +209,10 @@ import {
   DocumentBlockParam,
   EncryptedCodeExecutionResultBlock,
   EncryptedCodeExecutionResultBlockParam,
+  FileDocumentSource,
+  FileImageSource,
   ImageBlockParam,
+  ImageTransformationsParam,
   InputJSONDelta,
   JSONOutputFormat,
   MemoryTool20250818,
@@ -149,6 +221,7 @@ import {
   MessageCountTokensParams,
   MessageCountTokensTool,
   MessageCreateParams,
+  MessageCreateParamsContainer,
   MessageCreateParamsNonStreaming,
   MessageCreateParamsStreaming,
   MessageDeltaEvent,
@@ -160,7 +233,6 @@ import {
   MessageTokensCount,
   Messages,
   Metadata,
-  MidConversationSystemBlockParam,
   Model,
   OutputConfig,
   OutputTokensDetails,
@@ -183,6 +255,7 @@ import {
   ServerToolUseBlock,
   ServerToolUseBlockParam,
   SignatureDelta,
+  SkillParams,
   StopReason,
   TextBlock,
   TextBlockParam,
@@ -260,6 +333,15 @@ import {
   WebSearchToolResultError,
   WebSearchToolResultErrorCode,
 } from './resources/messages/messages';
+import {
+  DeletedSkill,
+  Skill,
+  SkillCreateParams,
+  SkillListParams,
+  SkillSource,
+  Skills,
+  SkillsPageCursor,
+} from './resources/skills/skills';
 import { type Fetch } from './internal/builtin-types';
 import { isRunningInBrowser } from './internal/detect-platform';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
@@ -1136,7 +1218,7 @@ export class BaseAnthropic {
     }
 
     const specialHeaders = [...response.headers.entries()]
-      .filter(([name]) => name === 'request-id')
+      .filter(([name]) => name === 'request-id' || name === 'anthropic-workspace-id')
       .map(([name, value]) => ', ' + name + ': ' + JSON.stringify(value))
       .join('');
     const responseInfo = `[${requestLogID}${retryLogStr}${specialHeaders}] ${req.method} ${url} ${
@@ -1596,12 +1678,16 @@ export class Anthropic extends BaseAnthropic {
   completions: API.Completions = new API.Completions(this);
   messages: API.Messages = new API.Messages(this);
   models: API.Models = new API.Models(this);
+  files: API.Files = new API.Files(this);
+  skills: API.Skills = new API.Skills(this);
   beta: API.Beta = new API.Beta(this);
 }
 
 Anthropic.Completions = Completions;
 Anthropic.Messages = Messages;
 Anthropic.Models = Models;
+Anthropic.Files = Files;
+Anthropic.Skills = Skills;
 Anthropic.Beta = Beta;
 
 export declare namespace Anthropic {
@@ -1646,6 +1732,46 @@ export declare namespace Anthropic {
     type BashCodeExecutionToolResultError as BashCodeExecutionToolResultError,
     type BashCodeExecutionToolResultErrorCode as BashCodeExecutionToolResultErrorCode,
     type BashCodeExecutionToolResultErrorParam as BashCodeExecutionToolResultErrorParam,
+    type BrowserCloseTabConfig as BrowserCloseTabConfig,
+    type BrowserDoubleClickConfig as BrowserDoubleClickConfig,
+    type BrowserFileUploadConfig as BrowserFileUploadConfig,
+    type BrowserFindConfig as BrowserFindConfig,
+    type BrowserFormInputConfig as BrowserFormInputConfig,
+    type BrowserGetPageTextConfig as BrowserGetPageTextConfig,
+    type BrowserHoldKeyConfig as BrowserHoldKeyConfig,
+    type BrowserHoverConfig as BrowserHoverConfig,
+    type BrowserJavascriptExecConfig as BrowserJavascriptExecConfig,
+    type BrowserKeyConfig as BrowserKeyConfig,
+    type BrowserLeftClickConfig as BrowserLeftClickConfig,
+    type BrowserLeftClickDragConfig as BrowserLeftClickDragConfig,
+    type BrowserLeftMouseDownConfig as BrowserLeftMouseDownConfig,
+    type BrowserLeftMouseUpConfig as BrowserLeftMouseUpConfig,
+    type BrowserListTabsConfig as BrowserListTabsConfig,
+    type BrowserMiddleClickConfig as BrowserMiddleClickConfig,
+    type BrowserMouseMoveConfig as BrowserMouseMoveConfig,
+    type BrowserNavigateConfig as BrowserNavigateConfig,
+    type BrowserNewTabConfig as BrowserNewTabConfig,
+    type BrowserReadConsoleConfig as BrowserReadConsoleConfig,
+    type BrowserReadNetworkConfig as BrowserReadNetworkConfig,
+    type BrowserReadPageConfig as BrowserReadPageConfig,
+    type BrowserRightClickConfig as BrowserRightClickConfig,
+    type BrowserScreenshotConfig as BrowserScreenshotConfig,
+    type BrowserScrollConfig as BrowserScrollConfig,
+    type BrowserScrollToConfig as BrowserScrollToConfig,
+    type BrowserStateBlockParam as BrowserStateBlockParam,
+    type BrowserStateChange as BrowserStateChange,
+    type BrowserStateChangeDownloadCompleted as BrowserStateChangeDownloadCompleted,
+    type BrowserStateChangeDownloadFailed as BrowserStateChangeDownloadFailed,
+    type BrowserStateChangeDownloadStarted as BrowserStateChangeDownloadStarted,
+    type BrowserStateChangeTabOpened as BrowserStateChangeTabOpened,
+    type BrowserStateTabEntry as BrowserStateTabEntry,
+    type BrowserSwitchTabConfig as BrowserSwitchTabConfig,
+    type BrowserToolset20260801 as BrowserToolset20260801,
+    type BrowserToolsetConfigs as BrowserToolsetConfigs,
+    type BrowserTripleClickConfig as BrowserTripleClickConfig,
+    type BrowserTypeConfig as BrowserTypeConfig,
+    type BrowserWaitConfig as BrowserWaitConfig,
+    type BrowserZoomConfig as BrowserZoomConfig,
     type CacheControlEphemeral as CacheControlEphemeral,
     type CacheCreation as CacheCreation,
     type CitationCharLocation as CitationCharLocation,
@@ -1676,7 +1802,28 @@ export declare namespace Anthropic {
     type CodeExecutionToolResultError as CodeExecutionToolResultError,
     type CodeExecutionToolResultErrorCode as CodeExecutionToolResultErrorCode,
     type CodeExecutionToolResultErrorParam as CodeExecutionToolResultErrorParam,
+    type ComputerCursorPositionConfig as ComputerCursorPositionConfig,
+    type ComputerDoubleClickConfig as ComputerDoubleClickConfig,
+    type ComputerHoldKeyConfig as ComputerHoldKeyConfig,
+    type ComputerKeyConfig as ComputerKeyConfig,
+    type ComputerLeftClickConfig as ComputerLeftClickConfig,
+    type ComputerLeftClickDragConfig as ComputerLeftClickDragConfig,
+    type ComputerLeftMouseDownConfig as ComputerLeftMouseDownConfig,
+    type ComputerLeftMouseUpConfig as ComputerLeftMouseUpConfig,
+    type ComputerMiddleClickConfig as ComputerMiddleClickConfig,
+    type ComputerMouseMoveConfig as ComputerMouseMoveConfig,
+    type ComputerRightClickConfig as ComputerRightClickConfig,
+    type ComputerScreenshotConfig as ComputerScreenshotConfig,
+    type ComputerScrollConfig as ComputerScrollConfig,
+    type ComputerToolset20260801 as ComputerToolset20260801,
+    type ComputerToolsetConfigs as ComputerToolsetConfigs,
+    type ComputerTripleClickConfig as ComputerTripleClickConfig,
+    type ComputerTypeConfig as ComputerTypeConfig,
+    type ComputerWaitConfig as ComputerWaitConfig,
+    type ComputerZoomConfig as ComputerZoomConfig,
     type Container as Container,
+    type ContainerParams as ContainerParams,
+    type ContainerSkill as ContainerSkill,
     type ContainerUploadBlock as ContainerUploadBlock,
     type ContainerUploadBlockParam as ContainerUploadBlockParam,
     type ContentBlock as ContentBlock,
@@ -1691,12 +1838,16 @@ export declare namespace Anthropic {
     type DocumentBlockParam as DocumentBlockParam,
     type EncryptedCodeExecutionResultBlock as EncryptedCodeExecutionResultBlock,
     type EncryptedCodeExecutionResultBlockParam as EncryptedCodeExecutionResultBlockParam,
+    type FileDocumentSource as FileDocumentSource,
+    type FileImageSource as FileImageSource,
     type ImageBlockParam as ImageBlockParam,
+    type ImageTransformationsParam as ImageTransformationsParam,
     type InputJSONDelta as InputJSONDelta,
     type JSONOutputFormat as JSONOutputFormat,
     type MemoryTool20250818 as MemoryTool20250818,
     type Message as Message,
     type MessageCountTokensTool as MessageCountTokensTool,
+    type MessageCreateParamsContainer as MessageCreateParamsContainer,
     type MessageDeltaEvent as MessageDeltaEvent,
     type MessageDeltaUsage as MessageDeltaUsage,
     type MessageParam as MessageParam,
@@ -1705,7 +1856,6 @@ export declare namespace Anthropic {
     type MessageStreamEvent as MessageStreamEvent,
     type MessageTokensCount as MessageTokensCount,
     type Metadata as Metadata,
-    type MidConversationSystemBlockParam as MidConversationSystemBlockParam,
     type Model as Model,
     type OutputConfig as OutputConfig,
     type OutputTokensDetails as OutputTokensDetails,
@@ -1728,6 +1878,7 @@ export declare namespace Anthropic {
     type ServerToolUseBlock as ServerToolUseBlock,
     type ServerToolUseBlockParam as ServerToolUseBlockParam,
     type SignatureDelta as SignatureDelta,
+    type SkillParams as SkillParams,
     type StopReason as StopReason,
     type TextBlock as TextBlock,
     type TextBlockParam as TextBlockParam,
@@ -1825,6 +1976,25 @@ export declare namespace Anthropic {
     type ModelListParams as ModelListParams,
   };
 
+  export {
+    Files as Files,
+    type DeletedFile as DeletedFile,
+    type FileMetadata as FileMetadata,
+    type FileMetadataPageCursor as FileMetadataPageCursor,
+    type FileListParams as FileListParams,
+    type FileUploadParams as FileUploadParams,
+  };
+
+  export {
+    Skills as Skills,
+    type DeletedSkill as DeletedSkill,
+    type Skill as Skill,
+    type SkillSource as SkillSource,
+    type SkillsPageCursor as SkillsPageCursor,
+    type SkillCreateParams as SkillCreateParams,
+    type SkillListParams as SkillListParams,
+  };
+
   export {
     Beta as Beta,
     type AnthropicBeta as AnthropicBeta,

package/src/core/api-promise.ts

@@ -7,7 +7,7 @@ import {
   type APIResponseProps,
   type WithRequestID,
   defaultParseResponse,
-  addRequestID,
+  addResponseIDs,
 } from '../internal/parse';
 
 /**
@@ -37,7 +37,7 @@ export class APIPromise<T> extends Promise<WithRequestID<T>> {
 
   _thenUnwrap<U>(transform: (data: T, props: APIResponseProps) => U): APIPromise<U> {
     return new APIPromise(this.#client, this.responsePromise, async (client, props) =>
-      addRequestID(transform(await this.parseResponse(client, props), props), props.response),
+      addResponseIDs(transform(await this.parseResponse(client, props), props), props.response),
     );
   }
 
@@ -68,9 +68,19 @@ export class APIPromise<T> extends Promise<WithRequestID<T>> {
    * Try setting `"moduleResolution": "NodeNext"` or add `"lib": ["DOM"]`
    * to your `tsconfig.json`.
    */
-  async withResponse(): Promise<{ data: T; response: Response; request_id: string | null | undefined }> {
+  async withResponse(): Promise<{
+    data: T;
+    response: Response;
+    request_id: string | null | undefined;
+    workspace_id: string | null | undefined;
+  }> {
     const [data, response] = await Promise.all([this.parse(), this.asResponse()]);
-    return { data, response, request_id: response.headers.get('request-id') };
+    return {
+      data,
+      response,
+      request_id: response.headers.get('request-id'),
+      workspace_id: response.headers.get('anthropic-workspace-id'),
+    };
   }
 
   private parse(): Promise<WithRequestID<T>> {

package/src/core/error.ts

@@ -18,6 +18,7 @@ export class APIError<
   readonly error: TError;
 
   readonly requestID: string | null | undefined;
+  readonly workspaceID: string | null | undefined;
 
   /** The `error.type` from the API response body, e.g. `"rate_limit_error"` */
   readonly type: ErrorType | null;
@@ -33,6 +34,7 @@ export class APIError<
     this.status = status;
     this.headers = headers;
     this.requestID = headers?.get('request-id');
+    this.workspaceID = headers?.get('anthropic-workspace-id');
     this.error = error;
     this.type = type ?? null;
   }

package/src/core/middleware.ts

@@ -1,7 +1,7 @@
 import type { BaseAnthropic } from '../client';
 import type { Fetch } from '../internal/builtin-types';
 import { castToError, isAbortError } from '../internal/errors';
-import { addRequestID } from '../internal/parse';
+import { addResponseIDs } from '../internal/parse';
 import type { FinalRequestOptions } from '../internal/request-options';
 import { defaultLogger, loggerFor, type Logger } from '../internal/utils/log';
 import type { APIRequest } from './api';
@@ -299,7 +299,7 @@ async function parseMiddlewareResponse(
       // if there is no content we can't do anything
       return undefined;
     }
-    return addRequestID(await response.clone().json(), response);
+    return addResponseIDs(await response.clone().json(), response);
   }
 
   return await response.clone().text();

package/src/helpers/beta/zod.ts

@@ -16,9 +16,7 @@ import { BetaToolResultContentBlockParam } from '../../resources/beta';
 export function betaZodOutputFormat<ZodInput extends z.ZodType>(
   zodObject: ZodInput,
 ): AutoParseableBetaOutputFormat<z.infer<ZodInput>> {
-  let jsonSchema = z.toJSONSchema(zodObject, { reused: 'ref' });
-
-  jsonSchema = transformJSONSchema(jsonSchema);
+  const jsonSchema = transformJSONSchema(z.toJSONSchema(zodObject, { reused: 'ref' }));
 
   return {
     type: 'json_schema',

package/src/helpers/zod.ts

@@ -15,9 +15,7 @@ import { AutoParseableOutputFormat } from '../lib/parser';
 export function zodOutputFormat<ZodInput extends z.ZodType>(
   zodObject: ZodInput,
 ): AutoParseableOutputFormat<z.infer<ZodInput>> {
-  let jsonSchema = z.toJSONSchema(zodObject, { reused: 'ref' });
-
-  jsonSchema = transformJSONSchema(jsonSchema);
+  const jsonSchema = transformJSONSchema(z.toJSONSchema(zodObject, { reused: 'ref' }));
 
   return {
     type: 'json_schema',

package/src/internal/parse.ts

@@ -51,7 +51,7 @@ export async function defaultParseResponse<T>(
       }
 
       const json = await response.json();
-      return addRequestID(json as T, response);
+      return addResponseIDs(json as T, response);
     }
 
     const text = await response.text();
@@ -80,16 +80,16 @@ export async function defaultParseResponse<T>(
 
 export type WithRequestID<T> =
   T extends Array<any> | Response | AbstractPage<any> ? T
-  : T extends Record<string, any> ? T & { _request_id?: string | null }
+  : T extends Record<string, any> ? T & { _request_id?: string | null; _workspace_id?: string | null }
   : T;
 
-export function addRequestID<T>(value: T, response: Response): WithRequestID<T> {
+export function addResponseIDs<T>(value: T, response: Response): WithRequestID<T> {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     return value as WithRequestID<T>;
   }
 
-  return Object.defineProperty(value, '_request_id', {
-    value: response.headers.get('request-id'),
-    enumerable: false,
+  return Object.defineProperties(value, {
+    _request_id: { value: response.headers.get('request-id'), enumerable: false },
+    _workspace_id: { value: response.headers.get('anthropic-workspace-id'), enumerable: false },
   }) as WithRequestID<T>;
 }

package/src/lib/BetaMessageStream.ts

@@ -74,6 +74,7 @@ export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMess
   #catchingPromiseCreated = false;
   #response: Response | null | undefined;
   #request_id: string | null | undefined;
+  #workspace_id: string | null | undefined;
   #logger: Logger;
 
   constructor(params: MessageCreateParamsBase | null, opts?: { logger?: Logger | undefined }) {
@@ -106,6 +107,10 @@ export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMess
     return this.#request_id;
   }
 
+  get workspace_id(): string | null | undefined {
+    return this.#workspace_id;
+  }
+
   /**
    * Returns the `MessageStream` data, the raw `Response` instance and the ID of the request,
    * returned vie the `request-id` header which is useful for debugging requests and resporting
@@ -120,6 +125,7 @@ export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMess
     data: BetaMessageStream<ParsedT>;
     response: Response;
     request_id: string | null | undefined;
+    workspace_id: string | null | undefined;
   }> {
     this.#catchingPromiseCreated = true;
 
@@ -132,6 +138,7 @@ export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMess
       data: this,
       response,
       request_id: response.headers.get('request-id'),
+      workspace_id: response.headers.get('anthropic-workspace-id'),
     };
   }
 
@@ -223,6 +230,7 @@ export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMess
     if (this.ended) return;
     this.#response = response;
     this.#request_id = response?.headers.get('request-id');
+    this.#workspace_id = response?.headers.get('anthropic-workspace-id');
     this.#resolveConnectedPromise(response);
     this._emit('connect');
   }

package/src/lib/MessageStream.ts

@@ -73,6 +73,7 @@ export class MessageStream<ParsedT = null> implements AsyncIterable<MessageStrea
   #catchingPromiseCreated = false;
   #response: Response | null | undefined;
   #request_id: string | null | undefined;
+  #workspace_id: string | null | undefined;
   #logger: Logger;
 
   constructor(params: MessageCreateParamsBase | null, opts?: { logger?: Logger | undefined }) {
@@ -105,6 +106,10 @@ export class MessageStream<ParsedT = null> implements AsyncIterable<MessageStrea
     return this.#request_id;
   }
 
+  get workspace_id(): string | null | undefined {
+    return this.#workspace_id;
+  }
+
   /**
    * Returns the `MessageStream` data, the raw `Response` instance and the ID of the request,
    * returned vie the `request-id` header which is useful for debugging requests and resporting
@@ -119,6 +124,7 @@ export class MessageStream<ParsedT = null> implements AsyncIterable<MessageStrea
     data: MessageStream<ParsedT>;
     response: Response;
     request_id: string | null | undefined;
+    workspace_id: string | null | undefined;
   }> {
     this.#catchingPromiseCreated = true;
 
@@ -131,6 +137,7 @@ export class MessageStream<ParsedT = null> implements AsyncIterable<MessageStrea
       data: this,
       response,
       request_id: response.headers.get('request-id'),
+      workspace_id: response.headers.get('anthropic-workspace-id'),
     };
   }
 
@@ -222,6 +229,7 @@ export class MessageStream<ParsedT = null> implements AsyncIterable<MessageStrea
     if (this.ended) return;
     this.#response = response;
     this.#request_id = response?.headers.get('request-id');
+    this.#workspace_id = response?.headers.get('anthropic-workspace-id');
     this.#resolveConnectedPromise(response);
     this._emit('connect');
   }

package/src/lib/environments/worker.ts

@@ -52,6 +52,10 @@ export interface EnvironmentWorkerOptions {
    * 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()`. */
@@ -110,10 +114,10 @@ type ClaimedWork = Pick<BetaSelfHostedWork, 'id' | 'environment_id' | 'data'>;
  * 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.
+ * while heartbeating the work-item lease on the same event loop; 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
@@ -196,8 +200,8 @@ export class EnvironmentWorker {
    * 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).
+   * lease, 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
@@ -293,19 +297,26 @@ export class EnvironmentWorker {
     const ctrl = new AbortController();
     const detachExternal = linkAbort(externalSignal, ctrl);
 
-    const heartbeatPromise = heartbeatLoop(sessionClient, work, ctrl, log, this.requestOptions).catch((e) => {
+    // Inert until iterated below.
+    const runner = new SessionToolRunner(sessionId, {
+      client: sessionClient,
+      tools,
+      ...(this.maxIdleMs !== undefined ? { maxIdleMs: this.maxIdleMs } : {}),
+      ...(this.requestOptions !== undefined ? { requestOptions: this.requestOptions } : {}),
+      signal: ctrl.signal,
+    });
+
+    // 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.
+    const heartbeatPromise = heartbeatLoop(sessionClient, work, ctrl, log, this.requestOptions, (ttlMs) =>
+      runner._setSendRetryWindow(ttlMs),
+    ).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
@@ -360,6 +371,8 @@ async function heartbeatLoop(
   ctrl: AbortController,
   logger: Logger,
   requestOptions?: BetaToolRunnerRequestOptions,
+  /** Called with the server-reported lease TTL after every successful beat. */
+  onLeaseTtl?: (ttlMs: number) => void,
 ): Promise<void> {
   let intervalMs = HEARTBEAT_DEFAULT_MS;
   let ttlMs = HEARTBEAT_TTL_DEFAULT_MS;
@@ -382,6 +395,7 @@ async function heartbeatLoop(
       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 });