@shardflux/sdk 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 Every API the README shows is available from the version named here. Breaking changes ship in minor releases and are
 marked **Breaking**.
 
+## 0.12.0 (release candidate)
+
+Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
+
+Pooled HTTP/1.1 on Node 26 with pinned undici 8.10.2; custom fetch stays unchanged. Labels on open/list and setLabels, typed idle(), keepalive() and setIdlePolicy(). Protocol errors carry source; isWorkspaceGone recognizes only an explicit API workspace_deleted refusal. Exec sessions accept stdin_open and offset-addressed exec.input. Failed workspaces recover through resume/auto-wake with the same ID. Completed deletions free keys for new IDs.
+
+Requires the QM integration backend release for labels, failed recovery, key reuse and pipe stdin. No production deployment has occurred from this branch.
+
+### Instant suspend: durable storage in the result
+
+Additive. A suspend returns as soon as the workspace is sealed on its host; the copy lands in durable storage right
+after. This release reads that from the result and can wait for it.
+
+- `suspend({ durable: true })` (`SuspendOptions.durable`, also `cloud.workspaces.suspend(id, { durable: true })`):
+  resolves once `result.durable` is `true`. It implies `wait` and uses the same `timeoutMs`/`signal` (one budget for
+  the suspend and the copy). Rejects with `DurabilityLostError` (new; `durability` with the reason) when the copy
+  cannot be made, and `OperationTimeoutError` with `durable: true` when the time runs out (the copy continues).
+  `suspend({ wait: true })` still resolves when the suspend succeeds, without waiting for the copy.
+- `cloud.workspaces.waitForDurable(operationOrId, waitOptions)`: the same wait for an operation you hold (a suspend, or
+  a fork of a running workspace).
+- `isDurable(op)`, `durabilityOf(op)` (`Durability`: `state` `pending` | `durable` | `lost`, `checkpointId`,
+  `generationId`, `localCommitAt`, `durableBy`, `durableAt`, `localCommitToDurableMs`, `overdueAt`, `reason`) and
+  `lostSuspendOf(op)` (`LostSuspend`, on a resume result). `ServerTiming` gains `durable`, `suspendPath`, `durability`
+  and `lostSuspend`; progress phase `durable` (reason `overdue` past `durableBy`); `formatTiming()` prints them.
+- `Operation.result` is typed with `durable`, `suspend_path`, `durability` and `lost_suspend` (OpenAPI).
+- `OperationFailedError.workspaceActive`: a suspend-when-idle canceled with `workspace_active` (the workspace was in
+  use; nothing changed and it keeps running). `workspace.waitUntilReady()` resolves for it instead of throwing, as
+  `wake()` already did.
+
+Requires the instant-suspend cell release for `durable: false` results; against other servers every succeeded suspend
+is already durable and `durable: true` resolves at once.
+
 ## 0.11.1
 
 Wording: messages and JSDoc say what to do, without internals (no behaviour change).

package/README.md

@@ -14,7 +14,7 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 > **(0.7.0+)** not in 0.6.x and **(0.6.0+)** not in 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
 > `npm ls @shardflux/sdk` or the exported `SDK_VERSION`.
 
-- ESM only, no runtime dependencies, Node.js 24 or later. Reading a YAML template file uses the optional peer
+- ESM only, Node.js 24 or later. Reading a YAML template file uses the optional peer
   dependency `yaml` (`npm install yaml`); JSON template files need nothing.
 - Typed from the published OpenAPI documents.
 - Retries, idempotency keys, operation polling and tool-token refresh are handled for you.
@@ -187,7 +187,7 @@ await workspace.resume({ wait: true });       // or simply open() the key again
 
 const { workspace: copy } = await workspace.fork({ key: 'customer-42/experiment' }, { wait: true });
 
