@shardflux/sdk 0.11.1 → 0.13.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'];
@@ -11,7 +11,7 @@ export type ErrorCode = AppErrorCode | CellErrorCode;
  * 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;
+ * reserved_key_prefix, invalid_defaults, 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 (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,
@@ -51,8 +51,27 @@ export type ErrorCode = AppErrorCode | CellErrorCode;
  * overage_unavailable, spend_cap_required, spend_cap_below_minimum (details.min_minor), spend_cap_above_plan_price
  * (details.max_minor) and spend_cap_below_charges (details.charges_minor); with `ifMatch`, 409 conflict
  * version_mismatch (details.current_version), as egress puts with `ifMatch` answer too.
+ * Elastic memory (0.13.0): 422 validation_failed allocation_mode_not_available (details.field
+ * `caps.allocation_mode`; the organization does not have elastic memory, nothing is created or changed),
+ * not_supported_for_mode (elastic with file_first), requires_elastic and exceeds_memory_mib (details.field
+ * `caps.memory_mib_held`).
+ * Burst execution (0.13.0): the codes `burst_unavailable` (409; details.reason
+ * not_available, layout_unsupported, shared_volumes, host_capacity, fence_not_drained, workspace_fenced, apply_pending,
+ * park_failed, workspace_resumed, interrupted; details.replayed on a journaled failure answered again) and
+ * `burst_apply_failed` (409; details.reason disk_full, apply_failed, reverted, revert_failed with
+ * details.applied_entries and details.pending_entries: retry with the same session id to finish an apply_failed one);
+ * 422 validation_failed burst_mode_not_supported (`auto`), burst_not_supported (with stdin; also 409 conflict for
+ * signal/cancel of a burst session) and burst_size_exceeds_plan (details.field, details.limit); a burst session nobody
+ * followed any more ends with burst.error service_unavailable burst_lost.
+ * Immutable paths (0.13.0): 422 validation_failed immutable_path_removed (a recipe drops a path of the template's open
+ * version: details.removed, details.open_version; a version keeps every immutable path), immutable_paths_unsupported_base
+ * (the base's guest agent lacks the feature, or a Dockerfile build of a template with immutable paths: details.base
+ * {name, version}, details.required_feature, details.paths) and invalid_path at details.field `recipe.immutable[<i>]`;
+ * 409 conflict read_only_path (a files write under an immutable path, from the cell gateway). The reason
+ * `update_policy_not_available` is gone with the update policy. A build that fails on them carries `failure.code`
+ * immutable_path_missing (details.path) or immutable_image_too_large.
  */
-export type KnownErrorReason = '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' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | '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' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'update_policy_not_available' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found' | 'revision_mismatch' | 'edit_not_found' | 'edit_ambiguous' | 'edit_not_text' | 'patch_invalid' | 'host_capacity' | 'wake_failed' | 'workspace_fenced' | 'offline_unavailable' | 'offline_budget' | 'offline_changed' | 'host_feature_unavailable' | 'not_supported_for_mode' | 'mode_mismatch' | 'mode_not_available' | 'layout_unsupported' | 'tree_revision_mismatch' | 'outside_tree_root' | 'execution_in_progress' | 'execution_id_reused' | 'operation_id_reused' | 'no_execution_host' | 'lease_expired' | 'host_unreachable' | 'host_restarted' | 'tree_moved' | 'blob_missing' | 'blob_corrupt' | 'exec_failed_to_start' | 'invalid_cwd' | 'allowance_used' | 'overage_paused' | 'spend_cap_reached' | 'overage_unavailable' | 'spend_cap_required' | 'spend_cap_below_minimum' | 'spend_cap_above_plan_price' | 'spend_cap_below_charges' | 'version_mismatch';
+export type KnownErrorReason = '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' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | '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' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found' | 'revision_mismatch' | 'edit_not_found' | 'edit_ambiguous' | 'edit_not_text' | 'patch_invalid' | 'host_capacity' | 'wake_failed' | 'workspace_fenced' | 'offline_unavailable' | 'offline_budget' | 'offline_changed' | 'host_feature_unavailable' | 'not_supported_for_mode' | 'mode_mismatch' | 'mode_not_available' | 'layout_unsupported' | 'tree_revision_mismatch' | 'outside_tree_root' | 'execution_in_progress' | 'execution_id_reused' | 'operation_id_reused' | 'no_execution_host' | 'lease_expired' | 'host_unreachable' | 'host_restarted' | 'tree_moved' | 'blob_missing' | 'blob_corrupt' | 'exec_failed_to_start' | 'invalid_cwd' | 'allowance_used' | 'overage_paused' | 'spend_cap_reached' | 'overage_unavailable' | 'spend_cap_required' | 'spend_cap_below_minimum' | 'spend_cap_above_plan_price' | 'spend_cap_below_charges' | 'version_mismatch' | 'allocation_mode_not_available' | 'requires_elastic' | 'exceeds_memory_mib' | 'burst_mode_not_supported' | 'burst_not_supported' | 'burst_size_exceeds_plan' | 'not_available' | 'shared_volumes' | 'fence_not_drained' | 'apply_pending' | 'park_failed' | 'workspace_resumed' | 'interrupted' | 'burst_lost' | 'disk_full' | 'apply_failed' | 'reverted' | 'revert_failed' | 'immutable_path_removed' | 'immutable_paths_unsupported_base' | 'read_only_path';
 /** A known reason, or any other string the server sends (reasons are open-ended). */
 export type ErrorReason = KnownErrorReason | (string & {});
 export interface ErrorBodyLike {
@@ -141,8 +160,12 @@ 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:
@@ -163,13 +186,24 @@ export declare class OperationTimeoutError extends Error {
     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: the start passed its deadline and nothing was started; send it again. The SDK never retries a failed
@@ -180,4 +214,18 @@ export declare class OperationFailedError extends Error {
     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,4 +1,4 @@
-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;
@@ -129,12 +129,20 @@ 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
@@ -154,10 +162,18 @@ export class OperationTimeoutError extends Error {
     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 stays queued server side until ${deadlineAt} and fails with capacity_unavailable if it has not started 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}`);
+        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,11 +183,17 @@ 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: the start passed its deadline and nothing was started; send it again. The SDK never retries a 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/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 };
 }