@shardflux/sdk 0.13.0 → 0.14.0

package/dist/cell.js

@@ -1,4 +1,4 @@
-import { ExecStartError, NotSupportedForModeError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { ExecStartError, NotSupportedForModeError, ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody, isWorkingQuotaRefusal } from "./errors.js";
 import { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 import { HttpClient, defaultSleep, randomId, treeRevisionOf } from "./http.js";
 import { describeFailure, emitTo } from "./progress.js";
@@ -20,8 +20,13 @@ export const DEFAULT_TRANSITION_TIMEOUT_MS = 120_000;
  * capture writes recorded before them (read-your-writes). Workspace.cell() sets it; the capture's own client does not.
  */
 export const CAPTURE_BARRIER = Symbol('shardflux.captureBarrier');
-/** Wakes per call at most: a workspace that keeps being suspended again surfaces the refusal. */
+/**
+ * Wakes per call at most: a workspace that keeps being suspended again, or keeps refusing the call while the API reports
+ * it running, surfaces the refusal.
+ */
 const MAX_WAKES = 3;
+/** The pause before retrying a call refused again while the API reports the workspace running (from the second time). */
+const RUNNING_AGAIN_PAUSE_MS = 500;
 /** 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;
@@ -63,6 +68,30 @@ export async function* ndjson(body) {
         reader.releaseLock();
     }
 }
+/**
+ * A refused attach the gateway had to accept (cell-api.yaml "WebSocket close codes": an allowed Origin cannot read the
+ * HTTP answer to a failed upgrade): its only text frame is exactly the ErrorBody, then a close with 4000 + the HTTP
+ * status (4410 for not_found). A 4429 without a body (its close reason is `{"code","retryable",...}`) is the same
+ * refusal in short. Undefined for any other close.
+ */
+function attachRefusal(code, reason, body) {
+    const status = code === 4410 ? 404 : code !== undefined && code >= 4000 && code < 5000 ? code - 4000 : undefined;
+    if (body) {
+        const hinted = body.error.details?.retry_after_seconds;
+        return apiError(status ?? 502, body, 'cell', typeof hinted === 'number' && hinted >= 0 ? hinted : undefined);
+    }
+    if (code !== 4429)
+        return undefined;
+    let short = {};
+    try {
+        short = JSON.parse(reason ?? '');
+    }
+    catch {
+        // Not the compact JSON: the close code alone says it.
+    }
+    const errCode = typeof short.code === 'string' ? short.code : 'rate_limited';
+    return apiError(429, { error: { code: errCode, message: `The attach was refused (${errCode}); retry shortly.`, request_id: typeof short.request_id === 'string' ? short.request_id : '', retryable: short.retryable !== false } }, 'cell');
+}
 class ByteSink {
     #max;
     #chunks = [];
@@ -108,6 +137,10 @@ const executionRetryDelayMs = (failures, retryAfterSeconds) => retryAfterSeconds
 const attemptTimedOut = (err) => err instanceof Error && err.name === 'TimeoutError';
 /** A transport failure or a retryable 429/5xx: the execution request may be sent again with the same id. */
 function transientExecutionFailure(err) {
+    // The working-at-once refusal was already retried by the HTTP layer within the client's maxRetries: a second loop
+    // here would multiply that budget, so it surfaces.
+    if (isWorkingQuotaRefusal(err))
+        return null;
     if (err instanceof ShardfluxApiError) {
         const status = err.status === 429 || err.status === 502 || err.status === 503 || err.status === 504;
         return status && err.retryable ? { retryAfterSeconds: err.retryAfterSeconds } : null;
@@ -213,8 +246,10 @@ export class CellClient {
      * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions,
      * bounded in total by `transitionTimeoutMs`: a call refused with `workspace_busy` is retried after `Retry-After`; one
      * refused with `workspace_not_running` (or whose token cannot be minted because the workspace is not running) wakes
-     * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call.
-     * Refused calls were never executed, so retrying is safe. When the budget is spent the refusal surfaces.
+     * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call. A
+     * wake that finds the workspace already running (`false`) is retried the same way: the transition that refused the
+     * call ended meanwhile (0.13.1+). Refused calls were never executed, so retrying is safe. When the budget is spent
+     * the refusal surfaces.
      */
     async request(method, path, init = {}) {
         const closer = this.#closer.signal;
@@ -237,6 +272,7 @@ export class CellClient {
         const retry = (cause, delayMs, attempt) => emit?.({ type: 'retry', retry: { atMs: Math.round((performance.now() - t0) * 10) / 10, request: `${method} ${path}`, attempt, cause, delayMs } });
         let refreshed = false;
         let wakes = 0;
+        let runningAgain = 0;
         let attempts = 0;
         for (;;) {
             try {
@@ -270,8 +306,17 @@ export class CellClient {
                 if (notRunning && wakeAllowed && this.#wake && wakes < MAX_WAKES && left > 0) {
                     wakes += 1;
                     const before = this.tokens.current;
-                    if ((await this.#wake(left, signal)) === false)
-                        throw err; // running per the API: nothing to wait for
+                    if ((await this.#wake(left, signal)) === false) {
+                        // Running per the API: the refusal was answered from a transition that ended before the wake looked (a
+                        // resume or a move committed in between: the token request was refused while the workspace was resuming,
+                        // and the wake found it running). The refused call never ran, so it is retried with a current token. A
+                        // refusal that comes back while the API keeps reporting the workspace running is retried after a pause,
+                        // within the same wakes and time budget, then surfaces.
+                        const pause = runningAgain++ === 0 ? 0 : Math.max(0, Math.min(deadline - Date.now(), RUNNING_AGAIN_PAUSE_MS));
+                        retry(`${err.code === 'conflict' ? 'conflict workspace_not_running' : err.code} (the workspace runs; new token)`, pause, (attempts += 1));
+                        if (pause > 0)
+                            await this.#opts.sleep(pause);
+                    }
                     // A held resume handed this client a token of the woken workspace: use it. Otherwise the
                     // old token is of the previous epoch: fetch a new one.
                     if (this.tokens.current === before)
@@ -399,6 +444,8 @@ export class CellClient {
                 req.kill_grace_ms = opts.killGraceMs;
             if (opts.secretRefs !== undefined)
                 req.secret_refs = opts.secretRefs;
+            if (opts.resourceHint !== undefined)
+                req.resource_hint = opts.resourceHint;
             if (opts.burst !== undefined)
                 req.burst = opts.burst;
             if (opts.burstVcpus !== undefined)
@@ -744,6 +791,7 @@ export class CellClient {
             let next = opts.offset ?? 0;
             let session = null;
             let exited = false;
+            let refusal;
             await new Promise((resolve, reject) => {
                 const onClose = () => finish(this.#closer.signal.reason instanceof Error ? this.#closer.signal.reason : new Error('closed'));
                 const ws = new WS(url, { headers: { authorization: `Bearer ${token}` } });
@@ -760,8 +808,10 @@ export class CellClient {
                     catch {
                         // already closed
                     }
-                    if (err)
-                        reject(err);
+                    // A refusal body whose close did not arrive within the read: the body alone says it.
+                    const failure = err ?? (refusal ? attachRefusal(undefined, undefined, refusal) : undefined);
+                    if (failure)
+                        reject(failure);
                     else
                         resolve();
                 };
@@ -775,6 +825,12 @@ export class CellClient {
                     if (typeof e.data !== 'string')
                         return;
                     const m = JSON.parse(e.data);
+                    // A refused attach (e.g. 4429 quota_exceeded: every working slot is taken): the bare ErrorBody, then the close.
+                    if (!('type' in m)) {
+                        if (isErrorBody(m))
+                            refusal = m;
+                        return;
+                    }
                     if (m.type === 'output' && m.data) {
                         const bytes = unb64(m.data);
                         sink.push(bytes);
@@ -791,7 +847,7 @@ export class CellClient {
                     }
                 });
                 ws.addEventListener('error', () => finish(new ShardfluxProtocolError('pty attach WebSocket failed', 0, 'cell')));
-                ws.addEventListener('close', () => finish());
+                ws.addEventListener('close', (e) => finish(attachRefusal(e.code, e.reason, refusal)));
                 if (this.closed)
                     onClose();
                 else
@@ -955,7 +1011,8 @@ export class CellClient {
         // Nothing of a file-first workspace sleeps: the cell would answer `resident`.
         if (this.mode === 'file_first')
             return Promise.resolve({ residency: 'resident' });
-        return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/wake-hint'), { wake: false, busy: false, timeoutMs: 10_000, ...(signal ? { signal } : {}) });
+        // A hint never waits: a 429 quota_exceeded (every working slot is taken) surfaces at once, like its other refusals.
+        return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/wake-hint'), { wake: false, busy: false, quotaRetry: false, timeoutMs: 10_000, ...(signal ? { signal } : {}) });
     }
     /** Read idle signals without recording activity or waking the workspace. */
     idle(signal) {

package/dist/client.d.ts

@@ -16,6 +16,7 @@ import type { ToolName, ToolToken } from './tokens.js';
 import { Workspace } from './workspace.js';
 import { AuditApi } from './audit.js';
 import { EgressPolicyApi } from './egress.js';
+import { WorkspacePorts } from './ports.js';
 import { SecretsApi } from './secrets.js';
 import { TemplatesApi } from './templates.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.js';
@@ -158,8 +159,9 @@ export interface Caps {
     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
+     * `fixed` or `elastic` (0.13.0). Omitted: fixed, or elastic where that is the organization's default (a reopen then
+     * keeps the stored mode); the SDK never fills it in. Given caps replace the stored ones; omitted caps keep the stored
+     * layout. `workspace.resize()` (0.14.0+) changes it on a running or suspended workspace. 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.
@@ -176,6 +178,64 @@ export interface ForkTarget {
     caps?: Caps;
     lifetime?: WorkspaceLifetime;
 }
+/**
+ * `workspace.resize()` / `workspaces.resize()` (0.14.0): the caps to change. Give at least one; the others keep their
+ * stored values. Each value is bounded by the plan's per-workspace maximum and the template's limit, as caps at open.
+ */
+export interface ResizeParams {
+    /** Memory in MiB: the size of a fixed workspace, the maximum an elastic one may grow to. */
+    memoryMib?: number;
+    /** Elastic only: the memory the workspace holds while idle, in MiB (at most the resulting `memoryMib`). */
+    memoryMibHeld?: number;
+    /** `fixed` or `elastic`: switches the mode, live on a running workspace. */
+    allocationMode?: AllocationMode;
+    /** CPU in millicores (1000 = one vCPU). */
+    cpuMillis?: number;
+    /** Disk in GiB; disks grow only. */
+    diskGib?: number;
+    /** Replays the stored response for a repeated request (default: a fresh key per call, so transport retries replay). */
+    idempotencyKey?: string;
+    /** Give up waiting for the resize after this long (default 300 000 ms); it continues server side. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Progress of the resize (the held request, the operation's states, retries, `done` with the timing). */
+    onProgress?: ProgressListener;
+}
+/** The held answer of `PATCH /v1/workspaces/{id}/caps` (and a finished resize operation's `result`). */
+export type ResizeResponse = components['schemas']['ResizeResult'];
+/** The memory part of a resize result (0.14.0). `*_mib` are MiB; `applied_mib` is what is live after the call (null when no VM runs), `held_mib` the elastic floor, `converged` whether a live change reached its target. */
+export type ResizeMemory = NonNullable<ResizeResponse['memory']>;
+/** The CPU part of a resize result (0.14.0), in millicores. */
+export type ResizeCpu = NonNullable<ResizeResponse['cpu']>;
+/** The disk part of a resize result (0.14.0), in GiB. */
+export type ResizeDisk = NonNullable<ResizeResponse['disk']>;
+/** When a resized resource takes effect (0.14.0): `now`, when the suspended workspace resumes, or at its next start. */
+export type ResizeAppliesAt = ResizeMemory['applies_at'];
+/** Why less than requested applied: clamped to the plan or template bound, the host had no room, or the guest kept memory it uses. */
+export type ResizeLimitReason = NonNullable<ResizeMemory['limit_reason']>;
+/**
+ * Why a resource applies later than now: `suspended` (at resume), `stopped` (at the next start), `boot_vcpus` (more CPU
+ * than the vCPUs the workspace booted with), `region` / `below_base` / `legacy_layout` (a memory size its running VM was
+ * not booted for).
+ */
+export type ResizeDeferReason = NonNullable<ResizeMemory['reason']>;
+/**
+ * What a resize did (0.14.0), per resource the request named (the others are null): when it applies (`applies_at`),
+ * what was asked, the bounded target, the size before, what is live now, and why less or later.
+ */
+export interface ResizeResult {
+    workspaceId: string;
+    operationId: string | null;
+    /** The workspace's state the result describes: `running`, `suspended` or `stopped`. */
+    state: string;
+    memory: ResizeMemory | null;
+    cpu: ResizeCpu | null;
+    disk: ResizeDisk | null;
+    /** The workspace's stored caps after the change: every later start uses them. */
+    caps: ResizeResponse['caps'] | null;
+    /** The finished `resize` operation when the API answered before it was done (202), else null. */
+    operation: Operation | null;
+}
 export interface WaitOptions {
     /**
      * Give up waiting after this long (default 300 000 ms); the operation continues server side. A queued start
@@ -338,6 +398,8 @@ export declare class WorkspacesApi {
         agentLabel?: string;
         tools?: ToolName[];
     }): Promise<Workspace>;
+    /** The exposed ports of a workspace by id (0.14.0; the same as `workspace.ports` without reading the workspace first). */
+    ports(workspaceId: string): WorkspacePorts;
     /** 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. */
@@ -412,6 +474,28 @@ export declare class WorkspacesApi {
      * is not undone: it is the workspace's `activeOperation` (resume or open the workspace instead).
      */
     cancelSuspendWhenIdle(workspaceId: string): Promise<Workspace>;
+    /**
+     * Resizes a workspace (0.14.0; `PATCH /v1/workspaces/{id}/caps`): any of memory, the held floor, the allocation mode,
+     * CPU and disk, of a running, suspended or stopped workspace, fixed or elastic, without a restart or a fork. The new
+     * caps are stored, so every later start uses them. Resolves once the resize has finished, with what applied per
+     * resource: `now` (live), `resume` (a suspended workspace gets it when it resumes, before its first call) or
+     * `next_start` (with the `reason`). The request is held by the server while the resize runs; a resize still running
+     * after the hold is waited for like any operation.
+     *
+     * A resize that meets another lifecycle operation (409 `operation_in_progress`: a suspend, a resume, another resize)
+     * waits for it and is sent again, within `timeoutMs`.
+     *
+     * Errors: ShardfluxApiError 409 `conflict` (reason `resize_not_available`, `workspace_deleted`), 422
+     * `validation_failed` (reason `shrink_not_supported` with `details.current_disk_gib`, `requires_elastic`,
+     * `exceeds_memory_mib`, `allocation_mode_not_available`, `not_supported_for_mode`). A resize that fails is its
+     * error: ShardfluxApiError with `operationId` when the server held the request until then, OperationFailedError when
+     * the SDK waited for the operation. OperationTimeoutError after `timeoutMs`. Params without a resource throw
+     * TypeError before any request.
+     *
+     *   const r = await cloud.workspaces.resize(id, { memoryMib: 6144 });
+     *   r.memory?.applies_at; // 'now'
+     */
+    resize(workspaceId: string, params: ResizeParams): Promise<ResizeResult>;
     /**
      * 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.

package/dist/client.js

@@ -3,6 +3,7 @@ import { HttpClient, SDK_VERSION, SERVER_WAIT_MAX_S, defaultFetch, defaultSleep,
 import { Workspace } from "./workspace.js";
 import { AuditApi } from "./audit.js";
 import { EgressPolicyApi } from "./egress.js";
+import { WorkspacePorts } from "./ports.js";
 import { SecretsApi } from "./secrets.js";
 import { TemplatesApi, saveAsTemplateBody } from "./templates.js";
 import { UsageApi } from "./usage.js";
@@ -46,6 +47,70 @@ function alreadyRunning(answer) {
         },
     }, 'api');
 }
+/** The `PATCH .../caps` body of a resize: the given caps only, snake_case. Throws TypeError when none is given. */
+function resizeBody(p) {
+    const body = {};
+    if (p.memoryMib !== undefined)
+        body.memory_mib = p.memoryMib;
+    if (p.memoryMibHeld !== undefined)
+        body.memory_mib_held = p.memoryMibHeld;
+    if (p.allocationMode !== undefined)
+        body.allocation_mode = p.allocationMode;
+    if (p.cpuMillis !== undefined)
+        body.cpu_millis = p.cpuMillis;
+    if (p.diskGib !== undefined)
+        body.disk_gib = p.diskGib;
+    if (Object.keys(body).length === 0)
+        throw new TypeError('resize() needs at least one of memoryMib, memoryMibHeld, allocationMode, cpuMillis, diskGib');
+    return body;
+}
+const RESIZE_KEYS = {
+    memory: ['applies_at', 'allocation_mode', 'requested_mib', 'target_mib', 'previous_mib', 'applied_mib', 'held_mib', 'converged', 'limit_reason', 'reason'],
+    cpu: ['applies_at', 'requested_millis', 'target_millis', 'previous_millis', 'applied_millis', 'limit_reason', 'reason'],
+    disk: ['applies_at', 'requested_gib', 'target_gib', 'previous_gib', 'applied_gib', 'limit_reason', 'reason'],
+};
+const record = (v) => (v !== null && typeof v === 'object' && !Array.isArray(v) ? v : {});
+/**
+ * A finished resize operation's `result` in the held answer's shape (as the API builds its 200): each resource the
+ * cell reported with its documented keys, a key the cell left out taken from the operation's input (target, requested)
+ * or null; the cell's other keys (timings, the previous values of a retried attempt) are left out.
+ */
+function resizeResultBodyOf(op) {
+    const result = record(op.result);
+    const input = record(op.input);
+    const target = record(input.target);
+    const requested = record(input.requested);
+    const fallback = {
+        memory: { allocation_mode: target.allocation_mode, requested_mib: requested.memory_mib, target_mib: target.memory_mib, held_mib: target.memory_mib_held },
+        cpu: { requested_millis: requested.cpu_millis, target_millis: target.cpu_millis },
+        disk: { requested_gib: requested.disk_gib, target_gib: target.disk_gib },
+    };
+    const out = { workspace_id: result.workspace_id ?? op.workspace_id, operation_id: op.id, state: result.state };
+    for (const [name, keys] of Object.entries(RESIZE_KEYS)) {
+        if (result[name] === null || typeof result[name] !== 'object')
+            continue;
+        const r = record(result[name]);
+        out[name] = Object.fromEntries(keys.map((k) => [k, r[k] ?? fallback[name]?.[k] ?? null]));
+    }
+    return out;
+}
+/** A resize result body (the held 200, or a finished operation's `result`) as ResizeResult. */
+function resizeResultOf(body, status, operation, workspaceId) {
+    if (!body || typeof body !== 'object' || !['memory', 'cpu', 'disk'].some((k) => body[k] && typeof body[k] === 'object')) {
+        throw new ShardfluxProtocolError('resize: the result names no resource (memory, cpu or disk)', status, 'api');
+    }
+    const part = (k) => (body[k] && typeof body[k] === 'object' ? body[k] : null);
+    return {
+        workspaceId: typeof body.workspace_id === 'string' ? body.workspace_id : workspaceId,
+        operationId: typeof body.operation_id === 'string' ? body.operation_id : (operation?.id ?? null),
+        state: typeof body.state === 'string' ? body.state : 'unknown',
+        memory: part('memory'),
+        cpu: part('cpu'),
+        disk: part('disk'),
+        caps: body.caps && typeof body.caps === 'object' ? body.caps : null,
+        operation,
+    };
+}
 /** Races the injected sleep against the signal (the injected sleep itself may not be abortable). */
 function abortableSleep(sleep, ms, signal) {
     if (signal.aborted)
@@ -316,6 +381,10 @@ export class WorkspacesApi {
     async get(workspaceId, opts = {}) {
         return this.#wrap(await this.#getView(workspaceId), opts);
     }
+    /** The exposed ports of a workspace by id (0.14.0; the same as `workspace.ports` without reading the workspace first). */
+    ports(workspaceId) {
+        return new WorkspacePorts(this.#ctx(), workspaceId);
+    }
     /** 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));
@@ -514,6 +583,85 @@ export class WorkspacesApi {
     async cancelSuspendWhenIdle(workspaceId) {
         return this.#wrap(await this.#http.json('DELETE', `/v1/workspaces/${encodeURIComponent(workspaceId)}/suspend-when-idle`, {}, this.#auth));
     }
+    /**
+     * Resizes a workspace (0.14.0; `PATCH /v1/workspaces/{id}/caps`): any of memory, the held floor, the allocation mode,
+     * CPU and disk, of a running, suspended or stopped workspace, fixed or elastic, without a restart or a fork. The new
+     * caps are stored, so every later start uses them. Resolves once the resize has finished, with what applied per
+     * resource: `now` (live), `resume` (a suspended workspace gets it when it resumes, before its first call) or
+     * `next_start` (with the `reason`). The request is held by the server while the resize runs; a resize still running
+     * after the hold is waited for like any operation.
+     *
+     * A resize that meets another lifecycle operation (409 `operation_in_progress`: a suspend, a resume, another resize)
+     * waits for it and is sent again, within `timeoutMs`.
+     *
+     * Errors: ShardfluxApiError 409 `conflict` (reason `resize_not_available`, `workspace_deleted`), 422
+     * `validation_failed` (reason `shrink_not_supported` with `details.current_disk_gib`, `requires_elastic`,
+     * `exceeds_memory_mib`, `allocation_mode_not_available`, `not_supported_for_mode`). A resize that fails is its
+     * error: ShardfluxApiError with `operationId` when the server held the request until then, OperationFailedError when
+     * the SDK waited for the operation. OperationTimeoutError after `timeoutMs`. Params without a resource throw
+     * TypeError before any request.
+     *
+     *   const r = await cloud.workspaces.resize(id, { memoryMib: 6144 });
+     *   r.memory?.applies_at; // 'now'
+     */
+    async resize(workspaceId, params) {
+        const body = resizeBody(params);
+        const trace = new Trace('resize', combineListeners(this.#ctx().onProgress, params.onProgress), { workspaceId });
+        return traced(trace, async () => {
+            const timeoutMs = params.timeoutMs ?? 300_000;
+            const started = Date.now();
+            const left = () => Math.max(1, timeoutMs - (Date.now() - started));
+            const idempotencyKey = params.idempotencyKey ?? randomId('op-');
+            const path = `/v1/workspaces/${encodeURIComponent(workspaceId)}/caps`;
+            let res;
+            for (let attempt = 0;; attempt += 1) {
+                const waitS = Math.min(SERVER_WAIT_MAX_S, Math.floor((attempt === 0 ? timeoutMs : left()) / 1000));
+                const init = { json: body, idempotencyKey, onRetry: trace.onRetry, ...(params.signal ? { signal: params.signal } : {}) };
+                if (waitS >= 1) {
+                    // Held: the server answers once the resize has finished (200) or the wait elapsed (202).
+                    init.headers = { prefer: `wait=${waitS}` };
+                    init.timeoutMs = Math.max(this.#http.opts.timeoutMs, waitS * 1000 + 10_000);
+                }
+                trace.phase('request', waitS >= 1 ? 'held' : attempt === 0 ? null : 'retry');
+                try {
+                    res = await this.#http.jsonWithStatus('PATCH', path, init, this.#auth);
+                    break;
+                }
+                catch (e) {
+                    // Another lifecycle operation (a suspend, a resume, another resize) holds the workspace: the refused request
+                    // changed nothing, so wait for that operation and send it again (bounded, within timeoutMs).
+                    const active = e instanceof ShardfluxApiError && e.code === 'conflict' && e.reason === 'operation_in_progress' ? (e.operationId ?? e.details?.['active_operation_id']) : undefined;
+                    if (typeof active !== 'string' || attempt >= 3 || Date.now() - started >= timeoutMs)
+                        throw e;
+                    trace.retry({ request: `PATCH ${path}`, attempt: attempt + 1, cause: `conflict operation_in_progress (waits for ${active})`, delayMs: 0 });
+                    try {
+                        await this.waitForOperation(active, { timeoutMs: left(), ...(params.signal ? { signal: params.signal } : {}), [TRACE]: trace });
+                    }
+                    catch (w) {
+                        if (!(w instanceof OperationFailedError))
+                            throw w;
+                    }
+                }
+            }
+            if (res.status !== 202)
+                return resizeResultOf(res.body, res.status, null, workspaceId);
+            const operation = res.body?.operation;
+            if (!operation || typeof operation !== 'object')
+                throw new ShardfluxProtocolError('resize: 202 response has no operation', res.status, 'api');
+            trace.observe(operation);
+            let final = operation;
+            if (operation.state !== 'succeeded') {
+                if (TERMINAL.has(operation.state))
+                    throw new OperationFailedError(operation);
+                const wait = { timeoutMs: Math.max(1, timeoutMs - (Date.now() - started)), ...(params.signal ? { signal: params.signal } : {}), [TRACE]: trace };
+                final = await this.waitForOperation(operation.id, wait);
+            }
+            // The finished operation's result is the cell's: shaped like the held answer, whose caps come from the view.
+            const result = resizeResultBodyOf(final);
+            const view = await trace.span('view', () => this.#getView(workspaceId, trace.onRetry));
+            return resizeResultOf({ ...result, state: result.state ?? view.observed_state, caps: view.caps }, res.status, final, workspaceId);
+        });
+    }
     async close(workspaceId, opts = {}) {
         return (await this.closeWithView(workspaceId, opts)).operation;
     }

package/dist/codex-proof.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Codex identity proof (0.14.0+, Node): the OpenAI ID token of the Codex CLI signed in on this machine, for
+ * `ShardfluxAccount.signup({ codexIdToken })` and `auth.stepUp({ codexIdToken })`.
+ *
+ * Codex keeps the token in `$CODEX_HOME/auth.json` (default `~/.codex/auth.json`) and refreshes it only every few
+ * days, while the API accepts one issued in the last 15 minutes. So this first asks Codex to refresh its own login
+ * (`codex app-server`, JSON-RPC `account/read {"refreshToken": true}`: Codex runs its normal refresh flow and writes
+ * its own file), then reads the token. Only the ID token is returned: Codex's access and refresh tokens are never read
+ * into memory beyond parsing the file, and never leave the machine. The ID token proves the ChatGPT account's verified
+ * email; it is not a credential to OpenAI.
+ *
+ *   const proof = await codexIdentityProof();
+ *   if (proof.ok) {
+ *     const { account, result } = await ShardfluxAccount.signup({ codexIdToken: proof.idToken });
+ *   }
+ */
+export type CodexProofUnavailable = 
+/** No `codex` executable on PATH (or CODEX_BIN), and no usable auth.json. */
+'codex_not_found'
+/** Codex is not signed in (no auth.json, or no ID token in it: signed in with an API key, or credentials in the OS keyring). */
+ | 'not_signed_in'
+/** Codex is signed in with an OpenAI API key, which carries no identity. */
+ | 'api_key_login'
+/** The token on disk is too old and Codex could not refresh it. */
+ | 'stale';
+export type CodexIdentityProof = {
+    ok: true;
+    idToken: string;
+    email: string | null;
+    refreshed: boolean;
+} | {
+    ok: false;
+    reason: CodexProofUnavailable;
+    message: string;
+};
+export interface CodexProofOptions {
+    /** Environment to read CODEX_HOME, CODEX_BIN and HOME from. Default `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Longest wait for `codex app-server` (ms). Default 15 000. */
+    timeoutMs?: number;
+    /** Skip the refresh and only read the file (tests, or when Codex must not be started). */
+    refresh?: boolean;
+    /** Accept a token issued at most this long ago (s), e.g. when Codex cannot refresh. Default 600 (the API allows 900). */
+    maxAgeSeconds?: number;
+    /** clientInfo sent to the app server. */
+    clientName?: string;
+    clientVersion?: string;
+}
+/**
+ * The ID token of this machine's Codex login, refreshed by Codex when needed. Never throws: `{ ok: false, reason }`
+ * says why there is none (sign up with an email address instead).
+ */
+export declare function codexIdentityProof(opts?: CodexProofOptions): Promise<CodexIdentityProof>;