@shardflux/sdk 0.11.0 → 0.12.0

package/dist/errors.d.ts

@@ -1,6 +1,6 @@
 import type { components as AppComponents } from './generated/app-api.js';
 import type { components as CellComponents } from './generated/cell-api.js';
-import type { LifecycleTiming } from './progress.js';
+import type { Durability, LifecycleTiming } from './progress.js';
 export type AppErrorBody = AppComponents['schemas']['ErrorBody'];
 export type AppErrorCode = AppErrorBody['error']['code'];
 export type CellErrorCode = CellComponents['schemas']['ErrorCode'];
@@ -8,28 +8,28 @@ export type CellErrorCode = CellComponents['schemas']['ErrorCode'];
 export type ErrorCode = AppErrorCode | CellErrorCode;
 /**
  * `details.reason` values the SDK knows (the error code enum is closed; new cases add reasons). Templates v2
- * (contracts §19.14) added: 409 conflict legacy_disk_layout, not_session, session_lifetime, lifetime_mismatch,
+ * added: 409 conflict legacy_disk_layout, not_session, session_lifetime, lifetime_mismatch,
  * not_resettable, template_not_layered, draft_exists, draft_stale, build_in_progress, file_list_unavailable,
  * file_list_indexing (retryable), guest_feature_unavailable; 422 validation_failed confirm_destructive_required,
  * reserved_key_prefix, invalid_defaults, update_policy_not_available, invalid_path, too_many_acknowledged_findings;
  * 403 forbidden template_dev_mode_role; 404 not_found draft_not_found, version_not_found, path_not_found.
- * The template editor (contracts §24.6, 0.7.0) added: 422 validation_failed invalid_recipe, base_not_layered,
+ * The template editor (0.7.0) added: 422 validation_failed invalid_recipe, base_not_layered,
  * language_unavailable, language_conflict, invalid_package, too_many_files, platform_owned_path, upload_required,
  * upload_missing, upload_digest_mismatch, upload_too_large, extra_hosts_without_auto, invalid_settings,
  * services_unsupported, input_required, input_unknown, input_invalid, egress_widening, reserved_session_id,
  * env_collision, reserved_template_slug; 409 conflict package_index_unavailable; 404 package_not_found; the operation
  * error `startup_failed` (details.reason startup_failed, service_not_ready, secrets_unavailable, secret_not_available,
- * guest_feature_unavailable). File tools and parking (contracts §25-§28, 0.9.0) added: 409 conflict revision_mismatch
+ * guest_feature_unavailable). File tools and parking (0.9.0) added: 409 conflict revision_mismatch
  * (details.current_revision); 422 validation_failed edit_not_found, edit_ambiguous (details.index), edit_not_text,
  * patch_invalid; 503 service_unavailable host_capacity and wake_failed (both retryable, with Retry-After); 409
  * workspace_busy workspace_fenced (a lifecycle operation holds the workspace; waited out like any workspace_busy).
  * Reads of a sleeping workspace (§26.4/§26.5): 409 workspace_not_running offline_unavailable and offline_budget
  * (retryable; the disk could not be read offline: the workspace is woken and the call retried like any
  * workspace_not_running), 503 offline_changed (retryable; the retry is served by the guest).
- * Hosts without the features (contracts §26.7, 0.9.0): 409 conflict host_feature_unavailable (not retryable;
- * details.feature `file_search` or `file_patch`): the workspace runs on a host agent that predates the call, until it
- * runs on an upgraded host (minutes to hours); read and write the file, or run a search command, instead.
- * File-first workspaces (contracts §29.7, §29.8; 0.9.0) added: 409 conflict not_supported_for_mode (details.mode,
+ * Calls not available for a workspace (0.9.0): 409 conflict host_feature_unavailable (not retryable; details.feature
+ * `file_search` or `file_patch`): the call is not available for this workspace; use the fallback in the hint (read and
+ * write the file, or run a search command).
+ * File-first workspaces (0.9.0) added: 409 conflict not_supported_for_mode (details.mode,
  * details.operation; NotSupportedForModeError), mode_mismatch (reopening a key with another mode), layout_unsupported (a
  * legacy template), tree_revision_mismatch (details.current_tree_revision; TreeRevisionMismatchError),
  * execution_id_reused, operation_id_reused (an Idempotency-Key reused for another request); 422 validation_failed
@@ -66,7 +66,7 @@ export interface ErrorBodyLike {
     };
 }
 export declare function isErrorBody(v: unknown): v is ErrorBodyLike;
-/** A structured error from the application API or a cell gateway (contracts §3). */
+/** A structured error from the application API or a cell gateway. */
 export declare class ShardfluxApiError extends Error {
     readonly status: number;
     readonly code: ErrorCode;
@@ -81,16 +81,16 @@ export declare class ShardfluxApiError extends Error {
     /** Where the time went when a traced call (open, a waited lifecycle call, a wake) failed with this error. */
     timing: LifecycleTiming | undefined;
     /**
-     * `X-Tree-Revision` of the refusal (file-first workspaces, contracts §29.8): the tree revision the refused call saw.
+     * `X-Tree-Revision` of the refusal (file-first workspaces): the tree revision the refused call saw.
      * Undefined when the response carried none (processful workspaces, the application API).
      */
     readonly treeRevision: number | undefined;
     constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number, treeRevision?: number);
 }
