@shardflux/sdk 0.8.0 → 0.9.0

package/dist/client.d.ts

@@ -9,8 +9,10 @@
  */
 import type { components, operations } from './generated/app-api.js';
 import { ShardfluxApiError } from './errors.js';
+import type { WorkspaceMode } from './errors.js';
 import { HttpClient } from './http.js';
-import type { ToolName } from './tokens.js';
+import type { RequestOptions } from './http.js';
+import type { ToolName, ToolToken } from './tokens.js';
 import { Workspace } from './workspace.js';
 import { AuditApi } from './audit.js';
 import { EgressPolicyApi } from './egress.js';
@@ -19,9 +21,11 @@ import { TemplatesApi } from './templates.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.js';
 import { UsageApi } from './usage.js';
 import { VolumesApi } from './volumes.js';
-import type { FinishedOperation, InternalLifecycleOptions, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
+import type { VersionCheckOption } from './version-check.js';
+import type { FinishedOperation, InternalLifecycleOptions, LifecycleOptions, ResumeOptions, WaitedLifecycleOptions, WaitedResumeOptions } from './lifecycle.js';
 import type { ProgressListener } from './progress.js';
 import { CaptureRegistry } from './capture.js';
+import type { FeedbackReceipt, SendFeedbackParams } from './feedback.js';
 export type WorkspaceView = components['schemas']['Workspace'];
 export type Operation = components['schemas']['Operation'];
 /** persistent (kept until deleted) or session (discarded when the session ends: close(), idle timeout; contracts §19.11). */
@@ -52,6 +56,32 @@ type Ok<Op> = Op extends {
     [K in keyof R]: K extends 200 | 201 | 202 ? JsonOf<R[K]> : never;
 }[keyof R] : never;
 export type OpenResponse = Ok<operations['postV1WorkspacesOpen']>;
+/** POST /v1/workspaces/{id}/resume: the held 200 (contracts §22.6) or the lifecycle 202. */
+export type ResumeResponse = Ok<operations['postV1WorkspacesWorkspaceIdResume']>;
+/** What a resume request answered (0.9.0; `WorkspacesApi.requestResume`). */
+export interface ResumeAnswer {
+    /**
+     * True for a held resume that ended with the workspace running (200 with `Preference-Applied`): `workspace` and
+     * `toolToken` are current. False for any other answer: wait for `operation` (an older server answers 202 at once).
+     */
+    ready: boolean;
+    /** The resume, or the open/resume it joined; null when a held resume found the workspace already running. */
+    operation: Operation | null;
+    workspace: WorkspaceView;
+    /** The tool token of a ready answer (null when the API could not issue one: the first tool call fetches it). */
+    toolToken: ToolToken | null;
+    requestId: string | null;
+}
+export interface ResumeRequestOptions {
+    /** Seconds the server may hold the request (`Prefer: wait`, at most 20); below 1 the request is not held. */
+    waitS: number;
+    /** The tool token a held resume returns: agent label and tools (default all the key's tools, label `default`). */
+    agentLabel?: string | undefined;
+    tools?: readonly ToolName[] | undefined;
+    idempotencyKey?: string | undefined;
+    signal?: AbortSignal | undefined;
+    onRetry?: RequestOptions['onRetry'] | undefined;
+}
 export type AgentSession = Ok<operations['getV1WorkspacesWorkspaceIdAgentSessions']>['data'][number];
 export type Entitlements = Ok<operations['getV1OrganizationsOrganizationIdEntitlements']>;
 export type Me = Ok<operations['getV1Me']>;
@@ -83,6 +113,13 @@ export interface ShardfluxOptions {
      * retries and busy waits of tool calls): for logs or telemetry. Per-call `onProgress` listeners get their own events too.
      */
     onProgress?: ProgressListener;
+    /**
+     * The automatic version check (0.9.0; contracts §30.4): after the first successful API response of the process, a
+     * background GET /v1/client-versions (3 s timeout, errors swallowed) emits a `ShardfluxUpdateWarning` when this
+     * package is outdated or unsupported. Default true (`@shardflux/sdk` at SDK_VERSION); tools built on the SDK pass
+     * their own `{ package, version }` or `false`. `SHARDFLUX_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER=1` turn it off.
+     */
+    versionCheck?: VersionCheckOption;
 }
 export interface Caps {
     cpu_millis?: number;
@@ -144,6 +181,16 @@ export interface OpenParams {
      * with another value is ShardfluxApiError 409 (details.reason `lifetime_mismatch`).
      */
     lifetime?: WorkspaceLifetime;
+    /**
+     * `file_first` (0.9.0; contracts §29): the workspace is a versioned file tree with no VM between executions. It is
+     * ready at once (no operation: the open answers with a tool token), never suspended, and runs commands as executions
+     * (`workspace.executions.run()`): a fresh VM on the latest tree whose changed files become the next tree revision;
+     * nothing else survives an execution. Needs a layered template version (409 `layout_unsupported` otherwise) and is
+     * persistent (`lifetime: 'session'` with it is 422 `not_supported_for_mode`). Omitted: `processful` for a new key, the
+     * stored mode for an existing one. Immutable: reopening a key with another mode is 409 `mode_mismatch`; 422
+     * `mode_not_available` while the deployment does not offer file-first workspaces.
+     */
+    mode?: WorkspaceMode;
     /** `false`: return immediately (possibly not ready). Default: wait until ready. */
     wait?: false | WaitOptions;
     /** Defaults to a fresh key per open() call so transport retries replay instead of duplicating. */
@@ -252,9 +299,24 @@ export declare class WorkspacesApi {
      */
     suspend(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     suspend(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
-    /** Resumes a suspended workspace. Resolves when the resume is requested; with `wait`, once the workspace runs. */
-    resume(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
-    resume(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
+    /**
+     * Resumes a suspended workspace. Resolves when the resume is requested; with `wait`, once the workspace runs. With
+     * `wait` (0.9.0) the request is held by the server until the workspace runs (contracts §22.6: one request, timing phase
+     * `request` with reason `held`); a server that does not hold it answers at once and the operation is polled.
+     * `serverWait: false` polls only. `agentLabel`/`tools` choose the tool token the held answer carries (attribution
+     * only here; `workspace.resume()` keeps it). A workspace that is already running is ShardfluxApiError 409 `conflict`
+     * (details.reason `already_running`), with or without `wait`.
+     */
+    resume(workspaceId: string, opts: WaitedResumeOptions): Promise<FinishedOperation>;
+    resume(workspaceId: string, opts?: ResumeOptions): Promise<Operation>;
+    /**
+     * One `POST /v1/workspaces/{id}/resume` (0.9.0), held for up to `waitS` seconds when that is at least 1 (`Prefer:
+     * wait`, contracts §22.6), asking for the tool token of `agentLabel`/`tools`. `ready` only for a 200 the server says it
+     * held (`Preference-Applied`); every other answer is the operation to wait for, so a server without the held resume
+     * works unchanged. Refusals (409 operation_in_progress, already_running without the hold, ...) throw as usual.
+     * `Workspace.wake()` and `resume({ wait })` use it; most callers want those.
+     */
+    requestResume(workspaceId: string, o: ResumeRequestOptions): Promise<ResumeAnswer>;
     /** Takes a snapshot. Resolves when it is requested; with `wait`, once it is taken. */
     snapshot(workspaceId: string, opts: WaitedLifecycleOptions & {
         label?: string;
@@ -354,6 +416,15 @@ export declare class Shardflux {
     /** The authenticated principal (the API key, its organization and project). */
     me(): Promise<Me>;
     entitlements(organizationId: string): Promise<Entitlements>;
+    /**
+     * Send feedback straight to the Shardflux founder (0.9.0+; POST /v1/feedback), who reads every message. Use it while
+     * you work, the moment something fails unexpectedly, an error or doc is confusing, something is missing or slow, or a
+     * workaround was needed; short and specific beats polished, and `context.requestId` / `errorCode` let the founder find
+     * the logs. `context.client` defaults to `shardflux-sdk-ts/<SDK_VERSION>`. Returns `{ id, receivedAt, duplicate }`
+     * (`duplicate`: the same message from this key within 24 hours; no second email). 429 `rate_limited` (with
+     * `retryAfterSeconds`) and 422 `validation_failed` are ShardfluxApiErrors; the call is never retried.
+     */
+    sendFeedback(params: SendFeedbackParams): Promise<FeedbackReceipt>;
     /** Raw access to any /v1 endpoint with the SDK's authentication and error handling. */
     request<T>(method: string, path: string, init?: Parameters<HttpClient['json']>[2]): Promise<T>;
 }

package/dist/client.js

@@ -1,4 +1,4 @@
-import { OperationFailedError, OperationTimeoutError, ShardfluxApiError } from "./errors.js";
+import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
 import { HttpClient, SDK_VERSION, SERVER_WAIT_MAX_S, defaultFetch, defaultSleep, pollWithWait, randomId } from "./http.js";
 import { Workspace } from "./workspace.js";
 import { AuditApi } from "./audit.js";
@@ -7,9 +7,11 @@ import { SecretsApi } from "./secrets.js";
 import { TemplatesApi, saveAsTemplateBody } from "./templates.js";
 import { UsageApi } from "./usage.js";
 import { VolumesApi } from "./volumes.js";
-import { AFTER_WAIT, TRACE, runLifecycle } from "./lifecycle.js";
+import { versionCheckHook } from "./version-check.js";
+import { AFTER_WAIT, HELD_RESUME, TRACE, runLifecycle, waitOptionsOf } from "./lifecycle.js";
 import { Trace, combineListeners, traced } from "./progress.js";
 import { CaptureRegistry } from "./capture.js";
+import { sendFeedback } from "./feedback.js";
 /**
  * The workspace a key names (contracts §19.11): the live row (deleted_at null) when there is one, since at most one live
  * workspace holds a key; otherwise the newest tombstone (ended sessions leave tombstones with the same key, and a
@@ -29,6 +31,21 @@ export function pickByKey(rows, key) {
     return tomb;
 }
 const TERMINAL = new Set(['succeeded', 'failed', 'canceled']);
+/**
+ * `resume({ wait })` of a workspace that is already running: a held resume answers 200 without an operation (contracts
+ * §22.6); the SDK reports it as the API does without the hold, 409 `conflict` `already_running`.
+ */
+function alreadyRunning(answer) {
+    return new ShardfluxApiError(409, {
+        error: {
+            code: 'conflict',
+            message: 'Only a suspended workspace can be resumed; this one is already running.',
+            request_id: answer.requestId ?? '',
+            retryable: false,
+            details: { reason: 'already_running', observed_state: answer.workspace.observed_state, desired_state: answer.workspace.desired_state },
+        },
+    }, 'api');
+}
 /** Races the injected sleep against the signal (the injected sleep itself may not be abortable). */
 function abortableSleep(sleep, ms, signal) {
     if (signal.aborted)
@@ -81,6 +98,8 @@ export class WorkspacesApi {
             body.inputs = params.inputs;
         if (params.lifetime !== undefined)
             body.lifetime = params.lifetime;
+        if (params.mode !== undefined)
+            body.mode = params.mode;
         const waitOpts = params.wait === false ? null : (params.wait ?? {});
         const trace = new Trace('open', combineListeners(this.#ctx().onProgress, params.onProgress, waitOpts?.onProgress));
         return traced(trace, async () => {
@@ -188,7 +207,7 @@ export class WorkspacesApi {
         return traced(trace, run);
     }
     async #poll(operationId, opts, trace) {
-        const { sleep, http, authorization } = this.#ctx();
+        const { sleep, http } = this.#ctx();
         const timeoutMs = opts.timeoutMs ?? 300_000;
         const maxInterval = opts.maxPollIntervalMs ?? 5_000;
         let interval = opts.pollIntervalMs ?? 250;
@@ -200,7 +219,8 @@ export class WorkspacesApi {
                 throw aborted();
             const waitS = opts.serverWait === false ? 0 : (timeoutMs - (Date.now() - started)) / 1000;
             const t0 = Date.now();
-            const { body, applied } = await pollWithWait(http, `/v1/operations/${encodeURIComponent(operationId)}`, authorization, waitS, opts.signal, trace.onRetry);
+            // Read per poll: a user session (ShardfluxAccount) may rotate its token while the wait runs.
+            const { body, applied } = await pollWithWait(http, `/v1/operations/${encodeURIComponent(operationId)}`, this.#ctx().authorization, waitS, opts.signal, trace.onRetry);
             const operation = body.operation;
             trace.observe(operation);
             if (operation.state === 'succeeded')
@@ -317,7 +337,83 @@ export class WorkspacesApi {
         return this.#op('suspend', workspaceId, undefined, opts);
     }
     resume(workspaceId, opts = {}) {
-        return this.#op('resume', workspaceId, undefined, opts);
+        const waitOpts = waitOptionsOf(opts);
+        if (!waitOpts || waitOpts.serverWait === false)
+            return this.#op('resume', workspaceId, undefined, opts);
+        const trace = new Trace('resume', combineListeners(this.#ctx().onProgress, opts.onProgress, waitOpts.onProgress), { workspaceId });
+        return traced(trace, async () => {
+            const timeoutMs = waitOpts.timeoutMs ?? 300_000;
+            const started = Date.now();
+            // A handle's target takes the answer; by id, `agentLabel`/`tools` only choose the token (attribution).
+            const target = opts[HELD_RESUME] ?? { agentLabel: opts.agentLabel, tools: opts.tools, adopt: () => undefined };
+            const waitS = Math.min(SERVER_WAIT_MAX_S, Math.floor(timeoutMs / 1000));
+            trace.phase('request', waitS >= 1 ? 'held' : null);
+            const answer = await this.requestResume(workspaceId, {
+                waitS,
+                agentLabel: target.agentLabel,
+                tools: target.tools,
+                idempotencyKey: opts.idempotencyKey,
+                signal: waitOpts.signal,
+                onRetry: trace.onRetry,
+            });
+            if (answer.operation)
+                trace.observe(answer.operation);
+            if (answer.ready) {
+                // Held (200): the running workspace and its token, no wait, view or token request.
+                target.adopt(answer.workspace, answer.toolToken);
+                if (!answer.operation)
+                    throw alreadyRunning(answer);
+                return answer.operation;
+            }
+            const operation = answer.operation;
+            if (operation.state === 'failed' || operation.state === 'canceled')
+                throw new OperationFailedError(operation);
+            let final = operation;
+            if (operation.state !== 'succeeded') {
+                const left = waitS >= 1 ? { timeoutMs: Math.max(1, timeoutMs - (Date.now() - started)) } : {};
+                final = await this.waitForOperation(operation.id, { ...waitOpts, ...left, [TRACE]: trace });
+            }
+            await opts[AFTER_WAIT]?.(trace, final);
+            return final;
+        });
+    }
+    /**
+     * One `POST /v1/workspaces/{id}/resume` (0.9.0), held for up to `waitS` seconds when that is at least 1 (`Prefer:
+     * wait`, contracts §22.6), asking for the tool token of `agentLabel`/`tools`. `ready` only for a 200 the server says it
+     * held (`Preference-Applied`); every other answer is the operation to wait for, so a server without the held resume
+     * works unchanged. Refusals (409 operation_in_progress, already_running without the hold, ...) throw as usual.
+     * `Workspace.wake()` and `resume({ wait })` use it; most callers want those.
+     */
+    async requestResume(workspaceId, o) {
+        const s = Math.min(SERVER_WAIT_MAX_S, Math.floor(o.waitS));
+        const held = s >= 1;
+        const body = {};
+        if (held && o.agentLabel !== undefined)
+            body.agent_label = o.agentLabel;
+        if (held && o.tools !== undefined)
+            body.tools = [...o.tools];
+        const init = {
+            idempotencyKey: o.idempotencyKey ?? randomId('op-'),
+            ...(Object.keys(body).length > 0 ? { json: body } : {}),
+            ...(o.signal ? { signal: o.signal } : {}),
+            ...(o.onRetry ? { onRetry: o.onRetry } : {}),
+        };
+        if (held) {
+            init.headers = { prefer: `wait=${s}` };
+            // The held response may take the whole wait: the request timeout must outlast it.
+            init.timeoutMs = Math.max(this.#http.opts.timeoutMs, s * 1000 + 10_000);
+        }
+        const res = await this.#http.jsonWithHeaders('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/resume`, init, this.#auth);
+        const b = res.body;
+        if (!b || typeof b !== 'object' || !b.workspace)
+            throw new ShardfluxProtocolError('resume: response has no workspace', res.status);
+        const pa = res.headers.get('preference-applied');
+        const ready = held && res.status === 200 && pa !== null && /\bwait\s*=/i.test(pa);
+        if (!ready && !b.operation)
+            throw new ShardfluxProtocolError('resume: response has no operation', res.status);
+        const toolToken = ready ? (b.tool_token ?? null) : null;
+        this.#noteToken(toolToken);
+        return { ready, operation: b.operation ?? null, workspace: b.workspace, toolToken, requestId: res.headers.get('x-request-id') };
     }
     snapshot(workspaceId, opts = {}) {
         return this.#op('snapshot', workspaceId, opts.label === undefined ? {} : { label: opts.label }, opts);
@@ -439,8 +535,9 @@ export class Shardflux {
         this.egress = new EgressPolicyApi(() => this.#ctx);
         this.audit = new AuditApi(() => this.#ctx);
         this.volumes = new VolumesApi(() => this.#ctx);
+        const baseUrl = opts.baseUrl ?? 'https://api.shardflux.dev';
         this.#ctx = {
-            http: new HttpClient({ baseUrl: opts.baseUrl ?? 'https://api.shardflux.dev', fetch: f, userAgent, timeoutMs: opts.timeoutMs ?? 30_000, maxRetries: opts.maxRetries ?? 2, source: 'api', sleep }),
+            http: new HttpClient({ baseUrl, fetch: f, userAgent, timeoutMs: opts.timeoutMs ?? 30_000, maxRetries: opts.maxRetries ?? 2, source: 'api', sleep, onSuccess: versionCheckHook(opts.versionCheck, baseUrl, f, userAgent) }),
             authorization: `Bearer ${opts.apiKey}`,
             fetch: f,
             userAgent,
@@ -457,6 +554,17 @@ export class Shardflux {
     entitlements(organizationId) {
         return this.#ctx.http.json('GET', `/v1/organizations/${encodeURIComponent(organizationId)}/entitlements`, {}, this.#ctx.authorization);
     }
+    /**
+     * Send feedback straight to the Shardflux founder (0.9.0+; POST /v1/feedback), who reads every message. Use it while
+     * you work, the moment something fails unexpectedly, an error or doc is confusing, something is missing or slow, or a
+     * workaround was needed; short and specific beats polished, and `context.requestId` / `errorCode` let the founder find
+     * the logs. `context.client` defaults to `shardflux-sdk-ts/<SDK_VERSION>`. Returns `{ id, receivedAt, duplicate }`
+     * (`duplicate`: the same message from this key within 24 hours; no second email). 429 `rate_limited` (with
+     * `retryAfterSeconds`) and 422 `validation_failed` are ShardfluxApiErrors; the call is never retried.
+     */
+    sendFeedback(params) {
+        return sendFeedback(this.#ctx, params);
+    }
     /** Raw access to any /v1 endpoint with the SDK's authentication and error handling. */
     request(method, path, init = {}) {
         return this.#ctx.http.json(method, path, init, this.#ctx.authorization);

package/dist/errors.d.ts

@@ -19,9 +19,27 @@ export type ErrorCode = AppErrorCode | CellErrorCode;
  * 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).
+ * guest_feature_unavailable). File tools and parking (contracts §25-§28, 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,
+ * 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
+ * mode_not_available (the deployment does not offer file-first workspaces), outside_tree_root (also 404 on reads); 409
+ * workspace_busy execution_in_progress (details.execution_id; waited out like any workspace_busy); 503
+ * service_unavailable no_execution_host (retryable, Retry-After). An execution that ended `failed` or `lost` names its
+ * cause in `error.details.reason`: lease_expired, host_unreachable, host_restarted, tree_moved, blob_missing,
+ * blob_corrupt, exec_failed_to_start, among others.
  */
-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';
+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';
 /** A known reason, or any other string the server sends (reasons are open-ended). */
 export type ErrorReason = KnownErrorReason | (string & {});
 export interface ErrorBodyLike {
@@ -49,8 +67,49 @@ export declare class ShardfluxApiError extends Error {
     readonly reason: ErrorReason | undefined;
     /** Where the time went when a traced call (open, a waited lifecycle call, a wake) failed with this error. */
     timing: LifecycleTiming | undefined;
-    constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number);
+    /**
+     * `X-Tree-Revision` of the refusal (file-first workspaces, contracts §29.8): 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). */
+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
+ * `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
+ * executions and no tree revisions. When the handle knows the workspace's mode the SDK raises it before any request
+ * (`local` true); otherwise it is the server's refusal. Either way `err.reason === 'not_supported_for_mode'`.
+ */
+export declare class NotSupportedForModeError extends ShardfluxApiError {
+    /** The workspace's mode (null when the server did not say). */
+    readonly mode: WorkspaceMode | null;
+    /** The refused call, e.g. `pty.open`, `suspend`, `executions.run` (null when the server did not say). */
+    readonly operation: string | null;
+    /** True when the SDK refused the call itself, without a request. */
+    readonly local: boolean;
+    constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number, treeRevision?: number, local?: boolean);
+    /** The SDK's own refusal of `operation` for a workspace whose mode it knows (no request was made). */
+    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
+ * `conflict`, details.reason `tree_revision_mismatch`. Nothing changed. `currentTreeRevision` is the revision the tree
+ * is at: read what changed, then retry against it.
+ */
+export declare class TreeRevisionMismatchError extends ShardfluxApiError {
+    readonly currentTreeRevision: number | null;
+    constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number, treeRevision?: number);
+}
+/**
+ * Builds the error for an error body, typed by its reason: NotSupportedForModeError for `not_supported_for_mode`,
+ * TreeRevisionMismatchError for `tree_revision_mismatch`, else ShardfluxApiError. Every SDK request builds its errors
+ * here, so `instanceof` works whichever call was refused.
+ */
+export declare function apiError(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number, treeRevision?: number): ShardfluxApiError;
 /** The response was not the documented shape (e.g. a proxy error page). */
 export declare class ShardfluxProtocolError extends Error {
     readonly status: number;

package/dist/errors.js

@@ -19,7 +19,12 @@ export class ShardfluxApiError extends Error {
     reason;
     /** Where the time went when a traced call (open, a waited lifecycle call, a wake) failed with this error. */
     timing = undefined;
-    constructor(status, body, source, retryAfterSeconds) {
+    /**
+     * `X-Tree-Revision` of the refusal (file-first workspaces, contracts §29.8): the tree revision the refused call saw.
+     * Undefined when the response carried none (processful workspaces, the application API).
+     */
+    treeRevision;
+    constructor(status, body, source, retryAfterSeconds, treeRevision) {
         super(body.error.message);
         this.name = 'ShardfluxApiError';
         this.status = status;
@@ -30,10 +35,69 @@ export class ShardfluxApiError extends Error {
         this.operationId = body.error.operation_id;
         this.source = source;
         this.retryAfterSeconds = retryAfterSeconds;
+        this.treeRevision = treeRevision;
         const reason = body.error.details?.reason;
         this.reason = typeof reason === 'string' ? reason : undefined;
     }
 }
+/**
+ * The call does not exist for the workspace's mode (contracts §29.7, §29.8): 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
+ * executions and no tree revisions. When the handle knows the workspace's mode the SDK raises it before any request
+ * (`local` true); otherwise it is the server's refusal. Either way `err.reason === 'not_supported_for_mode'`.
+ */
+export class NotSupportedForModeError extends ShardfluxApiError {
+    /** The workspace's mode (null when the server did not say). */
+    mode;
+    /** The refused call, e.g. `pty.open`, `suspend`, `executions.run` (null when the server did not say). */
+    operation;
+    /** True when the SDK refused the call itself, without a request. */
+    local;
+    constructor(status, body, source, retryAfterSeconds, treeRevision, local = false) {
+        super(status, body, source, retryAfterSeconds, treeRevision);
+        this.name = 'NotSupportedForModeError';
+        const mode = body.error.details?.mode;
+        const operation = body.error.details?.operation;
+        this.mode = mode === 'processful' || mode === 'file_first' ? mode : null;
+        this.operation = typeof operation === 'string' && operation !== '' ? operation : null;
+        this.local = local;
+    }
+    /** The SDK's own refusal of `operation` for a workspace whose mode it knows (no request was made). */
+    static local(mode, operation, source, message) {
+        return new NotSupportedForModeError(409, { error: { code: 'conflict', message, request_id: '', retryable: false, details: { reason: 'not_supported_for_mode', mode, operation } } }, source, undefined, undefined, true);
+    }
+}
+/**
+ * A file-first call with `ifTreeRevision` (`If-Match`) found the tree at another revision (contracts §29.8): 409
+ * `conflict`, details.reason `tree_revision_mismatch`. Nothing changed. `currentTreeRevision` is the revision the tree
+ * is at: read what changed, then retry against it.
+ */
+export class TreeRevisionMismatchError extends ShardfluxApiError {
+    currentTreeRevision;
+    constructor(status, body, source, retryAfterSeconds, treeRevision) {
+        super(status, body, source, retryAfterSeconds, treeRevision);
+        this.name = 'TreeRevisionMismatchError';
+        const cur = body.error.details?.current_tree_revision;
+        this.currentTreeRevision = typeof cur === 'number' && Number.isSafeInteger(cur) ? cur : (treeRevision ?? null);
+    }
+}
+/**
+ * Builds the error for an error body, typed by its reason: NotSupportedForModeError for `not_supported_for_mode`,
+ * TreeRevisionMismatchError for `tree_revision_mismatch`, else ShardfluxApiError. Every SDK request builds its errors
+ * here, so `instanceof` works whichever call was refused.
+ */
+export function apiError(status, body, source, retryAfterSeconds, treeRevision) {
+    switch (body.error.details?.reason) {
+        case 'not_supported_for_mode':
+            return new NotSupportedForModeError(status, body, source, retryAfterSeconds, treeRevision);
+        case 'tree_revision_mismatch':
+            return new TreeRevisionMismatchError(status, body, source, retryAfterSeconds, treeRevision);
+        default:
+            return new ShardfluxApiError(status, body, source, retryAfterSeconds, treeRevision);
+    }
+}
 /** The response was not the documented shape (e.g. a proxy error page). */
 export class ShardfluxProtocolError extends Error {
     status;

package/dist/executions.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Executions of file-first workspaces (contracts §29.1, §29.8): 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.
+ */
+import type { components } from './generated/cell-api.js';
+type S = components['schemas'];
+/** The cell's `ExecutionResult` as sent on the wire (stdout/stderr base64). */
+export type ExecutionResultBody = S['ExecutionResult'];
+/** One entry the execution added, modified or deleted under /home/user (`type` is the new entry's, or the removed one's). */
+export type ExecutionChange = S['ExecutionChange'];
+/** queued / running (in progress), succeeded (the command ran to its end, any exit code), failed or lost (nothing published). */
+export type ExecutionState = S['ExecutionState'];
+/** The `error` of a failed or lost execution: `details.reason` names the cause (e.g. `lease_expired`, `exec_failed_to_start`). */
+export interface ExecutionError {
+    code: string;
+    message: string;
+    /** A new execution id may succeed (the SDK never retries with a new id itself). */
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}
+/** `^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$` (cell-api.yaml ExecutionIdValue). */
+export declare const EXECUTION_ID: RegExp;
+/** A fresh execution id: `ex-` plus a random UUID (39 characters, valid per EXECUTION_ID). */
+export declare function newExecutionId(): string;
+export interface ExecutionRunOptions {
+    /**
+     * The execution's idempotency key (8-128 characters of A-Z a-z 0-9 . _ : -, starting with a letter or digit). Default:
+     * a fresh `ex-<uuid>`. Pass your own to make the call safe to repeat across processes: the same id with the same request
+     * returns the recorded result (`replayed`), with another request 409 `execution_id_reused`.
+     */
+    executionId?: string;
+    /** Working directory (absolute, under /home/user). */
+    cwd?: string;
+    env?: Record<string, string>;
+    user?: string;
+    /** Written to stdin, which is then closed (at most 1 MiB). */
+    stdin?: string | Uint8Array;
+    /** Kill the command after this long (`timedOut`); 0 or omitted: no limit. */
+    timeoutMs?: number;
+    killGraceMs?: number;
+    /** Names of customer secrets injected as environment variables of this command only (as for `exec.run`). */
+    secretRefs?: string[];
+    /** stdout and stderr are each captured up to this many bytes (1-16 MiB; cell default 1 MiB), `stdoutTruncated` beyond. */
+    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
+     * `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.
+     */
+    maxRetries?: number;
+    /**
+     * Longest single wait for the answer (default 300 000 ms). When it elapses the request is sent again with the same id,
+     * which joins the running execution; these re-attachments are not failures and never run the command again.
+     */
+    attemptTimeoutMs?: number;
+    /** Stops waiting (the execution continues server side; `executions.get(id)` returns its result later). */
+    signal?: AbortSignal;
+}
+export interface ExecutionGetOptions {
+    /**
+     * While the execution is queued or running (202), poll until it ended or this long passed (backoff 250 ms doubling to
+     * 2 s), then return the last view. Default 0: return at once (a pending result has `pending` true).
+     */
+    waitMs?: number;
+    signal?: AbortSignal;
+}
+/** The outcome of an execution: decoded output, exit status, the revision it produced and what it changed. */
+export declare class ExecutionResult {
+    readonly executionId: string;
+    readonly state: ExecutionState;
+    /** The tree revision the command ran on. */
+    readonly baseRevision: number;
+    /**
+     * The tree revision after the execution: `baseRevision + 1` when it changed files, else `baseRevision`; null unless
+     * `state` is `succeeded` (a failed or lost execution publishes nothing).
+     */
+    readonly treeRevision: number | null;
+    /** The command's exit status (-1 when a signal ended it); null unless succeeded. */
+    readonly exitCode: number | null;
+    readonly termSignal: number | null;
+    /** The command ran past `timeoutMs` and was killed. */
+    readonly timedOut: boolean;
+    /** Standard output, at most `outputLimitBytes`. */
+    readonly stdout: Uint8Array;
+    readonly stderr: Uint8Array;
+    readonly stdoutTruncated: boolean;
+    readonly stderrTruncated: boolean;
+    /** What the execution changed under /home/user, sorted by path (at most 10 000; see `changedTruncated`). */
+    readonly changed: ExecutionChange[];
+    readonly changedTruncated: boolean;
+    /** Milliseconds and counts: queue_ms, run_ms, publish_ms, total_ms and the host's (boot_ms, exec_ms, vm_seconds, ...). */
+    readonly timings: Record<string, number>;
+    /** failed / lost: why (`details.reason`); null otherwise. */
+    readonly error: ExecutionError | null;
+    readonly createdAt: string;
+    readonly finishedAt: string | null;
+    /**
+     * The call that returned this result did not start the execution: `executions.run()` answered 200 (the execution
+     * already existed: its recorded result, or the running one waited for), or it came from `executions.get()`. False
+     * only for the run() call whose request started it (201).
+     */
+    readonly replayed: boolean;
+    /** The body as the cell sent it. */
+    readonly raw: ExecutionResultBody;
+    constructor(body: ExecutionResultBody, replayed: boolean);
+    /** Still queued or running (only `executions.get()` returns such a result). */
+    get pending(): boolean;
+    /** The command ran to its end with exit code 0. */
+    get ok(): boolean;
+    /** A stream as text (UTF-8; invalid sequences become U+FFFD). */
+    text(stream?: 'stdout' | 'stderr'): string;
+    get stdoutText(): string;
+    get stderrText(): string;
+    /** `error.details.reason` of a failed or lost execution (null otherwise). */
+    get errorReason(): string | null;
+}
+export {};