@shardflux/sdk 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -3,7 +3,33 @@
 Every API the README shows is available from the version named here. Below 1.0, a minor release may break
 compatibility; breaking changes are marked **Breaking**.
 
-## 0.6.0 (not yet published; npm `latest` is 0.5.0)
+## 0.6.2 (not yet published; npm `latest` is 0.6.1)
+
+### Starts that wait for capacity end
+
+The API no longer lets a start (open, resume, restore, fork) wait in `capacity_pending` forever. One that no host
+could admit 15 minutes after it was created fails with `capacity_unavailable` and `retryable: true`: nothing was
+started, the concurrency slot is released, and a suspended workspace stays suspended with its state. Before, a VM could
+boot (and bill) long after every wait had given up.
+
+- `OperationFailedError.retryable`: the operation error's `retryable` flag (`false` when absent). `true` for
+  `capacity_unavailable` (retry later), `false` for a definitive failure. The SDK does not retry it itself.
+- `OperationTimeoutError.deadlineAt`: when a wait gives up while the start is still `capacity_pending`, the time it
+  stops waiting for a host (`error.details.deadline_at`); the message says so. Null in other states.
+- `onProgress`: a `capacity_pending` `phase` event carries `deadlineAt` when the API reports it.
+- Docs: waits no longer say a pending start continues indefinitely.
+
+## 0.6.1 (2026-09-28)
+
+- `formatTiming()` joined two phases that followed each other with `∥` (ran together) when their 0.1 ms times summed
+  with a floating-point error (1000.2 + 300.1 > 1300.3); it now prints `→`.
+- `open()`: the wait's `signal` also aborts the held request (up to 20 s); before, it only ended the polls after it,
+  and an abort during the held request was retried as a network failure.
+- `waitForOperation()` on its own records its first poll as a `request` phase; before, a held first poll's time
+  belonged to no phase (a 1 s wait could show `queued 0 ms`).
+- README: the timing example is the formatter's real output (durations under a second print in ms).
+
+## 0.6.0 (2026-09-28)
 
 ### Lifecycle calls: requested or finished
 

package/README.md

