@shardflux/sdk 0.13.0 → 0.14.0

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

@@ -191,7 +191,7 @@ export interface paths {
          *     Client messages are JSON `ExecClientMessage`. Close codes: 1000 after
          *     the `exit` event, 1001 on gateway shutdown (reconnect with offsets),
          *     4401 unauthenticated, 4403 forbidden, 4409 stale epoch / workspace
-         *     busy / workspace not running, 4410 workspace gone, 4429 rate limited,
+         *     busy / workspace not running, 4410 workspace gone, 4429 rate limited / quota exceeded,
          *     4500/4503/4504 internal/unavailable/timeout (4000 + HTTP status; see
          *     "WebSocket close codes" above; the close reason is compact JSON with
          *     the error `code`). A refused upgrade from an allowed Origin is
@@ -265,14 +265,18 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * 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`
+         * Stop the command and every process it started (SIGTERM, SIGKILL after grace)
+         * @description Sends SIGTERM to every process the command started, background and
+         *     setsid processes included, and SIGKILL after `grace_ms` (0 to 60000;
+         *     0 or omitted is 5000). Answers when they have all exited: at once when
+         *     SIGTERM ends them, otherwise after the grace and the SIGKILL. A lost
+         *     command is stopped the same way; a command that already exited keeps
+         *     its result and what it left running is stopped. `503
+         *     dependency_unavailable` (retryable) while a process cannot exit yet.
+         *     Template versions before python-node-browser 13, ubuntu-24.04 4,
+         *     ubuntu-22.04 2 and debian-12 2 signal the command's process group and
+         *     return an ended session as it is. 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;
@@ -876,7 +880,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" | "burst_unavailable" | "burst_apply_failed";
+        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" | "quota_exceeded";
         ErrorBody: {
             error: {
                 code: components["schemas"]["ErrorCode"];
@@ -949,6 +953,12 @@ export interface components {
             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 Contracts §41.1: whether an elastic workspace's memory grows before the command starts. `heavy` grows it to the exec-start size first; `light` starts at once (pressure grows cover a spike); `auto` (default) grows only for a heavy command family (package installers, test runners, compilers, type checkers, bundlers). Changes only elastic workspaces in memory layout v2; any other value is 422 validation_failed (details.field resource_hint).
+             * @default auto
+             * @enum {string}
+             */
+            resource_hint?: "auto" | "light" | "heavy";
         };
         /** @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[];

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.13.0";
+export declare const SDK_VERSION = "0.14.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -10,6 +10,11 @@ export interface RequestOptions {
     idempotencyKey?: string;
     /** The request has no effect a retry could duplicate (a read-only POST such as files/search): retried like a GET. */
     idempotent?: boolean;
+    /**
+     * false: the cell gateway's 429 `quota_exceeded` surfaces at once instead of being retried (the wake hint, which
+     * never waits). Default true.
+     */
+    quotaRetry?: boolean;
     signal?: AbortSignal;
     /** Override the client's default request timeout (ms); 0 disables it (streams). */
     timeoutMs?: number;
@@ -33,13 +38,45 @@ export interface HttpOptions {
     onSuccess?: (() => void) | undefined;
 }
 export declare const defaultSleep: (ms: number) => Promise<void>;
+/**
+ * How long an idle pooled connection stays reusable (ms): 5 minutes, instead of undici's 4 s default, so the request
+ * after an agent's usual pause between tool calls (15 s to a few minutes) skips a new TCP and TLS handshake. Far below
+ * the 3600 s idle timeout of the load balancer in front of the API and the cell endpoints, so the server side never
+ * closes a connection for idleness while the client still treats it as reusable; below the AWS NAT gateway's 350 s idle
+ * timeout; and the same limit Chrome keeps for used idle sockets. Also caps a server's `Keep-Alive: timeout` hint.
+ */
+export declare const KEEP_ALIVE_TIMEOUT_MS = 300000;
+/**
+ * TCP keepalive probes start after a pooled socket has been idle this long (ms), so NATs and firewalls with shorter
+ * idle timeouts than the pool's (Azure SNAT: 4 minutes) keep the connection instead of silently dropping it. Equal to
+ * undici's own default, set explicitly so it is visible and tested.
+ */
+export declare const TCP_KEEPALIVE_INITIAL_DELAY_MS = 60000;
+/** The private pool's undici Agent options (exported for tests). */
+export declare const POOL_OPTIONS: {
+    readonly allowH2: false;
+    readonly pipelining: 1;
+    readonly keepAliveTimeout: 300000;
+    readonly keepAliveMaxTimeout: 300000;
+    readonly connect: {
+        readonly keepAlive: true;
+        readonly keepAliveInitialDelay: 60000;
+    };
+};
 /**
  * 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.
+ * private HTTP/1.1-only dispatcher whose idle connections stay reusable for KEEP_ALIVE_TIMEOUT_MS. 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. Idle pooled sockets do not keep the process alive.
  */
 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;
+/**
+ * True when fetch failed because its connection closed or reset before a response arrived: what a request sees when
+ * it went out on a pooled connection the other side closed while it sat idle. Connect failures (ECONNREFUSED,
+ * ENOTFOUND, UND_ERR_CONNECT_TIMEOUT), timeouts and aborts are not this.
+ */
+export declare function isStaleConnectionError(err: unknown): boolean;
 /** `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). */

