@shardflux/sdk 0.8.0 → 0.10.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']>;
@@ -64,6 +94,28 @@ export type CheckoutSession = Ok<operations['postApiV1OrganizationsOrganizationI
 export type PortalSession = Ok<operations['postApiV1OrganizationsOrganizationIdBillingPortalSessions']>;
 export type InvoicePage = Ok<operations['getApiV1OrganizationsOrganizationIdBillingInvoices']>;
 export type Invoice = InvoicePage['data'][number];
+/**
+ * A pending suspend-when-idle request (0.10.0; contracts §20.6): once the workspace has been idle for `after_seconds`
+ * (counted from the later of its last work and `requested_at`), it is suspended; `not_before` = requested_at +
+ * after_seconds is the earliest.
+ */
+export type SuspendRequest = components['schemas']['SuspendRequest'];
+/** POST /v1/workspaces/{id}/suspend-when-idle (202). */
+export type SuspendWhenIdleResponse = Ok<operations['postV1WorkspacesWorkspaceIdSuspendWhenIdle']>;
+export interface SuspendWhenIdleOptions {
+    /** Seconds the workspace must stay idle before it is suspended: an integer from 30 to 3600 (the API refuses others with 422 validation_failed). */
+    afterSeconds: number;
+    /** Replays the stored response for a repeated request (default: a fresh key per call, so transport retries replay). */
+    idempotencyKey?: string;
+}
+export interface SuspendWhenIdleResult {
+    /** The recorded request; null when a suspend was already in progress (then `operation` is that suspend). */
+    suspendRequest: SuspendRequest | null;
+    /** The suspend already in progress (nothing was recorded), else null: the suspend itself happens later, from the cell's idle loop. */
+    operation: Operation | null;
+    /** The workspace after the call (on a handle: the handle itself, with its view updated). */
+    workspace: Workspace;
+}
 export interface ShardfluxOptions {
     /** Project API key: sfk_<key_id>_<secret>. */
     apiKey: string;
@@ -83,6 +135,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 +203,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 +321,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;
@@ -262,6 +346,28 @@ export declare class WorkspacesApi {
     snapshot(workspaceId: string, opts?: LifecycleOptions & {
         label?: string;
     }): Promise<Operation>;
+    /**
+     * Suspends the workspace once it has been idle for `afterSeconds` (0.9.0; contracts §20.6): meant for the end of an
+     * agent turn, so the workspace stops using RAM soon after instead of waiting out its idle policy. The idle time
+     * counts from the later of the workspace's last work and this request. A command still running, an attached exec or
+     * terminal stream, or a keepalive postpones the suspend until `afterSeconds` after it ends; a tool call after the
+     * request (the next turn) or a resume cancels it. Repeating replaces the pending request. It applies under every idle
+     * policy (`never` included) and never delays a suspend the policy would do sooner.
+     *
+     * Resolves with the recorded `suspendRequest`, or, when a suspend is already in progress, with that `operation` and
+     * nothing recorded. Tool-call capture writes recorded before the call land first (a later write would count as the
+     * next turn). Errors: ShardfluxApiError 409 with reason `not_running`, `operation_in_progress`, `session_lifetime` or
+     * `workspace_deleted`; 422 `validation_failed` for `afterSeconds` outside 30..3600.
+     *
+     *   await cloud.workspaces.suspendWhenIdle(workspace.id, { afterSeconds: 60 });
+     */
+    suspendWhenIdle(workspaceId: string, opts: SuspendWhenIdleOptions): Promise<SuspendWhenIdleResult>;
+    /**
+     * Cancels a pending suspend-when-idle request (0.10.0; DELETE /v1/workspaces/{id}/suspend-when-idle). Idempotent,
+     * in any workspace state; resolves with the workspace (`suspendRequest` null). A suspend the request already started
+     * is not undone: it is the workspace's `activeOperation` (resume or open the workspace instead).
+     */
+    cancelSuspendWhenIdle(workspaceId: string): Promise<Workspace>;
     /**
      * Ends a session workspace now (contracts §19.11): the workspace is deleted exactly like delete() (ended_reason
      * closed) and returns the `delete` operation (input.reason session_closed); the key then opens a NEW workspace.
@@ -354,6 +460,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,11 +337,115 @@ 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);
     }
+    /**
+     * Suspends the workspace once it has been idle for `afterSeconds` (0.9.0; contracts §20.6): meant for the end of an
+     * agent turn, so the workspace stops using RAM soon after instead of waiting out its idle policy. The idle time
+     * counts from the later of the workspace's last work and this request. A command still running, an attached exec or
+     * terminal stream, or a keepalive postpones the suspend until `afterSeconds` after it ends; a tool call after the
+     * request (the next turn) or a resume cancels it. Repeating replaces the pending request. It applies under every idle
+     * policy (`never` included) and never delays a suspend the policy would do sooner.
+     *
+     * Resolves with the recorded `suspendRequest`, or, when a suspend is already in progress, with that `operation` and
+     * nothing recorded. Tool-call capture writes recorded before the call land first (a later write would count as the
+     * next turn). Errors: ShardfluxApiError 409 with reason `not_running`, `operation_in_progress`, `session_lifetime` or
+     * `workspace_deleted`; 422 `validation_failed` for `afterSeconds` outside 30..3600.
+     *
+     *   await cloud.workspaces.suspendWhenIdle(workspace.id, { afterSeconds: 60 });
+     */
+    async suspendWhenIdle(workspaceId, opts) {
+        await this.#ctx().captures.settle(workspaceId);
+        const body = await this.#http.json('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/suspend-when-idle`, { json: { after_seconds: opts.afterSeconds }, idempotencyKey: opts.idempotencyKey ?? randomId('op-') }, this.#auth);
+        return { suspendRequest: body.suspend_request, operation: body.operation, workspace: this.#wrap(body.workspace) };
+    }
+    /**
+     * Cancels a pending suspend-when-idle request (0.10.0; DELETE /v1/workspaces/{id}/suspend-when-idle). Idempotent,
+     * in any workspace state; resolves with the workspace (`suspendRequest` null). A suspend the request already started
+     * is not undone: it is the workspace's `activeOperation` (resume or open the workspace instead).
+     */
+    async cancelSuspendWhenIdle(workspaceId) {
+        return this.#wrap(await this.#http.json('DELETE', `/v1/workspaces/${encodeURIComponent(workspaceId)}/suspend-when-idle`, {}, this.#auth));
+    }
     async close(workspaceId, opts = {}) {
         return (await this.closeWithView(workspaceId, opts)).operation;
     }
@@ -439,8 +563,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 +582,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,40 @@ 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.
+ * Working directories (0.10.0): 422 validation_failed invalid_cwd (details.field `cwd`): an exec, execution or PTY start
+ * named a relative cwd, which is refused rather than resolved (the message names the absolute path it likely means);
+ * a processful command that could not start rejects `exec.run()` with ExecStartError (409 conflict
+ * exec_failed_to_start).
+ * Opt-in overage with a spend cap (0.10.0): 402 allowance_exhausted on opens, resumes and forks carries details.reason
+ * allowance_used (a CPU-hours or RAM GiB-hours allowance is used up and overage is off or not on the plan),
+ * overage_paused (overage is on but paused while a plan payment is past due) or spend_cap_reached (overage charges
+ * reached the spend cap), plus details.spend_cap {cap_minor, effective_cap_minor, charges_minor, currency}; an API
+ * older than overage sends no reason. Changing overage is for owners and billing members (the console, or a user
+ * session: ShardfluxAccount.billing.setSpendPolicy; an API key gets 403), whose 422 validation_failed reasons are
+ * 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.
  */
-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' | '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';
 /** A known reason, or any other string the server sends (reasons are open-ended). */
 export type ErrorReason = KnownErrorReason | (string & {});
 export interface ErrorBodyLike {
@@ -49,8 +80,64 @@ 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);
+}
+type ExecSession = CellComponents['schemas']['ExecSession'];
+/**
+ * A command that could not start (0.10.0+): its working directory is not a directory, its program is not on PATH, or
+ * its user does not exist. Nothing ran, so there is no exit code and no output. `exec.run()` rejects with it when the
+ * session ends `failed_to_start` (before 0.10.0 it resolved with `exitCode: null` and empty output). It is a 409
+ * `conflict` with details.reason `exec_failed_to_start`, as a file-first execution that could not start reports it;
+ * the message carries the workspace's own words, e.g. `working directory "/home/user/app" is not a directory`.
+ */
+export declare class ExecStartError extends ShardfluxApiError {
+    /** The exec session that could not start. */
+    readonly sessionId: string;
+    /** The session as the cell reported it (state `failed_to_start`, `error`). */
+    readonly session: ExecSession;
+    constructor(session: ExecSession);
+}
+/**
+ * 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,97 @@ 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);
+    }
+}
+/**
+ * A command that could not start (0.10.0+): its working directory is not a directory, its program is not on PATH, or
+ * its user does not exist. Nothing ran, so there is no exit code and no output. `exec.run()` rejects with it when the
+ * session ends `failed_to_start` (before 0.10.0 it resolved with `exitCode: null` and empty output). It is a 409
+ * `conflict` with details.reason `exec_failed_to_start`, as a file-first execution that could not start reports it;
+ * the message carries the workspace's own words, e.g. `working directory "/home/user/app" is not a directory`.
+ */
+export class ExecStartError extends ShardfluxApiError {
+    /** The exec session that could not start. */
+    sessionId;
+    /** The session as the cell reported it (state `failed_to_start`, `error`). */
+    session;
+    constructor(session) {
+        const why = session.error ?? 'the workspace gave no reason';
+        super(409, {
+            error: {
+                code: 'conflict',
+                message: `The command could not start: ${why}`,
+                request_id: '',
+                retryable: false,
+                details: { reason: 'exec_failed_to_start', session_id: session.session_id, ...(session.error ? { error: session.error } : {}) },
+            },
+        }, 'cell');
+        this.name = 'ExecStartError';
+        this.sessionId = session.session_id;
+        this.session = session;
+    }
+}
+/**
+ * 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;