@shardflux/sdk 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -3,7 +3,30 @@
 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.10.2 (not yet published)
+## 0.11.0 (not yet published)
+
+### A resume that restarted processes says so (cold boot, contracts §12)
+
+Additive. When the platform's VM runtime changed after a suspend and no host can restore the memory snapshot, the
+cell resumes the workspace by booting its checkpoint's disk (a cold boot), automatically, also when a tool call wakes
+the workspace. The workspace runs and its files are as of the suspend, but every process was restarted. The API passes
+the resume's result through; this release reads it.
+
+- `ServerTiming.memoryRestored` (`boolean | null`): `result.memory_restored`. `true` when memory and running
+  processes came back; `false` for `cold_boot` (and `reset_blank_layer`); `null` when the result does not say (an API
+  from before the field), never read as `false`.
+- `ServerTiming.coldBootReason` (`string | null`): `result.cold_boot_reason` with `resumePath` `cold_boot`, today
+  `runtime_changed`.
+- `ServerTiming.resumePath` documents `cold_boot` and `reset_blank_layer`.
+- `formatTiming()` prints `resume from cold_boot: processes restarted (runtime_changed)` when memory was not restored;
+  other resumes print as before.
+- Where it shows: `workspace.lastTiming` and the `done` progress event after `resume({ wait: true })`, `wake()` and a
+  tool call that woke the workspace; the finished resume operation's `result` (`memory_restored`,
+  `cold_boot_reason`, and `cold_boot` with operator details such as `files_as_of`, whose shape may change).
+- The new `ServerTiming` fields are optional in the type (always set by the SDK), so timings built by hand still
+  type-check. No return type or behaviour changes: a wake that cold-booted still resolves `true`.
+
+## 0.10.2
 
 Fix: the SDK reports 0.10.2. 0.10.1 was published reporting 0.10.0, its previous version; the build now
 fails when `SDK_VERSION` differs from package.json.

package/README.md

@@ -10,7 +10,7 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 > **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.10.2. Anything marked **(0.10.0+)** is not in 0.9.0, **(0.9.0+)** not in 0.8.x, **(0.8.0+)** not in 0.7.x,
+> **Versions.** This README describes 0.11.0. Anything marked **(0.11.0+)** is not in 0.10.x, **(0.10.0+)** not in 0.9.0, **(0.9.0+)** not in 0.8.x, **(0.8.0+)** not in 0.7.x,
 > **(0.7.0+)** not in 0.6.x and **(0.6.0+)** 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`.
 
@@ -64,7 +64,8 @@ console.log(formatTiming(again.lastTiming!));            // (0.6.0+) where the r
 ```
 
 `open()` waits until the workspace is running. Opening the same key again never resets it: files,
-installed packages and running processes are still there. The same program is in
+installed packages and running processes are still there (a resume restarts processes only in the rare cold boot,
+see "A resume can restart processes" below). The same program is in
 [`examples/quickstart.ts`](./examples/quickstart.ts).
 
 With 0.5.0, wait for the suspend by its operation instead:
