@shardflux/sdk 0.10.2 → 0.11.1

package/dist/tools.js

@@ -83,11 +83,11 @@ export function validateArgs(schema, value, path = '$') {
     return issues;
 }
 const ALL = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
-/** The tool permissions whose tools work on a file-first workspace (contracts §29.8): files and executions. */
+/** The tool permissions whose tools work on a file-first workspace: files and executions. */
 const FILE_FIRST_TOOLS = ['exec', 'files'];
 /** Changed paths returned to the model per execution (the rest is flagged `changed_truncated`). */
 const MAX_CHANGED_LISTED = 200;
-/** Tools served from a sleeping workspace's disk without waking it (contracts §26.4): the runner sends no hint. */
+/** Tools served from a sleeping workspace's disk without waking it: the runner sends no hint. */
 const DISK_READS = new Set(['read_file', 'list_files', 'search_files']);
 const obj = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
 const path = (description = 'Absolute path inside the workspace, e.g. /home/user/project/main.py') => ({ type: 'string', minLength: 1, maxLength: 4096, description });
@@ -107,7 +107,7 @@ export function workspaceTools(workspace, opts = {}) {
     });
     const max = opts.maxOutputBytes ?? 65_536;
     const prefix = opts.prefix ?? '';
-    // A file-first workspace (contracts §29) has files and executions only: no processes, terminals, version control or
+    // A file-first workspace has files and executions only: no processes, terminals, version control or
     // browser between calls, so those tools are not offered, and exec runs each command as an execution.
     const fileFirst = (opts.mode ?? workspace.mode) === 'file_first';
     const allowed = new Set((opts.tools ?? workspace.grantedTools ?? ALL).filter((t) => !fileFirst || FILE_FIRST_TOOLS.includes(t)));
