@shardflux/sdk 0.11.1 → 0.12.0

package/dist/errors.js

@@ -1,4 +1,4 @@
-import { capacityDeadlineOf } from "./progress.js";
+import { capacityDeadlineOf, durabilityOf } from "./progress.js";
 export function isErrorBody(v) {
     if (typeof v !== 'object' || v === null || !('error' in v))
         return false;
@@ -129,12 +129,20 @@ export function apiError(status, body, source, retryAfterSeconds, treeRevision)
 /** The response was not the documented shape (e.g. a proxy error page). */
 export class ShardfluxProtocolError extends Error {
     status;
-    constructor(message, status) {
+    /** The responding surface; unknown only for errors constructed by older callers. Never proof of deletion. */
+    source;
+    constructor(message, status, source = 'unknown') {
         super(message);
         this.name = 'ShardfluxProtocolError';
         this.status = status;
+        this.source = source;
     }
 }
+/** True only for an explicit API tombstone refusal. A 404, even a structured one, may be routing or scope. */
+export function isWorkspaceGone(error) {
+    return error instanceof ShardfluxApiError && error.source === 'api' &&
+        error.code === 'conflict' && error.reason === 'workspace_deleted';
+}
 /**
  * Waiting for an operation ran out of time. The operation keeps running server side:
  * resume with `cloud.workspaces.waitForOperation(err.operationId)` or call open() again
@@ -154,10 +162,18 @@ export class OperationTimeoutError extends Error {
     waitedMs;
     /** Where the time went: client phases, retries and the operation's own server timing so far. */
     timing = undefined;
-    constructor(op, waitedMs) {
+    /**
+     * `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.
+     */
+    durable;
+    constructor(op, waitedMs, durable = false) {
         const deadlineAt = capacityDeadlineOf(op);
         const after = deadlineAt ? `it stays queued server side until ${deadlineAt} and fails with capacity_unavailable if it has not started by then.` : 'it continues server side.';
-        super(`Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; ${after}`);
+        super(durable
+            ? `Operation ${op.id} (${op.kind}) succeeded; its durable copy was still ${durabilityOf(op)?.state ?? 'pending'} after ${Math.round(waitedMs)} ms and continues server side.`
+            : `Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; ${after}`);
+        this.durable = durable;
         this.name = 'OperationTimeoutError';
         this.operationId = op.id;
         this.workspaceId = op.workspace_id;
@@ -167,11 +183,17 @@ export class OperationTimeoutError extends Error {
         this.waitedMs = waitedMs;
     }
 }
-/** 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 class OperationFailedError extends Error {
     operation;
     operationId;
     errorCode;
+    /** 0.12.0+: a suspend-when-idle canceled because the workspace was active; it keeps running, nothing changed. */
+    workspaceActive;
     /**
      * `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
@@ -187,6 +209,29 @@ export class OperationFailedError extends Error {
         this.operation = op;
         this.operationId = op.id;
         this.errorCode = code;
+        this.workspaceActive = code === 'workspace_active' && op.kind === 'suspend';
         this.retryable = op.error?.retryable === true;
     }
 }
+/**
+ * `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 class DurabilityLostError extends Error {
+    operation;
+    operationId;
+    workspaceId;
+    durability;
+    /** Where the time went. */
+    timing = undefined;
+    constructor(op) {
+        const durability = durabilityOf(op) ?? { state: 'lost', checkpointId: null, generationId: null, localCommitAt: null, durableBy: null, durableAt: null, localCommitToDurableMs: null, overdueAt: null, reason: null };
+        super(`Operation ${op.id} (${op.kind}): the durable copy of checkpoint ${durability.checkpointId ?? '?'} was not made${durability.reason ? ` (${durability.reason})` : ''}`);
+        this.name = 'DurabilityLostError';
+        this.operation = op;
+        this.operationId = op.id;
+        this.workspaceId = op.workspace_id;
+        this.durability = durability;
+    }
+}

package/dist/feedback.js

@@ -33,7 +33,7 @@ function feedbackBody(params) {
 export async function sendFeedback(ctx, params) {
     const { status, body } = await ctx.http.jsonWithStatus('POST', '/v1/feedback', { json: feedbackBody(params) }, ctx.authorization);
     if (typeof body?.id !== 'string' || typeof body.received_at !== 'string' || typeof body.duplicate !== 'boolean') {
-        throw new ShardfluxProtocolError('POST /v1/feedback: the response is not {id, received_at, duplicate}', status);
+        throw new ShardfluxProtocolError('POST /v1/feedback: the response is not {id, received_at, duplicate}', status, 'api');
     }
     return { id: body.id, receivedAt: body.received_at, duplicate: body.duplicate };
 }

package/dist/generated/app-api.d.ts

@@ -188,7 +188,7 @@ export interface paths {
         put?: never;
         /**
          * Consume an email verification token
-         * @description Single use. The emailed link is a frontend page (`/auth/verify-email#token=...`); GET never consumes. The first verification signs out every session, disables any MFA enrolled while unverified and invalidates the other open verification links. A link sent by a registration applies the password chosen in that same registration (`status: verified`; sign in again). A link from "resend" carries no password, so the stored one (set by an unverified registrant) is discarded: the response is `status: password_reset_required` with a single-use `reset_token` for POST /api/auth/password/reset/confirm, and no sign-in is possible until a password is set.
+         * @description Single use. The emailed link is a frontend page (`/auth/verify-email#token=...`); GET never consumes. The first verification signs out every session, disables any MFA enrolled while unverified and invalidates the other open verification links. A link sent by a registration applies the password chosen in that same registration (`status: verified`). A link from "resend" carries no password, so the stored one (set by an unverified registrant) is discarded: the response is `status: password_reset_required` with a single-use `reset_token` for POST /api/auth/password/reset/confirm, and no sign-in is possible until a password is set. Consumed in the browser whose registration sent the link (its __Host-sf_signup cookie), a `verified` link also signs that browser in: `signed_in: true` with the new session cookie and its `csrf_token`. Anywhere else `signed_in` is false: sign in.
          */
         post: operations["postApiAuthVerifyEmail"];
         delete?: never;
@@ -576,7 +576,7 @@ export interface paths {
         put?: never;
         /**
          * Consume an email verification token
-         * @description Single use. The emailed link is a frontend page (`/auth/verify-email#token=...`); GET never consumes. The first verification signs out every session, disables any MFA enrolled while unverified and invalidates the other open verification links. A link sent by a registration applies the password chosen in that same registration (`status: verified`; sign in again). A link from "resend" carries no password, so the stored one (set by an unverified registrant) is discarded: the response is `status: password_reset_required` with a single-use `reset_token` for POST /v1/auth/password/reset/confirm, and no sign-in is possible until a password is set.
+         * @description Single use. The emailed link is a frontend page (`/auth/verify-email#token=...`); GET never consumes. The first verification signs out every session, disables any MFA enrolled while unverified and invalidates the other open verification links. A link sent by a registration applies the password chosen in that same registration (`status: verified`). A link from "resend" carries no password, so the stored one (set by an unverified registrant) is discarded: the response is `status: password_reset_required` with a single-use `reset_token` for POST /v1/auth/password/reset/confirm, and no sign-in is possible until a password is set. Sign in afterwards.
          */
         post: operations["postV1AuthVerifyEmail"];
         delete?: never;
@@ -1366,7 +1366,7 @@ export interface paths {
         put?: never;
         /**
          * Open a workspace by key (create on first use, reconnect or resume afterwards)
-         * @description New keys resolve `template` to its latest published version; reopening never changes or resets the workspace (the response reports the template version actually used). 200 when the workspace is already running and ready (with `cell_endpoint` and a tool token); otherwise 202 with the operation to poll. A running workspace whose startup failed (`startup.state` failed, contracts §24.4) is not ready: the open is 202 with an `open` operation (input.startup_retry) that runs the failed step again. Concurrent opens of one key share one workspace and one operation. `secrets` (optional) binds secret names injected into every exec/PTY start: it sets the binding of a new key and replaces it on an existing key (omitted = unchanged); an unknown or unusable name is 422 details.reason secret_not_available with details.names (nothing is created or changed). The template version’s secret inputs (contracts §24.3) join the binding on create and whenever `secrets` is given; a required one this workspace may not use is 422 input_required (details.kind secret); a bound name equal to a template env key or text input is 422 env_collision (details.name). `inputs` (optional): the version’s text inputs {NAME: string}; stored on create (else the declared default) and replaced on an existing key (omitted = unchanged); 422 input_unknown, input_invalid or input_required (details.names). `lifetime` (contracts §19.11): omitted = the version’s default (else persistent); `session` workspaces are discarded when the session ends (close(), idle timeout), after which the key opens a NEW workspace; reopening a live key with another lifetime is 409 lifetime_mismatch. A new workspace is `layered` when its version supports it and layered opens are enabled (`disk_layout`). Errors: 404 template/key outside scope, 402 `entitlement_required`, 403 `quota_exceeded` (details.limit), 409 operation in progress, deleted key (workspace_deleted) or lifetime_mismatch, 422 reserved_key_prefix (keys starting with sf:). Supports Idempotency-Key. Held open (contracts §22.3): with `Prefer: wait=<seconds>` (at most 20) an open whose outcome is an operation is held until the operation is terminal or the wait elapses; success answers 200 with the running workspace, the succeeded operation and a tool token (`Preference-Applied: wait=<seconds>`), anything else 202 with the fresh operation. Without `Preference-Applied` the server did not wait: poll the operation. `mode` (contracts §29): omitted = processful for a new key and the stored mode for an existing one; `file_first` creates a workspace whose state is a versioned file tree with no VM between executions: it is ready at once (200 with a tool token, `observed_state` running, `tree_revision` 0, no operation), needs a layered template version (409 layout_unsupported otherwise) and is persistent (`lifetime: session` or `idle_policy` with it are 422 not_supported_for_mode); each open of a file-first key re-resolves the size of its execution VMs from `caps`, the template and the plan. 422 mode_not_available while the deployment does not offer file-first workspaces; reopening a key with another mode is 409 mode_mismatch.
+         * @description New keys resolve `template` to its latest published version; reopening never changes or resets the workspace (the response reports the template version actually used). 200 when the workspace is already running and ready (with `cell_endpoint` and a tool token); otherwise 202 with the operation to poll. A running workspace whose startup failed (`startup.state` failed, contracts §24.4) is not ready: the open is 202 with an `open` operation (input.startup_retry) that runs the failed step again. Concurrent opens of one key share one workspace and one operation. `secrets` (optional) binds secret names injected into every exec/PTY start: it sets the binding of a new key and replaces it on an existing key (omitted = unchanged); an unknown or unusable name is 422 details.reason secret_not_available with details.names (nothing is created or changed). The template version’s secret inputs (contracts §24.3) join the binding on create and whenever `secrets` is given; a required one this workspace may not use is 422 input_required (details.kind secret); a bound name equal to a template env key or text input is 422 env_collision (details.name). `inputs` (optional): the version’s text inputs {NAME: string}; stored on create (else the declared default) and replaced on an existing key (omitted = unchanged); 422 input_unknown, input_invalid or input_required (details.names). `lifetime` (contracts §19.11): omitted = the version’s default (else persistent); `session` workspaces are discarded when the session ends (close(), idle timeout), after which the key opens a NEW workspace; reopening a live key with another lifetime is 409 lifetime_mismatch. A new workspace is `layered` when its version supports it and layered opens are enabled (`disk_layout`). Errors: 404 template/key outside scope, 402 `entitlement_required`, 403 `quota_exceeded` (details.limit), 409 operation in progress, key whose deletion is still in progress (workspace_deleted) or lifetime_mismatch, 422 reserved_key_prefix (keys starting with sf:). Supports Idempotency-Key. Held open (contracts §22.3): with `Prefer: wait=<seconds>` (at most 20) an open whose outcome is an operation is held until the operation is terminal or the wait elapses; success answers 200 with the running workspace, the succeeded operation and a tool token (`Preference-Applied: wait=<seconds>`), anything else 202 with the fresh operation. Without `Preference-Applied` the server did not wait: poll the operation. `mode` (contracts §29): omitted = processful for a new key and the stored mode for an existing one; `file_first` creates a workspace whose state is a versioned file tree with no VM between executions: it is ready at once (200 with a tool token, `observed_state` running, `tree_revision` 0, no operation), needs a layered template version (409 layout_unsupported otherwise) and is persistent (`lifetime: session` or `idle_policy` with it are 422 not_supported_for_mode); each open of a file-first key re-resolves the size of its execution VMs from `caps`, the template and the plan. 422 mode_not_available while the deployment does not offer file-first workspaces; reopening a key with another mode is 409 mode_mismatch.
          */
         post: operations["postV1WorkspacesOpen"];
         delete?: never;
@@ -1428,7 +1428,7 @@ export interface paths {
         post?: never;
         /**
          * Delete a workspace (tombstone now, storage cleanup by the cell)
-         * @description Sets desired_state=deleted and deleted_at, revokes tool access immediately (workspace revocation watermark, agent sessions revoked) and creates a `delete` operation for the cell. A file-first workspace’s tree revisions are deleted with the tombstone and the cell deletes its stored files (contracts §29). Repeating returns the same operation. The key is never reused. Supports Idempotency-Key.
+         * @description Sets desired_state=deleted and deleted_at, revokes tool access immediately (workspace revocation watermark, agent sessions revoked) and creates a `delete` operation for the cell. A file-first workspace’s tree revisions are deleted with the tombstone and the cell deletes its stored files (contracts §29). Repeating returns the same operation. After deletion finishes (observed_state deleted), the key can open a new workspace ID; old IDs and tokens remain deleted. Supports Idempotency-Key.
          */
         delete: operations["deleteV1WorkspacesWorkspaceId"];
         options?: never;
@@ -1456,6 +1456,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspace_id}/labels": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Replace workspace labels */
+        put: operations["putV1WorkspacesWorkspaceIdLabels"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{workspace_id}/idle-policy": {
         parameters: {
             query?: never;
@@ -1507,7 +1524,7 @@ export interface paths {
         put?: never;
         /**
          * Resume a suspended workspace (admitted like a start)
-         * @description Creates a `resume` operation executed by the cell, or returns the active resume/open (concurrent wakes join one operation); 202 with it: poll GET /operations/{id}. Errors: 409 already_running or not_suspended, operation_in_progress (a suspend or another operation is active; details.active_operation_id), workspace_deleted, not_supported_for_mode (file-first, contracts §29); 402/403 as for open (admitted like a start). Supports Idempotency-Key. Held resume (contracts §22.6): with `Prefer: wait=<seconds>` (at most 20) the response is held until the operation is terminal or the wait elapses, exactly like a held open (§22.3); success answers 200 with the running workspace, the succeeded operation, `cell_endpoint` and a tool token for `agent_label`/`tools` (minted while the restore is in flight, at the new ownership epoch), `Preference-Applied: wait=<seconds>`; anything else is 202 with the fresh operation. With the preference a workspace that is already running answers 200 at once (operation null, a token) instead of 409 already_running. Without `Preference-Applied` the server did not wait: poll the operation. `tools` beyond the principal’s tool permissions are 403 (nothing is created); a token the API cannot issue otherwise is `tool_token: null`.
+         * @description Creates a `resume` operation for a suspended workspace, or an `open` recovery for a failed workspace (same ID and disk, no reset), or returns the active resume/open (concurrent wakes join one operation); 202 with it: poll GET /operations/{id}. Errors: 409 already_running or not_suspended, operation_in_progress (a suspend or another operation is active; details.active_operation_id), workspace_deleted, not_supported_for_mode (file-first, contracts §29); 402/403 as for open (admitted like a start). Supports Idempotency-Key. Held resume (contracts §22.6): with `Prefer: wait=<seconds>` (at most 20) the response is held until the operation is terminal or the wait elapses, exactly like a held open (§22.3); success answers 200 with the running workspace, the succeeded operation, `cell_endpoint` and a tool token for `agent_label`/`tools` (minted while the restore is in flight, at the new ownership epoch), `Preference-Applied: wait=<seconds>`; anything else is 202 with the fresh operation. With the preference a workspace that is already running answers 200 at once (operation null, a token) instead of 409 already_running. Without `Preference-Applied` the server did not wait: poll the operation. `tools` beyond the principal’s tool permissions are 403 (nothing is created); a token the API cannot issue otherwise is `tool_token: null`.
          */
         post: operations["postV1WorkspacesWorkspaceIdResume"];
         delete?: never;
@@ -1742,7 +1759,7 @@ export interface paths {
         put?: never;
         /**
          * Open a workspace by key (create on first use, reconnect or resume afterwards)
-         * @description New keys resolve `template` to its latest published version; reopening never changes or resets the workspace (the response reports the template version actually used). 200 when the workspace is already running and ready (with `cell_endpoint` and a tool token); otherwise 202 with the operation to poll. A running workspace whose startup failed (`startup.state` failed, contracts §24.4) is not ready: the open is 202 with an `open` operation (input.startup_retry) that runs the failed step again. Concurrent opens of one key share one workspace and one operation. `secrets` (optional) binds secret names injected into every exec/PTY start: it sets the binding of a new key and replaces it on an existing key (omitted = unchanged); an unknown or unusable name is 422 details.reason secret_not_available with details.names (nothing is created or changed). The template version’s secret inputs (contracts §24.3) join the binding on create and whenever `secrets` is given; a required one this workspace may not use is 422 input_required (details.kind secret); a bound name equal to a template env key or text input is 422 env_collision (details.name). `inputs` (optional): the version’s text inputs {NAME: string}; stored on create (else the declared default) and replaced on an existing key (omitted = unchanged); 422 input_unknown, input_invalid or input_required (details.names). `lifetime` (contracts §19.11): omitted = the version’s default (else persistent); `session` workspaces are discarded when the session ends (close(), idle timeout), after which the key opens a NEW workspace; reopening a live key with another lifetime is 409 lifetime_mismatch. A new workspace is `layered` when its version supports it and layered opens are enabled (`disk_layout`). Errors: 404 template/key outside scope, 402 `entitlement_required`, 403 `quota_exceeded` (details.limit), 409 operation in progress, deleted key (workspace_deleted) or lifetime_mismatch, 422 reserved_key_prefix (keys starting with sf:). Supports Idempotency-Key. Held open (contracts §22.3): with `Prefer: wait=<seconds>` (at most 20) an open whose outcome is an operation is held until the operation is terminal or the wait elapses; success answers 200 with the running workspace, the succeeded operation and a tool token (`Preference-Applied: wait=<seconds>`), anything else 202 with the fresh operation. Without `Preference-Applied` the server did not wait: poll the operation. `mode` (contracts §29): omitted = processful for a new key and the stored mode for an existing one; `file_first` creates a workspace whose state is a versioned file tree with no VM between executions: it is ready at once (200 with a tool token, `observed_state` running, `tree_revision` 0, no operation), needs a layered template version (409 layout_unsupported otherwise) and is persistent (`lifetime: session` or `idle_policy` with it are 422 not_supported_for_mode); each open of a file-first key re-resolves the size of its execution VMs from `caps`, the template and the plan. 422 mode_not_available while the deployment does not offer file-first workspaces; reopening a key with another mode is 409 mode_mismatch.
+         * @description New keys resolve `template` to its latest published version; reopening never changes or resets the workspace (the response reports the template version actually used). 200 when the workspace is already running and ready (with `cell_endpoint` and a tool token); otherwise 202 with the operation to poll. A running workspace whose startup failed (`startup.state` failed, contracts §24.4) is not ready: the open is 202 with an `open` operation (input.startup_retry) that runs the failed step again. Concurrent opens of one key share one workspace and one operation. `secrets` (optional) binds secret names injected into every exec/PTY start: it sets the binding of a new key and replaces it on an existing key (omitted = unchanged); an unknown or unusable name is 422 details.reason secret_not_available with details.names (nothing is created or changed). The template version’s secret inputs (contracts §24.3) join the binding on create and whenever `secrets` is given; a required one this workspace may not use is 422 input_required (details.kind secret); a bound name equal to a template env key or text input is 422 env_collision (details.name). `inputs` (optional): the version’s text inputs {NAME: string}; stored on create (else the declared default) and replaced on an existing key (omitted = unchanged); 422 input_unknown, input_invalid or input_required (details.names). `lifetime` (contracts §19.11): omitted = the version’s default (else persistent); `session` workspaces are discarded when the session ends (close(), idle timeout), after which the key opens a NEW workspace; reopening a live key with another lifetime is 409 lifetime_mismatch. A new workspace is `layered` when its version supports it and layered opens are enabled (`disk_layout`). Errors: 404 template/key outside scope, 402 `entitlement_required`, 403 `quota_exceeded` (details.limit), 409 operation in progress, key whose deletion is still in progress (workspace_deleted) or lifetime_mismatch, 422 reserved_key_prefix (keys starting with sf:). Supports Idempotency-Key. Held open (contracts §22.3): with `Prefer: wait=<seconds>` (at most 20) an open whose outcome is an operation is held until the operation is terminal or the wait elapses; success answers 200 with the running workspace, the succeeded operation and a tool token (`Preference-Applied: wait=<seconds>`), anything else 202 with the fresh operation. Without `Preference-Applied` the server did not wait: poll the operation. `mode` (contracts §29): omitted = processful for a new key and the stored mode for an existing one; `file_first` creates a workspace whose state is a versioned file tree with no VM between executions: it is ready at once (200 with a tool token, `observed_state` running, `tree_revision` 0, no operation), needs a layered template version (409 layout_unsupported otherwise) and is persistent (`lifetime: session` or `idle_policy` with it are 422 not_supported_for_mode); each open of a file-first key re-resolves the size of its execution VMs from `caps`, the template and the plan. 422 mode_not_available while the deployment does not offer file-first workspaces; reopening a key with another mode is 409 mode_mismatch.
          */
         post: operations["postApiV1WorkspacesOpen"];
         delete?: never;
@@ -1804,7 +1821,7 @@ export interface paths {
         post?: never;
         /**
          * Delete a workspace (tombstone now, storage cleanup by the cell)
-         * @description Sets desired_state=deleted and deleted_at, revokes tool access immediately (workspace revocation watermark, agent sessions revoked) and creates a `delete` operation for the cell. A file-first workspace’s tree revisions are deleted with the tombstone and the cell deletes its stored files (contracts §29). Repeating returns the same operation. The key is never reused. Supports Idempotency-Key.
+         * @description Sets desired_state=deleted and deleted_at, revokes tool access immediately (workspace revocation watermark, agent sessions revoked) and creates a `delete` operation for the cell. A file-first workspace’s tree revisions are deleted with the tombstone and the cell deletes its stored files (contracts §29). Repeating returns the same operation. After deletion finishes (observed_state deleted), the key can open a new workspace ID; old IDs and tokens remain deleted. Supports Idempotency-Key.
          */
         delete: operations["deleteApiV1WorkspacesWorkspaceId"];
         options?: never;
@@ -1832,6 +1849,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/workspaces/{workspace_id}/labels": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Replace workspace labels */
+        put: operations["putApiV1WorkspacesWorkspaceIdLabels"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/workspaces/{workspace_id}/idle-policy": {
         parameters: {
             query?: never;
@@ -1883,7 +1917,7 @@ export interface paths {
         put?: never;
         /**
          * Resume a suspended workspace (admitted like a start)
-         * @description Creates a `resume` operation executed by the cell, or returns the active resume/open (concurrent wakes join one operation); 202 with it: poll GET /operations/{id}. Errors: 409 already_running or not_suspended, operation_in_progress (a suspend or another operation is active; details.active_operation_id), workspace_deleted, not_supported_for_mode (file-first, contracts §29); 402/403 as for open (admitted like a start). Supports Idempotency-Key. Held resume (contracts §22.6): with `Prefer: wait=<seconds>` (at most 20) the response is held until the operation is terminal or the wait elapses, exactly like a held open (§22.3); success answers 200 with the running workspace, the succeeded operation, `cell_endpoint` and a tool token for `agent_label`/`tools` (minted while the restore is in flight, at the new ownership epoch), `Preference-Applied: wait=<seconds>`; anything else is 202 with the fresh operation. With the preference a workspace that is already running answers 200 at once (operation null, a token) instead of 409 already_running. Without `Preference-Applied` the server did not wait: poll the operation. `tools` beyond the principal’s tool permissions are 403 (nothing is created); a token the API cannot issue otherwise is `tool_token: null`.
+         * @description Creates a `resume` operation for a suspended workspace, or an `open` recovery for a failed workspace (same ID and disk, no reset), or returns the active resume/open (concurrent wakes join one operation); 202 with it: poll GET /operations/{id}. Errors: 409 already_running or not_suspended, operation_in_progress (a suspend or another operation is active; details.active_operation_id), workspace_deleted, not_supported_for_mode (file-first, contracts §29); 402/403 as for open (admitted like a start). Supports Idempotency-Key. Held resume (contracts §22.6): with `Prefer: wait=<seconds>` (at most 20) the response is held until the operation is terminal or the wait elapses, exactly like a held open (§22.3); success answers 200 with the running workspace, the succeeded operation, `cell_endpoint` and a tool token for `agent_label`/`tools` (minted while the restore is in flight, at the new ownership epoch), `Preference-Applied: wait=<seconds>`; anything else is 202 with the fresh operation. With the preference a workspace that is already running answers 200 at once (operation null, a token) instead of 409 already_running. Without `Preference-Applied` the server did not wait: poll the operation. `tools` beyond the principal’s tool permissions are 403 (nothing is created); a token the API cannot issue otherwise is `tool_token: null`.
          */
         post: operations["postApiV1WorkspacesWorkspaceIdResume"];
         delete?: never;
@@ -5548,6 +5582,55 @@ export interface components {
                 [key: string]: unknown;
             };
             result?: {
+                /** @description suspend and fork: whether the capture is in durable storage. false while `durability.state` is pending (the suspend completed on its host) or lost; true once it committed. Absent on other kinds. */
+                durable?: boolean;
+                /** @description suspend: `local_commit` when the suspend completed on its host and the durable copy followed in the background. */
+                suspend_path?: string;
+                durability?: {
+                    /**
+                     * @description pending: sealed on its host, the durable copy is being written; durable: the copy committed; lost: the copy could not be made and the previous recovery point stays current.
+                     * @enum {string}
+                     */
+                    state: "pending" | "durable" | "lost";
+                    /** @description The checkpoint being made durable. */
+                    checkpoint_id?: string;
+                    /** @description Its generation on the host. */
+                    generation_id?: string;
+                    /** @description RFC 3339: when the suspend (or fork) completed on its host. */
+                    local_commit_at?: string;
+                    /** @description RFC 3339: when the durable copy is expected to have committed (local_commit_at + the deadline). */
+                    durable_by?: string;
+                    /** @description RFC 3339 (state durable): when the durable copy committed. */
+                    durable_at?: string;
+                    /** @description State durable: local_commit_at to durable_at, in milliseconds. */
+                    local_commit_to_durable_ms?: number;
+                    /** @description RFC 3339: set once durable_by passed while the copy was still pending; it keeps retrying. */
+                    overdue_at?: string;
+                    /** @description State lost: why, e.g. host_lost. */
+                    reason?: string;
+                    /** @description State lost: the error code of the failed copy. */
+                    code?: string;
+                    recovery_point_checkpoint_id?: string | null;
+                } & {
+                    [key: string]: unknown;
+                };
+                lost_suspend?: {
+                    /** @description The suspend checkpoint whose durable copy was lost. */
+                    checkpoint_id: string;
+                    /** @description Its generation on the host. */
+                    generation_id?: string;
+                    /** @description Why it was lost, e.g. host_lost. */
+                    reason?: string;
+                    /** @description RFC 3339: when that suspend captured the workspace. */
+                    suspended_at?: string;
+                    /** @description The earlier durable checkpoint this resume restored. */
+                    restored_checkpoint_id?: string;
+                    /** @description RFC 3339: when the restored checkpoint committed; the workspace state is as of then. */
+                    state_as_of?: string;
+                } & {
+                    [key: string]: unknown;
+                };
+            } & {
                 [key: string]: unknown;
             };
         };
@@ -6668,6 +6751,10 @@ export interface components {
              */
             project_id: string;
             workspace_key: string;
+            /** @description Searchable workspace metadata; not secrets. At most 50 labels. */
+            labels: {
+                [key: string]: string;
+            };
             /**
              * Format: uuid
              * @description UUIDv7, lowercase canonical form.
@@ -7488,6 +7575,10 @@ export interface operations {
                         status: "verified" | "password_reset_required";
                         /** @description Present with password_reset_required: single-use token for POST /api/auth/password/reset/confirm. */
                         reset_token?: string;
+                        /** @description True when this response opened a session (the registering browser); false: sign in. */
+                        signed_in: boolean;
+                        /** @description Send as X-CSRF-Token on subsequent mutations. */
+                        csrf_token?: string;
                     };
                 };
             };
@@ -8487,7 +8578,7 @@ export interface operations {
                 content: {
                     "application/json": {
                         status: "verified" | "password_reset_required";
-                        /** @description Present with password_reset_required: single-use token for POST /api/auth/password/reset/confirm. */
+                        /** @description Present with password_reset_required: single-use token for POST /v1/auth/password/reset/confirm. */
                         reset_token?: string;
                     };
                 };
@@ -11495,6 +11586,10 @@ export interface operations {
                 "application/json": {
                     /** @description Stable workspace key, unique per organization (e.g. `${customerId}/${projectId}`). */
                     key: string;
+                    /** @description Searchable workspace metadata; not secrets. At most 50 labels. */
+                    labels?: {
+                        [key: string]: string;
+                    };
                     /** @description Template slug; new workspaces use its latest published version. */
                     template: string;
                     /** @description Optional user caps; the ceiling is min(template, cap, plan). Absent fields add no restriction. */
@@ -11586,6 +11681,8 @@ export interface operations {
                 state?: "creating" | "starting" | "running" | "suspending" | "suspended" | "resuming" | "forking" | "stopping" | "failed" | "deleting" | "deleted";
                 desired_state?: "running" | "suspended" | "deleted";
                 key_prefix?: string;
+                /** @description JSON object of exact label matches; all pairs must match. */
+                labels?: string;
                 include_deleted?: boolean;
                 /** @description persistent (default), session or any. Key lookups pass any. */
                 lifetime?: "persistent" | "session" | "any";
@@ -11641,6 +11738,8 @@ export interface operations {
                 state?: "creating" | "starting" | "running" | "suspending" | "suspended" | "resuming" | "forking" | "stopping" | "failed" | "deleting" | "deleted";
                 desired_state?: "running" | "suspended" | "deleted";
                 key_prefix?: string;
+                /** @description JSON object of exact label matches; all pairs must match. */
+                labels?: string;
                 include_deleted?: boolean;
                 /** @description persistent (default), session or any. Key lookups pass any. */
                 lifetime?: "persistent" | "session" | "any";
@@ -11814,6 +11913,56 @@ export interface operations {
             };
         };
     };
+    putV1WorkspacesWorkspaceIdLabels: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description UUIDv7, lowercase canonical form. */
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description Searchable workspace metadata; not secrets. At most 50 labels. */
+                    labels: {
+                        [key: string]: string;
+                    };
+                };
+            };
+        };
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Workspace"];
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
     putV1WorkspacesWorkspaceIdIdlePolicy: {
         parameters: {
             query?: never;
@@ -12623,6 +12772,10 @@ export interface operations {
                 "application/json": {
                     /** @description Stable workspace key, unique per organization (e.g. `${customerId}/${projectId}`). */
                     key: string;
+                    /** @description Searchable workspace metadata; not secrets. At most 50 labels. */
+                    labels?: {
+                        [key: string]: string;
+                    };
                     /** @description Template slug; new workspaces use its latest published version. */
                     template: string;
                     /** @description Optional user caps; the ceiling is min(template, cap, plan). Absent fields add no restriction. */
@@ -12714,6 +12867,8 @@ export interface operations {
                 state?: "creating" | "starting" | "running" | "suspending" | "suspended" | "resuming" | "forking" | "stopping" | "failed" | "deleting" | "deleted";
                 desired_state?: "running" | "suspended" | "deleted";
                 key_prefix?: string;
+                /** @description JSON object of exact label matches; all pairs must match. */
+                labels?: string;
                 include_deleted?: boolean;
                 /** @description persistent (default), session or any. Key lookups pass any. */
                 lifetime?: "persistent" | "session" | "any";
@@ -12769,6 +12924,8 @@ export interface operations {
                 state?: "creating" | "starting" | "running" | "suspending" | "suspended" | "resuming" | "forking" | "stopping" | "failed" | "deleting" | "deleted";
                 desired_state?: "running" | "suspended" | "deleted";
                 key_prefix?: string;
+                /** @description JSON object of exact label matches; all pairs must match. */
+                labels?: string;
                 include_deleted?: boolean;
                 /** @description persistent (default), session or any. Key lookups pass any. */
                 lifetime?: "persistent" | "session" | "any";
@@ -12942,6 +13099,56 @@ export interface operations {
             };
         };
     };
+    putApiV1WorkspacesWorkspaceIdLabels: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description UUIDv7, lowercase canonical form. */
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description Searchable workspace metadata; not secrets. At most 50 labels. */
+                    labels: {
+                        [key: string]: string;
+                    };
+                };
+            };
+        };
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Workspace"];
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
     putApiV1WorkspacesWorkspaceIdIdlePolicy: {
         parameters: {
             query?: never;
@@ -33652,6 +33859,10 @@ export interface operations {
                             controller_leases: {
                                 total: number;
                                 expired: number;
+                                /** @description Leases whose loop_state is late. */
+                                late: number;
+                                /** @description Leases whose loop_state is stalled (what Status alerts on). */
+                                stalled: number;
                                 leases: {
                                     name: string;
                                     holder: string;
@@ -33673,6 +33884,13 @@ export interface operations {
                                     expires_at: string;
                                     expired: boolean;
                                     renewed_age_seconds: number;
+                                    /**
+                                     * @description Against the loop's cell-loop-stalled CloudWatch alarm threshold: running (held), handover (no holder for at most one interval + 60 s, e.g. a deploy's release), late (no holder for longer, not stalled yet), stalled (no renewal for longer than the threshold).
+                                     * @enum {string}
+                                     */
+                                    loop_state: "running" | "handover" | "late" | "stalled";
+                                    /** @description The loop's alarm threshold: stalled past this many seconds without a renewal. */
+                                    stall_after_seconds: number;
                                 }[];
                             };
                             stale_after_seconds: number;

package/dist/generated/cell-api.d.ts

@@ -170,6 +170,29 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspace_id}/exec/{session_id}/stdin": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Write pipe stdin or send EOF to an exec session
+         * @description Requires stdin_open at start (processful only), host exec_stdin and guest exec_stdin.v1. Offset is the total bytes previously accepted (initially 0). A repeated identical last frame is safe; a different stale offset is refused. Writes are bounded: offset in the response may acknowledge only a prefix; continue from that offset. close takes effect only after the whole frame is accepted. The transport writes no input log or payload file; program output and full-state snapshots retain their normal persistence. An ended session refuses input.
+         */
+        post: operations["execInput"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{workspace_id}/exec/{session_id}/signal": {
         parameters: {
             query?: never;
@@ -843,6 +866,8 @@ export interface components {
             /** @description Absolute working directory; omitted or empty starts in the default (/home/user). A relative path is refused, not resolved: 422 validation_failed, details.reason invalid_cwd, details.field cwd, the message naming the absolute path it likely means. A cwd that is not a directory ends the session failed_to_start (processful) or the execution failed with details.reason exec_failed_to_start (file-first). */
             cwd?: string;
             user?: string;
+            /** @description Keep a pipe open for exec stdin writes; processful only, mutually exclusive with stdin. Requires exec_stdin.v1. */
+            stdin_open?: boolean;
             /** @description Written to stdin, which is then closed (max 1 MiB decoded). */
             stdin?: string;
             /** Format: int64 */
@@ -979,6 +1004,19 @@ export interface components {
         };
         /** @description Signal number (1-64) or name (e.g. "SIGTERM", "TERM"). */
         SignalValue: number | string;
+        ExecInputRequest: {
+            /** @description At most 64 KiB decoded. */
+            data?: string;
+            /** Format: int64 */
+            offset: number;
+            /** @default false */
+            close?: boolean;
+        };
+        ExecInputResult: {
+            /** Format: int64 */
+            offset: number;
+            closed: boolean;
+        };
         SignalRequest: {
             signal: components["schemas"]["SignalValue"];
             /**
@@ -1607,6 +1645,34 @@ export interface operations {
             default: components["responses"]["Error"];
         };
     };
+    execInput: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ExecInputRequest"];
+            };
+        };
+        responses: {
+            /** @description Acknowledged input offset and EOF state. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ExecInputResult"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
     execSignal: {
         parameters: {
             query?: never;