@shardflux/sdk 0.6.0 → 0.6.2

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.6.2";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;

package/dist/http.js

@@ -6,7 +6,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.6.0';
+export const SDK_VERSION = '0.6.2';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends

package/dist/lifecycle.d.ts

@@ -20,7 +20,8 @@ export interface LifecycleOptions {
     /**
      * Default (false): resolve once the change is requested; the returned operation is usually still `queued`.
      * `true` or WaitOptions: resolve once it has finished (the operation `succeeded`); throws OperationFailedError when it
-     * fails and OperationTimeoutError after `timeoutMs` (default 5 minutes; the operation continues server side).
+     * fails and OperationTimeoutError after `timeoutMs` (default 5 minutes; the operation continues server side, a start
+     * waiting for capacity until its deadline, then it fails with `capacity_unavailable`, retryable).
      */
     wait?: boolean | WaitOptions;
     /** Progress events of this call (phases, retries, and `done` with its timing). */

package/dist/progress.d.ts

@@ -68,7 +68,7 @@ export interface ServerTiming {
     startPath: string | null;
     /** `result.warm_fallback`: why a start that could be warm booted instead. */
     warmFallback: string | null;
-    /** `result.resume_path`: `local_cache` or `download` (the checkpoint had to be fetched first). */
+    /** `result.resume_path`: `local_cache`, `prestaged` (copied to this host ahead of the resume, contracts §23) or `download` (the checkpoint had to be fetched first). */
     resumePath: string | null;
     /** `result.boot_to_ready_ms`: VM start until the guest agent answered. */
     bootToReadyMs: number | null;
@@ -104,6 +104,8 @@ interface EventBase {
 }
 /**
  * - `phase`: a phase began (live progress: "capacity_pending: no_ready_host"). `tool` phases come from tool calls.
+ *   A `capacity_pending` phase carries `deadlineAt` (0.6.2+, when the API reports it): when the start gives up waiting
+ *   for a host and fails with `capacity_unavailable` (retryable; nothing was started).
  * - `retry`: a request is retried after a transient failure (also emitted for tool calls, action `tool`).
  * - `done`: the call ended, successfully or not, with its full timing.
  */
@@ -111,6 +113,7 @@ export type ProgressEvent = (EventBase & {
     type: 'phase';
     phase: LifecyclePhase;
     reason: string | null;
+    deadlineAt?: string;
 }) | (EventBase & {
     type: 'retry';
     retry: RetryRecord;
@@ -123,6 +126,12 @@ export type ProgressListener = (event: ProgressEvent) => void;
 export declare function emitTo(listeners: ReadonlyArray<ProgressListener | undefined>, event: ProgressEvent): void;
 /** Combines listeners (client-level and per call) into one; undefined when there are none. */
 export declare function combineListeners(...listeners: Array<ProgressListener | undefined>): ProgressListener | undefined;
+/**
+ * When a start waiting in `capacity_pending` gives up: the operation's `error.details.deadline_at` (RFC 3339). A start no
+ * host admits by then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or
+ * from an API that does not report it.
+ */
+export declare function capacityDeadlineOf(op: Operation): string | null;
 /** Server timing from an operation as GET /v1/operations/{id} returns it. */
 export declare function serverTiming(op: Operation): ServerTiming;
 /** Why a request failed, in one short phrase (for retry records). */
@@ -139,8 +148,11 @@ export declare class Trace {
     /** Milliseconds since the call began. */
     now(): number;
     get finished(): LifecycleTiming | null;
-    /** Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase. */
-    phase(phase: LifecyclePhase, reason?: string | null): void;
+    /**
+     * Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase.
+     * `deadlineAt`: when a `capacity_pending` start gives up (added to the event only).
+     */
+    phase(phase: LifecyclePhase, reason?: string | null, deadlineAt?: string | null): void;
     /** Runs `fn` as a phase that may overlap others (open() reads the view and issues the token together). */
     span<T>(phase: LifecyclePhase, fn: () => Promise<T>, reason?: string | null): Promise<T>;
     /** Records an operation snapshot: its ids, the observed state as a phase, and the server timing. */
@@ -157,9 +169,9 @@ export declare function traced<T>(trace: Trace, fn: () => Promise<T>): Promise<T
  * A human-readable account of a timing, for logs and bug reports:
  *
  *   open 34.18 s, succeeded (workspace <id>, operation <id>)
- *     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
  *     retries: 1 (POST /v1/workspaces/open, HTTP 503 unavailable, after 200 ms)
  */
 export declare function formatTiming(t: LifecycleTiming): string;

package/dist/progress.js

@@ -30,6 +30,17 @@ function diffMs(from, to) {
 }
 const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+/**
+ * When a start waiting in `capacity_pending` gives up: the operation's `error.details.deadline_at` (RFC 3339). A start no
+ * host admits by then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or
+ * from an API that does not report it.
+ */
+export function capacityDeadlineOf(op) {
+    if (op.state !== 'capacity_pending')
+        return null;
+    const details = op.error?.details;
+    return typeof details === 'object' && details !== null ? str(details.deadline_at) : null;
+}
 /** Server timing from an operation as GET /v1/operations/{id} returns it. */
 export function serverTiming(op) {
     const r = (op.result ?? {});
@@ -113,8 +124,11 @@ export class Trace {
             this.#current.durationMs = round(at - this.#current.startMs);
         this.#current = null;
     }
-    /** Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase. */
-    phase(phase, reason = null) {
+    /**
+     * Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase.
+     * `deadlineAt`: when a `capacity_pending` start gives up (added to the event only).
+     */
+    phase(phase, reason = null, deadlineAt = null) {
         if (this.#timing)
             return;
         if (this.#current && this.#current.phase === phase && this.#current.reason === reason)
@@ -123,7 +137,7 @@ export class Trace {
         this.#close(at);
         this.#current = { phase, reason, operationId: this.operationId, startMs: at, durationMs: 0 };
         this.#phases.push(this.#current);
-        this.#emit({ ...this.#base(), type: 'phase', phase, reason });
+        this.#emit({ ...this.#base(), type: 'phase', phase, reason, ...(deadlineAt ? { deadlineAt } : {}) });
     }
     /** Runs `fn` as a phase that may overlap others (open() reads the view and issues the token together). */
     async span(phase, fn, reason = null) {
@@ -145,7 +159,7 @@ export class Trace {
         this.workspaceId ??= op.workspace_id;
         this.#server = serverTiming(op);
         if (!TERMINAL.has(op.state))
-            this.phase(op.state, op.state_reason ?? null);
+            this.phase(op.state, op.state_reason ?? null, capacityDeadlineOf(op));
     }
     retry(r) {
         if (this.#timing)
@@ -202,9 +216,9 @@ const fmt = (ms) => (ms === null ? '?' : ms < 1000 ? `${Math.round(ms)} ms` : `$
  * A human-readable account of a timing, for logs and bug reports:
  *
  *   open 34.18 s, succeeded (workspace <id>, operation <id>)
- *     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
  *     retries: 1 (POST /v1/workspaces/open, HTTP 503 unavailable, after 200 ms)
  */
 export function formatTiming(t) {
@@ -213,8 +227,10 @@ export function formatTiming(t) {
     let client = '';
     t.phases.forEach((p, i) => {
         const prev = t.phases[i - 1];
-        // A phase that starts before the previous one ended ran alongside it (view and token at the end of open()).
-        const sep = i === 0 ? '' : prev && p.startMs < prev.startMs + prev.durationMs ? ' ∥ ' : ' → ';
+        // A phase that starts before the previous one ended ran alongside it (view and token at the end of open()). Times
+        // are 0.1 ms values, so a phase that follows another can appear to start a float error early (1000.2 + 300.1 >
+        // 1300.3): overlap must exceed that.
+        const sep = i === 0 ? '' : prev && p.startMs < prev.startMs + prev.durationMs - 0.05 ? ' ∥ ' : ' → ';
         client += `${sep}${p.phase} ${fmt(p.durationMs)}${p.reason ? ` (${p.reason})` : ''}`;
     });
     if (client)

package/dist/workspace.d.ts

@@ -154,7 +154,9 @@ export declare class Workspace {
      * (`timeoutMs`, default 120 000 ms) covers every step. Throws OperationFailedError when the resume/open fails,
      * OperationTimeoutError (naming the operation, its state and reason) when it is still queued, running or
      * capacity_pending at the deadline, and any other API error (a conflict other than already_running /
-     * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`.
+     * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`. A resume no
+     * host admits within 15 minutes fails with `capacity_unavailable` (OperationFailedError, `retryable`: the workspace
+     * stays suspended with its state; try again later).
      */
     wake(opts?: WakeOptions): Promise<boolean>;
     /** Tools granted by the most recent token (null before one was issued). */

package/dist/workspace.js

@@ -217,7 +217,9 @@ export class Workspace {
      * (`timeoutMs`, default 120 000 ms) covers every step. Throws OperationFailedError when the resume/open fails,
      * OperationTimeoutError (naming the operation, its state and reason) when it is still queued, running or
      * capacity_pending at the deadline, and any other API error (a conflict other than already_running /
-     * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`.
+     * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`. A resume no
+     * host admits within 15 minutes fails with `capacity_unavailable` (OperationFailedError, `retryable`: the workspace
+     * stays suspended with its state; try again later).
      */
     async wake(opts = {}) {
         const trace = new Trace('wake', combineListeners(this.#ctx.onProgress, this.#tracked(opts).onProgress), { workspaceId: this.id });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "type": "module",
   "description": "Shardflux TypeScript SDK: open persistent agent workspaces by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
   "license": "Apache-2.0",