@shardflux/sdk 0.11.1 → 0.13.0

package/dist/cell.js

@@ -2,6 +2,9 @@ import { ExecStartError, NotSupportedForModeError, ShardfluxApiError, ShardfluxP
 import { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 import { HttpClient, defaultSleep, randomId, treeRevisionOf } from "./http.js";
 import { describeFailure, emitTo } from "./progress.js";
+/** Error codes of a burst's own failure: the burst's terminal outcome, never a dropped stream. */
+const BURST_FAILURES = new Set(['burst_unavailable', 'burst_apply_failed']);
+const TERMINAL = Symbol('shardflux.terminal');
 /** Fills a path template that must exist in cell-api.yaml. */
 export function cellPath(template, params) {
     return template.replace(/\{([a-z_]+)\}/g, (_, name) => {
@@ -19,6 +22,13 @@ export const DEFAULT_TRANSITION_TIMEOUT_MS = 120_000;
 export const CAPTURE_BARRIER = Symbol('shardflux.captureBarrier');
 /** Wakes per call at most: a workspace that keeps being suspended again surfaces the refusal. */
 const MAX_WAKES = 3;
+/** exec.cancel grace: the workspace waits 5 s without one and takes at most 60 s. */
+const DEFAULT_CANCEL_GRACE_MS = 5_000;
+const MAX_CANCEL_GRACE_MS = 60_000;
+/** The API error of a burst's recorded failure (`burst.error` of its session). Internal (the agent tools use it too). */
+export function burstFailure(e) {
+    return new ShardfluxApiError(409, { error: { code: e.code, message: e.message, request_id: '', retryable: e.retryable, ...(e.details ? { details: e.details } : {}) } }, 'cell');
+}
 const b64 = (bytes) => Buffer.from(typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : bytes).toString('base64');
 const unb64 = (s) => (s ? new Uint8Array(Buffer.from(s, 'base64')) : new Uint8Array());
 /** Parses an NDJSON byte stream into objects (tolerates CRLF and a final unterminated line). */
@@ -89,7 +99,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 +292,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,20 +339,38 @@ 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)
                 return Promise.reject(refusal);
             return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/signal', { session_id: sessionId }), { json: { signal, only_leader: onlyLeader } });
         },
+        /**
+         * SIGTERM to the process group, SIGKILL after `graceMs` (0 to 60000; 0 or omitted is 5000). Resolves once the
+         * command has ended; the request waits for the grace.
+         */
         cancel: (sessionId, graceMs) => {
             const refusal = this.#noSessions('exec.cancel');
             if (refusal)
                 return Promise.reject(refusal);
-            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/cancel', { session_id: sessionId }), { json: graceMs === undefined ? {} : { grace_ms: graceMs } });
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/cancel', { session_id: sessionId }), {
+                json: graceMs === undefined ? {} : { grace_ms: graceMs },
+                timeoutMs: Math.max(this.#opts.timeoutMs, (graceMs || DEFAULT_CANCEL_GRACE_MS) + 15_000),
+            });
         },
         /**
          * Starts (or re-attaches to) a session and collects its output until it exits, reconnecting
@@ -371,21 +399,53 @@ export class CellClient {
                 req.kill_grace_ms = opts.killGraceMs;
             if (opts.secretRefs !== undefined)
                 req.secret_refs = opts.secretRefs;
-            const started = await this.exec.start(req, opts.signal);
-            if (started.state === 'failed_to_start')
-                throw new ExecStartError(started);
+            if (opts.burst !== undefined)
+                req.burst = opts.burst;
+            if (opts.burstVcpus !== undefined)
+                req.burst_vcpus = opts.burstVcpus;
+            if (opts.burstMemoryMib !== undefined)
+                req.burst_memory_mib = opts.burstMemoryMib;
+            const burst = opts.burst === 'always';
+            // One request starts the command and follows its output (0.13.0+). Each attempt's response headers are bounded
+            // like the old start request; the output stream then runs as long as the command. `initialAbort` ends that
+            // stream once it is drained.
+            const initialAbort = new AbortController();
+            const signal = opts.signal ? AbortSignal.any([opts.signal, initialAbort.signal]) : initialAbort.signal;
+            const res = await this.request('POST', this.#p('/v1/workspaces/{workspace_id}/exec'), {
+                json: req, accept: 'application/x-ndjson', timeoutMs: 0, headersTimeoutMs: this.#opts.timeoutMs, signal,
+            });
+            const streamed = res.headers.get('content-type')?.includes('application/x-ndjson') === true;
+            let started;
+            if (!streamed) {
+                // A cell without the combined start, and a start that failed, answer with the session JSON: start, then output.
+                const text = await res.text();
+                try {
+                    started = JSON.parse(text);
+                }
+                catch {
+                    throw new ShardfluxProtocolError('POST exec: response is not JSON', res.status, 'cell');
+                }
+                if (started.state === 'failed_to_start')
+                    throw started.burst?.error ? burstFailure(started.burst.error) : new ExecStartError(started);
+            }
             try {
-                return await this.#collect(sessionId, opts);
+                const r = await this.#collect(sessionId, opts, streamed ? { response: res, abort: initialAbort } : undefined);
+                // The start's session carries the grow (a combined stream carries it on its exit event); later reads may not.
+                const grow = started?.memory_grow ?? r.session.memory_grow;
+                return grow ? { ...r, memoryGrow: grow } : r;
             }
             catch (e) {
                 // Aborting the caller must stop the command too, not only our HTTP calls (MCP cancellation, timeouts):
-                // best-effort cancel (SIGTERM, SIGKILL after the grace), bounded so the abort stays prompt.
-                if (opts.signal?.aborted && opts.cancelOnAbort !== false) {
+                // best-effort cancel (SIGTERM, SIGKILL after the grace), bounded so the abort stays prompt. A burst cannot be
+                // canceled (it runs to its end or its timeout).
+                if (opts.signal?.aborted && opts.cancelOnAbort !== false && !burst) {
                     let timer;
                     const bound = new Promise((resolve) => {
                         timer = setTimeout(resolve, 5_000);
                     });
-                    await Promise.race([this.exec.cancel(sessionId, opts.killGraceMs).then(() => undefined, () => undefined), bound]);
+                    // killGraceMs goes up to 600000; a cancel takes at most 60000.
+                    const grace = opts.killGraceMs === undefined ? undefined : Math.min(opts.killGraceMs, MAX_CANCEL_GRACE_MS);
+                    await Promise.race([this.exec.cancel(sessionId, grace).then(() => undefined, () => undefined), bound]);
                     clearTimeout(timer);
                 }
                 throw e;
@@ -393,7 +453,7 @@ export class CellClient {
         },
     };
     /** exec.run's output loop: offsets, reconnects, exit. */
-    async #collect(sessionId, opts) {
+    async #collect(sessionId, opts, initial) {
         let session;
         const max = opts.maxOutputBytes ?? 1_048_576;
         const out = new ByteSink(max);
@@ -404,9 +464,18 @@ export class CellClient {
         const maxReconnects = opts.maxReconnects ?? 10;
         for (;;) {
             let exited;
+            const first = initial;
+            initial = undefined; // A dropped combined response reconnects only by GET, never re-starting the command.
+            const streamAbort = first?.abort ?? 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 } : {}) });
+                if (first && !first.response.body)
+                    throw new ShardfluxProtocolError('exec output: empty body', first.response.status, 'cell');
+                const events = first ? ndjson(first.response.body) : 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,20 +495,28 @@ 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) {
+                        // A burst's failure is its terminal outcome, not a dropped stream: never reconnect.
+                        if (BURST_FAILURES.has(ev.error.error.code))
+                            throw Object.assign(new ShardfluxApiError(409, ev.error, 'cell'), { [TERMINAL]: true });
                         throw new ShardfluxApiError(502, ev.error, 'cell');
                     }
                 }
             }
             catch (e) {
-                if (opts.signal?.aborted || this.closed)
+                if (opts.signal?.aborted || this.closed || (e instanceof ShardfluxApiError && TERMINAL in e))
                     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 +526,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) {
@@ -457,6 +534,9 @@ export class CellClient {
                 break;
             }
         }