@@ -436,7 +436,7 @@ export function workspaceTools(workspace, opts = {}) {
             const issues = validateArgs(d.parameters, args);
             if (issues.length > 0)
                 throw new ToolArgumentError(`${prefix}${d.name}`, issues);
-            // Fire and forget: a parked workspace starts restoring while this call is prepared (contracts §26.6). Not for
+            // Fire and forget: a parked workspace starts restoring while this call is prepared. Not for
             // the reads a sleeping workspace serves from its disk (§26.4): the hint would wake it for nothing.
             if (opts.hint !== false && !DISK_READS.has(d.name)) {
                 workspace

package/dist/version-check.d.ts

@@ -1,5 +1,5 @@
 /**
- * Client version check (contracts §30.4; 0.9.0+). `GET /v1/client-versions` (unauthenticated) lists every published
+ * Client version check (0.9.0+). `GET /v1/client-versions` (unauthenticated) lists every published
  * client with its `latest` and `minimum_supported` version.
  *
  *   const s = await checkClientVersion();            // @shardflux/sdk at SDK_VERSION

package/dist/volumes.d.ts

@@ -1,5 +1,5 @@
 /**
- * Shared volumes over the application API (/v1, contracts §15). Types come from
+ * Shared volumes over the application API (/v1). Types come from
  * the generated OpenAPI document (schemas `Volume` and `VolumeAttachment`).
  *
  * A volume is persistent shared storage (EFS-backed) owned by a project. It is

package/dist/workspace.d.ts

@@ -22,7 +22,7 @@ export interface WakeOptions {
     /** Progress of the wake: the resume request, observed states, conflicts retried, and `done` with the timing. */
     onProgress?: ProgressListener;
     /**
-     * The tool token the wake brings back (0.9.0): the held resume (contracts §22.6) returns one with the running
+     * The tool token the wake brings back (0.9.0): the held resume returns one with the running
      * workspace, for this agent label and tool set (defaults: those given to open()). It is kept for `cell()` clients of
      * the same label and tools, whose next call then needs no token request. A `cell()` client's own wake passes its
      * label and tools.
@@ -45,7 +45,7 @@ export interface HintOptions {
 }
 /** `workspace.hint()`: what the host found, or the background wake of a workspace that was not running. */
 export interface HintResult {
-    /** The VM's residency when the hint arrived (contracts §25.1); null when the workspace was not running. */
+    /** The VM's residency when the hint arrived; null when the workspace was not running. */
     residency: Residency | null;
     /**
      * The wake started in the background because the workspace was not running (409 `workspace_not_running`), else null.
@@ -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;
@@ -82,11 +84,11 @@ export declare class Workspace {
     get template(): WorkspaceView['template'];
     get pendingReason(): string | null;
     get activeOperation(): WorkspaceView['active_operation'];
-    /** persistent or session (contracts §19.11); immutable. A view without the field (older API) is persistent. */
+    /** persistent or session; immutable. A view without the field (older API) is persistent. */
     get lifetime(): WorkspaceLifetime;
-    /** standard, template_draft or template_test (contracts §19.9). */
+    /** standard, template_draft or template_test. */
     get purpose(): WorkspacePurpose;
-    /** legacy or layered (contracts §19.2); reset, save-as-template and changes need layered. */
+    /** legacy or layered; reset, save-as-template and changes need layered. */
     get diskLayout(): DiskLayout;
     /** Sessions: seconds without activity after which the session ends (null for persistent workspaces). */
     get idleTimeoutSeconds(): number | null;
@@ -95,7 +97,7 @@ export declare class Workspace {
     /** How a session ended (closed, idle_timeout, draft_discarded); null while live or for a plain delete. */
     get endedReason(): WorkspaceView['ended_reason'];
     /**
-     * Start commands and services of the workspace's template version (0.7.0; contracts §24.4): `state` pending, running,
+     * Start commands and services of the workspace's template version (0.7.0): `state` pending, running,
      * ready or failed (the failed step, its exit code, reason and output tail). Null when the version has neither, or on
      * an older API. A failed startup leaves the workspace running for inspection; the next open runs the failed step again.
      */
@@ -109,7 +111,7 @@ export declare class Workspace {
     /** The raw view (GET /v1/workspaces/{id}). */
     get data(): WorkspaceView;
     /**
-     * `processful` (one VM keeps processes, memory and files) or `file_first` (0.9.0; contracts §29: a versioned file
+     * `processful` (one VM keeps processes, memory and files) or `file_first` (0.9.0: a versioned file
      * tree, commands run as executions). Immutable. A view without the field (older API) is processful.
      */
     get mode(): WorkspaceMode;
@@ -121,7 +123,7 @@ export declare class Workspace {
      */
     get treeRevision(): number | null;
     /**
-     * Executions of this file-first workspace (contracts §29.8) through `cell()`'s default client: `run(argv, opts)` runs
+     * Executions of this file-first workspace through `cell()`'s default client: `run(argv, opts)` runs
      * a command in a fresh VM on the latest tree and returns an ExecutionResult (output, exit code, `changed`,
      * `treeRevision`); `get(id, { waitMs })` reads one. See CellClient.executions.
      *
@@ -152,7 +154,7 @@ export declare class Workspace {
     suspend(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     suspend(opts?: LifecycleOptions): Promise<Operation>;
     /**
-     * Suspends the workspace once it has been idle for `afterSeconds` (30..3600; 0.9.0): call it when your agent's turn
+     * Suspends the workspace once it has been idle for `afterSeconds` (0..3600, 0 = as soon as it is idle; 0.9.0): call it when your agent's turn
      * ends, so the workspace stops using RAM soon after instead of waiting out its idle policy. A command still running,
      * an attached stream or a keepalive postpones the suspend until `afterSeconds` after it ends; the next tool call (the
      * next turn) or a resume cancels it. Resolves with the recorded `suspendRequest` (also `workspace.suspendRequest`), or
@@ -170,9 +172,11 @@ export declare class Workspace {
     /**
      * Resumes a suspended workspace. Resolves when the resume is REQUESTED; with `{ wait: true }`, once the workspace runs.
      * 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:
+     * request: 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>;
@@ -206,7 +210,7 @@ export declare class Workspace {
     close(opts: WaitedLifecycleOptions): Promise<FinishedOperation | null>;
     close(opts?: LifecycleOptions): Promise<Operation | null>;
     /**
-     * Wipes every change in this layered workspace and restarts it on its template (contracts §19.12; sends
+     * Wipes every change in this layered workspace and restarts it on its template (sends
      * confirm_destructive). Returns the `reset` operation: requested, or with `{ wait: true }` finished. Tool tokens of
      * the old epoch are dropped.
      */
@@ -225,7 +229,7 @@ export declare class Workspace {
     captureToolCalls(opts?: ToolCallCaptureOptions): ToolCallCapture;
     /** Internal: waits for tool-call capture writes recorded so far (workspaceTools calls it before each tool). */
     [CAPTURE_BARRIER](): Promise<void> | undefined;
-    /** Saves this layered workspace as the next version of an organization template (contracts §19.8). */
+    /** Saves this layered workspace as the next version of an organization template. */
     saveAsTemplate(params: SaveAsTemplateParams): Promise<SaveAsTemplateResponse>;
     /**
      * The workspace's changes against its template (cell gateway GET /v1/workspaces/{id}/changes; needs the `files` tool).
@@ -251,26 +255,31 @@ export declare class Workspace {
         tools?: ToolName[];
     } & CellClientOptions): CellClient;
     /**
-     * Makes a suspended (or suspending/resuming) workspace run again and resolves once it does (contracts §20.4): resume,
+     * Makes a suspended (or suspending/resuming) workspace run again and resolves once it does: resume,
      * or join the active resume/open; an active suspend (or other operation) is waited out first. Resolves `true` when it
      * resumed or waited for a lifecycle operation, `false` when the workspace was already running. One deadline
      * (`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`. A resume no
-     * host admits within 15 minutes fails with `capacity_unavailable` (OperationFailedError, `retryable`: the workspace
-     * stays suspended with its state; try again later).
+     * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`. A queued
+     * resume has a deadline 15 minutes after it was created; past it, it fails with `capacity_unavailable`
+     * (OperationFailedError, `retryable`: nothing was started and the workspace stays suspended with its state; send it
+     * again).
      *
-     * Since 0.9.0 the resume is held by the server until the workspace runs (contracts §22.6): one request returns the
+     * Since 0.9.0 the resume is held by the server until the workspace runs: one request returns the
      * 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>;
     /**
-     * Announces an imminent tool call (cell `POST /wake-hint`, contracts §26.6; 0.9.0+) so a parked workspace is restored
+     * Announces an imminent tool call (cell `POST /wake-hint`; 0.9.0+) so a parked workspace is restored
      * ahead of it: call it when the model starts emitting a tool call, before its arguments are complete. The agent tools
-     * of `workspaceTools()` send it when a call starts. Cheap and best effort: it returns what the host found. A workspace
+     * of `workspaceTools()` send it when a call starts. Cheap and non-blocking: it returns what the host found. A workspace
      * that is not running (suspended, or a token cannot be issued for it) is woken in the background (`wake`, not awaited
      * here) so the call finds it running sooner. Other errors (network, auth) are thrown; callers that fire and forget
      * should catch them.

package/dist/workspace.js

@@ -33,7 +33,7 @@ export class Workspace {
         if (this.#treeRevision === null || rev > this.#treeRevision)
             this.#treeRevision = rev;
     }
-    /** The local refusal of a lifecycle call a file-first workspace does not have (contracts §29.7). */
+    /** The local refusal of a lifecycle call a file-first workspace does not have. */
     #needsVm(operation) {
         if (this.#view.mode !== 'file_first')
             return null;
@@ -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;
@@ -100,15 +102,15 @@ export class Workspace {
     get activeOperation() {
         return this.#view.active_operation;
     }
-    /** persistent or session (contracts §19.11); immutable. A view without the field (older API) is persistent. */
+    /** persistent or session; immutable. A view without the field (older API) is persistent. */
     get lifetime() {
         return this.#view.lifetime ?? 'persistent';
     }
-    /** standard, template_draft or template_test (contracts §19.9). */
+    /** standard, template_draft or template_test. */
     get purpose() {
         return this.#view.purpose ?? 'standard';
     }
-    /** legacy or layered (contracts §19.2); reset, save-as-template and changes need layered. */
+    /** legacy or layered; reset, save-as-template and changes need layered. */
     get diskLayout() {
         return this.#view.disk_layout ?? 'legacy';
     }
@@ -125,7 +127,7 @@ export class Workspace {
         return this.#view.ended_reason ?? null;
     }
     /**
-     * Start commands and services of the workspace's template version (0.7.0; contracts §24.4): `state` pending, running,
+     * Start commands and services of the workspace's template version (0.7.0): `state` pending, running,
      * ready or failed (the failed step, its exit code, reason and output tail). Null when the version has neither, or on
      * an older API. A failed startup leaves the workspace running for inspection; the next open runs the failed step again.
      */
@@ -145,7 +147,7 @@ export class Workspace {
         return this.#view;
     }
     /**
-     * `processful` (one VM keeps processes, memory and files) or `file_first` (0.9.0; contracts §29: a versioned file
+     * `processful` (one VM keeps processes, memory and files) or `file_first` (0.9.0: a versioned file
      * tree, commands run as executions). Immutable. A view without the field (older API) is processful.
      */
     get mode() {
@@ -161,7 +163,7 @@ export class Workspace {
         return this.mode === 'file_first' ? this.#treeRevision : null;
     }
     /**
-     * Executions of this file-first workspace (contracts §29.8) through `cell()`'s default client: `run(argv, opts)` runs
+     * Executions of this file-first workspace through `cell()`'s default client: `run(argv, opts)` runs
      * a command in a fresh VM on the latest tree and returns an ExecutionResult (output, exit code, `changed`,
      * `treeRevision`); `get(id, { waitMs })` reads one. See CellClient.executions.
      *
@@ -202,7 +204,7 @@ export class Workspace {
         return this.#ctx.workspaces.suspend(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
     /**
-     * Suspends the workspace once it has been idle for `afterSeconds` (30..3600; 0.9.0): call it when your agent's turn
+     * Suspends the workspace once it has been idle for `afterSeconds` (0..3600, 0 = as soon as it is idle; 0.9.0): call it when your agent's turn
      * ends, so the workspace stops using RAM soon after instead of waiting out its idle policy. A command still running,
      * an attached stream or a keepalive postpones the suspend until `afterSeconds` after it ends; the next tool call (the
      * next turn) or a resume cancels it. Resolves with the recorded `suspendRequest` (also `workspace.suspendRequest`), or
@@ -235,7 +237,7 @@ export class Workspace {
         const manager = this.tokens({ ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}), ...(opts.tools !== undefined ? { tools: opts.tools } : {}) });
         return this.#ctx.workspaces.resume(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait(), [HELD_RESUME]: this.#heldTarget(manager) });
     }
-    /** A held resume's 200 (contracts §22.6) goes straight into this handle: the view, and the token for `manager`. */
+    /** A held resume's 200 goes straight into this handle: the view, and the token for `manager`. */
     #heldTarget(manager) {
         return {
             agentLabel: manager.agentLabel,
@@ -313,7 +315,7 @@ export class Workspace {
     [CAPTURE_BARRIER]() {
         return this.#ctx.captures.settle(this.id);
     }
-    /** Saves this layered workspace as the next version of an organization template (contracts §19.8). */
+    /** Saves this layered workspace as the next version of an organization template. */
     saveAsTemplate(params) {
         const refusal = this.#needsVm('save_as_template');
         if (refusal)
@@ -376,23 +378,28 @@ export class Workspace {
         return c;
     }
     /**
-     * Makes a suspended (or suspending/resuming) workspace run again and resolves once it does (contracts §20.4): resume,
+     * Makes a suspended (or suspending/resuming) workspace run again and resolves once it does: resume,
      * or join the active resume/open; an active suspend (or other operation) is waited out first. Resolves `true` when it
      * resumed or waited for a lifecycle operation, `false` when the workspace was already running. One deadline
      * (`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`. A resume no
-     * host admits within 15 minutes fails with `capacity_unavailable` (OperationFailedError, `retryable`: the workspace
-     * stays suspended with its state; try again later).
+     * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`. A queued
+     * resume has a deadline 15 minutes after it was created; past it, it fails with `capacity_unavailable`
+     * (OperationFailedError, `retryable`: nothing was started and the workspace stays suspended with its state; send it
+     * again).
      *
-     * Since 0.9.0 the resume is held by the server until the workspace runs (contracts §22.6): one request returns the
+     * Since 0.9.0 the resume is held by the server until the workspace runs: one request returns the
      * 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.
+        // A file-first workspace runs from creation and is never suspended: nothing to wake.
         if (this.#view.mode === 'file_first')
             return false;
         const trace = new Trace('wake', combineListeners(this.#ctx.onProgress, this.#tracked(opts).onProgress), { workspaceId: this.id });
@@ -409,7 +416,7 @@ export class Workspace {
                 throw opts.signal.reason;
             let active;
             try {
-                // Held resume (contracts §22.6): answered once the workspace runs, with the view and a token; it returns the
+                // Held resume: answered once the workspace runs, with the view and a token; it returns the
                 // active resume/open when there is one, so concurrent wakes join a single operation. The request is made here
                 // rather than through resume() so the wake is one trace.
                 const waitS = Math.min(SERVER_WAIT_MAX_S, Math.floor((deadline - Date.now()) / 1000));
@@ -467,9 +474,9 @@ export class Workspace {
         throw new Error(`workspace ${this.id} did not become runnable after repeated lifecycle conflicts`);
     }
     /**
-     * Announces an imminent tool call (cell `POST /wake-hint`, contracts §26.6; 0.9.0+) so a parked workspace is restored
+     * Announces an imminent tool call (cell `POST /wake-hint`; 0.9.0+) so a parked workspace is restored
      * ahead of it: call it when the model starts emitting a tool call, before its arguments are complete. The agent tools
-     * of `workspaceTools()` send it when a call starts. Cheap and best effort: it returns what the host found. A workspace
+     * of `workspaceTools()` send it when a call starts. Cheap and non-blocking: it returns what the host found. A workspace
      * that is not running (suspended, or a token cannot be issued for it) is woken in the background (`wake`, not awaited
      * here) so the call finds it running sooner. Other errors (network, auth) are thrown; callers that fire and forget
      * should catch them.

package/package.json

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