package/dist/http.js

@@ -4,18 +4,44 @@
  * retries only where a retry cannot duplicate an effect (safe methods,
  * requests carrying an Idempotency-Key, and read-only POSTs marked
  * `idempotent`). A retryable 429/502/503/504 (e.g. 503 `host_capacity`, 503
- * `wake_failed`) waits `Retry-After` (at most 5 s) before the retry.
+ * `wake_failed`) waits `Retry-After` (at most 5 s) before the retry. Such a request whose connection closed before
+ * any response (a pooled connection gone stale while idle) is sent again at once, once, outside `maxRetries`. The cell
+ * gateway's 429 `quota_exceeded` (every working slot of the plan is taken) is retried for any request (0.14.0+): it is
+ * refused at admission, so nothing ran.
  */
-import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody } from "./errors.js";
+import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody, isWorkingQuotaRefusal } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.13.0';
+export const SDK_VERSION = '0.14.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * How long an idle pooled connection stays reusable (ms): 5 minutes, instead of undici's 4 s default, so the request
+ * after an agent's usual pause between tool calls (15 s to a few minutes) skips a new TCP and TLS handshake. Far below
+ * the 3600 s idle timeout of the load balancer in front of the API and the cell endpoints, so the server side never
+ * closes a connection for idleness while the client still treats it as reusable; below the AWS NAT gateway's 350 s idle
+ * timeout; and the same limit Chrome keeps for used idle sockets. Also caps a server's `Keep-Alive: timeout` hint.
+ */
+export const KEEP_ALIVE_TIMEOUT_MS = 300_000;
+/**
+ * TCP keepalive probes start after a pooled socket has been idle this long (ms), so NATs and firewalls with shorter
+ * idle timeouts than the pool's (Azure SNAT: 4 minutes) keep the connection instead of silently dropping it. Equal to
+ * undici's own default, set explicitly so it is visible and tested.
+ */
+export const TCP_KEEPALIVE_INITIAL_DELAY_MS = 60_000;
+/** The private pool's undici Agent options (exported for tests). */
+export const POOL_OPTIONS = {
+    allowH2: false,
+    pipelining: 1,
+    keepAliveTimeout: KEEP_ALIVE_TIMEOUT_MS,
+    keepAliveMaxTimeout: KEEP_ALIVE_TIMEOUT_MS,
+    connect: { keepAlive: true, keepAliveInitialDelay: TCP_KEEPALIVE_INITIAL_DELAY_MS },
+};
 /** One private HTTP/1.1 pool on Node 26+, shared by SDK clients. No global dispatcher changes. */
 let nodeFetch;
 /**
  * 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.
+ * private HTTP/1.1-only dispatcher whose idle connections stay reusable for KEEP_ALIVE_TIMEOUT_MS. 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. Idle pooled sockets do not keep the process alive.
  */
 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.
