@shardflux/sdk 0.10.2 → 0.11.1

package/dist/cell.d.ts

@@ -7,7 +7,7 @@
  * (token expired or revoked early) invalidates the token and retries once with
  * a fresh one; the retried request is safe because the gateway rejected the
  * first before any effect (and exec/PTY starts are idempotent by session_id).
- * The same holds for lifecycle refusals (contracts §20.4): `workspace_busy` is
+ * The same holds for lifecycle refusals: `workspace_busy` is
  * waited out and `workspace_not_running` wakes the workspace, then the call is
  * retried, all within one bounded transition budget per call.
  *
@@ -15,7 +15,7 @@
  * `exec.run()` survives gateway restarts/disconnects by reconnecting with the
  * offsets it already processed; it never starts the command a second time.
  *
- * File-first workspaces (contracts §29) serve the files routes from a
+ * File-first workspaces serve the files routes from a
  * versioned tree and run commands as executions (`executions.run()`); the
  * client tracks the tree revision every response reports (`X-Tree-Revision`)
  * and, when it knows the workspace's mode, refuses calls the mode does not
@@ -39,20 +39,20 @@ export type ProcessList = S['ProcessList'];
 export type FileInfo = S['FileInfo'];
 export type FileList = S['FileList'];
 export type FileWriteResult = S['FileWriteResult'];
-/** Search request/result of `POST /files/search` (contracts §26.1). */
+/** Search request/result of `POST /files/search`. */
 export type FileSearchRequest = S['FileSearchRequest'];
 export type FileSearchMatch = S['FileSearchMatch'];
 export type FileSearchResult = S['FileSearchResult'];
-/** One text edit of `POST /files/patch` (contracts §26.2), as sent on the wire. */
+/** One text edit of `POST /files/patch`, as sent on the wire. */
 export type FileEdit = S['FileEdit'];
 export type FilePatchRequest = S['FilePatchRequest'];
 export type FilePatchResult = S['FilePatchResult'];
 /** A content SHA-256 (lowercase hex), or `absent` for a path that must not exist. */
 export type FileRevision = S['FileRevision'];
 export type WakeHintResult = S['WakeHintResult'];
-/** Where a running workspace's VM is (contracts §25.1): resident, frozen, hibernated or restoring. */
+/** Where a running workspace's VM is: resident, frozen, hibernated or restoring. */
 export type Residency = WakeHintResult['residency'];
