@shardflux/sdk 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -3,7 +3,17 @@
 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.1 (not yet published; npm `latest` is 0.6.0)
+
+- `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.1. 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`.
 
@@ -184,9 +184,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.

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) {
@@ -175,7 +176,11 @@ export class WorkspacesApi {
         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/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.1";
 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.1';
 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/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;
@@ -157,9 +157,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

@@ -202,9 +202,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 +213,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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",