@shardflux/sdk 0.11.0 → 0.12.0

package/dist/generated/cell-api.d.ts

@@ -170,6 +170,29 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspace_id}/exec/{session_id}/stdin": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Write pipe stdin or send EOF to an exec session
+         * @description Requires stdin_open at start (processful only), host exec_stdin and guest exec_stdin.v1. Offset is the total bytes previously accepted (initially 0). A repeated identical last frame is safe; a different stale offset is refused. Writes are bounded: offset in the response may acknowledge only a prefix; continue from that offset. close takes effect only after the whole frame is accepted. The transport writes no input log or payload file; program output and full-state snapshots retain their normal persistence. An ended session refuses input.
+         */
+        post: operations["execInput"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{workspace_id}/exec/{session_id}/signal": {
         parameters: {
             query?: never;
@@ -843,6 +866,8 @@ export interface components {
             /** @description Absolute working directory; omitted or empty starts in the default (/home/user). A relative path is refused, not resolved: 422 validation_failed, details.reason invalid_cwd, details.field cwd, the message naming the absolute path it likely means. A cwd that is not a directory ends the session failed_to_start (processful) or the execution failed with details.reason exec_failed_to_start (file-first). */
             cwd?: string;
             user?: string;
+            /** @description Keep a pipe open for exec stdin writes; processful only, mutually exclusive with stdin. Requires exec_stdin.v1. */
+            stdin_open?: boolean;
             /** @description Written to stdin, which is then closed (max 1 MiB decoded). */
             stdin?: string;
             /** Format: int64 */
@@ -979,6 +1004,19 @@ export interface components {
         };
         /** @description Signal number (1-64) or name (e.g. "SIGTERM", "TERM"). */
         SignalValue: number | string;
+        ExecInputRequest: {
+            /** @description At most 64 KiB decoded. */
+            data?: string;
+            /** Format: int64 */
+            offset: number;
+            /** @default false */
+            close?: boolean;
+        };
+        ExecInputResult: {
+            /** Format: int64 */
+            offset: number;
+            closed: boolean;
+        };
         SignalRequest: {
             signal: components["schemas"]["SignalValue"];
             /**
@@ -1607,6 +1645,34 @@ export interface operations {
             default: components["responses"]["Error"];
         };
     };
+    execInput: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ExecInputRequest"];
+            };
+        };
+        responses: {
+            /** @description Acknowledged input offset and EOF state. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ExecInputResult"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
     execSignal: {
         parameters: {
             query?: never;

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.11.0";
+export declare const SDK_VERSION = "0.12.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -29,17 +29,13 @@ export interface HttpOptions {
 }
 export declare const defaultSleep: (ms: number) => Promise<void>;
 /**
- * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends
- * `Connection: close`: undici 8.9 intermittently stalls a request on a reused keep-alive connection after the
- * connection sat idle for a few seconds (measured against the staging API: 20.9 s and 26.3 s stalls in 50 requests
- * with 0.2-12 s gaps; Node 22 / undici 6.28 max 351 ms; Node 26 with `Connection: close` max 435 ms; node:http2 on the
- * same load balancer and gaps max 193 ms, and the load balancer's idle timeout is 3600 s, so it is not an idle-timeout
- * interaction). The CLI and MCP server do the same. Other runtimes keep the runtime's keep-alive pooling.
- * `SHARDFLUX_HTTP_KEEPALIVE=1` disables the workaround.
+ * Reuses TLS connections. Node 26's bundled undici 8.9 can stall reused connections: use pinned undici with a
+ * private HTTP/1.1-only dispatcher. Other runtimes retain native fetch. SHARDFLUX_HTTP_KEEPALIVE=0 forces close
+ * for diagnosis; =1 retains the historical opt-in to native pooling. An explicitly supplied fetch is untouched.
  */
 export declare function defaultFetch(env?: Record<string, string | undefined> | undefined, undiciVersion?: string | undefined): typeof fetch;
 export declare function buildUrl(base: string, path: string, query?: RequestOptions['query']): string;
-/** `X-Tree-Revision` (file-first workspaces, contracts §29.8): a non-negative integer, else null. */
+/** `X-Tree-Revision` (file-first workspaces): a non-negative integer, else null. */
 export declare function treeRevisionOf(headers: Headers): number | null;
 /** Turns a non-2xx response into a ShardfluxApiError (or a protocol error for undocumented bodies). */
 export declare function errorFrom(res: Response, source: 'api' | 'cell'): Promise<Error>;
@@ -61,10 +57,10 @@ export declare class HttpClient {
         body: T;
     }>;
 }
-/** Longest server-side wait the SDK asks for (contracts §3: servers cap `Prefer: wait` at 20 s). */
+/** Longest server-side wait the SDK asks for (servers cap `Prefer: wait` at 20 s). */
 export declare const SERVER_WAIT_MAX_S = 20;
 /**
- * One bounded-wait poll (contracts §3): GET `path` with `Prefer: wait=<s>` when `waitS` >= 1. `applied` is true only
+ * One bounded-wait poll: GET `path` with `Prefer: wait=<s>` when `waitS` >= 1. `applied` is true only
  * when the server says it waited (Preference-Applied); otherwise the caller keeps its own backoff.
  */
 export declare function pollWithWait<T>(http: HttpClient, path: string, authorization: string, waitS: number, signal?: AbortSignal, onRetry?: RequestOptions['onRetry']): Promise<{

package/dist/http.js

@@ -8,26 +8,37 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.11.0';
+export const SDK_VERSION = '0.12.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** One private HTTP/1.1 pool on Node 26+, shared by SDK clients. No global dispatcher changes. */
+let nodeFetch;
 /**
- * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends
- * `Connection: close`: undici 8.9 intermittently stalls a request on a reused keep-alive connection after the
- * connection sat idle for a few seconds (measured against the staging API: 20.9 s and 26.3 s stalls in 50 requests
- * with 0.2-12 s gaps; Node 22 / undici 6.28 max 351 ms; Node 26 with `Connection: close` max 435 ms; node:http2 on the
- * same load balancer and gaps max 193 ms, and the load balancer's idle timeout is 3600 s, so it is not an idle-timeout
- * interaction). The CLI and MCP server do the same. Other runtimes keep the runtime's keep-alive pooling.
- * `SHARDFLUX_HTTP_KEEPALIVE=1` disables the workaround.
+ * Reuses TLS connections. Node 26's bundled undici 8.9 can stall reused connections: use pinned undici with a
+ * private HTTP/1.1-only dispatcher. Other runtimes retain native fetch. SHARDFLUX_HTTP_KEEPALIVE=0 forces close
+ * for diagnosis; =1 retains the historical opt-in to native pooling. An explicitly supplied fetch is untouched.
  */
 export function defaultFetch(env = globalThis.process?.env, undiciVersion = globalThis.process?.versions?.undici) {
+    // Why a fresh connection on Node 26 (its bundled HTTP client, measured): docs/progress/startup-latency.md.
     const base = (input, init) => fetch(input, init);
-    const major = Number((undiciVersion ?? '').split('.')[0]);
-    if (!(major >= 8) || env?.SHARDFLUX_HTTP_KEEPALIVE === '1')
+    if (env?.SHARDFLUX_HTTP_KEEPALIVE === '0')
+        return (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set('connection', 'close');
+            return base(input, { ...init, headers });
+        };
+    if (Number((undiciVersion ?? '').split('.')[0]) < 8 || !undiciVersion || env?.SHARDFLUX_HTTP_KEEPALIVE === '1')
         return base;
-    return (input, init) => {
-        const headers = new Headers(init?.headers);
-        headers.set('connection', 'close');
-        return fetch(input, { ...init, headers });
+    return async (input, init) => {
+        nodeFetch ??= import('undici').then(({ Agent, fetch: pooledFetch }) => {
+            const dispatcher = new Agent({ allowH2: false, pipelining: 1 });
+            return async (input, init) => {
+                const response = await pooledFetch(input, { ...init, dispatcher });
+                // Web-standard runtime shape; undici and DOM iterator declarations differ.
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- Required by consumers compiling with lib.dom instead of only Node types.
+                return response;
+            };
+        });
+        return (await nodeFetch)(input, init);
     };
 }
 export function buildUrl(base, path, query) {
@@ -45,7 +56,7 @@ function retryAfterSeconds(res) {
     const n = Number(v);
     return Number.isFinite(n) && n >= 0 ? n : undefined;
 }
-/** `X-Tree-Revision` (file-first workspaces, contracts §29.8): a non-negative integer, else null. */
+/** `X-Tree-Revision` (file-first workspaces): a non-negative integer, else null. */
 export function treeRevisionOf(headers) {
     const v = headers.get('x-tree-revision');
     if (v === null || !/^\d{1,19}$/.test(v))
@@ -65,7 +76,7 @@ export async function errorFrom(res, source) {
     }
     if (isErrorBody(parsed))
         return apiError(res.status, parsed, source, retryAfterSeconds(res), treeRevisionOf(res.headers) ?? undefined);
-    return new ShardfluxProtocolError(`HTTP ${res.status} from ${source === 'api' ? 'the Shardflux API' : 'the cell gateway'} without an error body`, res.status);
+    return new ShardfluxProtocolError(`HTTP ${res.status} from ${source === 'api' ? 'the Shardflux API' : 'the cell gateway'} without an error body`, res.status, source);
 }
 export class HttpClient {
     opts;
@@ -145,7 +156,7 @@ export class HttpClient {
             return JSON.parse(text);
         }
         catch {
-            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status, this.opts.source);
         }
     }
     /** Like json() but also returns the status and the response headers (bounded waits read Preference-Applied). */
@@ -156,7 +167,7 @@ export class HttpClient {
             return { status: res.status, headers: res.headers, body: (text.length === 0 ? undefined : JSON.parse(text)) };
         }
         catch {
-            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status, this.opts.source);
         }
     }
     /** Like json() but also returns the HTTP status (open() distinguishes 200 from 202). */
@@ -167,14 +178,14 @@ export class HttpClient {
             return { status: res.status, body: (text.length === 0 ? undefined : JSON.parse(text)) };
         }
         catch {
-            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status, this.opts.source);
         }
     }
 }
