@shardflux/sdk 0.11.1 → 0.12.0

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.11.1";
+export declare const SDK_VERSION = "0.12.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -29,9 +29,9 @@ export interface HttpOptions {
 }
 export declare const defaultSleep: (ms: number) => Promise<void>;
 /**
- * The fetch the SDK uses when none is given. On Node 26 every request uses a fresh connection (`Connection: close`),
- * as in the CLI and the MCP server; other runtimes reuse connections. `SHARDFLUX_HTTP_KEEPALIVE=1` reuses connections
- * on Node 26 too.
+ * 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;

package/dist/http.js

@@ -8,23 +8,37 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.11.1';
+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 Node 26 every request uses a fresh connection (`Connection: close`),
- * as in the CLI and the MCP server; other runtimes reuse connections. `SHARDFLUX_HTTP_KEEPALIVE=1` reuses connections
- * on Node 26 too.
+ * 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) {
@@ -62,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;
@@ -142,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). */
@@ -153,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). */
@@ -164,7 +178,7 @@ 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);
         }
     }
 }

package/dist/index.d.ts

@@ -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,6 +32,22 @@ 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: `agentLabel` and `tools` choose that token (defaults: a workspace handle's own, those given
@@ -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

@@ -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

@@ -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`). */
@@ -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;

package/dist/progress.js

@@ -1,3 +1,55 @@
+const DURABILITY_STATES = new Set(['pending', 'durable', 'lost']);
+/**
+ * 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 function durabilityOf(op) {
+    const d = op.result?.durability;
+    if (typeof d !== 'object' || d === null)
+        return null;
+    const r = d;
+    if (typeof r.state !== 'string' || !DURABILITY_STATES.has(r.state))
+        return null;
+    return {
+        state: r.state,
+        checkpointId: str(r.checkpoint_id),
+        generationId: str(r.generation_id),
+        localCommitAt: str(r.local_commit_at),
+        durableBy: str(r.durable_by),
+        durableAt: str(r.durable_at),
+        localCommitToDurableMs: num(r.local_commit_to_durable_ms),
+        overdueAt: str(r.overdue_at),
+        reason: str(r.reason),
+    };
+}
+/** A resume operation's `result.lost_suspend` camelCased (0.12.0+), or null. */
+export function lostSuspendOf(op) {
+    const l = op.result?.lost_suspend;
+    if (typeof l !== 'object' || l === null)
+        return null;
+    const r = l;
+    const checkpointId = str(r.checkpoint_id);
+    if (!checkpointId)
+        return null;
+    return {
+        checkpointId,
+        generationId: str(r.generation_id),
+        reason: str(r.reason),
+        suspendedAt: str(r.suspended_at),
+        restoredCheckpointId: str(r.restored_checkpoint_id),
+        stateAsOf: str(r.state_as_of),
+    };
+}
+/**
+ * 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 function isDurable(op) {
+    const v = op.result?.durable;
+    if (typeof v === 'boolean')
+        return v;
+    return op.state === 'succeeded' && (op.kind === 'suspend' || op.kind === 'fork') ? true : null;
+}
 /** Calls every listener; a listener that throws never breaks the SDK call. */
 export function emitTo(listeners, event) {
     for (const l of listeners) {
@@ -66,6 +118,10 @@ export function serverTiming(op) {
         // Unknown (null) unless the result says so: a result without the field is never read as "not restored".
         memoryRestored: typeof r.memory_restored === 'boolean' ? r.memory_restored : null,
         coldBootReason: str(r.cold_boot_reason),
+        durable: typeof r.durable === 'boolean' ? r.durable : null,
+        suspendPath: str(r.suspend_path),
+        durability: durabilityOf(op),
+        lostSuspend: lostSuspendOf(op),
         bootToReadyMs: num(r.boot_to_ready_ms),
         hostTimingsMs,
     };
@@ -76,6 +132,8 @@ function outcomeOf(err) {
         return 'failed';
     if (name === 'OperationTimeoutError')
         return 'timed_out';
+    if (name === 'DurabilityLostError')
+        return 'failed';
     return 'error';
 }
 /** Why a request failed, in one short phrase (for retry records). */
@@ -249,6 +307,9 @@ export function formatTiming(t) {
         const how = [
             s.startPath ? `start ${s.startPath}${s.warmFallback ? ` (warm fallback: ${s.warmFallback})` : ''}` : null,
             s.resumePath ? `resume from ${s.resumePath}${s.memoryRestored === false ? `: processes restarted${s.coldBootReason ? ` (${s.coldBootReason})` : ''}` : ''}` : null,
+            s.lostSuspend ? `restored ${s.lostSuspend.restoredCheckpointId ?? 'no checkpoint'} (latest suspend ${s.lostSuspend.checkpointId} ${s.lostSuspend.reason ?? 'lost'})` : null,
+            s.suspendPath === 'local_commit' ? 'sealed on host' : null,
+            s.durability?.state === 'durable' ? `durable${s.durability.localCommitToDurableMs !== null ? ` ${fmt(s.durability.localCommitToDurableMs)} later` : ''}` : s.durability ? `durable copy ${s.durability.state}` : null,
             s.bootToReadyMs !== null ? `boot to ready ${fmt(s.bootToReadyMs)}` : null,
             s.hostTimingsMs ? `host ${Object.entries(s.hostTimingsMs).map(([k, v]) => `${k} ${fmt(v)}`).join(', ')}` : null,
         ].filter(Boolean);

package/dist/workspace.d.ts

@@ -2,12 +2,12 @@
  * A workspace handle: the latest view from the application API plus managed
  * tool tokens and cell clients (one per agent label / tool set).
  */
-import type { ClientContext, DiskLayout, ForkTarget, Operation, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
+import type { ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
 import { CAPTURE_BARRIER, CellClient } from './cell.js';
 import { ToolCallCapture } from './capture.js';
 import type { ToolCallCaptureOptions } from './capture.js';
 import type { WorkspaceMode } from './errors.js';
-import type { FinishedOperation, LifecycleOptions, ResumeOptions, WaitedLifecycleOptions, WaitedResumeOptions } from './lifecycle.js';
+import type { FinishedOperation, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 import { Trace } from './progress.js';
 import type { LifecycleTiming, ProgressListener } from './progress.js';
 import { WorkspaceSecrets } from './secrets.js';
@@ -135,11 +135,20 @@ export declare class Workspace {
     get secrets(): WorkspaceSecrets;
     /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
     inputs(): Promise<Record<string, string>>;
+    get labels(): Record<string, string>;
+    setLabels(labels: Record<string, string>): Promise<this>;
+    setIdlePolicy(policy: IdlePolicy | null): Promise<this>;
+    idle(signal?: AbortSignal): ReturnType<CellClient['idle']>;
+    keepalive(seconds: number, signal?: AbortSignal): ReturnType<CellClient['keepalive']>;
     refresh(): Promise<this>;
-    /** Waits for the active operation (if any) and refreshes. */
+    /**
+     * Waits for the active operation (if any) and refreshes. A suspend-when-idle that found the workspace active is
+     * canceled `workspace_active` (0.12.0+: `OperationFailedError.workspaceActive`); the workspace keeps running, so this
+     * resolves.
+     */
     waitUntilReady(opts?: WaitOptions): Promise<this>;
     /**
-     * Deletes the workspace (tool access ends at once; keys are never reused). Resolves when the delete is REQUESTED;
+     * Deletes the workspace (tool access ends at once; the key can be reused after deletion finishes). Resolves when the delete is REQUESTED;
      * with `{ wait: true }`, once it has FINISHED.
      */
     delete(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
@@ -147,12 +156,15 @@ export declare class Workspace {
     /**
      * Suspends the workspace: memory and processes are checkpointed, compute stops. Resolves when the suspend is
      * REQUESTED (the operation is usually still `queued`, and the workspace still running); pass `{ wait: true }` to
-     * resolve once it has FINISHED, with `workspace.state` then `suspended`.
+     * resolve once it has FINISHED, with `workspace.state` then `suspended`. That is as soon as the workspace is sealed on
+     * its host, typically in a few hundred ms. `result.durable` (also `lastTiming.server.durable`, 0.12.0+) turns true
+     * when the copy lands in durable storage, typically within a second; `{ durable: true }` resolves only then.
      *
      *   await workspace.suspend({ wait: true });
+     *   await workspace.suspend({ durable: true }); // 0.12.0+: also wait for the durable copy
      */
-    suspend(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
-    suspend(opts?: LifecycleOptions): Promise<Operation>;
+    suspend(opts: WaitedSuspendOptions): Promise<FinishedOperation>;
+    suspend(opts?: SuspendOptions): Promise<Operation>;
     /**
      * Suspends the workspace once it has been idle for `afterSeconds` (0..3600, 0 = as soon as it is idle; 0.9.0): call it when your agent's turn
      * ends, so the workspace stops using RAM soon after instead of waiting out its idle policy. A command still running,
@@ -176,7 +188,9 @@ export declare class Workspace {
      * those given to open()), so `cell()` calls with that label and tools start at once. A workspace that is already
      * running is ShardfluxApiError 409 `conflict` (`already_running`). The finished operation's `result.memory_restored`
      * (also `lastTiming.server.memoryRestored`, 0.11.0+) is false when the resume booted the saved disk instead
-     * (`resume_path` `cold_boot`): files kept, processes restarted.
+     * (`resume_path` `cold_boot`): files kept, processes restarted. `result.lost_suspend` (also
+     * `lastTiming.server.lostSuspend`, `lostSuspendOf(op)`, 0.12.0+) names a suspend this resume could not restore and the
+     * checkpoint it restored instead (see the lifecycle reference).
      */
     resume(opts: WaitedResumeOptions): Promise<FinishedOperation>;
     resume(opts?: ResumeOptions): Promise<Operation>;

package/dist/workspace.js

@@ -181,17 +181,39 @@ export class Workspace {
     inputs() {
         return this.#ctx.workspaces.inputs(this.id);
     }
+    get labels() { return { ...this.#view.labels }; }
+    async setLabels(labels) {
+        this.#view = (await this.#ctx.workspaces.setLabels(this.id, labels)).data;
+        return this;
+    }
+    async setIdlePolicy(policy) {
+        this.#view = (await this.#ctx.workspaces.setIdlePolicy(this.id, policy)).data;
+        return this;
+    }
+    idle(signal) { return this.cell().idle(signal); }
+    keepalive(seconds, signal) { return this.cell().keepalive(seconds, signal); }
     async refresh() {
         this.#view = await this.#ctx.http.json('GET', `/v1/workspaces/${encodeURIComponent(this.id)}`, {}, this.#ctx.authorization);
         if (this.#view.mode === 'file_first' && typeof this.#view.tree_revision === 'number')
             this.#noteTreeRevision(this.#view.tree_revision);
         return this;
     }
-    /** Waits for the active operation (if any) and refreshes. */
+    /**
+     * Waits for the active operation (if any) and refreshes. A suspend-when-idle that found the workspace active is
+     * canceled `workspace_active` (0.12.0+: `OperationFailedError.workspaceActive`); the workspace keeps running, so this
+     * resolves.
+     */
     async waitUntilReady(opts = {}) {
         const op = this.#view.active_operation;
-        if (op)
-            await this.#ctx.workspaces.waitForOperation(op.id, opts);
+        if (op) {
+            try {
+                await this.#ctx.workspaces.waitForOperation(op.id, opts);
+            }
+            catch (e) {
+                if (!(e instanceof OperationFailedError) || !e.workspaceActive)
+                    throw e;
+            }
+        }
         return this.refresh();
     }
     delete(opts = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "type": "module",
   "description": "Shardflux TypeScript SDK: open persistent agent workspaces by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
   "license": "Apache-2.0",
@@ -71,6 +71,9 @@
     "yaml": "2.9.1",
     "zod": "4.6.5"
   },
+  "dependencies": {
+    "undici": "8.10.2"
+  },
   "scripts": {
     "build": "node scripts/build.mjs",
     "generate": "openapi-typescript ../contracts/openapi/app-api.json -o src/generated/app-api.ts && openapi-typescript ../contracts/openapi/cell-api.yaml --default-non-nullable false -o src/generated/cell-api.ts",