@@ -266,6 +267,26 @@ const cell = workspace.cell({ transitionTimeoutMs: 30_000 }); // give up waking
 await cell.exec.run(['make', 'test']);                         // resumes the workspace first if it is suspended
 ```
 
+**A resume can restart processes (0.11.0+).** A resume normally restores memory and running processes from the
+checkpoint. When the platform's VM runtime changed after the suspend and no host can restore that memory snapshot, the
+resume boots the checkpoint's disk instead (a cold boot), automatically, also when a tool call wakes the workspace. The
+workspace runs, its files are as of the suspend, but every process was restarted, as after a reboot: start dev
+servers, databases and background jobs again. You can tell from the resume's timing:
+
+```ts
+const t = workspace.lastTiming; // after resume({ wait: true }), wake(), or a tool call that woke the workspace
+if (t?.server?.memoryRestored === false) {
+  // t.server.resumePath === 'cold_boot', t.server.coldBootReason === 'runtime_changed'
+}
+```
+
+- `ServerTiming.memoryRestored`: `true` when memory and processes came back, `false` when the workspace booted
+  (`resumePath` `cold_boot`, or `reset_blank_layer` after a reset), `null` when the API did not say (older APIs).
+- `ServerTiming.coldBootReason`: why it booted (`runtime_changed`), else null. `formatTiming()` prints
+  `resume from cold_boot: processes restarted (runtime_changed)`.
+- The finished resume operation carries the same in `result` (`memory_restored`, `cold_boot_reason`, and
+  `cold_boot` with details such as `files_as_of`; its shape may change, so do not depend on it).
+
 `suspend`, `resume`, `fork`, `snapshot` and `delete` return the lifecycle operation.
 `cloud.workspaces.waitForOperation(id)` waits for it (default timeout 5 minutes): each poll asks the API to hold
 the response until the operation changes (`Prefer: wait`, at most 20 s per request), so completion arrives within
@@ -320,7 +341,8 @@ Here the time went to waiting for a host with capacity; the network and the VM s
   issuing the first tool token (together).
 - **server** timing comes from the operation itself (one database clock): `queued` is creation until it began
   running, including any wait for capacity; `ran` is the cell's work (placement, boot or restore, guest readiness).
-  `start` / `resume from` and `boot to ready` / `host …` are what the cell reported.
+  `start` / `resume from` and `boot to ready` / `host …` are what the cell reported. A resume that booted the saved
+  disk instead of restoring memory reads `resume from cold_boot: processes restarted (runtime_changed)` (0.11.0+).
 - **outside the server** is your total minus the operation's: network, TLS, polling latency, view and token. A large
   value with a small server total points at the connection between you and the API, not at the workspace.
 - **retries** lists transient failures the SDK retried (cause and backoff).

package/dist/http.d.ts

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

package/dist/http.js

@@ -8,7 +8,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.10.2';
+export const SDK_VERSION = '0.11.0';
 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

@@ -70,8 +70,25 @@ 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`, `prestaged` (copied to this host ahead of the resume, contracts §23) 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),
+     * `download` (the checkpoint had to be fetched first), `cold_boot` (0.11.0+: no host could restore the memory
+     * snapshot, so the checkpoint's disk was booted; see `memoryRestored`) or `reset_blank_layer` (the first start after
+     * a reset).
+     */
     resumePath: string | null;
+    /**
+     * `result.memory_restored` (0.11.0+): `true` when memory and running processes came back from the checkpoint;
+     * `false` when the workspace booted instead (`cold_boot`, `reset_blank_layer`): its files are as of the suspend, but
+     * every process was restarted, as after a reboot. `null` when the result does not say (an older API, or not a
+     * resume). Always set by `serverTiming()`; optional only so timings built by hand still type-check.
+     */
+    memoryRestored?: boolean | null;
+    /**
+     * `result.cold_boot_reason` (0.11.0+), with `resumePath` `cold_boot`: why the memory could not be restored, e.g.
+     * `runtime_changed` (the platform's VM runtime changed after the suspend). Null otherwise.
+     */
+    coldBootReason?: string | null;
     /** `result.boot_to_ready_ms`: VM start until the guest agent answered. */
     bootToReadyMs: number | null;
     /** `result.host_timings_ms`: the host's own steps (restore: load, after_restore, ready, …). */
@@ -175,6 +192,9 @@ export declare function traced<T>(trace: Trace, fn: () => Promise<T>): Promise<T
  *     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)
+ *
+ * A resume that booted the workspace instead of restoring its memory (0.11.0+) says so in the server line:
+ * `resume from cold_boot: processes restarted (runtime_changed)`.
  */
 export declare function formatTiming(t: LifecycleTiming): string;
 export {};

package/dist/progress.js

@@ -63,6 +63,9 @@ export function serverTiming(op) {
         startPath: str(r.start_path),
         warmFallback: str(r.warm_fallback),
         resumePath: str(r.resume_path),
+        // Unknown (null) unless the result says so: a result without the field is never read as "not restored".
+        memoryRestored: typeof r.memory_restored === 'boolean' ? r.memory_restored : null,
+        coldBootReason: str(r.cold_boot_reason),
         bootToReadyMs: num(r.boot_to_ready_ms),
         hostTimingsMs,
     };