-/** processful (the default: one VM keeps processes, memory and files) or file_first (contracts §29). */
+/** processful (the default: one VM keeps processes, memory and files) or file_first. */
 export type WorkspaceMode = AppComponents['schemas']['WorkspaceMode'];
 /**
- * The call does not exist for the workspace's mode (contracts §29.7, §29.8): 409 `conflict` with details.reason
+ * The call does not exist for the workspace's mode: 409 `conflict` with details.reason
  * `not_supported_for_mode`, `details.mode` (the workspace's mode) and `details.operation`. File-first workspaces have no
  * VM between executions, so exec sessions, PTY, processes, version control, browser, changes, suspend, resume,
  * snapshot, fork, reset, save-as-template, volumes and idle policies are refused; processful workspaces have no
@@ -109,7 +109,7 @@ export declare class NotSupportedForModeError extends ShardfluxApiError {
     static local(mode: WorkspaceMode, operation: string, source: 'api' | 'cell', message: string): NotSupportedForModeError;
 }
 /**
- * A file-first call with `ifTreeRevision` (`If-Match`) found the tree at another revision (contracts §29.8): 409
+ * A file-first call with `ifTreeRevision` (`If-Match`) found the tree at another revision: 409
  * `conflict`, details.reason `tree_revision_mismatch`. Nothing changed. `currentTreeRevision` is the revision the tree
  * is at: read what changed, then retry against it.
  */
@@ -141,14 +141,18 @@ export declare function apiError(status: number, body: ErrorBodyLike, source: 'a
 /** The response was not the documented shape (e.g. a proxy error page). */
 export declare class ShardfluxProtocolError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    /** The responding surface; unknown only for errors constructed by older callers. Never proof of deletion. */
+    readonly source: 'api' | 'cell' | 'unknown';
+    constructor(message: string, status: number, source?: 'api' | 'cell' | 'unknown');
 }