-/** `X-Served-From`: `disk` when a read was served from a suspended or hibernated workspace's disk (contracts §26.4). */
+/** `X-Served-From`: `disk` when a read was served from a suspended or hibernated workspace's disk. */
 export type ServedFrom = 'guest' | 'disk';
 /** `files.readWithInfo()`: the bytes plus what the gateway reported about the file. */
 export interface FileReadResult {
@@ -122,7 +122,7 @@ export type BrowserScreenshotRequest = S['BrowserScreenshotRequest'];
 export type BrowserContentRequest = S['BrowserContentRequest'];
 export type BrowserContent = S['BrowserContent'];
 export type Signal = S['SignalValue'];
-/** One entry of a workspace's changes against its template (contracts §19.10). */
+/** One entry of a workspace's changes against its template. */
 export type WorkspaceChange = S['WorkspaceChange'];
 export type WorkspaceChangeKind = WorkspaceChange['change'];
 export type WorkspaceChangesSummary = S['WorkspaceChangesSummary'];
@@ -155,8 +155,8 @@ export interface CellClientOptions {
      * resolves `false` when there was nothing to wake (the API already reports it running), and the refusal then
      * surfaces. It throws when the wake fails (OperationFailedError) or outlasts `timeoutMs` (OperationTimeoutError).
      * Workspace.cell() supplies `workspace.wake()`. A call refused with `workspace_not_running` wakes the workspace and is
-     * retried; a refused call was never executed (contracts §20.4), so the retry cannot duplicate it. `null` surfaces
-     * the refusal instead. A wake that put a new token into this client's manager (the held resume, contracts §22.6;
+     * retried; a refused call was never executed, so the retry cannot duplicate it. `null` surfaces
+     * the refusal instead. A wake that put a new token into this client's manager (the held resume;
      * `workspace.wake({ agentLabel, tools })`) is retried with it; otherwise the token is replaced before the retry.
      */
     wake?: ((timeoutMs: number, signal?: AbortSignal) => Promise<boolean | void>) | null;
@@ -174,7 +174,7 @@ export interface CellClientOptions {
     /** Internal: see CAPTURE_BARRIER. */
     [CAPTURE_BARRIER]?: (() => Promise<unknown> | undefined) | undefined;
     /**
-     * The workspace's mode (contracts §29), or a function returning it (undefined: unknown). When known, calls the mode
+     * The workspace's mode, or a function returning it (undefined: unknown). When known, calls the mode
      * does not have fail at once with NotSupportedForModeError (`local` true) instead of a request: exec sessions, PTY,
      * processes, version control, browser and changes on a file-first workspace; executions and `ifTreeRevision` on a
      * processful one. Workspace.cell() supplies the workspace's.
@@ -183,7 +183,7 @@ export interface CellClientOptions {
     /** Called with every tree revision a response reports (`X-Tree-Revision`, execution results, mismatch refusals). */
     onTreeRevision?: (revision: number) => void;
 }
-/** `ifTreeRevision` (file-first workspaces, contracts §29.8): the tree revision a mutating files call applies to. */
+/** `ifTreeRevision` (file-first workspaces): the tree revision a mutating files call applies to. */
 export interface TreeRevisionOptions {
     /**
      * Sent as `If-Match`: the call applies only while the tree is at this revision (`workspace.treeRevision`, or a
@@ -197,7 +197,7 @@ export interface TreeRevisionOptions {
 interface TransitionOptions {
     /** Wake a suspended workspace for this call (default true; exec output follow reconnects pass false). */
     wake?: boolean;
-    /** Wait out `workspace_busy` (default true; the wake hint passes false: it is best effort). */
+    /** Wait out `workspace_busy` (default true; the wake hint passes false: it never waits). */
     busy?: boolean;
 }
 export declare const DEFAULT_TRANSITION_TIMEOUT_MS = 120000;
@@ -245,7 +245,7 @@ export interface RunOptions {
     /** Output reconnect attempts after a dropped stream (default 10). */
     maxReconnects?: number;
     /**
-     * Names of customer secrets (contracts §17) the cell injects as environment variables `NAME=value` of this
+     * Names of customer secrets the cell injects as environment variables `NAME=value` of this
      * process only (sent as `secret_refs`). Values are resolved at session start with this workspace's tool token and
      * never returned. A name the caller may not use refuses the whole start with 403 `forbidden`
      * (details.reason `secret_not_available`, details.names) and nothing runs; a name also present in `env` is 422.
@@ -274,7 +274,7 @@ export declare class CellClient {
      */
     close(): void;
     /**
-     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions (contracts §20.4),
+     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions,
      * bounded in total by `transitionTimeoutMs`: a call refused with `workspace_busy` is retried after `Retry-After`; one
      * refused with `workspace_not_running` (or whose token cannot be minted because the workspace is not running) wakes
      * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call.
@@ -314,9 +314,9 @@ export declare class CellClient {
          * the next revision (`treeRevision`, `changed`); processes, memory and files elsewhere do not survive it.
          *
          * The execution id (`executionId`, default a fresh `ex-<uuid>`) is the idempotency key: network failures and
-         * retryable 429/5xx answers (503 `no_execution_host`: no host has room, with Retry-After) are retried with the same
-         * id and request, at most `maxRetries` times, and an attempt that waits longer than `attemptTimeoutMs` re-attaches
-         * with the same id. The cell answers 201 for the call that ran the command and 200 (`replayed`) with the recorded
+         * retryable 429/5xx answers (503 `no_execution_host`: the execution cannot be placed right now, with Retry-After) are
+         * retried with the same id and request, at most `maxRetries` times, and an attempt that waits longer than
+         * `attemptTimeoutMs` re-attaches with the same id. The cell answers 201 for the call that ran the command and 200 (`replayed`) with the recorded
          * result otherwise, so the command runs at most once. `workspace_busy` (`execution_in_progress`: another execution
          * holds the workspace) is waited out within `transitionTimeoutMs`; `execution_id_reused` (the id with another
          * request) and validation errors are thrown at once. The SDK never retries with a new id: a result whose `state` is
@@ -376,7 +376,7 @@ export declare class CellClient {
         /**
          * Like `read()`, plus the file's size, `revision` (SHA-256 of the whole file, `X-File-Revision`, for regular files of
          * 16 MiB or less; pass it as `expectedRevision` to `patch()`) and `servedFrom` (`disk` when a sleeping workspace was
-         * read from its disk without waking it, contracts §26.4). 0.9.0+.
+         * read from its disk without waking it). 0.9.0+.
          */
         readWithInfo: (path: string, opts?: {
             offset?: number;
@@ -414,7 +414,7 @@ export declare class CellClient {
             overwrite?: boolean;
         } & TreeRevisionOptions) => Promise<FileInfo>;
         /**
-         * Searches file contents under `path`, a directory or one file (contracts §26.1; 0.9.0+): matching lines in path
+         * Searches file contents under `path`, a directory or one file (0.9.0+): matching lines in path
          * order, bounded by `maxMatches`, a 10 s budget and 4 MiB of results (`truncated`, `stop_reason` `max_matches`,
          * `budget` or `max_bytes`). Binary files, symbolic links, special files and files above `maxFileBytes` are
          * skipped. Read-only, so transient failures (e.g. 503 `host_capacity`) are retried; a suspended workspace whose
@@ -423,7 +423,7 @@ export declare class CellClient {
         search: (path: string, pattern: string, opts?: FileSearchOptions) => Promise<FileSearchResponse>;
         /**
          * Applies text `edits` (each `oldText` must occur exactly once unless `replaceAll`; in order) or replaces the whole
-         * file with `content`, atomically and durably (contracts §26.2; 0.9.0+). With `expectedRevision` the file must
+         * file with `content`, atomically and durably (0.9.0+). With `expectedRevision` the file must
          * still have that revision (`absent`: must not exist), else 409 `conflict` `revision_mismatch` with
          * `details.current_revision`. Edits that do not apply: 422 `validation_failed` `edit_not_found` / `edit_ambiguous`
          * (`details.index`), `edit_not_text`. Limits: a request of up to 7 MiB (else 413 `payload_too_large`; larger
@@ -437,7 +437,7 @@ export declare class CellClient {
         } & TreeRevisionOptions) => Promise<FilePatchResult>;
     };
     /**
-     * `POST /wake-hint` (contracts §26.6; 0.9.0+): announces an imminent tool call so a hibernated workspace is restored
+     * `POST /wake-hint` (0.9.0+): announces an imminent tool call so a hibernated workspace is restored
      * ahead of it. It never wakes a suspended workspace, never waits out `workspace_busy` and is not retried: a suspended
      * workspace answers 409 `workspace_not_running` (`Workspace.hint()` then wakes it in the background).
      */

package/dist/cell.js

@@ -200,7 +200,7 @@ export class CellClient {
             this.#closer.abort(new DOMException('The workspace handle was closed.', 'AbortError'));
     }
     /**
-     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions (contracts §20.4),
+     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions,
      * bounded in total by `transitionTimeoutMs`: a call refused with `workspace_busy` is retried after `Retry-After`; one
      * refused with `workspace_not_running` (or whose token cannot be minted because the workspace is not running) wakes
      * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call.
@@ -262,7 +262,7 @@ export class CellClient {
                     const before = this.tokens.current;
                     if ((await this.#wake(left, signal)) === false)
                         throw err; // running per the API: nothing to wait for
-                    // A held resume (contracts §22.6) handed this client a token of the woken workspace: use it. Otherwise the
+                    // A held resume handed this client a token of the woken workspace: use it. Otherwise the
                     // old token is of the previous epoch: fetch a new one.
                     if (this.tokens.current === before)
                         this.tokens.invalidate();
@@ -475,7 +475,7 @@ export class CellClient {
             reconnects,
         };
     }
-    // ---- executions (file-first workspaces, contracts §29.8) -----------------------------
+    // ---- executions (file-first workspaces) -----------------------------
     executions = {
         /**
          * Runs argv (no shell; `['bash', '-lc', line]` for shell syntax) as an execution of this file-first workspace: a
@@ -483,9 +483,9 @@ export class CellClient {
          * the next revision (`treeRevision`, `changed`); processes, memory and files elsewhere do not survive it.
          *
          * The execution id (`executionId`, default a fresh `ex-<uuid>`) is the idempotency key: network failures and
-         * retryable 429/5xx answers (503 `no_execution_host`: no host has room, with Retry-After) are retried with the same
-         * id and request, at most `maxRetries` times, and an attempt that waits longer than `attemptTimeoutMs` re-attaches
-         * with the same id. The cell answers 201 for the call that ran the command and 200 (`replayed`) with the recorded
+         * retryable 429/5xx answers (503 `no_execution_host`: the execution cannot be placed right now, with Retry-After) are
+         * retried with the same id and request, at most `maxRetries` times, and an attempt that waits longer than
+         * `attemptTimeoutMs` re-attaches with the same id. The cell answers 201 for the call that ran the command and 200 (`replayed`) with the recorded
          * result otherwise, so the command runs at most once. `workspace_busy` (`execution_in_progress`: another execution
          * holds the workspace) is waited out within `transitionTimeoutMs`; `execution_id_reused` (the id with another
          * request) and validation errors are thrown at once. The SDK never retries with a new id: a result whose `state` is
@@ -744,7 +744,7 @@ export class CellClient {
         /**
          * Like `read()`, plus the file's size, `revision` (SHA-256 of the whole file, `X-File-Revision`, for regular files of
          * 16 MiB or less; pass it as `expectedRevision` to `patch()`) and `servedFrom` (`disk` when a sleeping workspace was
-         * read from its disk without waking it, contracts §26.4). 0.9.0+.
+         * read from its disk without waking it). 0.9.0+.
          */
         readWithInfo: async (path, opts = {}) => {
             const url = this.#p('/v1/workspaces/{workspace_id}/files');
@@ -805,7 +805,7 @@ export class CellClient {
             headers: this.#ifMatch('files.move', opts),
         }),
         /**
-         * Searches file contents under `path`, a directory or one file (contracts §26.1; 0.9.0+): matching lines in path
+         * Searches file contents under `path`, a directory or one file (0.9.0+): matching lines in path
          * order, bounded by `maxMatches`, a 10 s budget and 4 MiB of results (`truncated`, `stop_reason` `max_matches`,
          * `budget` or `max_bytes`). Binary files, symbolic links, special files and files above `maxFileBytes` are
          * skipped. Read-only, so transient failures (e.g. 503 `host_capacity`) are retried; a suspended workspace whose
@@ -833,7 +833,7 @@ export class CellClient {
         },
         /**
          * Applies text `edits` (each `oldText` must occur exactly once unless `replaceAll`; in order) or replaces the whole
-         * file with `content`, atomically and durably (contracts §26.2; 0.9.0+). With `expectedRevision` the file must
+         * file with `content`, atomically and durably (0.9.0+). With `expectedRevision` the file must
          * still have that revision (`absent`: must not exist), else 409 `conflict` `revision_mismatch` with
          * `details.current_revision`. Edits that do not apply: 422 `validation_failed` `edit_not_found` / `edit_ambiguous`
          * (`details.index`), `edit_not_text`. Limits: a request of up to 7 MiB (else 413 `payload_too_large`; larger
@@ -865,17 +865,17 @@ export class CellClient {
         },
     };
     /**
-     * `POST /wake-hint` (contracts §26.6; 0.9.0+): announces an imminent tool call so a hibernated workspace is restored
+     * `POST /wake-hint` (0.9.0+): announces an imminent tool call so a hibernated workspace is restored
      * ahead of it. It never wakes a suspended workspace, never waits out `workspace_busy` and is not retried: a suspended
      * workspace answers 409 `workspace_not_running` (`Workspace.hint()` then wakes it in the background).
      */
     wakeHint(signal) {
-        // Nothing of a file-first workspace sleeps: the cell would answer `resident` (contracts §29.8).
+        // Nothing of a file-first workspace sleeps: the cell would answer `resident`.
         if (this.mode === 'file_first')
             return Promise.resolve({ residency: 'resident' });
         return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/wake-hint'), { wake: false, busy: false, timeoutMs: 10_000, ...(signal ? { signal } : {}) });
     }
-    // ---- changes against the template (layered workspaces, contracts §19.10) ------------------
+    // ---- changes against the template (layered workspaces) ------------------
     /**
      * One page of the workspace's changes against its template (needs the `files` tool). File-first workspaces: each
      * execution's result lists what it changed (`changed`); this route is refused (NotSupportedForModeError).

package/dist/client.d.ts

@@ -28,9 +28,9 @@ 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). */
+/** persistent (kept until deleted) or session (discarded when the session ends: close(), idle timeout). */
 export type WorkspaceLifetime = components['schemas']['WorkspaceLifetime'];
-/** legacy (one disk) or layered (the template chain read-only plus a workspace layer; contracts §19.2). */
+/** legacy (one disk) or layered (the template chain read-only plus a workspace layer). */
 export type DiskLayout = components['schemas']['DiskLayout'];
 /** standard, template_draft (a template's dev-mode draft) or template_test (a test instance of a draft state). */
 export type WorkspacePurpose = components['schemas']['WorkspacePurpose'];
@@ -56,7 +56,7 @@ 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. */
+/** POST /v1/workspaces/{id}/resume: the held 200 or the lifecycle 202. */
 export type ResumeResponse = Ok<operations['postV1WorkspacesWorkspaceIdResume']>;
 /** What a resume request answered (0.9.0; `WorkspacesApi.requestResume`). */
 export interface ResumeAnswer {
@@ -95,7 +95,7 @@ export type PortalSession = Ok<operations['postApiV1OrganizationsOrganizationIdB
 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`
+ * A pending suspend-when-idle request (0.10.0): 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.
  */
@@ -103,7 +103,7 @@ 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). */
+    /** Seconds the workspace must stay idle before it is suspended: an integer from 0 (as soon as it is idle) 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;
@@ -121,7 +121,7 @@ export interface ShardfluxOptions {
     apiKey: string;
     /** Default https://api.shardflux.dev (override with `baseUrl`). */
     baseUrl?: string;
-    /** Default: the runtime's fetch, with `Connection: close` on Node 26 (undici 8 keep-alive stalls; see defaultFetch in http.ts). */
+    /** Default: the runtime's fetch; on Node 26 every request uses a fresh connection (`Connection: close`) unless SHARDFLUX_HTTP_KEEPALIVE=1. */
     fetch?: typeof fetch;
     userAgent?: string;
     /** Per-request timeout (ms), default 30 s. */
@@ -136,7 +136,7 @@ export interface ShardfluxOptions {
      */
     onProgress?: ProgressListener;
     /**
-     * The automatic version check (0.9.0; contracts §30.4): after the first successful API response of the process, a
+     * The automatic version check (0.9.0): 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.
@@ -155,16 +155,16 @@ export interface ForkTarget {
 }
 export interface WaitOptions {
     /**
-     * Give up waiting after this long (default 300 000 ms); the operation continues server side. A start waiting for
-     * capacity (`capacity_pending`) does so until its deadline (`error.details.deadline_at`, 15 minutes after it was
-     * created) and then fails with `capacity_unavailable` (retryable; nothing was started).
+     * Give up waiting after this long (default 300 000 ms); the operation continues server side. A queued start
+     * (`capacity_pending`) has a deadline (`error.details.deadline_at`, 15 minutes after it was created); past it, it
+     * fails with `capacity_unavailable` (retryable; nothing was started).
      */
     timeoutMs?: number;
     /** First poll delay (default 250 ms); doubles up to `maxPollIntervalMs` with jitter. Used when the server does not wait. */
     pollIntervalMs?: number;
     maxPollIntervalMs?: number;
     /**
-     * Ask the server to hold each poll until the state changes (`Prefer: wait`, contracts §3; default true). A server
+     * Ask the server to hold each poll until the state changes (`Prefer: wait`; default true). A server
      * that does not wait answers at once and the SDK falls back to the backoff above.
      */
     serverWait?: boolean;
@@ -189,7 +189,7 @@ export interface OpenParams {
      */
     secrets?: string[];
     /**
-     * The template version's text inputs `{NAME: value}` (0.7.0; contracts §24.3), put into the environment of every
+     * The template version's text inputs `{NAME: value}` (0.7.0), put into the environment of every
      * exec, terminal, start command and service. A new key stores each given value, else the declared default; an
      * existing key replaces them all (omitted leaves them unchanged). Secret inputs are not passed here: they bind the
      * stored secret of the same name. ShardfluxApiError 422 with details.reason `input_unknown` (an undeclared name),
@@ -204,7 +204,7 @@ export interface OpenParams {
      */
     lifetime?: WorkspaceLifetime;
     /**
-     * `file_first` (0.9.0; contracts §29): the workspace is a versioned file tree with no VM between executions. It is
+     * `file_first` (0.9.0): 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
@@ -248,7 +248,7 @@ export interface FindByKeyOptions {
     signal?: AbortSignal;
 }
 /**
- * The workspace a key names (contracts §19.11): the live row (deleted_at null) when there is one, since at most one live
+ * The workspace a key names: 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
  * deleted persistent key keeps its tombstone). Null when no row has exactly this key. Rows need not be sorted.
  */
@@ -283,13 +283,13 @@ export declare class WorkspacesApi {
     open(params: OpenParams): Promise<Workspace>;
     /**
      * Waits for an operation: each GET /v1/operations/{id} asks the server to hold the response until the state changes
-     * (`Prefer: wait`, at most 20 s, contracts §3), so completion is seen within one notification of the commit. A server
+     * (`Prefer: wait`, at most 20 s), so completion is seen within one notification of the commit. A server
      * that does not wait is polled with bounded exponential backoff (+-20 % jitter). Resolves when the operation
      * succeeds; throws OperationFailedError when it fails or is canceled, OperationTimeoutError after `timeoutMs` (the
      * operation keeps running and can be awaited again). Both errors carry the wait's `timing`; `onProgress` sees each
-     * state change (queued, capacity_pending, running, with the server's reason) as it is observed. A start waiting in
-     * capacity_pending gives up at its deadline (`deadlineAt` on the phase event) and fails with `capacity_unavailable`
-     * (`err.retryable` true: nothing was started, retry later); the SDK does not retry it.
+     * state change (queued, capacity_pending, running, with the server's reason) as it is observed. A start in
+     * capacity_pending that passes its deadline (`deadlineAt` on the phase event) fails with `capacity_unavailable`
+     * (`err.retryable` true: nothing was started; send it again); the SDK does not retry it.
      */
     waitForOperation(operationId: string, opts?: WaitOptions): Promise<Operation>;
     /** One operation (GET /v1/operations/{id}); lifecycle operations stay pollable after a workspace is deleted. */
@@ -323,7 +323,7 @@ export declare class WorkspacesApi {
     suspend(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
+     * `wait` (0.9.0) the request is held by the server until the workspace runs (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`
@@ -333,7 +333,7 @@ export declare class WorkspacesApi {
     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
+     * wait`), 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.
@@ -347,7 +347,7 @@ export declare class WorkspacesApi {
         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
+     * Suspends the workspace once it has been idle for `afterSeconds` (0.9.0): 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
@@ -357,7 +357,7 @@ export declare class WorkspacesApi {
      * 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.
+     * `workspace_deleted`; 422 `validation_failed` for `afterSeconds` outside 0..3600.
      *
      *   await cloud.workspaces.suspendWhenIdle(workspace.id, { afterSeconds: 60 });
      */
@@ -369,7 +369,7 @@ export declare class WorkspacesApi {
      */
     cancelSuspendWhenIdle(workspaceId: string): Promise<Workspace>;
     /**
-     * Ends a session workspace now (contracts §19.11): the workspace is deleted exactly like delete() (ended_reason
+     * Ends a session workspace now: 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.
      * Idempotent. A persistent workspace is ShardfluxApiError 409 (details.reason `not_session`): use
      * `workspace.close()`, which calls this only for sessions. With `wait`, resolves once the delete has finished.
@@ -382,7 +382,7 @@ export declare class WorkspacesApi {
         workspace: WorkspaceView;
     }>;
     /**
-     * Resets a layered workspace to its template (contracts §19.12): every change in the workspace layer is wiped; key,
+     * Resets a layered workspace to its template: every change in the workspace layer is wiped; key,
      * id, template version, caps, secret bindings and volume attachments stay. Running: restarted on a blank layer
      * (processes are gone; old tool tokens get 409 stale_epoch and the SDK refreshes them). Suspended: stays suspended and
      * boots blank on the next resume. Returns the `reset` operation; its result names the recovery checkpoint (restorable
@@ -391,7 +391,7 @@ export declare class WorkspacesApi {
     reset(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     reset(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
     /**
-     * Saves a layered workspace as the next version of an organization template (contracts §19.8). A running workspace is
+     * Saves a layered workspace as the next version of an organization template. A running workspace is
      * captured briefly (`operation`, layer_snapshot); poll `build` with templates.builds.waitForBuild. Owners/admins and
      * API keys with a tool permission only.
      */
@@ -409,7 +409,7 @@ export declare class WorkspacesApi {
         operation: Operation;
         workspace: Workspace;
     }>;
-    /** The workspace's text inputs `{NAME: value}` (0.7.0; contracts §24.3). Secret inputs are bound secrets, never listed. */
+    /** The workspace's text inputs `{NAME: value}` (0.7.0). Secret inputs are bound secrets, never listed. */
     inputs(workspaceId: string): Promise<Record<string, string>>;
     operations(workspaceId: string, params?: {
         limit?: number;
@@ -454,17 +454,17 @@ export declare class Shardflux {
     readonly egress: EgressPolicyApi;
     /** Organization audit trail (owner/admin; API keys are refused with 403). */
     readonly audit: AuditApi;
-    /** Shared volumes: persistent storage attached to workspaces at a mount path (contracts §15). */
+    /** Shared volumes: persistent storage attached to workspaces at a mount path. */
     readonly volumes: VolumesApi;
     constructor(opts: ShardfluxOptions);
     /** 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 }`
+     * Send feedback straight to the Shardflux team (0.9.0+; POST /v1/feedback), who read every message. Use it while you
+     * work, the moment something fails unexpectedly, an error or doc is unclear, an option is missing, or a workaround was
+     * needed, and when your user asks for a capability, an option or a smoother workflow; short and specific beats
+     * polished, and `context.requestId` / `errorCode` let the team 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.
      */

package/dist/client.js

@@ -13,7 +13,7 @@ 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
+ * The workspace a key names: 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
  * deleted persistent key keeps its tombstone). Null when no row has exactly this key. Rows need not be sorted.
  */
@@ -61,7 +61,7 @@ function abortableSleep(sleep, ms, signal) {
 }
 export class WorkspacesApi {
     #ctx;
-    /** The cell endpoint of the last tool token seen: an open pre-connects to it while the server works (contracts §22.3). */
+    /** The cell endpoint of the last tool token seen: an open pre-connects to it while the server works. */
     #cellHint = null;
     constructor(ctx) {
         this.#ctx = ctx;
@@ -108,7 +108,7 @@ export class WorkspacesApi {
             const started = Date.now();
             const timeoutMs = waitOpts?.timeoutMs ?? 300_000;
             if (waitOpts && waitOpts.serverWait !== false) {
-                // Held open (contracts §22.3): the server answers once the operation is terminal (200 with the running workspace
+                // Held open: the server answers once the operation is terminal (200 with the running workspace
                 // and a tool token) or the wait elapsed (202); a server without it answers 202 at once and the poll below runs.
                 const s = Math.min(SERVER_WAIT_MAX_S, Math.floor(timeoutMs / 1000));
                 if (s >= 1) {
@@ -188,13 +188,13 @@ export class WorkspacesApi {
     }
     /**
      * Waits for an operation: each GET /v1/operations/{id} asks the server to hold the response until the state changes
-     * (`Prefer: wait`, at most 20 s, contracts §3), so completion is seen within one notification of the commit. A server
+     * (`Prefer: wait`, at most 20 s), so completion is seen within one notification of the commit. A server
      * that does not wait is polled with bounded exponential backoff (+-20 % jitter). Resolves when the operation
      * succeeds; throws OperationFailedError when it fails or is canceled, OperationTimeoutError after `timeoutMs` (the
      * operation keeps running and can be awaited again). Both errors carry the wait's `timing`; `onProgress` sees each
-     * state change (queued, capacity_pending, running, with the server's reason) as it is observed. A start waiting in
-     * capacity_pending gives up at its deadline (`deadlineAt` on the phase event) and fails with `capacity_unavailable`
-     * (`err.retryable` true: nothing was started, retry later); the SDK does not retry it.
+     * state change (queued, capacity_pending, running, with the server's reason) as it is observed. A start in
+     * capacity_pending that passes its deadline (`deadlineAt` on the phase event) fails with `capacity_unavailable`
+     * (`err.retryable` true: nothing was started; send it again); the SDK does not retry it.
      */
     async waitForOperation(operationId, opts = {}) {
         const inherited = opts[TRACE];
@@ -379,7 +379,7 @@ export class WorkspacesApi {
     }
     /**
      * 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
+     * wait`), 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.
@@ -419,7 +419,7 @@ export class WorkspacesApi {
         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
+     * Suspends the workspace once it has been idle for `afterSeconds` (0.9.0): 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
@@ -429,7 +429,7 @@ export class WorkspacesApi {
      * 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.
+     * `workspace_deleted`; 422 `validation_failed` for `afterSeconds` outside 0..3600.
      *
      *   await cloud.workspaces.suspendWhenIdle(workspace.id, { afterSeconds: 60 });
      */
@@ -465,7 +465,7 @@ export class WorkspacesApi {
         return this.#op('reset', workspaceId, body, opts);
     }
     /**
-     * Saves a layered workspace as the next version of an organization template (contracts §19.8). A running workspace is
+     * Saves a layered workspace as the next version of an organization template. A running workspace is
      * captured briefly (`operation`, layer_snapshot); poll `build` with templates.builds.waitForBuild. Owners/admins and
      * API keys with a tool permission only.
      */
@@ -488,7 +488,7 @@ export class WorkspacesApi {
         }, { settle: true });
         return { operation, workspace: copy };
     }
-    /** The workspace's text inputs `{NAME: value}` (0.7.0; contracts §24.3). Secret inputs are bound secrets, never listed. */
+    /** The workspace's text inputs `{NAME: value}` (0.7.0). Secret inputs are bound secrets, never listed. */
     async inputs(workspaceId) {
         const body = await this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}/inputs`, {}, this.#auth);
         return body.inputs;
@@ -546,7 +546,7 @@ export class Shardflux {
     egress;
     /** Organization audit trail (owner/admin; API keys are refused with 403). */
     audit;
-    /** Shared volumes: persistent storage attached to workspaces at a mount path (contracts §15). */
+    /** Shared volumes: persistent storage attached to workspaces at a mount path. */
     volumes;
     #ctx;
     constructor(opts) {
@@ -583,10 +583,10 @@ export class Shardflux {
         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 }`
+     * Send feedback straight to the Shardflux team (0.9.0+; POST /v1/feedback), who read every message. Use it while you
+     * work, the moment something fails unexpectedly, an error or doc is unclear, an option is missing, or a workaround was
+     * needed, and when your user asks for a capability, an option or a smoother workflow; short and specific beats
+     * polished, and `context.requestId` / `errorCode` let the team 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.
      */

package/dist/egress.d.ts

@@ -50,7 +50,7 @@ export interface EgressPolicyVersion {
     created_at: string;
 }
 export interface EffectiveEgressPolicy {
-    /** organization: an organization egress override (contracts §18) wins over every policy (mode deny_all, no version). */
+    /** organization: an organization egress override wins over every policy (mode deny_all, no version). */
     source: 'organization' | 'workspace' | 'project' | 'platform_default';
     policy_version_id: string | null;
     policy_version: number | null;
@@ -60,7 +60,7 @@ export interface EffectiveEgressPolicy {
     policy_sha256: string;
 }
 /**
- * Active organization egress override (contracts §18): the organization used its whole outbound transfer allowance,
+ * Active organization egress override: the organization used its whole outbound transfer allowance,
  * so outbound internet traffic of every workspace is blocked until `lifts_at` (period end) or an upgrade/purchase.
  * Stored policies are kept and apply again when it lifts.
  */
@@ -123,7 +123,7 @@ export interface WorkspaceEgressPolicy {
     organization_override: OrganizationEgressOverride | null;
     enforcement: EgressEnforcement;
     /**
-     * The template version's network ceiling (0.7.0; contracts §24.3 `defaults.egress`), or null. The host enforces
+     * The template version's network ceiling (0.7.0 `defaults.egress`), or null. The host enforces
      * `effective` intersected with it; a workspace policy it would narrow is refused with 422 egress_widening.
      */
     template_egress: {