@shardflux/sdk 0.11.0 → 0.12.0

package/dist/workspace.d.ts

@@ -2,12 +2,12 @@
  * A workspace handle: the latest view from the application API plus managed
  * tool tokens and cell clients (one per agent label / tool set).
  */
-import type { ClientContext, DiskLayout, ForkTarget, Operation, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
+import type { ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
 import { CAPTURE_BARRIER, CellClient } from './cell.js';
 import { ToolCallCapture } from './capture.js';
 import type { ToolCallCaptureOptions } from './capture.js';
 import type { WorkspaceMode } from './errors.js';
-import type { FinishedOperation, LifecycleOptions, ResumeOptions, WaitedLifecycleOptions, WaitedResumeOptions } from './lifecycle.js';
+import type { FinishedOperation, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 import { Trace } from './progress.js';
 import type { LifecycleTiming, ProgressListener } from './progress.js';
 import { WorkspaceSecrets } from './secrets.js';
@@ -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.
@@ -84,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;
@@ -97,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.
      */
@@ -111,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;
@@ -123,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.
      *
@@ -135,11 +135,20 @@ export declare class Workspace {
     get secrets(): WorkspaceSecrets;
     /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
     inputs(): Promise<Record<string, string>>;
+    get labels(): Record<string, string>;
+    setLabels(labels: Record<string, string>): Promise<this>;
+    setIdlePolicy(policy: IdlePolicy | null): Promise<this>;
+    idle(signal?: AbortSignal): ReturnType<CellClient['idle']>;
+    keepalive(seconds: number, signal?: AbortSignal): ReturnType<CellClient['keepalive']>;
     refresh(): Promise<this>;
-    /** Waits for the active operation (if any) and refreshes. */
+    /**
+     * Waits for the active operation (if any) and refreshes. A suspend-when-idle that found the workspace active is
+     * canceled `workspace_active` (0.12.0+: `OperationFailedError.workspaceActive`); the workspace keeps running, so this
+     * resolves.
+     */
     waitUntilReady(opts?: WaitOptions): Promise<this>;
     /**
-     * Deletes the workspace (tool access ends at once; keys are never reused). Resolves when the delete is REQUESTED;
+     * Deletes the workspace (tool access ends at once; the key can be reused after deletion finishes). Resolves when the delete is REQUESTED;
      * with `{ wait: true }`, once it has FINISHED.
      */
     delete(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
@@ -147,14 +156,17 @@ export declare class Workspace {
     /**
      * Suspends the workspace: memory and processes are checkpointed, compute stops. Resolves when the suspend is
      * REQUESTED (the operation is usually still `queued`, and the workspace still running); pass `{ wait: true }` to
-     * resolve once it has FINISHED, with `workspace.state` then `suspended`.
+     * resolve once it has FINISHED, with `workspace.state` then `suspended`. That is as soon as the workspace is sealed on
+     * its host, typically in a few hundred ms. `result.durable` (also `lastTiming.server.durable`, 0.12.0+) turns true
+     * when the copy lands in durable storage, typically within a second; `{ durable: true }` resolves only then.
      *
      *   await workspace.suspend({ wait: true });
+     *   await workspace.suspend({ durable: true }); // 0.12.0+: also wait for the durable copy
      */
-    suspend(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
-    suspend(opts?: LifecycleOptions): Promise<Operation>;
+    suspend(opts: WaitedSuspendOptions): Promise<FinishedOperation>;
+    suspend(opts?: SuspendOptions): 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
@@ -172,11 +184,13 @@ 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`). 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_path` `cold_boot`): files kept, processes restarted. `result.lost_suspend` (also
+     * `lastTiming.server.lostSuspend`, `lostSuspendOf(op)`, 0.12.0+) names a suspend this resume could not restore and the
+     * checkpoint it restored instead (see the lifecycle reference).
      */
     resume(opts: WaitedResumeOptions): Promise<FinishedOperation>;
     resume(opts?: ResumeOptions): Promise<Operation>;
@@ -210,7 +224,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.
      */
@@ -229,7 +243,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).
@@ -255,17 +269,18 @@ 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.
@@ -276,9 +291,9 @@ export declare class Workspace {
      */
     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;
@@ -102,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';
     }
@@ -127,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.
      */
@@ -147,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() {
@@ -163,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.
      *
@@ -181,17 +181,39 @@ export class Workspace {
     inputs() {
         return this.#ctx.workspaces.inputs(this.id);
     }
+    get labels() { return { ...this.#view.labels }; }
+    async setLabels(labels) {
+        this.#view = (await this.#ctx.workspaces.setLabels(this.id, labels)).data;
+        return this;
+    }
+    async setIdlePolicy(policy) {
+        this.#view = (await this.#ctx.workspaces.setIdlePolicy(this.id, policy)).data;
+        return this;
+    }
+    idle(signal) { return this.cell().idle(signal); }
+    keepalive(seconds, signal) { return this.cell().keepalive(seconds, signal); }
     async refresh() {
         this.#view = await this.#ctx.http.json('GET', `/v1/workspaces/${encodeURIComponent(this.id)}`, {}, this.#ctx.authorization);
         if (this.#view.mode === 'file_first' && typeof this.#view.tree_revision === 'number')
             this.#noteTreeRevision(this.#view.tree_revision);
         return this;
     }
-    /** Waits for the active operation (if any) and refreshes. */
+    /**
+     * Waits for the active operation (if any) and refreshes. A suspend-when-idle that found the workspace active is
+     * canceled `workspace_active` (0.12.0+: `OperationFailedError.workspaceActive`); the workspace keeps running, so this
+     * resolves.
+     */
     async waitUntilReady(opts = {}) {
         const op = this.#view.active_operation;
-        if (op)
-            await this.#ctx.workspaces.waitForOperation(op.id, opts);
+        if (op) {
+            try {
+                await this.#ctx.workspaces.waitForOperation(op.id, opts);
+            }
+            catch (e) {
+                if (!(e instanceof OperationFailedError) || !e.workspaceActive)
+                    throw e;
+            }
+        }
         return this.refresh();
     }
     delete(opts = {}) {
@@ -204,7 +226,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
@@ -237,7 +259,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,
@@ -315,7 +337,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)
@@ -378,17 +400,18 @@ 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.
@@ -398,7 +421,7 @@ export class Workspace {
      * 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 });
@@ -415,7 +438,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));
@@ -473,9 +496,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.11.0",
+  "version": "0.12.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",
@@ -71,6 +71,9 @@
     "yaml": "2.9.1",
     "zod": "4.6.5"
   },
+  "dependencies": {
+    "undici": "8.10.2"
+  },
   "scripts": {
     "build": "node scripts/build.mjs",
     "generate": "openapi-typescript ../contracts/openapi/app-api.json -o src/generated/app-api.ts && openapi-typescript ../contracts/openapi/cell-api.yaml --default-non-nullable false -o src/generated/cell-api.ts",