@shardflux/sdk 0.11.0 → 0.12.0

package/dist/client.d.ts

@@ -22,15 +22,15 @@ 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';
 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: 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. */
@@ -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;
@@ -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;
@@ -189,7 +193,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 +208,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
@@ -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;
@@ -248,7 +254,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,15 +289,24 @@ 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>;
+    /**
+     * 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,13 +336,15 @@ 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 (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 +354,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 +368,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 +378,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 +390,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 +403,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 +412,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 +430,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 +475,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

@@ -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,11 +9,11 @@ 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";
 /**
- * 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;
@@ -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)
@@ -108,7 +112,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 +192,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];
@@ -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,
@@ -379,7 +447,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.
@@ -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') };
@@ -419,7 +487,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 +497,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 +533,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 +556,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 +614,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 +651,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: {