-await copy.delete();                          // tool access ends immediately; keys are never reused
+await copy.delete();                          // tool access ends immediately; the key can be reused after deletion finishes
 ```
 
 ### Requested or finished
@@ -199,12 +199,34 @@ means depends on `wait`:
 | --- | --- | --- |
 | `await workspace.suspend()` | the suspend is **requested** (usually `queued`; the workspace is still running) | the operation (`Operation`) |
 | `await workspace.suspend({ wait: true })` **(0.6.0+)** | the suspend has **finished** (`workspace.state` is then `suspended`) | the succeeded operation (`FinishedOperation`) |
+| `await workspace.suspend({ durable: true })` **(0.12.0+)** | the suspend has finished **and** its copy is in durable storage (`result.durable` is `true`) | the succeeded operation (`FinishedOperation`) |
 
 `wait` also takes `WaitOptions` (`timeoutMs`, default 5 minutes; `signal`; `onProgress`). A failed operation throws
 `OperationFailedError`. Running out of time throws `OperationTimeoutError`, and the operation continues server side:
 wait again with `cloud.workspaces.waitForOperation(err.operationId)`. Without `wait`, the returned operation is the
 handle for the work in progress: pass its `id` to `waitForOperation()` when you need it finished.
 
+**Durable storage (0.12.0+).** A suspend returns as soon as the workspace is sealed on its host, typically in a few
+hundred ms, and its RAM and CPU are released at that moment. `result.durable` turns `true` when the copy lands in
+durable storage, typically within a second; until then it is `false` and `result.durability` shows the copy's
+progress. Most code needs nothing more: a suspended workspace resumes, is read and is forked the same way either way.
+When your code must know the copy is durable (before deleting a local artifact, or at the end of a job), ask for it:
+
+```ts
+import { durabilityOf } from '@shardflux/sdk';
+
+const op = await workspace.suspend({ durable: true }); // resolves once result.durable is true
+durabilityOf(op);   // { state: 'durable', checkpointId, localCommitAt, durableAt, localCommitToDurableMs, ... }
+```
+
+- `durable: true` implies `wait` and shares its `timeoutMs` and `signal` (e.g. `{ durable: true, wait: { timeoutMs: 60_000 } }`).
+  If the time runs out first, `OperationTimeoutError` has `durable: true` and the copy continues server side.
+- `cloud.workspaces.waitForDurable(operationOrId)` does the same for an operation you already hold, such as a
+  finished fork of a running workspace, whose result carries `durable` and `durability` the same way.
+- `isDurable(op)`, `durabilityOf(op)` and `lastTiming.server.durable` / `.durability` read the fields; `formatTiming()`
+  prints `sealed on host, durable 435 ms later`. Results from before 0.12.0 servers count as durable.
+- The errors reference on docs.shardflux.dev lists what `durable: true` can reject with.
+
 **Start deadlines.** A queued open, resume, restore or fork (`capacity_pending`) has a deadline 15 minutes after it
 was created. Its `error.details.deadline_at` carries the deadline; the `phase` progress event carries it as
 `deadlineAt` **(0.6.2+)**, and so does `OperationTimeoutError` when your wait ends first. A start still pending at the
@@ -295,8 +317,7 @@ operation keeps running server side (a queued start until its `deadlineAt`); wai
 same call. `templates.builds.waitForBuild()` waits the same way. A waited `open()` issues the first tool token
 together with the final workspace read, so the first tool call starts at once.
 
-On Node 26 the default fetch uses a fresh connection for every request (`Connection: close`);
-`SHARDFLUX_HTTP_KEEPALIVE=1`, or your own `fetch`, reuses connections.
+From 0.12.0, Node 26 reuses TLS connections through a private HTTP/1.1 pool. Other runtimes keep native fetch. A supplied `fetch` stays unchanged. `SHARDFLUX_HTTP_KEEPALIVE=0` forces connection closure for diagnosis; `=1` opts into native pooling. No global dispatcher is installed.
 
 List and look up workspaces:
 
@@ -941,3 +962,44 @@ or no longer supported, it emits one warning:
 ## License
 
 Apache-2.0
+
+
+## Workspace integrations (0.12.0+)
+
+```ts
+const ws = await cloud.workspaces.open({ key: 'qm/project-42', template: 'python-node-browser',
+  labels: { scope: 'project-42', owner: 'qm' }, idlePolicy: 'never' });
+const matches = await cloud.workspaces.list({ labels: { scope: 'project-42' } });
+await ws.setLabels({ scope: 'project-42', owner: 'qm' }); // replaces all labels; {} clears
+await ws.setIdlePolicy('adaptive'); // null restores the inherited policy
+const idle = await ws.idle(); // read-only, does not wake or record activity
+await ws.keepalive(60); // seconds; never shortens an existing keepalive
+await ws.suspendWhenIdle({ afterSeconds: 2 }); // one safe server-side request; no /idle + suspend race
+```
+
+Labels are exact string pairs (at most 50, keys 1–64 and values 0–256 characters); they are metadata, not secrets.
+A failed workspace is recoverable: `await ws.wake()` and ordinary auto-waking calls restart that ID using its existing disk. They do not create a replacement workspace. A failed attempt still raises its operation error; there is no unbounded restart loop.
+After `await ws.delete({ wait: true })`, opening its key creates a **new ID**. The old ID, tokens and history remain deleted. A key stays reserved while deletion is in progress.
+
+For a background command with a pipe (no PTY):
+
+```ts
+const cell = ws.cell();
+const session = await cell.exec.start({ session_id: 'qm-worker-1', argv: ['cat'], stdin_open: true });
+let ack = await cell.exec.input(session.session_id, 'hello\n', { offset: 0 });
+ack = await cell.exec.input(session.session_id, '', { offset: ack.offset, close: true });
+```
+
+Input frames are at most 64 KiB. The acknowledged offset counts bytes accepted into the pipe, not bytes consumed by the program. A blocked writer may receive a partial acknowledgement; continue from the returned offset. Retrying the identical last frame is safe. `close` sends EOF only once the entire frame is accepted. Do not combine `stdin_open` with the existing one-shot `stdin` option. The transport writes no separate input log or payload file; program output and full-state snapshots retain their normal persistence. Full-state suspend preserves the pipe. Older hosts/guests explicitly refuse this feature until upgraded (`exec_stdin` / `exec_stdin.v1`). Running sessions count as work within the documented idle-command window; long-running services should declare keepalives or choose `never`.
+
+```ts
+import { isWorkspaceGone, ShardfluxProtocolError } from '@shardflux/sdk';
+// isWorkspaceGone(error) is true only for an explicit API workspace_deleted refusal.
+// A protocol error, a cell 404, a scoped API 404 or a network failure is never deletion evidence.
+```
+
+`ShardfluxProtocolError.source` is `api` or `cell` for SDK responses (`unknown` only for an error constructed without a source by older caller code). It remains a protocol failure even when `status === 404`. Never delete local data based on an HTTP status alone.
+
+### Repositories with a minimum release age
+
+Keep your repository's age policy. Pin an exact version that has aged enough; do not exempt the entire `@shardflux/*` scope. The first SDK, 0.5.0, was published September 26, 2026 at 21:13:52 UTC and reaches seven days on October 3 at that time. New versions, including 0.12.0, need their own seven days after publication. Before then no registry setting on our side can make them eligible. `npm view @shardflux/sdk time --json` shows publication times. A targeted exception for an inspected exact release is a repository-owner decision, not an installation requirement we bypass. Older versions do not contain this release's fixes.

package/dist/account.d.ts

@@ -102,7 +102,7 @@ export interface ShardfluxAccountOptions {
     sessionToken?: string;
     /** Default https://api.shardflux.dev. */
     baseUrl?: string;
