@shardflux/sdk 0.15.0 → 0.16.0

package/dist/workspace.js

@@ -6,6 +6,7 @@ import { AFTER_WAIT, HELD_RESUME, TRACE } from "./lifecycle.js";
 import { Trace, combineListeners, traced } from "./progress.js";
 import { WorkspaceComputer } from "./computer.js";
 import { WorkspacePorts } from "./ports.js";
+import { WorkspaceTunnels } from "./tunnels.js";
 import { WorkspaceSecrets } from "./secrets.js";
 import { ToolTokenManager } from "./tokens.js";
 const notRunning = (e) => e instanceof ShardfluxApiError && (e.code === 'workspace_not_running' || (e.code === 'conflict' && e.reason === 'workspace_not_running'));
@@ -16,12 +17,14 @@ export class Workspace {
     #ctx;
     #defaults;
     #managers = new Map();
+    #computer;
     #cells = new Map();
     /** The open() that produced this handle; its timing is final once open() has returned. */
     #openTrace;
     #lastTiming;
     /** The newest tree revision seen (file-first): the view's, or any cell response's since. */
     #treeRevision;
+    #tunnels;
     /**
      * Whether the open() that returned this handle created the workspace (0.15.0+, contracts §46.2): true for a new key
      * (or a key whose session ended), false when it reconnected to or resumed an existing workspace. Null for handles
@@ -101,6 +104,10 @@ export class Workspace {
     get grants() {
         return this.#view.grants;
     }
+    /** Stored caps every later start uses, as of the latest workspace view. */
+    get caps() {
+        return this.#view.caps;
+    }
     get ceilings() {
         return this.#view.ceilings;
     }
@@ -220,13 +227,17 @@ export class Workspace {
     get ports() {
         return new WorkspacePorts(this.#ctx, this.id);
     }
+    /** Forward a guest TCP port to this machine. Close the returned handle in finally. */
+    get tunnels() {
+        return this.#tunnels ??= new WorkspaceTunnels(() => this.cell({ transitionTimeoutMs: 30_000 }), () => this.grantedTools);
+    }
     /**
      * The workspace desktop (0.15.0+, contracts §45): `act(actions)`, `screenshot()`, `stream()` (a private link to watch
      * it), `status()`, `start()`, `stop()`. Needs computer use on (`setComputerUse(true)`, or the template's switch); the
      * platform starts the desktop on the first call that needs it.
      */
     get computer() {
-        return new WorkspaceComputer({
+        return this.#computer ??= new WorkspaceComputer({
             cell: () => this.cell(),
             ports: () => this.ports,
             setEnabled: (enabled) => this.setComputerUse(enabled).then(() => this.computerUse),
@@ -257,6 +268,11 @@ export class Workspace {
         this.#view = (await this.#ctx.workspaces.setLabels(this.id, labels)).data;
         return this;
     }
+    get retention() { return this.#view.retention ?? null; }
+    async setRetention(policy) {
+        this.#view = (await this.#ctx.workspaces.setRetention(this.id, policy)).data;
+        return this;
+    }
     async setIdlePolicy(policy) {
         this.#view = (await this.#ctx.workspaces.setIdlePolicy(this.id, policy)).data;
         return this;
@@ -342,7 +358,10 @@ export class Workspace {
             throw refusal;
         const out = await this.#ctx.workspaces.resize(this.id, this.#tracked(params));
         // The resize has happened: a failed view read leaves the old view (the next refresh() reads it again).
-        await this.refresh().catch(() => undefined);
+        if (params.wait !== false)
+            await this.refresh().catch(() => undefined);
+        else if (out.caps)
+            this.#view = { ...this.#view, caps: out.caps };
         return out;
     }
     resume(opts = {}) {
@@ -378,19 +397,49 @@ export class Workspace {
         return this.#ctx.workspaces.fork(this.id, target, this.#tracked(opts));
     }
     async close(opts = {}) {
+        let tunnelError;
+        try {
+            await this.#tunnels?.close();
+        }
+        catch (e) {
+            tunnelError = e instanceof Error ? e : new Error(String(e));
+        }
         // Closing aborts in-flight cell requests: tool-call capture writes recorded before it are flushed first (bounded).
         await this.#ctx.captures.settle(this.id);
         for (const c of this.#cells.values())
             c.close();
         this.#cells.clear();
-        if (this.lifetime !== 'session')
+        if (this.lifetime !== 'session') {
+            if (tunnelError)
+                throw tunnelError;
             return null;
+        }
         const out = await this.#ctx.workspaces.closeWithView(this.id, this.#tracked(opts));
         this.#view = out.workspace;
         for (const m of this.#managers.values())
             m.invalidate();
+        if (tunnelError)
+            throw tunnelError;
         return out.operation;
     }
+    /**
+     * 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.
+     */
+    /** Upgrade in place: keep files/packages/home; cold start drops memory and processes. */
+    async upgrade(opts = {}) {
+        const refusal = this.#needsVm('upgrade');
+        if (refusal)
+            throw refusal;
+        const op = await this.#ctx.workspaces.upgrade(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
+        if (opts.at !== 'next_resume')
+            for (const m of this.#managers.values())
+                m.invalidate();
+        return op;
+    }
+    get upgradeAvailable() { return this.#view.upgrade_available ?? null; }
+    get upgradePending() { return this.#view.upgrade_pending ?? null; }
     async reset(opts = {}) {
         const refusal = this.#needsVm('reset');
         if (refusal)
@@ -590,6 +639,30 @@ export class Workspace {
         }
         throw new Error(`workspace ${this.id} did not become runnable after repeated lifecycle conflicts`);
     }
+    /** Hints without waiting, runs the turn, and requests idle suspension even if the body throws. */
+    async turn(fn, { afterSeconds = 0 } = {}) {
+        void this.hint().catch(() => undefined);
+        let result;
+        let failure;
+        let failed = false;
+        try {
+            result = await fn(this);
+        }
+        catch (err) {
+            failed = true;
+            failure = err;
+        }
+        try {
+            await this.suspendWhenIdle({ afterSeconds });
+        }
+        catch (err) {
+            if (!failed)
+                throw err;
+        }
+        if (failed)
+            throw failure;
+        return result;
+    }
     /**
      * 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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.15.0",
+  "version": "0.16.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).",
+  "description": "Shardflux TypeScript SDK: serverless VMs for AI agents. Open a workspace by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
   "license": "Apache-2.0",
   "homepage": "https://shardflux.dev",
   "bugs": {
@@ -29,6 +29,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
     }
   },
   "files": [