@@ -222,6 +225,9 @@ const fmt = (ms) => (ms === null ? '?' : ms < 1000 ? `${Math.round(ms)} 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)
+ *
+ * A resume that booted the workspace instead of restoring its memory (0.11.0+) says so in the server line:
+ * `resume from cold_boot: processes restarted (runtime_changed)`.
  */
 export function formatTiming(t) {
     const ids = [t.workspaceId ? `workspace ${t.workspaceId}` : null, t.operationId ? `operation ${t.operationId}` : null].filter(Boolean).join(', ');
@@ -242,7 +248,7 @@ export function formatTiming(t) {
         const parts = [s.queuedMs !== null ? `queued ${fmt(s.queuedMs)}` : null, s.runMs !== null ? `ran ${fmt(s.runMs)}` : null, s.totalMs !== null ? `total ${fmt(s.totalMs)}` : `still ${s.state}`];
         const how = [
             s.startPath ? `start ${s.startPath}${s.warmFallback ? ` (warm fallback: ${s.warmFallback})` : ''}` : null,
-            s.resumePath ? `resume from ${s.resumePath}` : null,
+            s.resumePath ? `resume from ${s.resumePath}${s.memoryRestored === false ? `: processes restarted${s.coldBootReason ? ` (${s.coldBootReason})` : ''}` : ''}` : null,
             s.bootToReadyMs !== null ? `boot to ready ${fmt(s.bootToReadyMs)}` : null,
             s.hostTimingsMs ? `host ${Object.entries(s.hostTimingsMs).map(([k, v]) => `${k} ${fmt(v)}`).join(', ')}` : null,
         ].filter(Boolean);

package/dist/workspace.d.ts

@@ -65,7 +65,9 @@ export declare class Workspace {
     /**
      * Where the time went in the last lifecycle call made through this handle: open(), wake() (also when a tool call
      * woke the workspace), or a lifecycle call with `wait`. Null for handles from get()/list() until such a call.
-     * `formatTiming(workspace.lastTiming)` prints it.
+     * `formatTiming(workspace.lastTiming)` prints it. After a resume or wake, `server.memoryRestored === false` (0.11.0+)
+     * means the workspace booted from its saved disk instead of restoring its memory (`server.resumePath` `cold_boot`,
+     * reason in `server.coldBootReason`): files are as of the suspend, running processes were restarted.
      */
     get lastTiming(): LifecycleTiming | null;
     get id(): string;
@@ -172,7 +174,9 @@ export declare class Workspace {
      * Tool calls wake a suspended workspace by themselves, so this is rarely needed. With `wait` (0.9.0) it is one held
      * request (contracts §22.6): the handle takes the running view and a tool token for `agentLabel`/`tools` (defaults:
      * those given to open()), so `cell()` calls with that label and tools start at once. A workspace that is already
-     * running is ShardfluxApiError 409 `conflict` (`already_running`).
+     * running is ShardfluxApiError 409 `conflict` (`already_running`). The finished operation's `result.memory_restored`
+     * (also `lastTiming.server.memoryRestored`, 0.11.0+) is false when the resume booted the saved disk instead
+     * (`resume_path` `cold_boot`): files kept, processes restarted.
      */
     resume(opts: WaitedResumeOptions): Promise<FinishedOperation>;
     resume(opts?: ResumeOptions): Promise<Operation>;
@@ -265,6 +269,10 @@ export declare class Workspace {
      * running workspace and a tool token for `agentLabel`/`tools`, which this handle keeps, so a tool call that woke the
      * workspace is retried at once (refused call, resume, call). Timing: one `request` phase with reason `held`. A server
      * that does not hold the request answers at once; the wake then waits for the operation and reads the view.
+     *
+     * A wake whose resume could not restore the workspace's memory (0.11.0+; the platform's VM runtime changed after the
+     * suspend) still resolves `true`: the workspace runs from its saved disk, with every process restarted. `lastTiming`
+     * and the `done` progress event say so (`server.memoryRestored === false`, `server.resumePath` `cold_boot`).
      */
     wake(opts?: WakeOptions): Promise<boolean>;
     /**

package/dist/workspace.js

@@ -42,7 +42,9 @@ export class Workspace {
     /**
      * Where the time went in the last lifecycle call made through this handle: open(), wake() (also when a tool call
      * woke the workspace), or a lifecycle call with `wait`. Null for handles from get()/list() until such a call.
-     * `formatTiming(workspace.lastTiming)` prints it.
+     * `formatTiming(workspace.lastTiming)` prints it. After a resume or wake, `server.memoryRestored === false` (0.11.0+)
+     * means the workspace booted from its saved disk instead of restoring its memory (`server.resumePath` `cold_boot`,
+     * reason in `server.coldBootReason`): files are as of the suspend, running processes were restarted.
      */
     get lastTiming() {
         return this.#lastTiming ?? this.#openTrace?.finished ?? null;
@@ -390,6 +392,10 @@ export class Workspace {
      * running workspace and a tool token for `agentLabel`/`tools`, which this handle keeps, so a tool call that woke the
      * workspace is retried at once (refused call, resume, call). Timing: one `request` phase with reason `held`. A server
      * that does not hold the request answers at once; the wake then waits for the operation and reads the view.
+     *
+     * A wake whose resume could not restore the workspace's memory (0.11.0+; the platform's VM runtime changed after the
+     * suspend) still resolves `true`: the workspace runs from its saved disk, with every process restarted. `lastTiming`
+     * and the `done` progress event say so (`server.memoryRestored === false`, `server.resumePath` `cold_boot`).
      */
     async wake(opts = {}) {
         // A file-first workspace runs from creation and is never suspended (contracts §29.7): nothing to wake.

package/package.json

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