-    /** Default: the runtime's fetch, with `Connection: close` on Node 26 (see defaultFetch in http.ts). */
+    /** Default: pooled HTTP/1.1 on Node 26+, native fetch on other runtimes (see defaultFetch in http.ts). */
     fetch?: typeof fetch;
     userAgent?: string;
     /** Per-request timeout (ms), default 30 s. */

package/dist/account.js

@@ -571,7 +571,7 @@ export class ShardfluxAccount {
         const b = body;
         if (b && typeof b === 'object' && typeof b.session_token === 'string') {
             if (!isSessionToken(b.session_token))
-                throw new ShardfluxProtocolError('the API returned a session_token that is not a CLI session token (sfu_...)', 200);
+                throw new ShardfluxProtocolError('the API returned a session_token that is not a CLI session token (sfu_...)', 200, 'api');
             this.#token = b.session_token;
             const expiresAt = typeof b.session_expires_at === 'string' ? b.session_expires_at : '';
             await this.#onSessionToken?.({ token: b.session_token, expiresAt });

package/dist/cell.d.ts

@@ -31,6 +31,7 @@ import type { ToolTokenManager } from './tokens.js';
 type S = components['schemas'];
 export type ExecStartRequest = S['ExecStartRequest'];
 export type ExecSession = S['ExecSession'];
+export type ExecInputResult = S['ExecInputResult'];
 export type OutputEvent = S['OutputEvent'];
 export type PtyOpenRequest = S['PtyOpenRequest'];
 export type PtySession = S['PtySession'];
@@ -50,6 +51,8 @@ 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'];
+export type IdleStatus = S['IdleStatus'];
+export type KeepaliveResult = S['KeepaliveResult'];
 /** 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. */
@@ -296,6 +299,14 @@ export declare class CellClient {
             follow?: boolean;
             signal?: AbortSignal;
         }) => Promise<AsyncGenerator<OutputEvent>>;
+        /** Write at the acknowledged offset (initially 0); a repeated identical last frame cannot duplicate input.
+         * At most 64 KiB per call. A partial acknowledgement requires continuing from the returned offset.
+         * Start with stdin_open: true. close sends EOF after this frame is fully accepted. */
+        input: (sessionId: string, data: string | Uint8Array, opts: {
+            offset: number;
+            close?: boolean;
+            signal?: AbortSignal;
+        }) => Promise<ExecInputResult>;
         signal: (sessionId: string, signal: Signal, onlyLeader?: boolean) => Promise<ExecSession>;
         cancel: (sessionId: string, graceMs?: number) => Promise<ExecSession>;
         /**
@@ -442,6 +453,10 @@ export declare class CellClient {
      * workspace answers 409 `workspace_not_running` (`Workspace.hint()` then wakes it in the background).
      */
     wakeHint(signal?: AbortSignal): Promise<WakeHintResult>;
+    /** Read idle signals without recording activity or waking the workspace. */
+    idle(signal?: AbortSignal): Promise<IdleStatus>;
+    /** Declare work for seconds (1..the server maximum). Never shortens a previous keepalive. */
+    keepalive(seconds: number, signal?: AbortSignal): Promise<KeepaliveResult>;
     /**
      * 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/cell.js

@@ -89,7 +89,7 @@ async function parseJson(res, what) {
         return JSON.parse(text);
     }
     catch {
-        throw new ShardfluxProtocolError(`${what}: response is not JSON`, res.status);
+        throw new ShardfluxProtocolError(`${what}: response is not JSON`, res.status, 'cell');
     }
 }
 /** Delay before a retry of an execution: Retry-After (at most 30 s), else 0.5 s doubling to 8 s. */
@@ -282,7 +282,7 @@ export class CellClient {
             return (text.length === 0 ? undefined : JSON.parse(text));
         }
         catch {
-            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status, 'cell');
         }
     }
     async #bytes(method, path, init = {}) {
