@shardflux/sdk 0.10.2 → 0.11.1

package/dist/errors.d.ts

@@ -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.
  */
@@ -147,8 +147,8 @@ 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,8 +156,8 @@ 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;
@@ -172,8 +172,8 @@ export declare class OperationFailedError extends Error {
     readonly errorCode: string | null;
     /**
      * `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. */

package/dist/errors.js

@@ -5,7 +5,7 @@ export function isErrorBody(v) {
     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.
  */
@@ -138,8 +138,8 @@ export class ShardfluxProtocolError extends Error {
 /**
  * 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,8 +147,8 @@ 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;
@@ -156,7 +156,7 @@ export class OperationTimeoutError extends Error {
     timing = undefined;
     constructor(op, waitedMs) {
         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.';
+        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}`);
         this.name = 'OperationTimeoutError';
         this.operationId = op.id;
@@ -174,8 +174,8 @@ export class OperationFailedError extends Error {
     errorCode;
     /**
      * `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. */

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;