@shardflux/sdk 0.12.0 → 0.13.1

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, IdlePolicy, 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, SuspendOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } 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';
@@ -67,7 +67,9 @@ export declare class Workspace {
      * woke the workspace), or a lifecycle call with `wait`. Null for handles from get()/list() until such a call.
      * `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.
+     * reason in `server.coldBootReason`): files are as of the suspend, running processes were restarted. Reason
+     * `host_lost` (0.13.1+): the machine the workspace ran on failed and it booted from its disk, files kept;
+     * `server.hostLost` says what the resume restored (`hostLostOf(op)` on the operation).
      */
     get lastTiming(): LifecycleTiming | null;
     get id(): string;
@@ -82,6 +84,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 +117,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;
     /**
@@ -159,6 +176,8 @@ export declare class Workspace {
      * 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.
+     * A suspend that finds the machine the workspace ran on failed succeeds at once (0.13.1+): `result.durable` is true
+     * and `result.host_lost` (`hostLostOf(op)`) has `detectedAt`; the next resume restores the workspace.
      *
      *   await workspace.suspend({ wait: true });
      *   await workspace.suspend({ durable: true }); // 0.12.0+: also wait for the durable copy
@@ -190,11 +209,16 @@ export declare class Workspace {
      * (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. `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).
+     * checkpoint it restored instead (see the lifecycle reference). `result.host_lost` (also `lastTiming.server.hostLost`,
+     * `hostLostOf(op)`, 0.13.1+): the machine the workspace ran on failed and this resume restored it, from its disk
+     * (`cold_boot_reason` `host_lost`) or from its newest checkpoint (`state_as_of`).
      */
     resume(opts: WaitedResumeOptions): Promise<FinishedOperation>;
     resume(opts?: ResumeOptions): Promise<Operation>;
-    /** Takes a snapshot. Resolves when it is REQUESTED; with `{ wait: true }`, once it is taken. */
+    /**
+     * Takes a snapshot. Resolves when it is REQUESTED; with `{ wait: true }`, once it is taken. After the machine the
+     * workspace ran on failed, resume it first: until then the snapshot fails `resume_required` (0.13.1+).
+     */
     snapshot(opts: WaitedLifecycleOptions & {
         label?: string;
     }): Promise<FinishedOperation>;
@@ -203,13 +227,14 @@ export declare class Workspace {
     }): Promise<Operation>;
     /**
      * 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.
+     * `{ wait: true }`, once the copy exists, with its handle refreshed. After the machine the workspace ran on failed,
+     * resume it first: until then the fork fails `resume_required` (0.13.1+).
      */
-    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;
     }>;
@@ -286,8 +311,9 @@ export declare class Workspace {
      * 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`).
+     * suspend, or, 0.13.1+, the machine the workspace ran on failed) 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`, `server.coldBootReason`).
      */
     wake(opts?: WakeOptions): Promise<boolean>;
     /**

package/dist/workspace.js

@@ -44,7 +44,9 @@ export class Workspace {
      * woke the workspace), or a lifecycle call with `wait`. Null for handles from get()/list() until such a call.
      * `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.
+     * reason in `server.coldBootReason`): files are as of the suspend, running processes were restarted. Reason
+     * `host_lost` (0.13.1+): the machine the workspace ran on failed and it booted from its disk, files kept;
+     * `server.hostLost` says what the resume restored (`hostLostOf(op)` on the operation).
      */
     get lastTiming() {
         return this.#lastTiming ?? this.#openTrace?.finished ?? null;
@@ -96,6 +98,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 +153,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;
@@ -417,8 +440,9 @@ export class Workspace {
      * 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`).
+     * suspend, or, 0.13.1+, the machine the workspace ran on failed) 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`, `server.coldBootReason`).
      */
     async wake(opts = {}) {
         // A file-first workspace runs from creation and is never suspended: nothing to wake.

package/package.json

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