@@ -329,9 +329,20 @@ export class CellClient {
                 ...(opts.signal ? { signal: opts.signal } : {}),
             });
             if (!res.body)
-                throw new ShardfluxProtocolError('exec output: empty body', res.status);
+                throw new ShardfluxProtocolError('exec output: empty body', res.status, 'cell');
             return ndjson(res.body);
         },
+        /** Write at the acknowledged offset (initially 0); a repeated identical last frame cannot duplicate input.
+         * At most 64 KiB per call. A partial acknowledgement requires continuing from the returned offset.
+         * Start with stdin_open: true. close sends EOF after this frame is fully accepted. */
+        input: (sessionId, data, opts) => {
+            const refusal = this.#noSessions('exec.input');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/stdin', { session_id: sessionId }), {
+                json: { data: b64(data), offset: opts.offset, close: opts.close ?? false }, ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+        },
         signal: (sessionId, signal, onlyLeader = false) => {
             const refusal = this.#noSessions('exec.signal');
             if (refusal)
@@ -404,9 +415,14 @@ export class CellClient {
         const maxReconnects = opts.maxReconnects ?? 10;
         for (;;) {
             let exited;
+            const streamAbort = new AbortController();
+            const signal = opts.signal ? AbortSignal.any([opts.signal, streamAbort.signal]) : streamAbort.signal;
+            let drainTimer;
             try {
-                const events = await this.exec.output(sessionId, { stdoutOffset: so, stderrOffset: se, follow: true, ...(opts.signal ? { signal: opts.signal } : {}) });
+                const events = await this.exec.output(sessionId, { stdoutOffset: so, stderrOffset: se, follow: true, signal });
                 for await (const ev of events) {
+                    if (exited)
+                        continue;
                     if (ev.type === 'output' && ev.data !== undefined) {
                         const bytes = unb64(ev.data);
                         const start = ev.offset ?? (ev.stream === 'stderr' ? se : so);
@@ -426,7 +442,9 @@ export class CellClient {
                     }
                     else if (ev.type === 'exit') {
                         exited = ev.session ?? (await this.exec.get(sessionId));
-                        break;
+                        // Consume the terminal HTTP framing so the connection can be reused.
+                        // A peer that never closes after exit must not hold the completed run forever.
+                        drainTimer = setTimeout(() => streamAbort.abort(), 250);
                     }
                     else if (ev.type === 'error' && ev.error) {
                         throw new ShardfluxApiError(502, ev.error, 'cell');
@@ -437,9 +455,12 @@ export class CellClient {
                 if (opts.signal?.aborted || this.closed)
                     throw e;
                 const transient = !(e instanceof ShardfluxApiError) || e.retryable;
-                if (!transient || reconnects >= maxReconnects)
+                if (!exited && (!transient || reconnects >= maxReconnects))
                     throw e;
             }
+            finally {
+                clearTimeout(drainTimer);
+            }
             if (exited) {
                 session = exited;
                 break;
@@ -449,7 +470,7 @@ export class CellClient {
                 throw this.#closer.signal.reason;
             reconnects += 1;
             if (reconnects > maxReconnects)
-                throw new ShardfluxProtocolError(`exec ${sessionId}: output stream kept dropping`, 0);
+                throw new ShardfluxProtocolError(`exec ${sessionId}: output stream kept dropping`, 0, 'cell');
             await this.#opts.sleep(Math.min(2_000, 100 * 2 ** reconnects));
             const now = await this.exec.get(sessionId);
             if (now.state !== 'starting' && now.state !== 'running' && so >= now.stdout_size && se >= now.stderr_size) {
@@ -708,7 +729,7 @@ export class CellClient {
                         finish(new ShardfluxApiError(502, m.error, 'cell'));
                     }
                 });
-                ws.addEventListener('error', () => finish(new ShardfluxProtocolError('pty attach WebSocket failed', 0)));
+                ws.addEventListener('error', () => finish(new ShardfluxProtocolError('pty attach WebSocket failed', 0, 'cell')));
                 ws.addEventListener('close', () => finish());
                 if (this.closed)
                     onClose();
@@ -875,6 +896,14 @@ export class CellClient {
             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 } : {}) });
     }
+    /** Read idle signals without recording activity or waking the workspace. */
+    idle(signal) {
+        return this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/idle'), { wake: false, ...(signal ? { signal } : {}) });
+    }
+    /** Declare work for seconds (1..the server maximum). Never shortens a previous keepalive. */
+    keepalive(seconds, signal) {
+        return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/keepalive'), { json: { seconds }, wake: false, ...(signal ? { signal } : {}) });
+    }
     // ---- changes against the template (layered workspaces) ------------------
     /**
      * One page of the workspace's changes against its template (needs the `files` tool). File-first workspaces: each

package/dist/client.d.ts

@@ -22,7 +22,7 @@ import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.j
 import { UsageApi } from './usage.js';
 import { VolumesApi } from './volumes.js';
 import type { VersionCheckOption } from './version-check.js';
-import type { FinishedOperation, InternalLifecycleOptions, LifecycleOptions, ResumeOptions, WaitedLifecycleOptions, WaitedResumeOptions } from './lifecycle.js';
+import type { FinishedOperation, InternalLifecycleOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 import type { ProgressListener } from './progress.js';
 import { CaptureRegistry } from './capture.js';
 import type { FeedbackReceipt, SendFeedbackParams } from './feedback.js';
@@ -121,7 +121,7 @@ export interface ShardfluxOptions {
     apiKey: string;
     /** Default https://api.shardflux.dev (override with `baseUrl`). */
     baseUrl?: string;
-    /** Default: the runtime's fetch; on Node 26 every request uses a fresh connection (`Connection: close`) unless SHARDFLUX_HTTP_KEEPALIVE=1. */
+    /** Default: pooled HTTP/1.1 on Node 26+, native fetch on other runtimes (see defaultFetch in http.ts). */
     fetch?: typeof fetch;
     userAgent?: string;
     /** Per-request timeout (ms), default 30 s. */
@@ -172,7 +172,11 @@ export interface WaitOptions {
     /** Progress while waiting: each observed state (queued, capacity_pending, running with its reason), retries, and `done` with the timing. */
     onProgress?: ProgressListener;
 }
+export type IdlePolicy = 'adaptive' | 'never' | `fixed:${number}`;
 export interface OpenParams {
+    /** Searchable metadata; supplied labels replace the existing map. */
+    labels?: Record<string, string>;
+    idlePolicy?: IdlePolicy;
     key: string;
     template: string;
     caps?: Caps;
@@ -225,6 +229,8 @@ export interface OpenParams {
     onProgress?: ProgressListener;
 }
 export interface ListParams {
+    /** All supplied labels must match exactly. */
+    labels?: Record<string, string>;
     state?: WorkspaceView['observed_state'];
     desiredState?: WorkspaceView['desired_state'];
     keyPrefix?: string;
@@ -292,6 +298,15 @@ export declare class WorkspacesApi {
      * (`err.retryable` true: nothing was started; send it again); the SDK does not retry it.
      */
     waitForOperation(operationId: string, opts?: WaitOptions): Promise<Operation>;
+    /**
+     * Waits for the durable copy of a succeeded suspend or fork (0.12.0+): resolves with the operation once
+     * `result.durable` is true, typically within a second of the suspend. An operation already durable (or one whose result
+     * predates the field) resolves at once without a request. Polls GET /v1/operations/{id} (`pollIntervalMs`, default
+     * 250 ms, doubling up to `maxPollIntervalMs`, default 1 000 ms). Throws DurabilityLostError when the copy cannot be
+     * made (`durability.state` `lost`), OperationFailedError if the operation did not succeed, and OperationTimeoutError
+     * (`durable: true`) after `timeoutMs` (default 300 000 ms; the copy continues server side). `signal` aborts the wait.
+     */
+    waitForDurable(operation: string | Operation, opts?: WaitOptions): Promise<FinishedOperation>;
     /** One operation (GET /v1/operations/{id}); lifecycle operations stay pollable after a workspace is deleted. */
     getOperation(operationId: string, opts?: {
         signal?: AbortSignal;
@@ -300,6 +315,10 @@ export declare class WorkspacesApi {
         agentLabel?: string;
         tools?: ToolName[];
     }): Promise<Workspace>;
+    /** Replace labels. An empty map clears them. */
+    setLabels(workspaceId: string, labels: Record<string, string>): Promise<Workspace>;
+    /** null clears the override, restoring the template or platform policy. */
+    setIdlePolicy(workspaceId: string, idlePolicy: IdlePolicy | null): Promise<Workspace>;
     list(params?: ListParams): Promise<Page<Workspace>>;
     /** Iterates every page. */
     listAll(params?: Omit<ListParams, 'cursor'>): AsyncGenerator<Workspace>;
@@ -317,10 +336,12 @@ export declare class WorkspacesApi {
     delete(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
     /**
      * Suspends the workspace (memory and processes checkpointed). Resolves when the suspend is REQUESTED: the returned
-     * operation is usually still `queued`. Pass `{ wait: true }` to resolve once it has FINISHED (`succeeded`).
+     * operation is usually still `queued`. Pass `{ wait: true }` to resolve once it has FINISHED (`succeeded`): the
+     * workspace is sealed on its host, typically in a few hundred ms, and `result.durable` turns true when the copy lands
+     * in durable storage, typically within a second. `{ durable: true }` (0.12.0+) resolves only then (see SuspendOptions).
      */
-    suspend(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
-    suspend(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
+    suspend(workspaceId: string, opts: WaitedSuspendOptions): Promise<FinishedOperation>;
+    suspend(workspaceId: string, opts?: SuspendOptions): 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 (one request, timing phase

package/dist/client.js

@@ -1,4 +1,4 @@
-import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { DurabilityLostError, 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";
@@ -9,7 +9,7 @@ import { UsageApi } from "./usage.js";
 import { VolumesApi } from "./volumes.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 { Trace, combineListeners, durabilityOf, isDurable, traced } from "./progress.js";
 import { CaptureRegistry } from "./capture.js";
 import { sendFeedback } from "./feedback.js";
 /**
@@ -96,6 +96,10 @@ export class WorkspacesApi {
             body.secrets = params.secrets;
         if (params.inputs !== undefined)
             body.inputs = params.inputs;
+        if (params.labels !== undefined)
+            body.labels = params.labels;
+        if (params.idlePolicy !== undefined)
+            body.idle_policy = params.idlePolicy;
         if (params.lifetime !== undefined)
             body.lifetime = params.lifetime;
         if (params.mode !== undefined)
@@ -246,6 +250,61 @@ export class WorkspacesApi {
             interval = Math.min(maxInterval, interval * 2);
         }
     }
+    /**
+     * Waits for the durable copy of a succeeded suspend or fork (0.12.0+): resolves with the operation once
+     * `result.durable` is true, typically within a second of the suspend. An operation already durable (or one whose result
+     * predates the field) resolves at once without a request. Polls GET /v1/operations/{id} (`pollIntervalMs`, default
+     * 250 ms, doubling up to `maxPollIntervalMs`, default 1 000 ms). Throws DurabilityLostError when the copy cannot be
+     * made (`durability.state` `lost`), OperationFailedError if the operation did not succeed, and OperationTimeoutError
+     * (`durable: true`) after `timeoutMs` (default 300 000 ms; the copy continues server side). `signal` aborts the wait.
+     */
+    async waitForDurable(operation, opts = {}) {
+        const inherited = opts[TRACE];
+        const id = typeof operation === 'string' ? operation : operation.id;
+        const trace = inherited ?? new Trace('wait', combineListeners(this.#ctx().onProgress, opts.onProgress), { operationId: id });
+        const run = async () => {
+            const { sleep, http } = this.#ctx();
+            const timeoutMs = opts.timeoutMs ?? 300_000;
+            const maxInterval = opts.maxPollIntervalMs ?? 1_000;
+            let interval = opts.pollIntervalMs ?? 250;
+            const started = Date.now();
+            const aborted = () => (opts.signal?.reason instanceof Error ? opts.signal.reason : new Error('aborted'));
+            let op = typeof operation === 'string' ? null : operation;
+            for (;;) {
+                if (opts.signal?.aborted)
+                    throw aborted();
+                if (op === null) {
+                    const { body } = await pollWithWait(http, `/v1/operations/${encodeURIComponent(id)}`, this.#ctx().authorization, 0, opts.signal, trace.onRetry);
+                    op = body.operation;
+                    trace.observe(op);
+                }
+                if (op.state !== 'succeeded') {
+                    if (TERMINAL.has(op.state))
+                        throw new OperationFailedError(op);
+                    // Not finished yet (a fork or suspend passed by id): wait for it first, then for its copy.
+                    op = await this.waitForOperation(id, { ...opts, timeoutMs: Math.max(1, timeoutMs - (Date.now() - started)), [TRACE]: trace });
+                }
+                if (isDurable(op) !== false)
+                    return op;
+                const durability = durabilityOf(op);
+                if (durability?.state === 'lost')
+                    throw new DurabilityLostError(op);
+                trace.phase('durable', durability?.overdueAt ? 'overdue' : null);
+                const waited = Date.now() - started;
+                if (waited >= timeoutMs)
+                    throw new OperationTimeoutError(op, waited, true);
+                const jitter = interval * 0.2 * (Math.random() * 2 - 1);
+                const delay = Math.max(10, Math.min(interval + jitter, timeoutMs - waited));
+                await (opts.signal ? abortableSleep(sleep, delay, opts.signal) : sleep(delay));
+                interval = Math.min(maxInterval, interval * 2);
+                op = null;
+            }
+        };
+        if (inherited)
+            return run();
+        trace.phase('request');
+        return traced(trace, run);
+    }
     /** One operation (GET /v1/operations/{id}); lifecycle operations stay pollable after a workspace is deleted. */
     async getOperation(operationId, opts = {}) {
         const { operation } = await this.#http.json('GET', `/v1/operations/${encodeURIComponent(operationId)}`, opts.signal ? { signal: opts.signal } : {}, this.#auth);
@@ -257,12 +316,21 @@ export class WorkspacesApi {
     async get(workspaceId, opts = {}) {
         return this.#wrap(await this.#getView(workspaceId), opts);
     }
+    /** Replace labels. An empty map clears them. */
+    async setLabels(workspaceId, labels) {
+        return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/labels`, { json: { labels } }, this.#auth));
+    }
+    /** null clears the override, restoring the template or platform policy. */
+    async setIdlePolicy(workspaceId, idlePolicy) {
+        return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/idle-policy`, { json: { idle_policy: idlePolicy } }, this.#auth));
+    }
     async list(params = {}) {
         const page = await this.#http.json('GET', '/v1/workspaces', {
             query: {
                 state: params.state,
                 desired_state: params.desiredState,
                 key_prefix: params.keyPrefix,
+                labels: params.labels === undefined ? undefined : JSON.stringify(params.labels),
                 project_id: params.projectId,
                 organization_id: params.organizationId,
                 include_deleted: params.includeDeleted,
@@ -406,11 +474,11 @@ export class WorkspacesApi {
         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);
+            throw new ShardfluxProtocolError('resume: response has no workspace', res.status, 'api');
         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);
+            throw new ShardfluxProtocolError('resume: response has no operation', res.status, 'api');
         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') };

package/dist/errors.d.ts

@@ -1,6 +1,6 @@
 import type { components as AppComponents } from './generated/app-api.js';
 import type { components as CellComponents } from './generated/cell-api.js';
-import type { LifecycleTiming } from './progress.js';
+import type { Durability, LifecycleTiming } from './progress.js';
 export type AppErrorBody = AppComponents['schemas']['ErrorBody'];
 export type AppErrorCode = AppErrorBody['error']['code'];
 export type CellErrorCode = CellComponents['schemas']['ErrorCode'];
@@ -141,8 +141,12 @@ export declare function apiError(status: number, body: ErrorBodyLike, source: 'a
 /** The response was not the documented shape (e.g. a proxy error page). */
 export declare class ShardfluxProtocolError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    /** The responding surface; unknown only for errors constructed by older callers. Never proof of deletion. */
+    readonly source: 'api' | 'cell' | 'unknown';
+    constructor(message: string, status: number, source?: 'api' | 'cell' | 'unknown');
 }
+/** True only for an explicit API tombstone refusal. A 404, even a structured one, may be routing or scope. */
+export declare function isWorkspaceGone(error: unknown): boolean;
 type Operation = AppComponents['schemas']['Operation'];
 /**
  * Waiting for an operation ran out of time. The operation keeps running server side:
@@ -163,13 +167,24 @@ export declare class OperationTimeoutError extends Error {
     readonly waitedMs: number;
     /** Where the time went: client phases, retries and the operation's own server timing so far. */
     timing: LifecycleTiming | undefined;
-    constructor(op: Operation, waitedMs: number);
+    /**
+     * `durable` (0.12.0+): the wait was for the durable copy of a succeeded suspend or fork (`suspend({ durable: true })`,
+     * `waitForDurable()`); `lastState` is then `succeeded` and the copy continues server side.
+     */
+    readonly durable: boolean;
+    constructor(op: Operation, waitedMs: number, durable?: boolean);
 }
-/** The operation reached `failed` or `canceled`. */
+/**
+ * The operation reached `failed` or `canceled`. A suspend-when-idle that found the workspace active (a tool call after
+ * the request, an attached stream) is `canceled` with `errorCode` `workspace_active` (`workspaceActive` true, 0.12.0+):
+ * nothing changed and the workspace keeps running. `waitUntilReady()` and `wake()` treat it as running, not as a failure.
+ */
 export declare class OperationFailedError extends Error {
     readonly operation: Operation;
     readonly operationId: string;
     readonly errorCode: string | null;
+    /** 0.12.0+: a suspend-when-idle canceled because the workspace was active; it keeps running, nothing changed. */
+    readonly workspaceActive: boolean;
     /**
      * `operation.error.retryable` (false when absent): the same request may succeed later. `capacity_unavailable` is
      * retryable: the start passed its deadline and nothing was started; send it again. The SDK never retries a failed
@@ -180,4 +195,18 @@ export declare class OperationFailedError extends Error {
     timing: LifecycleTiming | undefined;
     constructor(op: Operation);
 }
+/**
+ * `suspend({ durable: true })` or `waitForDurable()` (0.12.0+): the suspend (or fork) succeeded, but its durable copy
+ * could not be made (`durability.state` `lost`). `durability` has the reason; see the lifecycle reference for what the
+ * next resume restores.
+ */
+export declare class DurabilityLostError extends Error {
+    readonly operation: Operation;
+    readonly operationId: string;
+    readonly workspaceId: string | null;
+    readonly durability: Durability;
+    /** Where the time went. */
+    timing: LifecycleTiming | undefined;
+    constructor(op: Operation);
+}
 export {};