@shardflux/sdk 0.11.1 → 0.13.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 { AllocationMode, ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceMemory, 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, ForkOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 import { Trace } from './progress.js';
 import type { LifecycleTiming, ProgressListener } from './progress.js';
 import { WorkspaceSecrets } from './secrets.js';
@@ -82,6 +82,13 @@ export declare class Workspace {
     get grants(): WorkspaceView['grants'];
     get ceilings(): WorkspaceView['ceilings'];
     get template(): WorkspaceView['template'];
+    /**
+     * The template version whose immutable paths the workspace has mounted (0.13.0; `template.immutable_version`): the
+     * template's newest published version as of the workspace's last cold boot or resume, which can be newer than
+     * `template.version`. Null when the workspace mounts none (its version declares no immutable paths, it has not started
+     * since, or an older API).
+     */
+    get immutableVersion(): number | null;
     get pendingReason(): string | null;
     get activeOperation(): WorkspaceView['active_operation'];
     /** persistent or session; immutable. A view without the field (older API) is persistent. */
@@ -108,6 +115,14 @@ export declare class Workspace {
      * a resume after the request cancelled it. `refresh()` reads it again.
      */
     get suspendRequest(): SuspendRequest | null;
+    /**
+     * Memory of the workspace as of the last view (0.13.0): `{allocation_mode, promised_mib, held_mib,
+     * plugged_mib}`. An elastic workspace holds `held_mib` while idle and is grown towards `promised_mib` when a command
+     * needs it; `plugged_mib` is what is plugged above the floor now (null without a live allocation). Null on an older API.
+     */
+    get memory(): WorkspaceMemory | null;
+    /** `fixed` or `elastic` (0.13.0): the running VM's layout, else the next start's. Fixed on an older API. */
+    get allocationMode(): AllocationMode;
     /** The raw view (GET /v1/workspaces/{id}). */
     get data(): WorkspaceView;
     /**
@@ -135,11 +150,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,12 +171,15 @@ 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` (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,
@@ -176,7 +203,9 @@ export declare class Workspace {
      * 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>;
@@ -191,11 +220,11 @@ export declare class Workspace {
      * Forks into a new key. Resolves when the fork is REQUESTED (the copy's handle is returned at once); with
      * `{ wait: true }`, once the copy exists, with its handle refreshed.
      */
-    fork(target: ForkTarget, opts: WaitedLifecycleOptions): Promise<{
+    fork(target: ForkTarget, opts: WaitedForkOptions): Promise<{
         operation: FinishedOperation;
         workspace: Workspace;
     }>;
-    fork(target: ForkTarget, opts?: LifecycleOptions): Promise<{
+    fork(target: ForkTarget, opts?: ForkOptions): Promise<{
         operation: Operation;
         workspace: Workspace;
     }>;

package/dist/workspace.js

@@ -96,6 +96,15 @@ export class Workspace {
     get template() {
         return this.#view.template;
     }
+    /**
+     * The template version whose immutable paths the workspace has mounted (0.13.0; `template.immutable_version`): the
+     * template's newest published version as of the workspace's last cold boot or resume, which can be newer than
+     * `template.version`. Null when the workspace mounts none (its version declares no immutable paths, it has not started
+     * since, or an older API).
+     */
+    get immutableVersion() {
+        return this.#view.template.immutable_version ?? null;
+    }
     get pendingReason() {
         return this.#view.pending_reason;
     }
@@ -142,6 +151,18 @@ export class Workspace {
     get suspendRequest() {
         return this.#view.idle?.suspend_request ?? null;
     }
+    /**
+     * Memory of the workspace as of the last view (0.13.0): `{allocation_mode, promised_mib, held_mib,
+     * plugged_mib}`. An elastic workspace holds `held_mib` while idle and is grown towards `promised_mib` when a command
+     * needs it; `plugged_mib` is what is plugged above the floor now (null without a live allocation). Null on an older API.
+     */
+    get memory() {
+        return this.#view.memory ?? null;
+    }
+    /** `fixed` or `elastic` (0.13.0): the running VM's layout, else the next start's. Fixed on an older API. */
+    get allocationMode() {
+        return this.#view.memory?.allocation_mode ?? this.#view.caps?.allocation_mode ?? 'fixed';
+    }
     /** The raw view (GET /v1/workspaces/{id}). */
     get data() {
         return this.#view;
@@ -181,17 +202,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 = {}) {

package/package.json

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