-/** Longest server-side wait the SDK asks for (contracts §3: servers cap `Prefer: wait` at 20 s). */
+/** Longest server-side wait the SDK asks for (servers cap `Prefer: wait` at 20 s). */
 export const SERVER_WAIT_MAX_S = 20;
 /**
- * One bounded-wait poll (contracts §3): GET `path` with `Prefer: wait=<s>` when `waitS` >= 1. `applied` is true only
+ * One bounded-wait poll: GET `path` with `Prefer: wait=<s>` when `waitS` >= 1. `applied` is true only
  * when the server says it waited (Preference-Applied); otherwise the caller keeps its own backoff.
  */
 export async function pollWithWait(http, path, authorization, waitS, signal, onRetry) {

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  *   const workspace = await cloud.workspaces.open({ key: `${customerId}/${projectId}`, template: 'python-node-browser' });
  *   await agent.run({ input: userMessage, tools: workspaceTools(workspace) });
  *
- * File-first workspaces (`mode: 'file_first'`, contracts §29) keep a versioned file tree and run each command as an
+ * File-first workspaces (`mode: 'file_first'`) keep a versioned file tree and run each command as an
  * execution: `await workspace.executions.run(['bash', '-lc', 'pytest -q'])`.
  *
  * Types come from the committed OpenAPI documents: application API
@@ -16,9 +16,9 @@ export type { components, operations, paths } from './generated/app-api.js';
 export type { components as CellComponents, paths as CellPaths } from './generated/cell-api.js';
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from './client.js';
 export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, UpdatePolicy, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
-export type { FinishedOperation, LifecycleOptions, ResumeOptions, WaitedLifecycleOptions, WaitedResumeOptions } from './lifecycle.js';
-export { formatTiming } from './progress.js';
-export type { LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
+export type { FinishedOperation, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
+export { durabilityOf, formatTiming, isDurable, lostSuspendOf } from './progress.js';
+export type { Durability, LostSuspend, LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
 export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from './feedback.js';
 export type { AccountFeedbackParams, FeedbackCategory, FeedbackContext, FeedbackReceipt, SendFeedbackParams } from './feedback.js';
 export { UsageApi } from './usage.js';
@@ -50,10 +50,15 @@ export type { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, Ope
 export { CaptureError, ToolCallCapture, captureTool } from './capture.js';
 export type { CallLike, CallRef, CaptureCall, CaptureErrorKind, CaptureEvent, CaptureFlushResult, CapturePart, CaptureSelector, CaptureSource, CaptureStats, CaptureStatus, DropReason, ToolCallCaptureOptions, WrapOptions, } from './capture.js';
 export type { AiSdkAdapter, AiSdkToolEndEvent, AnthropicAdapter, ClaudeAdapter, ClaudeCaptureHooks, ClaudeHookCallback, ClaudeHookMatcher, LangChainAdapter, LangChainToolHandler, MastraAdapter, MastraAfterToolCallContext, McpAdapter, OpenAIAgentsAdapter, } from './capture-adapters.js';
-export { ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from './errors.js';
+export { DurabilityLostError, ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from './errors.js';
 export type { AppErrorCode, CellErrorCode, ErrorCode, ErrorReason, KnownErrorReason, WorkspaceMode } from './errors.js';
 export { SDK_VERSION } from './http.js';
 export { API_KEY_TOOL_PERMISSIONS, AccountApiKeysApi, AccountAuditApi, AccountAuthApi, AccountBillingApi, AccountExportsApi, AccountInvitationsApi, AccountMembersApi, AccountOrganizationsApi, AccountProjectsApi, AccountTemplatesApi, AccountTotpApi, AccountUserApi, CheckoutTimeoutError, OrganizationExportsApi, SESSION_TOKEN_PATTERN, ShardfluxAccount, isSessionToken, parseEmailToken, } from './account.js';
 export type { AccountClientOptions, AccountDeletion, AccountDeletionCanceled, AccountDeletionScheduled, ApiKey, ApiKeyPage, ApiKeyToolPermission, AuditExportParams, AuthSessionInfo, AuthSessionPage, AuthSessionState, AuthUser, BillingInvoicePage, BillingPortalSession, CheckoutStatus, CreateApiKeyParams, CreatedApiKey, DataExport, EmailChangeConfirmResult, EmailChangeResult, Invitation, InvitationPage, LoginResult, Member, MemberPage, MemberRole, MfaChallengeResult, Organization, OrganizationDeletion, OrganizationDeletionResult, OrganizationPage, OrganizationRole, OrganizationWorkspacePage, OrganizationWorkspacesParams, PageParams, PasswordChangeResult, PasswordResetConfirmResult, PasswordResetRequestResult, Project, ProjectPage, RecoveryCodes, RegisterResult, ResendVerificationResult, SessionTokenUpdate, ShardfluxAccountOptions, SpendPolicyUpdate, StepUpResult, TotpConfirmResult, TotpDisableResult, TotpEnrollment, VerifyEmailResult, WaitForCheckoutOptions, } from './account.js';
 export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from './version-check.js';
 export type { CheckClientVersionOptions, ClientEcosystem, ClientVersionEntry, ClientVersionStatus, ClientVersionStatusKind, ClientVersions, VersionCheckIdentity, VersionCheckOption, } from './version-check.js';
+export { isWorkspaceGone } from './errors.js';
+export { defaultFetch } from './http.js';
+export type { IdlePolicy } from './client.js';
+export type { IdleStatus, KeepaliveResult } from './cell.js';
+export type { ExecInputResult } from './cell.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
-export { formatTiming } from "./progress.js";
+export { durabilityOf, formatTiming, isDurable, lostSuspendOf } from "./progress.js";
 export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from "./feedback.js";
 export { UsageApi } from "./usage.js";
 export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatePackagesApi, TemplateUploadError, TemplateUploadsApi, TemplateVersionTestInstancesApi, TemplateVersionsApi, TemplatesApi, buildSettled, saveAsTemplateBody, } from "./templates.js";
@@ -15,7 +15,9 @@ export { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 export { ToolTokenManager } from "./tokens.js";
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from "./tools.js";
 export { CaptureError, ToolCallCapture, captureTool } from "./capture.js";
-export { ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from "./errors.js";
+export { DurabilityLostError, ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from "./errors.js";
 export { SDK_VERSION } from "./http.js";
 export { API_KEY_TOOL_PERMISSIONS, AccountApiKeysApi, AccountAuditApi, AccountAuthApi, AccountBillingApi, AccountExportsApi, AccountInvitationsApi, AccountMembersApi, AccountOrganizationsApi, AccountProjectsApi, AccountTemplatesApi, AccountTotpApi, AccountUserApi, CheckoutTimeoutError, OrganizationExportsApi, SESSION_TOKEN_PATTERN, ShardfluxAccount, isSessionToken, parseEmailToken, } from "./account.js";
 export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from "./version-check.js";
+export { isWorkspaceGone } from "./errors.js";
+export { defaultFetch } from "./http.js";

package/dist/lifecycle.d.ts

@@ -32,9 +32,25 @@ export interface LifecycleOptions {
 export type WaitedLifecycleOptions = LifecycleOptions & {
     wait: true | WaitOptions;
 };
+/**
+ * `suspend()` options (0.12.0+). A waited suspend resolves as soon as the workspace is sealed on its host, typically in a
+ * few hundred ms; the finished operation's `result.durable` turns true when the copy lands in durable storage,
+ * typically within a second. `durable: true` resolves only then: it waits for the suspend (so it implies `wait`), then
+ * for `result.durable`, within the same `timeoutMs` and `signal`. It throws DurabilityLostError if the copy cannot be
+ * made, and OperationTimeoutError (`durable: true`) when the time runs out first; the copy continues server side.
+ */
+export interface SuspendOptions extends LifecycleOptions {
+    durable?: boolean;
+}
+/** Suspend options that wait: `wait` or `durable`. */
+export type WaitedSuspendOptions = SuspendOptions & ({
+    wait: true | WaitOptions;
+} | {
+    durable: true;
+});
 /**
  * `resume()` options (0.9.0). With `wait`, the server holds the resume until the workspace runs and returns a tool token
- * with it (contracts §22.6): `agentLabel` and `tools` choose that token (defaults: a workspace handle's own, those given
+ * with it: `agentLabel` and `tools` choose that token (defaults: a workspace handle's own, those given
  * to open(); `workspaces.resume(id)` otherwise the key's tools and label `default`). A handle keeps it for its `cell()`
  * clients of the same label and tools; `workspaces.resume(id)` only attributes it.
  */
@@ -50,7 +66,7 @@ export declare const TRACE: unique symbol;
 /** Internal: work a workspace handle does after the operation finished, inside the same trace (refreshing its view). */
 export declare const AFTER_WAIT: unique symbol;
 /**
- * Internal: a workspace handle's part in a held resume (contracts §22.6): the tool token to ask for, and how it takes the
+ * Internal: a workspace handle's part in a held resume: the tool token to ask for, and how it takes the
  * running workspace and that token from a 200 (instead of reading the view and fetching a token afterwards).
  */
 export declare const HELD_RESUME: unique symbol;
@@ -63,6 +79,7 @@ export type InternalWaitOptions = WaitOptions & {
     [TRACE]?: Trace;
 };
 export type InternalLifecycleOptions = ResumeOptions & {
+    durable?: boolean;
     [AFTER_WAIT]?: (trace: Trace, operation: Operation) => Promise<void>;
     [HELD_RESUME]?: HeldResumeTarget;
 };

package/dist/lifecycle.js

@@ -5,7 +5,7 @@ export const TRACE = Symbol('shardflux.trace');
 /** Internal: work a workspace handle does after the operation finished, inside the same trace (refreshing its view). */
 export const AFTER_WAIT = Symbol('shardflux.afterWait');
 /**
- * Internal: a workspace handle's part in a held resume (contracts §22.6): the tool token to ask for, and how it takes the
+ * Internal: a workspace handle's part in a held resume: the tool token to ask for, and how it takes the
  * running workspace and that token from a 200 (instead of reading the view and fetching a token afterwards).
  */
 export const HELD_RESUME = Symbol('shardflux.heldResume');
@@ -19,7 +19,9 @@ export function waitOptionsOf(opts) {
  * the request, every observed state, and `AFTER_WAIT`; it ends with `done` either way.
  */
 export async function runLifecycle(ctx, kind, workspaceId, start, opts, capture = {}) {
-    const waitOpts = waitOptionsOf(opts);
+    // `durable` (suspend) waits for the durable copy, so it implies `wait`.
+    const waitOpts = waitOptionsOf(opts) ?? (opts.durable ? {} : null);
+    const started = Date.now();
     const trace = new Trace(kind, combineListeners(ctx.onProgress, opts.onProgress, waitOpts?.onProgress), { workspaceId });
     return traced(trace, async () => {
         // Tool-call capture writes recorded before this call land first (snapshot, fork, suspend and close include them).
@@ -36,6 +38,11 @@ export async function runLifecycle(ctx, kind, workspaceId, start, opts, capture
             throw new OperationFailedError(operation);
         if (operation.state !== 'succeeded')
             final = await ctx.workspaces.waitForOperation(operation.id, { ...waitOpts, [TRACE]: trace });
+        if (opts.durable) {
+            // One budget for the whole call: what the suspend itself left.
+            const timeoutMs = Math.max(1, (waitOpts.timeoutMs ?? 300_000) - (Date.now() - started));
+            final = await ctx.workspaces.waitForDurable(final, { ...waitOpts, timeoutMs, [TRACE]: trace });
+        }
         await opts[AFTER_WAIT]?.(trace, final);
         return final;
     });

package/dist/progress.d.ts

@@ -1,7 +1,7 @@
 /**
- * Lifecycle timing and progress. A slow open (0.8 s one day, 34 s the next) should say where the time went without a
- * packet capture: waiting for a host, the cell booting or restoring the VM, the network between the caller and the API,
- * the first tool token, or retries.
+ * Lifecycle timing and progress. Every open, resume and wake says where its time went, without a packet capture: the
+ * queue, the cell booting or restoring the VM, the network between the caller and the API, the first tool token, or
+ * retries.
  *
  * A Trace follows one SDK call (open, a lifecycle call with `wait`, a wake, a token fetch). It records two clocks and
  * never mixes them:
@@ -28,8 +28,10 @@ export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork
  * - `busy`: a tool call waiting out `workspace_busy` (only in `tool` events).
  * - `capture_flush` (0.7.0+): a lifecycle call waiting for tool-call capture writes recorded before it (only when some
  *   were pending).
+ * - `durable` (0.12.0+): `suspend({ durable: true })` or `waitForDurable()` waiting for the durable copy after the
+ *   operation succeeded (reason `overdue` once the result has `durability.overdue_at`).
  */
-export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy' | 'capture_flush';
+export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy' | 'capture_flush' | 'durable';
 export interface TimingPhase {
     phase: LifecyclePhase;
     /** The server's state_reason, or why the SDK entered the phase (`held`, `initial`, `expiring`, `invalidated`). */
@@ -56,8 +58,8 @@ export interface ServerTiming {
     kind: Operation['kind'];
     state: Operation['state'];
     /**
-     * created_at → started_at: waiting until the cell began running the operation, including any wait for a host with
-     * capacity (started_at is set when the operation first enters `running`). Null when the API does not report
+     * created_at → started_at: waiting until the cell began running the operation, including any time in
+     * `capacity_pending` (started_at is set when the operation first enters `running`). Null when the API does not report
      * started_at or the operation has not run yet. An operation that finished without running (e.g. a failed dependency)
      * has started_at = completed_at, so all of its time shows here.
      */
@@ -71,10 +73,10 @@ export interface ServerTiming {
     /** `result.warm_fallback`: why a start that could be warm booted instead. */
     warmFallback: string | null;
     /**
-     * `result.resume_path`: `local_cache`, `prestaged` (copied to this host ahead of the resume, contracts §23),
-     * `download` (the checkpoint had to be fetched first), `cold_boot` (0.11.0+: no host could restore the memory
-     * snapshot, so the checkpoint's disk was booted; see `memoryRestored`) or `reset_blank_layer` (the first start after
-     * a reset).
+     * `result.resume_path`: `local_cache`, `prestaged` (copied to this host ahead of the resume),
+     * `download` (the checkpoint had to be fetched first), `cold_boot` (0.11.0+: the saved disk was booted after a
+     * platform runtime change; processes restarted; see `memoryRestored`) or `reset_blank_layer` (the first start after a
+     * reset).
      */
     resumePath: string | null;
     /**
@@ -89,11 +91,70 @@ export interface ServerTiming {
      * `runtime_changed` (the platform's VM runtime changed after the suspend). Null otherwise.
      */
     coldBootReason?: string | null;
+    /**
+     * `result.durable` (0.12.0+), suspend and fork: `true` when the capture is in durable storage, `false` while its
+     * durable copy is being written (see `durability`). `null` when the result does not say (other kinds, an older API).
+     */
+    durable?: boolean | null;
+    /** `result.suspend_path` (0.12.0+): `local_commit` when the suspend returned as soon as it was sealed on its host. */
+    suspendPath?: string | null;
+    /** `result.durability` (0.12.0+): the durable copy's state and timestamps. Null when the result has none. */
+    durability?: Durability | null;
+    /**
+     * `result.lost_suspend` (0.12.0+), resume: the workspace's latest suspend could not be kept and this resume restored the
+     * checkpoint before it (`restoredCheckpointId`, state as of `stateAsOf`). Null otherwise.
+     */
+    lostSuspend?: LostSuspend | null;
     /** `result.boot_to_ready_ms`: VM start until the guest agent answered. */
     bootToReadyMs: number | null;
     /** `result.host_timings_ms`: the host's own steps (restore: load, after_restore, ready, …). */
     hostTimingsMs: Record<string, number> | null;
 }
+/**
+ * `result.durability` of a suspend or fork (0.12.0+), camelCased. A suspend returns as soon as the workspace is sealed on
+ * its host (`pending`); `durable` follows when the copy lands in durable storage (`durableAt`). Timestamps are RFC 3339.
+ */
+export interface Durability {
+    /** `pending` (the durable copy is being written), `durable` (it committed) or `lost` (see the lifecycle reference). */
+    state: 'pending' | 'durable' | 'lost';
+    checkpointId: string | null;
+    generationId: string | null;
+    /** When the suspend (or fork) completed on its host. */
+    localCommitAt: string | null;
+    /** When the durable copy is expected by. */
+    durableBy: string | null;
+    /** When the durable copy committed (state `durable`). */
+    durableAt: string | null;
+    /** Local commit to durable commit, in milliseconds (state `durable`). */
+    localCommitToDurableMs: number | null;
+    /** Set once `durableBy` passed while the copy was still being written; it keeps going. */
+    overdueAt: string | null;
+    /** State `lost`: why (e.g. `host_lost`). */
+    reason: string | null;
+}
+/** `result.lost_suspend` of a resume (0.12.0+), camelCased. See the lifecycle reference. */
+export interface LostSuspend {
+    checkpointId: string;
+    generationId: string | null;
+    reason: string | null;
+    suspendedAt: string | null;
+    /** The earlier checkpoint this resume restored. */
+    restoredCheckpointId: string | null;
+    /** The restored state is as of this time (RFC 3339). */
+    stateAsOf: string | null;
+}
+/**
+ * The durable copy of a suspend or fork operation (0.12.0+): `result.durability` camelCased, or null when the result has
+ * none (the suspend was stored durably before it completed, or another kind).
+ */
+export declare function durabilityOf(op: Pick<Operation, 'result'>): Durability | null;
+/** A resume operation's `result.lost_suspend` camelCased (0.12.0+), or null. */
+export declare function lostSuspendOf(op: Pick<Operation, 'result'>): LostSuspend | null;
+/**
+ * Whether a suspend or fork operation's capture is in durable storage (0.12.0+): `result.durable`, else `true` for a
+ * succeeded suspend or fork whose result predates the field, else null.
+ */
+export declare function isDurable(op: Pick<Operation, 'result' | 'kind' | 'state'>): boolean | null;
 export type TimingOutcome = 'succeeded' | 'failed' | 'timed_out' | 'error';
 export interface LifecycleTiming {
     action: LifecycleAction;
@@ -123,8 +184,8 @@ interface EventBase {
 }
 /**
  * - `phase`: a phase began (live progress: "capacity_pending: no_ready_host"). `tool` phases come from tool calls.
- *   A `capacity_pending` phase carries `deadlineAt` (0.6.2+, when the API reports it): when the start gives up waiting
- *   for a host and fails with `capacity_unavailable` (retryable; nothing was started).
+ *   A `capacity_pending` phase carries `deadlineAt` (0.6.2+, when the API reports it): the start's deadline, past which
+ *   it fails with `capacity_unavailable` (retryable; nothing was started).
  * - `retry`: a request is retried after a transient failure (also emitted for tool calls, action `tool`).
  * - `done`: the call ended, successfully or not, with its full timing.
  */
@@ -146,9 +207,9 @@ export declare function emitTo(listeners: ReadonlyArray<ProgressListener | undef
 /** Combines listeners (client-level and per call) into one; undefined when there are none. */
 export declare function combineListeners(...listeners: Array<ProgressListener | undefined>): ProgressListener | undefined;
 /**
- * When a start waiting in `capacity_pending` gives up: the operation's `error.details.deadline_at` (RFC 3339). A start no
- * host admits by then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or
- * from an API that does not report it.
+ * The deadline of a start in `capacity_pending`: the operation's `error.details.deadline_at` (RFC 3339). A start still
+ * queued then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or from an
+ * API that does not report it.
  */
 export declare function capacityDeadlineOf(op: Operation): string | null;
 /** Server timing from an operation as GET /v1/operations/{id} returns it. */
@@ -169,7 +230,7 @@ export declare class Trace {
     get finished(): LifecycleTiming | null;
     /**
      * Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase.
-     * `deadlineAt`: when a `capacity_pending` start gives up (added to the event only).
+     * `deadlineAt`: the deadline of a `capacity_pending` start (added to the event only).
      */
     phase(phase: LifecyclePhase, reason?: string | null, deadlineAt?: string | null): void;
     /** Runs `fn` as a phase that may overlap others (open() reads the view and issues the token together). */
@@ -185,14 +246,14 @@ export declare class Trace {
 /** Runs `fn` under `trace` and ends the trace either way (the error keeps its timing). */
 export declare function traced<T>(trace: Trace, fn: () => Promise<T>): Promise<T>;
 /**
- * A human-readable account of a timing, for logs and bug reports:
+ * A human-readable account of a timing, for logs and bug reports. A resume in production:
  *
- *   open 34.18 s, succeeded (workspace <id>, operation <id>)
- *     client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 590 ms → view 42 ms ∥ token 61 ms
- *     server: queued 33.40 s, ran 620 ms, total 34.02 s; start warm, boot to ready 79 ms
- *     outside the server: 161 ms
- *     retries: 1 (POST /v1/workspaces/open, HTTP 503 unavailable, after 200 ms)
+ *   resume 413 ms, succeeded (workspace <id>, operation <id>)
+ *     client: request 218 ms → queued 195 ms
+ *     server: queued 51 ms, ran 290 ms, total 341 ms; resume from local_cache, boot to ready 211 ms, host disk 0 ms, load 6 ms, ready 62 ms, total 211 ms, after_restore 36 ms
+ *     outside the server: 72 ms
  *
+ * A call that retried a request adds `retries: <n> (<request>, <cause>, after <delay>)`.
  * A resume that booted the workspace instead of restoring its memory (0.11.0+) says so in the server line:
  * `resume from cold_boot: processes restarted (runtime_changed)`.
  */