@shardflux/sdk 0.11.0 → 0.11.1

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.
@@ -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.
      *
@@ -154,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
@@ -172,7 +172,7 @@ 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
@@ -210,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.
      */
@@ -229,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).
@@ -255,17 +255,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 +277,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.
      *
@@ -204,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
@@ -237,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,
@@ -315,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)
@@ -378,17 +378,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 +399,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 +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));
@@ -473,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.11.0",
+  "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",