+        // A burst that failed after its start answered (the session ended with burst.error).
+        if (session.burst?.error)
+            throw burstFailure(session.burst.error);
         // A start answered while the session was still starting can end without starting the command.
         if (session.state === 'failed_to_start')
             throw new ExecStartError(session);
@@ -473,6 +553,8 @@ export class CellClient {
             truncated: out.total > out.kept || err.total > err.kept,
             session,
             reconnects,
+            memoryGrow: null,
+            burst: session.burst ?? null,
         };
     }
     // ---- executions (file-first workspaces) -----------------------------
@@ -708,7 +790,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 +957,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, ForkOptions, InternalLifecycleOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 import type { ProgressListener } from './progress.js';
 import { CaptureRegistry } from './capture.js';
 import type { FeedbackReceipt, SendFeedbackParams } from './feedback.js';
@@ -34,8 +34,6 @@ export type WorkspaceLifetime = components['schemas']['WorkspaceLifetime'];
 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'];
-/** Reserved (T2): always `pinned` in T1. */
-export type UpdatePolicy = components['schemas']['UpdatePolicy'];
 /** Where the workspace's disk came from: null, a fork, or a draft state (test instances). */
 export type WorkspaceOrigin = components['schemas']['WorkspaceOrigin'];
 export type ResetWorkspaceBody = components['schemas']['ResetWorkspaceBody'];
