@shardflux/sdk 0.11.1 → 0.13.0

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

@@ -80,6 +80,45 @@ export interface paths {
          *     `503 service_unavailable` (`no_execution_host`: no host with
          *     protocol feature `file_first` has room; retry), secret resolution
          *     errors as for processful starts.
+         *
+         *     Burst execution (contracts §33, not public yet): `burst: always` runs
+         *     the command on a larger, short-lived burst VM on the workspace's
+         *     host over a copy of the workspace disk and applies its file changes
+         *     back when it exits. The session is read, streamed and attached like
+         *     any other; it carries `burst` (BurstSummary) and cannot be signalled
+         *     or canceled (`409 conflict`, `details.reason burst_not_supported`).
+         *     Refusals: `422 validation_failed` with `details.reason`
+         *     `burst_mode_not_supported` (`auto`), `burst_not_supported` (stdin),
+         *     `burst_size_exceeds_plan` (`burst_vcpus`/`burst_memory_mib` above the
+         *     plan's per-workspace ceilings; `details.field`, `details.limit`);
+         *     `409 burst_unavailable` with `details.reason` `not_available` (no
+         *     entitlement `policy.burst_exec`, or the host lacks protocol feature
+         *     `burst_exec`), `layout_unsupported`, `shared_volumes`,
+         *     `host_capacity`, `fence_not_drained`, `workspace_fenced`,
+         *     `apply_pending`, `park_failed`, `workspace_resumed`, `interrupted`;
+         *     `409 burst_apply_failed` (`details.reason` `disk_full` or
+         *     `apply_failed`, `details.applied_entries`, `details.pending_entries`;
+         *     the workspace refuses writes until a retry with the same
+         *     `session_id` completes the apply). A refusal the host gives within
+         *     the first seconds is the start's answer; a later one ends the
+         *     session (`failed_to_start` for `burst_unavailable`, `lost` for
+         *     `burst_apply_failed`), is recorded in `burst.error`, and is the
+         *     output stream's final `error` event. A retry with the same
+         *     `session_id` replays the recorded outcome (the host journals the
+         *     burst by the exec's operation id) or resumes an unfinished apply.
+         *
+         *     Start and follow in one request: a processful start sent with
+         *     `Accept: application/x-ndjson` (or `text/event-stream`) answers 200
+         *     with the session's output stream, as `GET .../output?follow=true`
+         *     from offset 0 (output events, `exit`, a final `error`), and
+         *     `X-Exec-Session-Id` names the session. The stream slot is taken
+         *     before the command starts (`503 service_unavailable` when the
+         *     gateway has no stream slot: nothing ran). Headers are sent as soon
+         *     as the command started, before any output. A `failed_to_start`
+         *     session, a refusal and a file-first execution keep their JSON
+         *     answers. A replayed `session_id` streams the existing session and
+         *     never runs it again; after a dropped stream, reconnect with
+         *     `GET .../output` from the byte offsets already read.
          */
         post: operations["execStart"];
         delete?: never;
@@ -170,6 +209,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;
@@ -202,7 +264,16 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** SIGTERM the process group, SIGKILL after grace */
+        /**
+         * SIGTERM the process group, SIGKILL after grace
+         * @description Sends SIGTERM to the session's process group and SIGKILL after
+         *     `grace_ms` (0 to 60000; 0 or omitted is 5000). Answers when the
+         *     command has ended: at once when SIGTERM ends it, otherwise after the
+         *     grace and the SIGKILL. A `grace_ms` outside the range is `422
+         *     validation_failed`
+         *     (`details.field` `grace_ms`, `details.minimum`, `details.maximum`).
+         *     An ended session is returned as it is.
+         */
         post: operations["execCancel"];
         delete?: never;
         options?: never;
@@ -270,7 +341,11 @@ export interface paths {
         get: operations["ptyGet"];
         put?: never;
         post?: never;
-        /** Close (SIGHUP, then SIGKILL after grace) */
+        /**
+         * Close (SIGHUP, then SIGKILL after grace)
+         * @description Sends SIGHUP to the session's process group and SIGKILL 2 s later
+         *     if it is still running; answers once it has ended.
+         */
         delete: operations["ptyClose"];
         options?: never;
         head?: never;
@@ -721,8 +796,9 @@ export interface paths {
          * @description `idle_since` = max(`last_tool_at`, `last_attach_at`, `keepalive_until`,
          *     `running_since`, the work horizon of running exec commands) (null when
          *     none is known; in the future while a keepalive or a running command is
-         *     active). A running exec command counts as work until min(its start +
-         *     `IDLE_COMMAND_MAX_SECONDS`, its start + `timeout_ms`), and its end is
+         *     active). A running exec command counts as work until it ends or its
+         *     timeout passes: its start + `timeout_ms` when it has one, else its
+         *     start + `IDLE_COMMAND_MAX_SECONDS` (1 hour by default). Its end is
          *     activity (contracts §20.6): an end seen without a client call is
          *     recorded in `last_attach_at`, which is work but not a tool call.
          *     `suspend_at` = `idle_since` + `idle_minutes` when
@@ -800,7 +876,7 @@ export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
         /** @enum {string} */
-        ErrorCode: "bad_request" | "unauthenticated" | "forbidden" | "not_found" | "conflict" | "stale_epoch" | "workspace_not_running" | "validation_failed" | "payload_too_large" | "range_not_satisfiable" | "rate_limited" | "capacity_pending" | "dependency_unavailable" | "timeout" | "internal_error" | "service_unavailable" | "workspace_busy";
+        ErrorCode: "bad_request" | "unauthenticated" | "forbidden" | "not_found" | "conflict" | "stale_epoch" | "workspace_not_running" | "validation_failed" | "payload_too_large" | "range_not_satisfiable" | "rate_limited" | "capacity_pending" | "dependency_unavailable" | "timeout" | "internal_error" | "service_unavailable" | "workspace_busy" | "burst_unavailable" | "burst_apply_failed";
         ErrorBody: {
             error: {
                 code: components["schemas"]["ErrorCode"];
@@ -843,11 +919,16 @@ 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 */
             timeout_ms?: number;
-            /** Format: int64 */
+            /**
+             * Format: int64
+             * @description Time between the SIGTERM and the SIGKILL when timeout_ms ends the command; 0 or omitted is 5000.
+             */
             kill_grace_ms?: number;
             secret_refs?: components["schemas"]["SecretRefs"];
             /** @description File-first workspaces (required there, refused otherwise) — the execution's idempotency key. */
@@ -858,6 +939,16 @@ export interface components {
              * @default 1048576
              */
             output_limit_bytes?: number;
+            /**
+             * @description Burst execution (contracts §33): `always` runs this run-to-completion command on a larger, short-lived burst VM and applies its file changes back. Needs entitlement `policy.burst_exec` and a layered processful workspace; not with stdin. `auto` is reserved (422 validation_failed, details.reason burst_mode_not_supported).
+             * @default never
+             * @enum {string}
+             */
+            burst?: "never" | "always";
+            /** @description The burst VM's vCPUs (burst always only; default the host's, 8), at most the plan's workspace CPU ceiling. */
+            burst_vcpus?: number;
+            /** @description The burst VM's memory in MiB (burst always only; default the host's, 8192), at most the plan's workspace memory ceiling. */
+            burst_memory_mib?: number;
         };
         /** @description Names of customer secrets (contracts §17) to inject as environment variables NAME=value of this process only. The cell resolves them at session start through the API with the caller's tool token (permission-checked and audited by the API); values are never logged, persisted or returned by the cell. Any name the caller may not use (unknown, not permitted for this workspace/project/tool) refuses the whole start with 403 forbidden (details.reason secret_not_available, details.names); nothing is started. A name that is also a key of `env` is refused (422 validation_failed). Requires a workspace tool token (browser stream tickets cannot resolve secrets: 403, details.reason secret_refs_require_tool_token). Resolution failures: 401 (token revoked/expired), 409 stale_epoch, 429 rate_limited, 503 dependency_unavailable. A retried start with the same session_id re-resolves the names; if a value changed since the first start the host refuses the different request (409 conflict). */
         SecretRefs: string[];
@@ -955,6 +1046,88 @@ export interface components {
             ended_at?: string | null;
             /** @description Why the session ended without an exit code. For failed_to_start the command never ran and this names the cause, e.g. `working directory "/home/user/app" is not a directory` or `executable "foo" not found in PATH`. */
             error?: string;
+            memory_grow?: components["schemas"]["MemoryGrow"];
+            burst?: components["schemas"]["BurstSummary"];
+        };
+        /** @description Burst execution (contracts §33.5): present on every session started with `burst: always`. The size, method and counts are set once the burst ended (the host's result); while it runs only host, applied and the requested size are known. */
+        BurstSummary: {
+            /**
+             * @description Where the burst VM ran; `local` = the workspace's host (`remote` is reserved).
+             * @enum {string}
+             */
+            host: "local" | "remote";
+            /** @description The burst VM's vCPUs (the requested count while it runs, absent for the host default). */
+            vcpus?: number;
+            /** @description The burst VM's memory in MiB (the requested size while it runs, absent for the host default). */
+            memory_mib?: number;
+            /**
+             * @description How the burst VM got the workspace copy.
+             * @enum {string}
+             */
+            method?: "layer" | "clone";
+            /** @description The command's file changes were applied to the workspace. */
+            applied: boolean;
+            /** Format: int64 */
+            written_files?: number;
+            /** Format: int64 */
+            written_dirs?: number;
+            /** Format: int64 */
+            removed?: number;
+            /** Format: int64 */
+            written_bytes?: number;
+            /** @description Processes the command left behind in the burst VM (killed; they do not survive a burst). */
+            leftover_killed?: number;
+            /**
+             * Format: int64
+             * @description Wall time of the burst minus the command's own run time.
+             */
+            overhead_ms?: number;
+            /** @description The burst VM's own paths whose changes are never carried back (the host's denylist). */
+            excluded_paths?: string[];
+            /** @description The host's phase timings (ms) and counters. */
+            timings?: {
+                [key: string]: number;
+            };
+            /** @description The recorded outcome of an earlier attempt with the same session_id. */
+            replayed?: boolean;
+            /** @description Set when the burst failed after the start answered: burst_unavailable (the workspace is unchanged) or burst_apply_failed (details.applied_entries, details.pending_entries). */
+            error?: components["schemas"]["BurstError"];
+        };
+        BurstError: {
+            code: components["schemas"]["ErrorCode"];
+            message: string;
+            retryable: boolean;
+            details?: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Elastic memory (contracts §32.3, §32.6): the host grew the workspace's memory before this exec started (the exec waited for it). Present only on the session returned by the start that grew the VM; absent when no grow ran (fixed workspaces, or already at the exec size). */
+        MemoryGrow: {
+            /**
+             * @description delivered: the whole grow; partial: less than wanted; missed: nothing could be plugged; failed: the plug did not converge or errored.
+             * @enum {string}
+             */
+            outcome: "delivered" | "partial" | "missed" | "failed";
+            /**
+             * Format: int64
+             * @description Guest memory before the grow (MiB).
+             */
+            from_mib: number;
+            /**
+             * Format: int64
+             * @description Guest memory the grow aimed for (MiB).
+             */
+            want_mib: number;
+            /**
+             * Format: int64
+             * @description Guest memory after the grow (MiB).
+             */
+            got_mib: number;
+            /**
+             * Format: int64
+             * @description Trigger to plugged and guest MemTotal settled (ms, rounded).
+             */
+            deliver_ms: number;
         };
         OutputEvent: {
             /** @enum {string} */
@@ -974,11 +1147,27 @@ export interface components {
             /** @enum {string} */
             type: "signal" | "cancel";
             signal?: components["schemas"]["SignalValue"];
-            /** Format: int64 */
+            /**
+             * Format: int64
+             * @description For cancel, as CancelRequest.grace_ms; out of range is an `error` event (validation_failed).
+             */
             grace_ms?: number;
         };
         /** @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"];
             /**
@@ -988,7 +1177,10 @@ export interface components {
             only_leader?: boolean;
         };
         CancelRequest: {
-            /** Format: int64 */
+            /**
+             * Format: int64
+             * @description Time between the SIGTERM and the SIGKILL; 0 or omitted is 5000.
+             */
             grace_ms?: number;
         };
         PtyOpenRequest: {
@@ -1507,12 +1699,16 @@ export interface operations {
             };
         };
         responses: {
-            /** @description The session already existed; nothing was run again (processful), or the recorded result of an existing execution (file-first). */
+            /** @description An existing session/result, or followed output when a processful start accepts NDJSON/SSE. A failed-to-start session stays JSON. */
             200: {
                 headers: {
+                    /** @description The streamed session id; replay/reconnect use the same session and byte offsets. */
+                    "X-Exec-Session-Id"?: string;
                     [name: string]: unknown;
                 };
                 content: {
+                    "application/x-ndjson": string;
+                    "text/event-stream": string;
                     "application/json": components["schemas"]["ExecSession"] | components["schemas"]["ExecutionResult"];
                 };
             };
@@ -1607,6 +1803,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.1";
+export declare const SDK_VERSION = "0.13.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -13,6 +13,11 @@ export interface RequestOptions {
     signal?: AbortSignal;
     /** Override the client's default request timeout (ms); 0 disables it (streams). */
     timeoutMs?: number;
+    /**
+     * Bounds each attempt until the response headers arrive (ms), leaving the body unbounded: a stream that answers a
+     * start (exec.run's combined start and output). Usually with `timeoutMs: 0`.
+     */
+    headersTimeoutMs?: number;
     /** Called before each retry of a transient failure (lifecycle timing records these). */
     onRetry?: (retry: Omit<RetryRecord, 'atMs'>) => void;
 }
@@ -29,9 +34,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.13.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;
@@ -94,7 +108,13 @@ export class HttpClient {
             }
             const timeoutMs = init.timeoutMs ?? this.opts.timeoutMs;
             const timeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
-            const signal = timeout && init.signal ? AbortSignal.any([timeout, init.signal]) : (timeout ?? init.signal);
+            const headersMs = init.headersTimeoutMs ?? 0;
+            const headersAbort = headersMs > 0 ? new AbortController() : undefined;
+            const headersTimer = headersAbort
+                ? setTimeout(() => headersAbort.abort(new DOMException('The response headers timed out.', 'TimeoutError')), headersMs)
+                : undefined;
+            const signals = [timeout, init.signal, headersAbort?.signal].filter((s) => s !== undefined);
+            const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
             let res;
             try {
                 res = await this.opts.fetch(url, { method, headers, ...(body === undefined ? {} : { body: body }), ...(signal ? { signal } : {}) });
@@ -105,10 +125,13 @@ export class HttpClient {
                 if (!retriable || attempt >= this.opts.maxRetries)
                     throw err;
                 const delayMs = Math.min(2_000, 200 * 2 ** attempt);
-                init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(err, timeoutMs), delayMs });
+                init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(err, headersAbort?.signal.aborted ? headersMs : timeoutMs), delayMs });
                 await sleep(delayMs);
                 continue;
             }
+            finally {
+                clearTimeout(headersTimer);
+            }
             if (res.ok) {
                 if (this.opts.onSuccess) {
                     try {
@@ -142,7 +165,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 +176,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 +187,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

@@ -15,10 +15,10 @@
 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 { AgentSession, AllocationMode, 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, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export type { FinishedOperation, ForkOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, 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';
@@ -28,7 +28,7 @@ export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile }
 export type { PackedFile, YamlParser } from './template-file.js';
 export { tarEnd, tarHeader, tarPadding } from './tar.js';
 export type { TarEntry, TarEntryType } from './tar.js';
-export type { BuildFromFileEvent, BuildFromFileOptions, BuildFromFileResult, BuildFromRecipeOptions, BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, CreateVersionTestInstanceBody, CreateVersionTestInstanceParams, DraftOpened, LocalUpload, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, PutUploadOptions, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRecipeV2, TemplateBuildRegistrationState, TemplateBuildState, TemplateCategory, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateEgressDefault, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateInput, TemplateLanguage, TemplateLanguages, TemplateOwner, TemplatePackage, TemplatePackageEcosystem, TemplatePackagePage, TemplateRecipe, TemplateRecipeV2, TemplateRecipeV2File, TemplateService, TemplateSettings, TemplateSettingsInput, TemplateSource, TemplateStartCommand, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateUpload, TemplateUploadRequest, TemplateUploadResponse, TemplateUploadResult, TemplateVersion, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
+export type { BuildFromFileEvent, BuildFromFileOptions, BuildFromFileResult, BuildFromRecipeOptions, BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, CreateVersionTestInstanceBody, CreateVersionTestInstanceParams, DraftOpened, LocalUpload, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, PutUploadOptions, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRecipeV2, TemplateBuildRegistrationState, TemplateBuildState, TemplateCategory, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateEgressDefault, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateInput, TemplateLanguage, TemplateLanguages, TemplateOwner, TemplatePackage, TemplatePackageEcosystem, TemplatePackagePage, TemplateRecipe, TemplateRecipeV2, TemplateRecipeV2File, TemplateService, TemplateSettings, TemplateSettingsInput, TemplateSource, TemplateStartCommand, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateUpload, TemplateUploadRequest, TemplateUploadResponse, TemplateUploadResult, TemplateVersion, TemplateVersionImmutable, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
 export { SecretsApi, WorkspaceSecrets } from './secrets.js';
 export type { BoundSecretStatus, CreateOrganizationSecretParams, CreateSecretParams, Secret, SecretAccessEvent, SecretPermissions, SecretScope, SecretVersion, UpdateSecretParams, WorkspaceSecretBindings, } from './secrets.js';
 export { EgressPolicyApi } from './egress.js';
@@ -42,7 +42,7 @@ export type { HintOptions, HintResult, WakeOptions } from './workspace.js';
 export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from './cell.js';
 export { EXECUTION_ID, ExecutionResult, newExecutionId } from './executions.js';
 export type { ExecutionChange, ExecutionError, ExecutionGetOptions, ExecutionResultBody, ExecutionRunOptions, ExecutionState } from './executions.js';
-export type { TreeRevisionOptions, BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, RunOptions, RunResult, ServedFrom, Signal, WakeHintResult, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
+export type { TreeRevisionOptions, BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, MemoryGrow, BurstSummary, BurstError, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, RunOptions, RunResult, ServedFrom, Signal, WakeHintResult, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
 export { ToolTokenManager } from './tokens.js';
 export type { ToolName, ToolToken, ToolTokenOptions } from './tokens.js';
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from './tools.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
@@ -45,6 +61,11 @@ export interface ResumeOptions extends LifecycleOptions {
 export type WaitedResumeOptions = ResumeOptions & {
     wait: true | WaitOptions;
 };
+/** A waited fork (0.13.0+) returns the target view and token together when the API supports it. */
+export type ForkOptions = ResumeOptions;
+export type WaitedForkOptions = ForkOptions & {
+    wait: true | WaitOptions;
+};
 /** Internal: the trace a wait continues instead of starting its own (open(), wake() and waited lifecycle calls). */
 export declare const TRACE: unique symbol;
 /** Internal: work a workspace handle does after the operation finished, inside the same trace (refreshing its view). */
@@ -63,6 +84,7 @@ export type InternalWaitOptions = WaitOptions & {
     [TRACE]?: Trace;
 };
 export type InternalLifecycleOptions = ResumeOptions & {
+    durable?: boolean;
     [AFTER_WAIT]?: (trace: Trace, operation: Operation) => Promise<void>;
     [HELD_RESUME]?: HeldResumeTarget;
 };
@@ -71,6 +93,7 @@ export declare function waitOptionsOf(opts: LifecycleOptions): WaitOptions | nul
  * Starts a lifecycle operation with `start` and, when `opts.wait` asks for it, waits for it to finish. The trace covers
  * the request, every observed state, and `AFTER_WAIT`; it ends with `done` either way.
  */
-export declare function runLifecycle(ctx: ClientContext, kind: LifecycleAction, workspaceId: string, start: (init: Pick<RequestOptions, 'onRetry'>) => Promise<Operation>, opts: InternalLifecycleOptions, capture?: {
+export declare function runLifecycle(ctx: ClientContext, kind: LifecycleAction, workspaceId: string, start: (init: Pick<RequestOptions, 'onRetry'>, trace: Trace) => Promise<Operation>, opts: InternalLifecycleOptions, capture?: {
     settle?: boolean;
+    requestReason?: string | null;
 }): Promise<Operation>;