@@ -9,7 +9,7 @@ tools (exec, files, processes, PTY, git, browser) that plug into any model provi
 > **Early access.** Shardflux is in early access. The API is versioned (`/v1`), but this SDK is
 > below 1.0: a minor release may contain breaking changes (see [Compatibility](#compatibility)).
 
-> **Versions.** This README describes 0.6.0. Anything marked **(0.6.0+)** is not in 0.5.0;
+> **Versions.** This README describes 0.6.2. Anything marked **(0.6.0+)** is not in 0.5.0;
 > [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
 > `npm ls @shardflux/sdk` or the exported `SDK_VERSION`.
 
@@ -127,6 +127,23 @@ means depends on `wait`:
 wait again with `cloud.workspaces.waitForOperation(err.operationId)`. Without `wait`, the returned operation is the
 handle for the work in progress: pass its `id` to `waitForOperation()` when you need it finished.
 
+**A start waits for capacity for at most 15 minutes.** An open, resume, restore or fork that no host can admit yet
+waits in `capacity_pending`. Its `error.details.deadline_at` says when it gives up; the `phase` progress event carries
+it as `deadlineAt` **(0.6.2+)**, and so does `OperationTimeoutError` when your wait ends first. A start still pending
+at the deadline fails with `capacity_unavailable`: nothing was started, the concurrency slot is released, and a
+suspended workspace stays suspended with its state. `OperationFailedError.retryable` **(0.6.2+)** is `true` for it,
+so you can tell "retry later" from a definitive failure. The SDK does not retry it for you.
+
+```ts
+try {
+  await workspace.resume({ wait: true });
+} catch (err) {
+  if (err instanceof OperationFailedError && err.retryable) {
+    // err.errorCode === 'capacity_unavailable': no host had room; nothing changed. Try again later.
+  } else throw err;
+}
+```
+
 **Suspended workspaces wake on use.** A tool call on a suspended workspace resumes it (or joins the resume or open
 already running), then runs. A call made during a suspend or resume waits for the transition to finish. The call
 never runs twice: the cell executes nothing it refused.
@@ -148,9 +165,9 @@ await cell.exec.run(['make', 'test']);                         // resumes the wo
 the response until the operation changes (`Prefer: wait`, at most 20 s per request), so completion arrives within
 one round trip of the commit. Against an API without bounded waits (or with `serverWait: false`) it polls with
 backoff (250 ms doubling to 5 s, ±20 % jitter). If the timeout passes, it throws `OperationTimeoutError` and the
-operation keeps running server side; wait for it again with the same call. `templates.builds.waitForBuild()` waits
-the same way. A waited `open()` issues the first tool token together with the final workspace read, so the first
-tool call starts at once.
+operation keeps running server side (a start waiting for capacity until its `deadlineAt`); wait for it again with the
+same call. `templates.builds.waitForBuild()` waits the same way. A waited `open()` issues the first tool token
+together with the final workspace read, so the first tool call starts at once.
 
 On Node 26 the default fetch sends `Connection: close`: its bundled undici 8 can stall a request on a reused
 keep-alive connection for tens of seconds. Pass your own `fetch`, or set `SHARDFLUX_HTTP_KEEPALIVE=1`, to change that.
@@ -184,9 +201,9 @@ A slow open (34 s instead of the usual second) then reads, for example:
 
 ```text
 open 34.18 s, succeeded (workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342, operation 01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33)
-  client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 0.59 s → view 42 ms ∥ token 61 ms
-  server: queued 33.40 s, ran 0.62 s, total 34.02 s; start warm, boot to ready 79 ms
-  outside the server: 0.16 s
+  client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 590 ms → view 42 ms ∥ token 61 ms
+  server: queued 33.40 s, ran 620 ms, total 34.02 s; start warm, boot to ready 79 ms
+  outside the server: 161 ms
 ```
 
 Here the time went to waiting for a host with capacity; the network and the VM start were fast.
@@ -338,8 +355,11 @@ await workspace.cell().exec.run(['python3', 'agent.py']);          // sees $OPEN
   `message`, `requestId`, `retryable`, `details`, `operationId`, `retryAfterSeconds`, and `reason`
   (`details.reason`, e.g. `not_session`, `draft_not_found`, `legacy_disk_layout`; see `KnownErrorReason`).
 - `OperationFailedError`: an awaited operation ended `failed` or `canceled` (`errorCode`,
-  `operation`, `timing`).
-- `OperationTimeoutError`: waiting gave up; the operation continues (`operationId`, `timing`).
+  `retryable` **(0.6.2+)**, `operation`, `timing`). `retryable` is the operation error's own flag: `true` for
+  `capacity_unavailable` (no host could admit the start before its deadline; retry later), `false` for a definitive
+  failure.
+- `OperationTimeoutError`: waiting gave up; the operation continues (`operationId`, `lastState`, `lastReason`,
+  `deadlineAt` **(0.6.2+)** while it waits for capacity, `timing`).
 - `ShardfluxProtocolError`: a response was not the documented shape.
 
 Treat unknown error codes and reasons as generic errors: show `message`, and use `retryable`.

package/dist/client.d.ts

@@ -92,7 +92,11 @@ export interface ForkTarget {
     lifetime?: WorkspaceLifetime;
 }
 export interface WaitOptions {
-    /** Give up waiting after this long (default 300 000 ms); the operation continues server side. */
+    /**
+     * 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).
+     */
     timeoutMs?: number;
     /** First poll delay (default 250 ms); doubles up to `maxPollIntervalMs` with jitter. Used when the server does not wait. */
     pollIntervalMs?: number;
@@ -200,7 +204,9 @@ export declare class WorkspacesApi {
      * 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.
+     * 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.
      */
     waitForOperation(operationId: string, opts?: WaitOptions): Promise<Operation>;
     /** One operation (GET /v1/operations/{id}); lifecycle operations stay pollable after a workspace is deleted. */

package/dist/client.js

@@ -81,7 +81,8 @@ export class WorkspacesApi {
         const waitOpts = params.wait === false ? null : (params.wait ?? {});
         const trace = new Trace('open', combineListeners(this.#ctx().onProgress, params.onProgress, waitOpts?.onProgress));
         return traced(trace, async () => {
-            const init = { json: body, idempotencyKey: params.idempotencyKey ?? randomId('open-'), onRetry: trace.onRetry };
+            // The wait's signal also ends the held request (it can take up to 20 s), not only the polls after it.
+            const init = { json: body, idempotencyKey: params.idempotencyKey ?? randomId('open-'), onRetry: trace.onRetry, ...(waitOpts?.signal ? { signal: waitOpts.signal } : {}) };
             const started = Date.now();
             const timeoutMs = waitOpts?.timeoutMs ?? 300_000;
             if (waitOpts && waitOpts.serverWait !== false) {
@@ -169,13 +170,19 @@ export class WorkspacesApi {
      * 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.
+     * 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.
      */
     async waitForOperation(operationId, opts = {}) {
         const inherited = opts[TRACE];
         const trace = inherited ?? new Trace('wait', combineListeners(this.#ctx().onProgress, opts.onProgress), { operationId });
         const run = () => this.#poll(operationId, opts, trace);
-        return inherited ? run() : traced(trace, run);
+        if (inherited)
+            return run();
+        // A wait on its own starts with its first poll: a held poll can take seconds before the first state is known.
+        trace.phase('request');
+        return traced(trace, run);
     }
     async #poll(operationId, opts, trace) {
         const { sleep, http, authorization } = this.#ctx();

package/dist/errors.d.ts

@@ -53,13 +53,19 @@ type Operation = AppComponents['schemas']['Operation'];
 /**
  * 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
- * (it returns the same operation while it is active).
+ * (it returns the same operation while it is active). A start still waiting for capacity
+ * (`capacity_pending`) gives up at `deadlineAt` and then fails with `capacity_unavailable`.
  */
 export declare class OperationTimeoutError extends Error {
     readonly operationId: string;
     readonly workspaceId: string | null;
     readonly lastState: Operation['state'];
     readonly lastReason: string | null;
+    /**
+     * When the operation was last `capacity_pending`: when it gives up waiting for a host (`error.details.deadline_at`,
+     * RFC 3339) and fails with `capacity_unavailable`. Null in other states or from an API that does not report it.
+     */
+    readonly deadlineAt: string | null;
     readonly waitedMs: number;
     /** Where the time went: client phases, retries and the operation's own server timing so far. */
     timing: LifecycleTiming | undefined;
@@ -70,6 +76,12 @@ export declare class OperationFailedError extends Error {
     readonly operation: Operation;
     readonly operationId: string;
     readonly errorCode: string | null;
+    /**
+     * `operation.error.retryable` (false when absent): the same request may succeed later. `capacity_unavailable` is
+     * retryable: no host could admit the start before its deadline, nothing was started, retry later. The SDK never
+     * retries a failed operation itself.
+     */
+    readonly retryable: boolean;
     /** Where the time went before the operation failed. */
     timing: LifecycleTiming | undefined;
     constructor(op: Operation);

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { capacityDeadlineOf } from "./progress.js";
 export function isErrorBody(v) {
     if (typeof v !== 'object' || v === null || !('error' in v))
         return false;
@@ -45,23 +46,32 @@ export class ShardfluxProtocolError extends Error {
 /**
  * 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
- * (it returns the same operation while it is active).
+ * (it returns the same operation while it is active). A start still waiting for capacity
+ * (`capacity_pending`) gives up at `deadlineAt` and then fails with `capacity_unavailable`.
  */
 export class OperationTimeoutError extends Error {
     operationId;
     workspaceId;
     lastState;
     lastReason;
+    /**
+     * When the operation was last `capacity_pending`: when it gives up waiting for a host (`error.details.deadline_at`,
+     * RFC 3339) and fails with `capacity_unavailable`. Null in other states or from an API that does not report it.
+     */
+    deadlineAt;
     waitedMs;
     /** Where the time went: client phases, retries and the operation's own server timing so far. */
     timing = undefined;
     constructor(op, waitedMs) {
-        super(`Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; it continues server side.`);
+        const deadlineAt = capacityDeadlineOf(op);
+        const after = deadlineAt ? `it keeps waiting for a host server side until ${deadlineAt} and fails with capacity_unavailable if none admits it 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}`);
         this.name = 'OperationTimeoutError';
         this.operationId = op.id;
         this.workspaceId = op.workspace_id;
         this.lastState = op.state;
         this.lastReason = op.state_reason ?? null;
+        this.deadlineAt = deadlineAt;
         this.waitedMs = waitedMs;
     }
 }
@@ -70,6 +80,12 @@ export class OperationFailedError extends Error {
     operation;
     operationId;
     errorCode;
+    /**
+     * `operation.error.retryable` (false when absent): the same request may succeed later. `capacity_unavailable` is
+     * retryable: no host could admit the start before its deadline, nothing was started, retry later. The SDK never
+     * retries a failed operation itself.
+     */
+    retryable;
     /** Where the time went before the operation failed. */
     timing = undefined;
     constructor(op) {
@@ -79,5 +95,6 @@ export class OperationFailedError extends Error {
         this.operation = op;
         this.operationId = op.id;
         this.errorCode = code;
+        this.retryable = op.error?.retryable === true;
     }
 }