+/** True only for an explicit API tombstone refusal. A 404, even a structured one, may be routing or scope. */
+export declare function isWorkspaceGone(error: unknown): boolean;
 type Operation = AppComponents['schemas']['Operation'];
 /**
  * Waiting for an operation ran out of time. The operation keeps running server side:
  * resume with `cloud.workspaces.waitForOperation(err.operationId)` or call open() again
- * (it returns the same operation while it is active). A start still waiting for capacity
- * (`capacity_pending`) gives up at `deadlineAt` and then fails with `capacity_unavailable`.
+ * (it returns the same operation while it is active). A queued start (`capacity_pending`) that
+ * passes its deadline (`deadlineAt`) fails with `capacity_unavailable`; nothing was started.
  */
 export declare class OperationTimeoutError extends Error {
     readonly operationId: string;
@@ -156,28 +160,53 @@ export declare class OperationTimeoutError extends Error {
     readonly lastState: Operation['state'];
     readonly lastReason: string | null;
     /**
-     * When the operation was last `capacity_pending`: when it gives up waiting for a host (`error.details.deadline_at`,
-     * RFC 3339) and fails with `capacity_unavailable`. Null in other states or from an API that does not report it.
+     * When the operation was last `capacity_pending`: its deadline (`error.details.deadline_at`, RFC 3339), past which it
+     * fails with `capacity_unavailable`. Null in other states or from an API that does not report it.
      */
     readonly deadlineAt: string | null;
     readonly waitedMs: number;
     /** Where the time went: client phases, retries and the operation's own server timing so far. */
     timing: LifecycleTiming | undefined;
-    constructor(op: Operation, waitedMs: number);
+    /**
+     * `durable` (0.12.0+): the wait was for the durable copy of a succeeded suspend or fork (`suspend({ durable: true })`,
+     * `waitForDurable()`); `lastState` is then `succeeded` and the copy continues server side.
+     */
+    readonly durable: boolean;
+    constructor(op: Operation, waitedMs: number, durable?: boolean);
 }
-/** The operation reached `failed` or `canceled`. */
+/**
+ * The operation reached `failed` or `canceled`. A suspend-when-idle that found the workspace active (a tool call after
+ * the request, an attached stream) is `canceled` with `errorCode` `workspace_active` (`workspaceActive` true, 0.12.0+):
+ * nothing changed and the workspace keeps running. `waitUntilReady()` and `wake()` treat it as running, not as a failure.
+ */
 export declare class OperationFailedError extends Error {
     readonly operation: Operation;
     readonly operationId: string;
     readonly errorCode: string | null;
+    /** 0.12.0+: a suspend-when-idle canceled because the workspace was active; it keeps running, nothing changed. */
+    readonly workspaceActive: boolean;
     /**
      * `operation.error.retryable` (false when absent): the same request may succeed later. `capacity_unavailable` is
-     * retryable: no host could admit the start before its deadline, nothing was started, retry later. The SDK never
-     * retries a failed operation itself.
+     * retryable: the start passed its deadline and nothing was started; send it again. The SDK never retries a failed
+     * operation itself.
      */
     readonly retryable: boolean;
     /** Where the time went before the operation failed. */
     timing: LifecycleTiming | undefined;
     constructor(op: Operation);
 }
+/**
+ * `suspend({ durable: true })` or `waitForDurable()` (0.12.0+): the suspend (or fork) succeeded, but its durable copy
+ * could not be made (`durability.state` `lost`). `durability` has the reason; see the lifecycle reference for what the
+ * next resume restores.
+ */
+export declare class DurabilityLostError extends Error {
+    readonly operation: Operation;
+    readonly operationId: string;
+    readonly workspaceId: string | null;
+    readonly durability: Durability;
+    /** Where the time went. */
+    timing: LifecycleTiming | undefined;
+    constructor(op: Operation);
+}
 export {};

package/dist/errors.js

@@ -1,11 +1,11 @@
-import { capacityDeadlineOf } from "./progress.js";
+import { capacityDeadlineOf, durabilityOf } from "./progress.js";
 export function isErrorBody(v) {
     if (typeof v !== 'object' || v === null || !('error' in v))
         return false;
     const e = v.error;
     return typeof e === 'object' && e !== null && typeof e.code === 'string' && typeof e.message === 'string';
 }
-/** A structured error from the application API or a cell gateway (contracts §3). */
+/** A structured error from the application API or a cell gateway. */
 export class ShardfluxApiError extends Error {
     status;
     code;
@@ -20,7 +20,7 @@ export class ShardfluxApiError extends Error {
     /** Where the time went when a traced call (open, a waited lifecycle call, a wake) failed with this error. */
     timing = undefined;
     /**
-     * `X-Tree-Revision` of the refusal (file-first workspaces, contracts §29.8): the tree revision the refused call saw.
+     * `X-Tree-Revision` of the refusal (file-first workspaces): the tree revision the refused call saw.
      * Undefined when the response carried none (processful workspaces, the application API).
      */
     treeRevision;
@@ -41,7 +41,7 @@ export class ShardfluxApiError extends Error {
     }
 }
 /**
- * The call does not exist for the workspace's mode (contracts §29.7, §29.8): 409 `conflict` with details.reason
+ * The call does not exist for the workspace's mode: 409 `conflict` with details.reason
  * `not_supported_for_mode`, `details.mode` (the workspace's mode) and `details.operation`. File-first workspaces have no
  * VM between executions, so exec sessions, PTY, processes, version control, browser, changes, suspend, resume,
  * snapshot, fork, reset, save-as-template, volumes and idle policies are refused; processful workspaces have no
@@ -70,7 +70,7 @@ export class NotSupportedForModeError extends ShardfluxApiError {
     }
 }
 /**
- * A file-first call with `ifTreeRevision` (`If-Match`) found the tree at another revision (contracts §29.8): 409
+ * A file-first call with `ifTreeRevision` (`If-Match`) found the tree at another revision: 409
  * `conflict`, details.reason `tree_revision_mismatch`. Nothing changed. `currentTreeRevision` is the revision the tree
  * is at: read what changed, then retry against it.
  */
@@ -129,17 +129,25 @@ export function apiError(status, body, source, retryAfterSeconds, treeRevision)
 /** The response was not the documented shape (e.g. a proxy error page). */
 export class ShardfluxProtocolError extends Error {
     status;
-    constructor(message, status) {
+    /** The responding surface; unknown only for errors constructed by older callers. Never proof of deletion. */
+    source;
+    constructor(message, status, source = 'unknown') {
         super(message);
         this.name = 'ShardfluxProtocolError';
         this.status = status;
+        this.source = source;
     }
 }
+/** True only for an explicit API tombstone refusal. A 404, even a structured one, may be routing or scope. */
+export function isWorkspaceGone(error) {
+    return error instanceof ShardfluxApiError && error.source === 'api' &&
+        error.code === 'conflict' && error.reason === 'workspace_deleted';
+}
 /**
  * Waiting for an operation ran out of time. The operation keeps running server side:
  * resume with `cloud.workspaces.waitForOperation(err.operationId)` or call open() again
- * (it returns the same operation while it is active). A start still waiting for capacity
- * (`capacity_pending`) gives up at `deadlineAt` and then fails with `capacity_unavailable`.
+ * (it returns the same operation while it is active). A queued start (`capacity_pending`) that
+ * passes its deadline (`deadlineAt`) fails with `capacity_unavailable`; nothing was started.
  */
 export class OperationTimeoutError extends Error {
     operationId;
@@ -147,17 +155,25 @@ export class OperationTimeoutError extends Error {
     lastState;
     lastReason;
     /**
-     * When the operation was last `capacity_pending`: when it gives up waiting for a host (`error.details.deadline_at`,
-     * RFC 3339) and fails with `capacity_unavailable`. Null in other states or from an API that does not report it.
+     * When the operation was last `capacity_pending`: its deadline (`error.details.deadline_at`, RFC 3339), past which it
+     * fails with `capacity_unavailable`. Null in other states or from an API that does not report it.
      */
     deadlineAt;
     waitedMs;
     /** Where the time went: client phases, retries and the operation's own server timing so far. */
     timing = undefined;
-    constructor(op, waitedMs) {
+    /**
+     * `durable` (0.12.0+): the wait was for the durable copy of a succeeded suspend or fork (`suspend({ durable: true })`,
+     * `waitForDurable()`); `lastState` is then `succeeded` and the copy continues server side.
+     */
+    durable;
+    constructor(op, waitedMs, durable = false) {
         const deadlineAt = capacityDeadlineOf(op);
-        const after = deadlineAt ? `it keeps waiting for a host server side until ${deadlineAt} and fails with capacity_unavailable if none admits it by then.` : 'it continues server side.';
-        super(`Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; ${after}`);
+        const after = deadlineAt ? `it stays queued server side until ${deadlineAt} and fails with capacity_unavailable if it has not started by then.` : 'it continues server side.';
+        super(durable
+            ? `Operation ${op.id} (${op.kind}) succeeded; its durable copy was still ${durabilityOf(op)?.state ?? 'pending'} after ${Math.round(waitedMs)} ms and continues server side.`
+            : `Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; ${after}`);
+        this.durable = durable;
         this.name = 'OperationTimeoutError';
         this.operationId = op.id;
         this.workspaceId = op.workspace_id;
@@ -167,15 +183,21 @@ export class OperationTimeoutError extends Error {
         this.waitedMs = waitedMs;
     }
 }
-/** The operation reached `failed` or `canceled`. */
+/**
+ * The operation reached `failed` or `canceled`. A suspend-when-idle that found the workspace active (a tool call after
+ * the request, an attached stream) is `canceled` with `errorCode` `workspace_active` (`workspaceActive` true, 0.12.0+):
+ * nothing changed and the workspace keeps running. `waitUntilReady()` and `wake()` treat it as running, not as a failure.
+ */
 export class OperationFailedError extends Error {
     operation;
     operationId;
     errorCode;
+    /** 0.12.0+: a suspend-when-idle canceled because the workspace was active; it keeps running, nothing changed. */
+    workspaceActive;
     /**
      * `operation.error.retryable` (false when absent): the same request may succeed later. `capacity_unavailable` is
-     * retryable: no host could admit the start before its deadline, nothing was started, retry later. The SDK never
-     * retries a failed operation itself.
+     * retryable: the start passed its deadline and nothing was started; send it again. The SDK never retries a failed
+     * operation itself.
      */
     retryable;
     /** Where the time went before the operation failed. */
@@ -187,6 +209,29 @@ export class OperationFailedError extends Error {
         this.operation = op;
         this.operationId = op.id;
         this.errorCode = code;
+        this.workspaceActive = code === 'workspace_active' && op.kind === 'suspend';
         this.retryable = op.error?.retryable === true;
     }
 }
+/**
+ * `suspend({ durable: true })` or `waitForDurable()` (0.12.0+): the suspend (or fork) succeeded, but its durable copy
+ * could not be made (`durability.state` `lost`). `durability` has the reason; see the lifecycle reference for what the
+ * next resume restores.
+ */
+export class DurabilityLostError extends Error {
+    operation;
+    operationId;
+    workspaceId;
+    durability;
+    /** Where the time went. */
+    timing = undefined;
+    constructor(op) {
+        const durability = durabilityOf(op) ?? { state: 'lost', checkpointId: null, generationId: null, localCommitAt: null, durableBy: null, durableAt: null, localCommitToDurableMs: null, overdueAt: null, reason: null };
+        super(`Operation ${op.id} (${op.kind}): the durable copy of checkpoint ${durability.checkpointId ?? '?'} was not made${durability.reason ? ` (${durability.reason})` : ''}`);
+        this.name = 'DurabilityLostError';
+        this.operation = op;
+        this.operationId = op.id;
+        this.workspaceId = op.workspace_id;
+        this.durability = durability;
+    }
+}

package/dist/executions.d.ts

@@ -1,5 +1,5 @@
 /**
- * Executions of file-first workspaces (contracts §29.1, §29.8): each `POST /exec` runs one command in a fresh VM on the
+ * Executions of file-first workspaces: each `POST /exec` runs one command in a fresh VM on the
  * workspace's latest tree revision and answers when it ended; the files it changed under /home/user become the next
  * revision. The execution id is the idempotency key: a request retried with the same id returns the recorded result
  * (or waits for the running execution) and never runs the command a second time.
@@ -46,7 +46,7 @@ export interface ExecutionRunOptions {
     outputLimitBytes?: number;
     /**
      * Retries, with the same execution id, of network failures and retryable 429/5xx answers (e.g. 503
-     * `no_execution_host`: no host has room; `Retry-After` is honoured up to 30 s). Default 5. Refusals such as
+     * `no_execution_host`: the execution cannot be placed right now; `Retry-After` is honoured up to 30 s). Default 5. Refusals such as
      * `execution_id_reused` or a validation error are not retried; `workspace_busy` (another execution holds the
      * workspace) is waited out within the client's `transitionTimeoutMs` like any tool call.
      */

package/dist/feedback.d.ts

@@ -1,8 +1,8 @@
 /**
  * Product feedback (POST /v1/feedback, 0.9.0+): a short message from the customer or their coding agent that goes
- * straight to the Shardflux founder by email.
+ * straight to the Shardflux team by email.
  *
- *   await cloud.sendFeedback({ message: 'open took 40 s on python-node-browser', category: 'bug', context: { requestId: err.requestId } });
+ *   await cloud.sendFeedback({ message: 'open rejected template "python-node" with template_not_found; expected a suggestion of the closest slug', category: 'bug', context: { requestId: err.requestId } });
  *
  * Any valid API key may send (no tool permission needed). The server bounds it per key (429 `rate_limited`,
  * `retryAfterSeconds` on the error; the SDK never retries it) and folds a repeat of the same message within 24 hours
@@ -23,7 +23,7 @@ export type FeedbackCategory = 'bug' | 'confusing' | 'missing' | 'idea' | 'prais
 export declare const FEEDBACK_CATEGORIES: readonly FeedbackCategory[];
 /** Longest message the API accepts, in characters after trimming (it must also contain a non-whitespace character). */
 export declare const FEEDBACK_MESSAGE_MAX_LENGTH = 8000;
-/** What the feedback is about, so the founder can find the logs. Every field is optional text. */
+/** What the feedback is about, so the team can find the logs. Every field is optional text. */
 export interface FeedbackContext {
     /** Who is reporting: e.g. `claude-code`, `codex`, `cursor`, or a person (<= 100 characters). */
     agent?: string;

package/dist/feedback.js

@@ -33,7 +33,7 @@ function feedbackBody(params) {
 export async function sendFeedback(ctx, params) {
     const { status, body } = await ctx.http.jsonWithStatus('POST', '/v1/feedback', { json: feedbackBody(params) }, ctx.authorization);
     if (typeof body?.id !== 'string' || typeof body.received_at !== 'string' || typeof body.duplicate !== 'boolean') {
-        throw new ShardfluxProtocolError('POST /v1/feedback: the response is not {id, received_at, duplicate}', status);
+        throw new ShardfluxProtocolError('POST /v1/feedback: the response is not {id, received_at, duplicate}', status, 'api');
     }
     return { id: body.id, receivedAt: body.received_at, duplicate: body.duplicate };
 }