@shardflux/sdk 0.14.0 → 0.16.0

package/dist/workspace-ref.js

@@ -0,0 +1,173 @@
+import { CAPTURE_BARRIER } from "./cell.js";
+import { ShardfluxApiError, isWorkspaceGone } from "./errors.js";
+import { workspaceTools } from "./tools.js";
+const FILE_METHODS = ['read', 'readText', 'readWithInfo', 'write', 'list', 'stat', 'remove', 'mkdir', 'move', 'search', 'patch'];
+/**
+ * A workspace named by its key. Nothing is requested until the first call: `exec()`, `files`, a tool from `tools()`,
+ * `hint()` or `open()`. Concurrent first calls share one open; a failed open is not kept, so the next call opens again.
+ * A workspace deleted under the ref (409 `workspace_deleted`, `isWorkspaceGone`) fails the call that meets it and is
+ * forgotten: the next call opens the key again (a new workspace, as `open()` would). `open()` returns the full
+ * `Workspace` (suspend, fork, ports, computer, tool-call capture).
+ */
+export class WorkspaceRef {
+    key;
+    #api;
+    #params;
+    #grants;
+    #workspace = null;
+    #opening = null;
+    /** Internal: use `cloud.workspace(key, params)` or the module-level `workspace(key, params)`. */
+    constructor(api, key, params, grants) {
+        if (typeof key !== 'string' || key.length === 0)
+            throw new TypeError('workspace(key, params): key must be a non-empty string');
+        if (params.create !== false && (typeof params.template !== 'string' || params.template.length === 0)) {
+            throw new TypeError(`workspace("${key}", params): params.template is required (a template slug, e.g. "default")`);
+        }
+        this.key = key;
+        this.#api = api;
+        this.#params = params;
+        this.#grants = grants;
+    }
+    /**
+     * Whether the open that produced the current workspace created it (contracts §46.2): undefined until the ref has
+     * opened (or when the API does not report it), false for `create: false`.
+     */
+    get created() {
+        if (!this.#workspace)
+            return undefined;
+        if (this.#params.create === false)
+            return false;
+        return this.#workspace.created ?? undefined;
+    }
+    /** The opened workspace's mode, else the params' (`processful` when neither says). */
+    get mode() {
+        return this.#workspace?.mode ?? this.#params.mode ?? 'processful';
+    }
+    /** Tools granted by the opened workspace's last token; null before the open. */
+    get grantedTools() {
+        return this.#workspace?.grantedTools ?? null;
+    }
+    /** The workspace: opened (or, with `create: false`, found) on the first call and kept. */
+    open() {
+        if (this.#workspace)
+            return Promise.resolve(this.#workspace);
+        this.#opening ??= this.#open().then((ws) => {
+            this.#workspace = ws;
+            this.#opening = null;
+            return ws;
+        }, (err) => {
+            this.#opening = null;
+            throw err;
+        });
+        return this.#opening;
+    }
+    async #open() {
+        const params = this.#params;
+        // open() sends only the open's own parameters (`create` is the ref's).
+        if (params.create !== false)
+            return this.#api.open({ ...params, key: this.key });
+        const found = await this.#api.findByKey(this.key, {
+            includeDeleted: false,
+            ...(params.projectId !== undefined ? { projectId: params.projectId } : {}),
+            ...(params.agentLabel !== undefined ? { agentLabel: params.agentLabel } : {}),
+            ...(params.tools !== undefined ? { tools: params.tools } : {}),
+        });
+        if (found)
+            return found;
+        throw new ShardfluxApiError(404, { error: { code: 'not_found', message: `No workspace with key "${this.key}" in this project (create: false).`, request_id: '', retryable: false, details: { key: this.key } } }, 'api');
+    }
+    /** Runs `fn` on the workspace; a workspace found deleted is forgotten so the next call opens the key again. */
+    async #use(fn) {
+        const ws = await this.open();
+        try {
+            return await fn(ws);
+        }
+        catch (err) {
+            if (isWorkspaceGone(err) && this.#workspace === ws)
+                this.#workspace = null;
+            throw err;
+        }
+    }
+    /**
+     * Runs a command and collects its output (`cell().exec.run()`). A string runs through `bash -lc`, so shell syntax
+     * works; an argv array runs without a shell. A file-first workspace runs commands with `executions.run()`.
+     */
+    exec(command, opts = {}) {
+        const argv = typeof command === 'string' ? ['bash', '-lc', command] : [...command];
+        return this.#use((ws) => ws.cell().exec.run(argv, opts));
+    }
+    /** The workspace's files, as on `cell().files`. */
+    files = Object.fromEntries(FILE_METHODS.map((name) => [
+        name,
+        (...args) => this.#use((ws) => ws.cell().files[name](...args)),
+    ]));
+    /** A file-first workspace's executions (`run`, `get`), as on `Workspace.executions`. */
+    executions = {
+        run: (argv, opts = {}) => this.#use((ws) => ws.executions.run(argv, opts)),
+        get: (executionId, opts = {}) => this.#use((ws) => ws.executions.get(executionId, opts)),
+    };
+    /** The workspace's cell client (`Workspace.cell()`), opening the key first if needed. */
+    async cell(opts = {}) {
+        return (await this.open()).cell(opts);
+    }
+    /** 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.#use((ws) => ws.suspendWhenIdle({ afterSeconds }));
+        }
+        catch (err) {
+            if (!failed)
+                throw err;
+        }
+        if (failed)
+            throw failure;
+        return result;
+    }
+    /**
+     * Says a tool call is coming. Before the first open it starts the open in the background (`wake` resolves when the
+     * workspace runs; nothing has to await it), unless `wake: null`; afterwards it is `Workspace.hint()`.
+     */
+    async hint(opts = {}) {
+        if (this.#workspace)
+            return this.#workspace.hint(opts);
+        if (opts.wake === null)
+            return { residency: null, wake: null };
+        const wake = this.open().then(() => true);
+        wake.catch(() => undefined); // a failed open is left to the next call, which opens again
+        return { residency: null, wake };
+    }
+    /**
+     * Workspace tools for this key (`workspaceTools`), built before any VM exists: the definitions come from the API
+     * key's tool permissions (`GET /v1/me`, read once per client), and `computer` only with `computerUse: true` in the
+     * params or on an opened workspace whose computer use is on. The first tool call opens the key.
+     */
+    async tools(opts = {}) {
+        // create: false finds the workspace now (a lookup, no VM start), so the tools match its mode.
+        if (this.#params.create === false)
+            await this.open();
+        let tools = opts.tools ?? this.grantedTools ?? undefined;
+        if (tools === undefined) {
+            const granted = await this.#grants();
+            if (granted) {
+                const computer = this.#workspace ? this.#workspace.computerUse.enabled : this.#params.computerUse === true;
+                tools = granted.filter((t) => t !== 'computer' || computer);
+            }
+        }
+        return workspaceTools(this, { ...opts, ...(tools !== undefined ? { tools } : {}) });
+    }
+    /** Internal: tool-call capture's read-your-writes barrier, once the workspace is open. */
+    [CAPTURE_BARRIER]() {
+        return this.#workspace?.[CAPTURE_BARRIER]();
+    }
+}

package/dist/workspace.d.ts

@@ -2,7 +2,7 @@
  * 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 { AllocationMode, ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, ResizeParams, ResizeResult, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
+import type { AllocationMode, ComputerUse, ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, ResizeParams, ResizeResult, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, RetentionPolicy, 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';
@@ -10,7 +10,9 @@ import type { WorkspaceMode } from './errors.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 { WorkspaceComputer } from './computer.js';
 import { WorkspacePorts } from './ports.js';
+import { WorkspaceTunnels } from './tunnels.js';
 import { WorkspaceSecrets } from './secrets.js';
 import type { CellClientOptions, Residency, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse, WorkspaceStartup } from './templates.js';
@@ -57,11 +59,18 @@ export interface HintResult {
 }
 export declare class Workspace {
     #private;
+    /**
+     * 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
+     * from get(), list() and findByKey(), and from an API that does not report it.
+     */
+    readonly created: boolean | null;
     constructor(ctx: ClientContext, view: WorkspaceView, opts?: {
         agentLabel?: string | undefined;
         tools?: ToolName[] | undefined;
         token?: ToolToken | null;
         trace?: Trace;
+        created?: boolean | null;
     });
     /**
      * Where the time went in the last lifecycle call made through this handle: open(), wake() (also when a tool call
@@ -83,6 +92,8 @@ export declare class Workspace {
     get cellEndpoint(): string | null;
     /** Actual grants reported by the cell for the running workspace (null until known). */
     get grants(): WorkspaceView['grants'];
+    /** Stored caps every later start uses, as of the latest workspace view. */
+    get caps(): WorkspaceView['caps'];
     get ceilings(): WorkspaceView['ceilings'];
     get template(): WorkspaceView['template'];
     /**
@@ -160,10 +171,28 @@ export declare class Workspace {
      *   const link = await workspace.ports.link(3000);            // open link.url in a browser
      */
     get ports(): WorkspacePorts;
+    /** Forward a guest TCP port to this machine. Close the returned handle in finally. */
+    get tunnels(): WorkspaceTunnels;
+    /**
+     * 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(): WorkspaceComputer;
+    /** Computer use (0.15.0+): `enabled` is what tool tokens carry; `workspace` null follows the `template`'s switch. */
+    get computerUse(): ComputerUse;
+    /**
+     * Switches computer use on or off for this workspace (null follows the template). Takes effect on the next tool token:
+     * this handle's cached tokens are dropped. 409 `computer_use_unavailable` when its template version cannot run a
+     * desktop.
+     */
+    setComputerUse(enabled: boolean | null): Promise<this>;
     /** 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>;
+    get retention(): WorkspaceView['retention'];
+    setRetention(policy: RetentionPolicy | null): Promise<this>;
     setIdlePolicy(policy: IdlePolicy | null): Promise<this>;
     idle(signal?: AbortSignal): ReturnType<CellClient['idle']>;
     keepalive(seconds: number, signal?: AbortSignal): ReturnType<CellClient['keepalive']>;
@@ -278,6 +307,12 @@ export declare class Workspace {
      * 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. */
+    upgrade(opts?: LifecycleOptions & {
+        at?: 'now' | 'next_resume';
+    }): Promise<Operation>;
+    get upgradeAvailable(): WorkspaceView['upgrade_available'];
+    get upgradePending(): WorkspaceView['upgrade_pending'];
     reset(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     reset(opts?: LifecycleOptions): Promise<Operation>;
     /**
@@ -341,6 +376,10 @@ export declare class Workspace {
      * (`server.memoryRestored === false`, `server.resumePath` `cold_boot`, `server.coldBootReason`).
      */
     wake(opts?: WakeOptions): Promise<boolean>;
+    /** Hints without waiting, runs the turn, and requests idle suspension even if the body throws. */
+    turn<T>(fn: (workspace: this) => T | Promise<T>, { afterSeconds }?: {
+        afterSeconds?: number;
+    }): Promise<T>;
     /**
      * 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/dist/workspace.js

@@ -4,7 +4,9 @@ import { NotSupportedForModeError, OperationFailedError, ShardfluxApiError } fro
 import { SERVER_WAIT_MAX_S, defaultSleep, randomId } from "./http.js";
 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'));
@@ -15,14 +17,23 @@ 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
+     * from get(), list() and findByKey(), and from an API that does not report it.
+     */
+    created;
     constructor(ctx, view, opts = {}) {
         this.#ctx = ctx;
+        this.created = opts.created ?? null;
         this.#view = view;
         this.#treeRevision = view.mode === 'file_first' && typeof view.tree_revision === 'number' ? view.tree_revision : null;
         this.#defaults = { agentLabel: opts.agentLabel, tools: opts.tools };
@@ -93,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;
     }
@@ -212,6 +227,38 @@ 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 this.#computer ??= new WorkspaceComputer({
+            cell: () => this.cell(),
+            ports: () => this.ports,
+            setEnabled: (enabled) => this.setComputerUse(enabled).then(() => this.computerUse),
+        });
+    }
+    /** Computer use (0.15.0+): `enabled` is what tool tokens carry; `workspace` null follows the `template`'s switch. */
+    get computerUse() {
+        return this.#view.computer_use;
+    }
+    /**
+     * Switches computer use on or off for this workspace (null follows the template). Takes effect on the next tool token:
+     * this handle's cached tokens are dropped. 409 `computer_use_unavailable` when its template version cannot run a
+     * desktop.
+     */
+    async setComputerUse(enabled) {
+        const cu = await this.#ctx.workspaces.setComputerUse(this.id, enabled);
+        this.#view = { ...this.#view, computer_use: cu };
+        for (const m of this.#managers.values())
+            m.invalidate();
+        return this;
+    }
     /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
     inputs() {
         return this.#ctx.workspaces.inputs(this.id);
@@ -221,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;
@@ -306,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 = {}) {
@@ -342,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)
@@ -554,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.14.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": [