@@ -121,7 +119,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. */
@@ -143,10 +141,35 @@ export interface ShardfluxOptions {
      */
     versionCheck?: VersionCheckOption;
 }
+/**
+ * How a workspace holds its memory (0.13.0): `fixed` boots `memory_mib` and holds it; `elastic` makes
+ * `memory_mib` a promise: the VM holds `memory_mib_held` while idle and the host grows it when a command needs it.
+ */
+export type AllocationMode = 'fixed' | 'elastic';
+/**
+ * Memory of a workspace (0.13.0): `promised_mib` (what it may grow to), `held_mib` (the idle floor;
+ * for a fixed workspace the same as the promise) and `plugged_mib` (plugged above the held floor on the live
+ * allocation, refreshed about every 60 s; null without one). `allocation_mode` is the running VM's, else the next start's.
+ */
+export type WorkspaceMemory = WorkspaceView['memory'];
 export interface Caps {
     cpu_millis?: number;
+    /** Memory in MiB; for an elastic workspace the promise (what it may grow to). */
     memory_mib?: number;
     disk_gib?: number;
+    /**
+     * `fixed` (default) or `elastic` (0.13.0). Given caps replace the stored ones: caps without it make
+     * the workspace fixed again; omitted caps keep the stored layout. Elastic needs the organization's entitlement, else
+     * ShardfluxApiError 422 `validation_failed` reason `allocation_mode_not_available` (nothing is created or changed);
+     * a file-first workspace gets `not_supported_for_mode`. A promise that does not exceed the held floor by at least
+     * 512 MiB is fixed at the promise (the returned `caps.allocation_mode` says which). Takes effect at the next VM start.
+     */
+    allocation_mode?: AllocationMode;
+    /**
+     * Elastic only (0.13.0): the memory held while idle, in MiB (at least 512, default 1024 server side, at most
+     * `memory_mib`). Without elastic: 422 reason `requires_elastic`; above `memory_mib`: 422 `exceeds_memory_mib`.
+     */
+    memory_mib_held?: number;
 }
 export interface ForkTarget {
     key: string;
@@ -172,7 +195,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 +252,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 +321,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 +338,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 +359,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
@@ -399,13 +443,14 @@ export declare class WorkspacesApi {
     /**
      * Forks into a new key. `lifetime` is the fork's own (default persistent): forking a session is how it is kept.
      * Resolves when the fork is requested (the copy's handle is returned at once); with `wait`, once the copy exists,
-     * with its handle refreshed.
+     * with its handle ready. From 0.13.0, a supporting API returns the target view and final-epoch token together.
+     * `agentLabel`/`tools` choose that token; an older API ignoring Prefer falls back to polling and refreshing.
      */
-    fork(workspaceId: string, target: ForkTarget, opts: WaitedLifecycleOptions): Promise<{
+    fork(workspaceId: string, target: ForkTarget, opts: WaitedForkOptions): Promise<{
         operation: FinishedOperation;
         workspace: Workspace;
     }>;
-    fork(workspaceId: string, target: ForkTarget, opts?: LifecycleOptions): Promise<{
+    fork(workspaceId: string, target: ForkTarget, opts?: ForkOptions): Promise<{
         operation: Operation;
         workspace: Workspace;
     }>;

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') };
@@ -475,17 +543,45 @@ export class WorkspacesApi {
     }
     async fork(workspaceId, target, opts = {}) {
         let copy;
-        const operation = await runLifecycle(this.#ctx(), 'fork', workspaceId, async (init) => {
-            const out = await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/fork`, target, opts.idempotencyKey, init);
-            copy = this.#wrap(out.workspace);
+        let heldReady = false;
+        const requestedWait = waitOptionsOf(opts);
+        const wait = requestedWait ? { ...requestedWait } : null;
+        const timeoutMs = wait?.timeoutMs ?? 300_000;
+        const started = Date.now();
+        const operation = await runLifecycle(this.#ctx(), 'fork', workspaceId, async (init, trace) => {
+            const waitS = wait && wait.serverWait !== false ? Math.min(SERVER_WAIT_MAX_S, Math.floor(timeoutMs / 1000)) : 0;
+            const body = { ...target };
+            if (waitS >= 1 && opts.agentLabel !== undefined)
+                body.agent_label = opts.agentLabel;
+            if (waitS >= 1 && opts.tools !== undefined)
+                body.tools = [...opts.tools];
+            const res = await this.#http.jsonWithHeaders('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/fork`, {
+                ...init, json: body, idempotencyKey: opts.idempotencyKey ?? randomId('op-'),
+                ...(wait?.signal ? { signal: wait.signal } : {}),
+                ...(waitS >= 1 ? { headers: { prefer: `wait=${waitS}` }, timeoutMs: Math.max(this.#http.opts.timeoutMs, waitS * 1000 + 10_000) } : {}),
+            }, this.#auth);
+            const out = res.body;
+            if (!out?.workspace || !out.operation)
+                throw new ShardfluxProtocolError('fork: response has no workspace or operation', res.status, 'api');
+            heldReady = waitS >= 1 && res.status === 200 && /\bwait\s*=/i.test(res.headers.get('preference-applied') ?? '');
+            if (heldReady && (out.operation.state !== 'succeeded' || out.workspace.observed_state !== 'running')) {
+                throw new ShardfluxProtocolError('fork: held response is not a succeeded running target', res.status, 'api');
+            }
+            const token = heldReady ? out.tool_token ?? null : null;
+            this.#noteToken(token);
+            copy = this.#wrap(out.workspace, { agentLabel: opts.agentLabel, tools: opts.tools, token, trace });
+            if (wait && waitS >= 1)
+                wait.timeoutMs = Math.max(1, timeoutMs - (Date.now() - started));
             return out.operation;
         }, {
             ...opts,
+            ...(wait ? { wait } : {}),
             [AFTER_WAIT]: async (trace, op) => {
-                await trace.span('view', () => copy.refresh());
+                if (!heldReady)
+                    await trace.span('view', () => copy.refresh());
                 await opts[AFTER_WAIT]?.(trace, op);
             },
-        }, { settle: true });
+        }, { settle: true, requestReason: wait && wait.serverWait !== false && timeoutMs >= 1000 ? 'held' : null });
         return { operation, workspace: copy };
     }
     /** The workspace's text inputs `{NAME: value}` (0.7.0). Secret inputs are bound secrets, never listed. */