@@ -30,7 +56,7 @@ export function defaultFetch(env = globalThis.process?.env, undiciVersion = glob
         return base;
     return async (input, init) => {
         nodeFetch ??= import('undici').then(({ Agent, fetch: pooledFetch }) => {
-            const dispatcher = new Agent({ allowH2: false, pipelining: 1 });
+            const dispatcher = new Agent({ ...POOL_OPTIONS, connect: { ...POOL_OPTIONS.connect } });
             return async (input, init) => {
                 const response = await pooledFetch(input, { ...init, dispatcher });
                 // Web-standard runtime shape; undici and DOM iterator declarations differ.
@@ -49,6 +75,25 @@ export function buildUrl(base, path, query) {
     }
     return u.toString();
 }
+/** Codes (on fetch's `cause` chain) of a connection that closed or reset before the response arrived. */
+const STALE_CONNECTION_CODES = new Set(['UND_ERR_SOCKET', 'ECONNRESET', 'EPIPE', 'UND_ERR_CLOSED']);
+/**
+ * True when fetch failed because its connection closed or reset before a response arrived: what a request sees when
+ * it went out on a pooled connection the other side closed while it sat idle. Connect failures (ECONNREFUSED,
+ * ENOTFOUND, UND_ERR_CONNECT_TIMEOUT), timeouts and aborts are not this.
+ */
+export function isStaleConnectionError(err) {
+    if (!(err instanceof TypeError))
+        return false;
+    const seen = new Set();
+    for (let c = err.cause; typeof c === 'object' && c !== null && !seen.has(c); c = c.cause) {
+        seen.add(c);
+        const code = c.code;
+        if (typeof code === 'string' && STALE_CONNECTION_CODES.has(code))
+            return true;
+    }
+    return false;
+}
 function retryAfterSeconds(res) {
     const v = res.headers.get('retry-after');
     if (v === null)
@@ -89,6 +134,9 @@ export class HttpClient {
         const safe = method === 'GET' || method === 'HEAD';
         const retriable = safe || init.idempotencyKey !== undefined || init.idempotent === true;
         const sleep = this.opts.sleep ?? defaultSleep;
+        // Retries counted against maxRetries (they also set the backoff); `attempt` counts every send.
+        let counted = 0;
+        let staleReplayed = false;
         for (let attempt = 0;; attempt += 1) {
             const headers = {
                 accept: init.accept ?? 'application/json',
@@ -122,9 +170,20 @@ export class HttpClient {
             catch (err) {
                 if (init.signal?.aborted)
                     throw err;
-                if (!retriable || attempt >= this.opts.maxRetries)
+                if (!retriable)
+                    throw err;
+                if (!staleReplayed && !signal?.aborted && isStaleConnectionError(err)) {
+                    // The connection closed before any response, typically a pooled one the server or a NAT closed while idle:
+                    // send again at once on a fresh connection, once per request and outside maxRetries (as Go's net/http
+                    // replays a request that failed on a reused connection when it is idempotent or carries an Idempotency-Key).
+                    staleReplayed = true;
+                    init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(err), delayMs: 0 });
+                    continue;
+                }
+                if (counted >= this.opts.maxRetries)
                     throw err;
-                const delayMs = Math.min(2_000, 200 * 2 ** attempt);
+                const delayMs = Math.min(2_000, 200 * 2 ** counted);
+                counted += 1;
                 init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(err, headersAbort?.signal.aborted ? headersMs : timeoutMs), delayMs });
                 await sleep(delayMs);
                 continue;
@@ -146,10 +205,15 @@ export class HttpClient {
             const error = await errorFrom(res, this.opts.source);
             const retryableStatus = res.status === 429 || res.status === 502 || res.status === 503 || res.status === 504;
             const retryableError = error instanceof ShardfluxApiError ? error.retryable && retryableStatus : retryableStatus;
-            if (!retriable || !retryableError || attempt >= this.opts.maxRetries)
+            // The working-at-once quota (cell 429 quota_exceeded): the gateway refuses the call at admission, before the
+            // workspace is touched, so nothing ran and even a non-idempotent request (exec start, stdin, PTY create,
+            // keepalive) is safe to send again. Same Retry-After wait and retry budget as every other retry.
+            const admissionRefusal = init.quotaRetry !== false && isWorkingQuotaRefusal(error);
+            if ((!retriable && !admissionRefusal) || !retryableError || counted >= this.opts.maxRetries)
                 throw error;
             const hinted = error instanceof ShardfluxApiError ? error.retryAfterSeconds : undefined;
-            const delayMs = Math.min(5_000, hinted !== undefined ? hinted * 1000 : 200 * 2 ** attempt);
+            const delayMs = Math.min(5_000, hinted !== undefined ? hinted * 1000 : 200 * 2 ** counted);
+            counted += 1;
             init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(error), delayMs });
             await sleep(delayMs);
         }

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, 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 { AgentSession, AllocationMode, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResizeAppliesAt, ResizeCpu, ResizeDeferReason, ResizeDisk, ResizeLimitReason, ResizeMemory, ResizeParams, ResizeResult, ResizeResponse, 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 { COLD_BOOT_REASONS, durabilityOf, formatTiming, hostLostOf, isDurable, lostSuspendOf } from './progress.js';
+export type { ColdBootReason, Durability, HostLost, 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';
@@ -29,6 +29,8 @@ 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, TemplateVersionImmutable, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
+export { WorkspacePorts } from './ports.js';
+export type { ExposePortResult, ExposedPort, PortCallbackResponse, PortCallbackUrl, PortLink, PortLinkOptions, PortLinkResponse, PortToken, PortTokenOptions, PortTokenResponse, PortView } from './ports.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 +44,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, 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 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, ResourceHint, 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';
@@ -54,7 +56,9 @@ export { DurabilityLostError, ExecStartError, NotSupportedForModeError, Operatio
 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 { codexIdentityProof } from './codex-proof.js';
+export type { CodexIdentityProof, CodexProofOptions, CodexProofUnavailable } from './codex-proof.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, SignupResult, SignupAccess, EmailCodeResult, 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';

package/dist/index.js

@@ -1,10 +1,11 @@
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
-export { durabilityOf, formatTiming, isDurable, lostSuspendOf } from "./progress.js";
+export { COLD_BOOT_REASONS, durabilityOf, formatTiming, hostLostOf, 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";
 export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from "./template-file.js";
 export { tarEnd, tarHeader, tarPadding } from "./tar.js";
+export { WorkspacePorts } from "./ports.js";
 export { SecretsApi, WorkspaceSecrets } from "./secrets.js";
 export { EgressPolicyApi } from "./egress.js";
 export { VolumesApi } from "./volumes.js";
@@ -18,6 +19,7 @@ export { CaptureError, ToolCallCapture, captureTool } from "./capture.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 { codexIdentityProof } from "./codex-proof.js";
 export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from "./version-check.js";
 export { isWorkspaceGone } from "./errors.js";
 export { defaultFetch } from "./http.js";

package/dist/ports.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Inbound ports (0.14.0; contracts §39.3): serve a TCP port of a processful workspace at its own HTTPS URL,
+ * `https://<port>-<handle>.<ingress domain>`. Every port is private: a request carries a port token
+ * (`Authorization: Bearer sfp_…`), a signed link's browser session, or arrives on the port's callback URL. A request
+ * to a suspended or parked workspace wakes it and is served once it runs.
+ *
+ *   const { url } = await workspace.ports.expose(3000);
+ *   const { token } = await workspace.ports.token(3000);
+ *   await fetch(url, { headers: { authorization: `Bearer ${token}` } });
+ *
+ * Types are written by hand (checked against the generated contract in type-checks.ts).
+ */
+import type { components, operations } from './generated/app-api.js';
+import type { ClientContext } from './client.js';
+type Created<Op> = Op extends {
+    responses: {
+        201: {
+            content: {
+                'application/json': infer T;
+            };
+        };
+    };
+} ? T : never;
+/** An exposed port as the API sends it (`Port`). */
+export type PortView = components['schemas']['Port'];
+/** POST …/ports/{port}/tokens (201). */
+export type PortTokenResponse = Created<operations['postV1WorkspacesWorkspaceIdPortsPortTokens']>;
+/** POST …/ports/{port}/links (201). */
+export type PortLinkResponse = Created<operations['postV1WorkspacesWorkspaceIdPortsPortLinks']>;
+/** POST …/ports/{port}/callback (201). */
+export type PortCallbackResponse = Created<operations['postV1WorkspacesWorkspaceIdPortsPortCallback']>;
+/** An exposed port of a workspace. */
+export interface ExposedPort {
+    /** TCP port inside the workspace (1-65535). */
+    port: number;
+    /** `https://<port>-<handle>.<ingress domain>`: requests need a port token, a link's browser session or the callback URL. */
+    url: string;
+    /** When the port was exposed (RFC 3339). Exposing it again after a close starts a new exposure. */
+    createdAt: string;
+    /** Set when the port has a callback URL (its secret is shown only by `createCallbackUrl()`). */
+    callback: {
+        createdAt: string;
+    } | null;
+}
+/** `expose()`: the port, and whether this call exposed it (201) or it already was (200, unchanged). */
+export interface ExposePortResult extends ExposedPort {
+    created: boolean;
+}
+/** A port token: send it as `Authorization: Bearer <token>` (or `X-Shardflux-Token`) to `url`. */
+export interface PortToken {
+    /** `sfp_…`. Revoked when the port is closed, the workspace is deleted or the API key that minted it is revoked. */
+    token: string;
+    /** RFC 3339. */
+    expiresAt: string;
+    /** The port's URL. */
+    url: string;
+}
+/** A signed link: opening it in a browser starts a session for the port (a cookie until `expiresAt`) and lands on its path. */
+export interface PortLink {
+    url: string;
+    /** RFC 3339: the link and the browser session it starts end then. */
+    expiresAt: string;
+}
+/**
+ * The port's callback URL: register `url` plus your own path with GitHub, Slack, Stripe or an OAuth provider. A request
+ * to `<url><rest>` reaches `/<rest>` (query kept) without a token header and wakes the workspace like any request.
+ */
+export interface PortCallbackUrl {
+    /** `https://<port>-<handle>.<domain>/__shardflux/callback/sfcb_…/`. Shown once: the API keeps only its hash. */
+    url: string;
+    /** RFC 3339. */
+    createdAt: string;
+}
+export interface PortTokenOptions {
+    /** Lifetime in seconds: 60-86400 (default 3600). */
+    ttlSeconds?: number;
+}
+export interface PortLinkOptions {
+    /** Lifetime of the link and of the browser session it starts, in seconds: 60-604800 (default 86400). */
+    ttlSeconds?: number;
+    /** Where the link lands: a path starting with one `/`, printable ASCII, query allowed (default `/`). */
+    path?: string;
+}
+export declare function exposedPortOf(view: PortView): ExposedPort;
+/**
+ * The exposed ports of one workspace (`workspace.ports`, `cloud.workspaces.ports(id)`). Errors are ShardfluxApiError:
+ * 403 `forbidden` reason `inbound_ports_not_available` (inbound ports are not enabled for the organization), 404
+ * `not_found` reason `port_not_exposed` (tokens, links and callback URLs of a port that is not exposed), 409 `conflict`
+ * reason `port_limit` (at most 10 exposed ports, `details.limit`) or `workspace_deleted`, NotSupportedForModeError for a
+ * file-first workspace, 422 `validation_failed` for a port outside 1-65535 or an option out of range.
+ */
+export declare class WorkspacePorts {
+    #private;
+    constructor(ctx: ClientContext, workspaceId: string);
+    /**
+     * Exposes TCP `port` at its own HTTPS URL (idempotent: a port already exposed is returned unchanged, `created`
+     * false, and its tokens, links and callback URL stay valid). The server inside the workspace must listen on
+     * 0.0.0.0 (all interfaces), not only on 127.0.0.1.
+     */
+    expose(port: number): Promise<ExposePortResult>;
+    /** The exposed ports, ordered by port. */
+    list(): Promise<ExposedPort[]>;
+    /**
+     * Closes the port (idempotent: also when it is not exposed). Its tokens, links and callback URL stop working at once,
+     * and stay revoked if the port is exposed again.
+     */
+    close(port: number): Promise<void>;
+    /** Mints a port token for an exposed port (`use` bearer): `Authorization: Bearer <token>` on requests to `url`. */
+    token(port: number, opts?: PortTokenOptions): Promise<PortToken>;
+    /** A signed link that opens the port in a browser. Share it like a password: anyone with it can open the port until it expires. */
+    link(port: number, opts?: PortLinkOptions): Promise<PortLink>;
+    /** Creates the port's callback URL, or replaces it (the previous one stops working). Its secret is shown only here. */
+    createCallbackUrl(port: number): Promise<PortCallbackUrl>;
+    /** Revokes the port's callback URL (idempotent while the port is exposed). */
+    revokeCallbackUrl(port: number): Promise<void>;
+}
+export {};

package/dist/ports.js

@@ -0,0 +1,62 @@
+export function exposedPortOf(view) {
+    return { port: view.port, url: view.url, createdAt: view.created_at, callback: view.callback ? { createdAt: view.callback.created_at } : null };
+}
+/**
+ * The exposed ports of one workspace (`workspace.ports`, `cloud.workspaces.ports(id)`). Errors are ShardfluxApiError:
+ * 403 `forbidden` reason `inbound_ports_not_available` (inbound ports are not enabled for the organization), 404
+ * `not_found` reason `port_not_exposed` (tokens, links and callback URLs of a port that is not exposed), 409 `conflict`
+ * reason `port_limit` (at most 10 exposed ports, `details.limit`) or `workspace_deleted`, NotSupportedForModeError for a
+ * file-first workspace, 422 `validation_failed` for a port outside 1-65535 or an option out of range.
+ */
+export class WorkspacePorts {
+    #ctx;
+    #workspaceId;
+    constructor(ctx, workspaceId) {
+        this.#ctx = ctx;
+        this.#workspaceId = workspaceId;
+    }
+    #path(port, rest = '') {
+        const base = `/v1/workspaces/${encodeURIComponent(this.#workspaceId)}/ports`;
+        return port === undefined ? base : `${base}/${encodeURIComponent(String(port))}${rest}`;
+    }
+    /**
+     * Exposes TCP `port` at its own HTTPS URL (idempotent: a port already exposed is returned unchanged, `created`
+     * false, and its tokens, links and callback URL stay valid). The server inside the workspace must listen on
+     * 0.0.0.0 (all interfaces), not only on 127.0.0.1.
+     */
+    async expose(port) {
+        const r = await this.#ctx.http.jsonWithStatus('PUT', this.#path(port), { idempotent: true }, this.#ctx.authorization);
+        return { ...exposedPortOf(r.body), created: r.status === 201 };
+    }
+    /** The exposed ports, ordered by port. */
+    async list() {
+        const body = await this.#ctx.http.json('GET', this.#path(), {}, this.#ctx.authorization);
+        return body.ports.map(exposedPortOf);
+    }
+    /**
+     * Closes the port (idempotent: also when it is not exposed). Its tokens, links and callback URL stop working at once,
+     * and stay revoked if the port is exposed again.
+     */
+    async close(port) {
+        await this.#ctx.http.json('DELETE', this.#path(port), { idempotent: true }, this.#ctx.authorization);
+    }
+    /** Mints a port token for an exposed port (`use` bearer): `Authorization: Bearer <token>` on requests to `url`. */
+    async token(port, opts = {}) {
+        const body = await this.#ctx.http.json('POST', this.#path(port, '/tokens'), { json: opts.ttlSeconds !== undefined ? { ttl_seconds: opts.ttlSeconds } : {} }, this.#ctx.authorization);
+        return { token: body.token, expiresAt: body.expires_at, url: body.url };
+    }
+    /** A signed link that opens the port in a browser. Share it like a password: anyone with it can open the port until it expires. */
+    async link(port, opts = {}) {
+        const body = await this.#ctx.http.json('POST', this.#path(port, '/links'), { json: { ...(opts.ttlSeconds !== undefined ? { ttl_seconds: opts.ttlSeconds } : {}), ...(opts.path !== undefined ? { path: opts.path } : {}) } }, this.#ctx.authorization);
+        return { url: body.url, expiresAt: body.expires_at };
+    }
+    /** Creates the port's callback URL, or replaces it (the previous one stops working). Its secret is shown only here. */
+    async createCallbackUrl(port) {
+        const body = await this.#ctx.http.json('POST', this.#path(port, '/callback'), {}, this.#ctx.authorization);
+        return { url: body.url, createdAt: body.created_at };
+    }
+    /** Revokes the port's callback URL (idempotent while the port is exposed). */
+    async revokeCallbackUrl(port) {
+        await this.#ctx.http.json('DELETE', this.#path(port, '/callback'), { idempotent: true }, this.#ctx.authorization);
+    }
+}

package/dist/progress.d.ts

@@ -18,7 +18,7 @@
 import type { components } from './generated/app-api.js';
 type Operation = components['schemas']['Operation'];
 /** The SDK call a trace follows. `wait` is a direct waitForOperation(); `token` a tool token fetched for tool calls. */
-export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork' | 'delete' | 'close' | 'reset' | 'wake' | 'wait' | 'token';
+export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork' | 'delete' | 'close' | 'reset' | 'resize' | 'wake' | 'wait' | 'token';
 /**
  * - `request`: an API request that starts or joins the operation. A held open (`Prefer: wait`) spends the server's
  *   hold here (reason `held`), so the states inside it show only in the server timing.
@@ -74,9 +74,10 @@ export interface ServerTiming {
     warmFallback: string | null;
     /**
      * `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).
+     * `download` (the checkpoint had to be fetched first), `cold_boot` (0.11.0+: the saved disk was booted instead of
+     * restoring memory, see `coldBootReason`; processes restarted; see `memoryRestored`), `reset_blank_layer` (the first
+     * start after a reset) or `thaw` (0.13.1+: resumed while its suspend was still being written; the same VM continued
+     * in place).
      */
     resumePath: string | null;
     /**
@@ -87,10 +88,12 @@ export interface ServerTiming {
      */
     memoryRestored?: boolean | null;
     /**
-     * `result.cold_boot_reason` (0.11.0+), with `resumePath` `cold_boot`: why the memory could not be restored, e.g.
-     * `runtime_changed` (the platform's VM runtime changed after the suspend). Null otherwise.
+     * `result.cold_boot_reason` (0.11.0+), with `resumePath` `cold_boot`: why the memory could not be restored:
+     * `runtime_changed` (the platform's VM runtime changed after the suspend), `host_lost` (0.13.1+: the machine the
+     * workspace ran on failed; it booted from its disk, files kept, see `hostLost`) or `runtime_retired` (0.14.0+: the
+     * runtime the workspace was suspended on was retired after an announced window). Null otherwise.
      */
-    coldBootReason?: string | null;
+    coldBootReason?: ColdBootReason | 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).
@@ -105,6 +108,12 @@ export interface ServerTiming {
      * checkpoint before it (`restoredCheckpointId`, state as of `stateAsOf`). Null otherwise.
      */
     lostSuspend?: LostSuspend | null;
+    /**
+     * `result.host_lost` (0.13.1+): the machine the workspace ran on failed. A resume (or open) that restored the
+     * workspace says from what (`restoredFrom` `disk`, or `checkpoint` with `stateAsOf`); a suspend that found it so
+     * succeeds with only `detectedAt`. Null otherwise.
+     */
+    hostLost?: HostLost | 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, …). */
@@ -143,6 +152,33 @@ export interface LostSuspend {
     /** The restored state is as of this time (RFC 3339). */
     stateAsOf: string | null;
 }
+/**
+ * `result.cold_boot_reason` (0.11.0+): `runtime_changed` (the platform's VM runtime changed after the suspend),
+ * `host_lost` (0.13.1+: the machine the workspace ran on failed) or `runtime_retired` (0.14.0+: the runtime the
+ * workspace was suspended on was retired after an announced window). Any other string is a reason this version does
+ * not know.
+ */
+export type ColdBootReason = (typeof COLD_BOOT_REASONS)[number] | (string & {});
+/** Every {@link ColdBootReason} this version knows (0.14.0+). */
+export declare const COLD_BOOT_REASONS: readonly ["runtime_changed", "host_lost", "runtime_retired"];
+/**
+ * `result.host_lost` (0.13.1+), camelCased: the machine the workspace ran on failed. The workspace was moved to
+ * `suspended` at that moment, and its next use (a resume, a tool call's wake, an open) restored it. See the lifecycle
+ * reference.
+ */
+export interface HostLost {
+    /** When the failure was detected (RFC 3339). */
+    detectedAt: string | null;
+    /**
+     * What the resume restored: `disk` (the workspace's own disk, files kept; `coldBootReason` `host_lost`, processes
+     * restarted) or `checkpoint` (its newest checkpoint, see `stateAsOf`). Null on a suspend's result.
+     */
+    restoredFrom: 'disk' | 'checkpoint' | null;
+    /** `checkpoint`: the checkpoint the resume restored. */
+    restoredCheckpointId: string | null;
+    /** `checkpoint`: the restored state is as of this time (RFC 3339); changes after it are not in the workspace. */
+    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).
@@ -150,6 +186,11 @@ export interface LostSuspend {
 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;
+/**
+ * An operation's `result.host_lost` camelCased (0.13.1+), or null: on a resume or open that restored a workspace whose
+ * machine failed, and on a suspend that found it so (`detectedAt` only).
+ */
+export declare function hostLostOf(op: Pick<Operation, 'result'>): HostLost | 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.
@@ -255,7 +296,10 @@ export declare function traced<T>(trace: Trace, fn: () => Promise<T>): Promise<T
  *
  * 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)`.
+ * `resume from cold_boot: processes restarted (runtime_changed)`, or `(host_lost)` (0.13.1+) when the machine the
+ * workspace ran on failed and it booted from its disk. A resume that restored the newest checkpoint after such a
+ * failure adds `restored checkpoint <id> (host_lost; state as of <time>)`; a suspend that found the machine failed
+ * adds `host_lost (detected <time>)`.
  */
 export declare function formatTiming(t: LifecycleTiming): string;
 export {};