@shardflux/sdk 0.13.1 → 0.15.0

package/dist/workspace-ref.js

@@ -0,0 +1,149 @@
+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);
+    }
+    /**
+     * 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, 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, 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,6 +10,8 @@ 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 { WorkspaceSecrets } from './secrets.js';
 import type { CellClientOptions, Residency, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse, WorkspaceStartup } from './templates.js';
@@ -56,11 +58,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
@@ -150,6 +159,29 @@ export declare class Workspace {
     get executions(): CellClient['executions'];
     /** Secret names bound to this workspace (injected into every exec/PTY start): `get()`, `set(names)`. */
     get secrets(): WorkspaceSecrets;
+    /**
+     * Inbound ports (0.14.0): serve a TCP port of the workspace at its own private HTTPS URL. A request wakes a parked or
+     * suspended workspace and is served once it runs.
+     *
+     *   const { url } = await workspace.ports.expose(3000);       // the server listens on 0.0.0.0:3000
+     *   const { token } = await workspace.ports.token(3000);      // Authorization: Bearer <token>
+     *   const link = await workspace.ports.link(3000);            // open link.url in a browser
+     */
+    get ports(): WorkspacePorts;
+    /**
+     * 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>;
@@ -200,6 +232,21 @@ export declare class Workspace {
      * A suspend the request already started is not undone (it shows as `activeOperation`).
      */
     cancelSuspendWhenIdle(): Promise<this>;
+    /**
+     * Resizes this workspace (0.14.0): memory, the held floor, the allocation mode, CPU and disk, whether it is running or
+     * suspended, fixed or elastic, without a restart or a fork. Memory changes live on a running workspace (a shrink gives
+     * back what the guest frees: `memory.converged`); a suspended one gets its new size when it resumes, before its first
+     * call. CPU changes live up to the vCPUs the workspace booted with, beyond that at its next start. Disks grow online.
+     * The new caps are stored, so every later start uses them. Resolves once the resize has finished, with per resource
+     * when it applies (`now`, `resume` or `next_start` with the `reason`); the handle's view is refreshed. See
+     * WorkspacesApi.resize for the errors. A file-first workspace (no VM to resize) is refused locally with
+     * NotSupportedForModeError.
+     *
+     *   const r = await workspace.resize({ memoryMib: 6144, cpuMillis: 4000 });
+     *   r.memory?.applies_at; // 'now'
+     *   r.cpu?.applies_at;    // 'next_start' (reason 'boot_vcpus': more vCPUs than it booted with)
+     */
+    resize(params: ResizeParams): Promise<ResizeResult>;
     /**
      * 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

package/dist/workspace.js

@@ -4,6 +4,8 @@ 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 { 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'));
@@ -20,8 +22,15 @@ export class Workspace {
     #lastTiming;
     /** The newest tree revision seen (file-first): the view's, or any cell response's since. */
     #treeRevision;
+    /**
+     * 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 };
@@ -200,6 +209,45 @@ export class Workspace {
     get secrets() {
         return new WorkspaceSecrets(this.#ctx, this.id);
     }
+    /**
+     * Inbound ports (0.14.0): serve a TCP port of the workspace at its own private HTTPS URL. A request wakes a parked or
+     * suspended workspace and is served once it runs.
+     *
+     *   const { url } = await workspace.ports.expose(3000);       // the server listens on 0.0.0.0:3000
+     *   const { token } = await workspace.ports.token(3000);      // Authorization: Bearer <token>
+     *   const link = await workspace.ports.link(3000);            // open link.url in a browser
+     */
+    get ports() {
+        return new WorkspacePorts(this.#ctx, this.id);
+    }
+    /**
+     * 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({
+            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);
@@ -274,6 +322,29 @@ export class Workspace {
         this.#view = (await this.#ctx.workspaces.cancelSuspendWhenIdle(this.id)).data;
         return this;
     }
+    /**
+     * Resizes this workspace (0.14.0): memory, the held floor, the allocation mode, CPU and disk, whether it is running or
+     * suspended, fixed or elastic, without a restart or a fork. Memory changes live on a running workspace (a shrink gives
+     * back what the guest frees: `memory.converged`); a suspended one gets its new size when it resumes, before its first
+     * call. CPU changes live up to the vCPUs the workspace booted with, beyond that at its next start. Disks grow online.
+     * The new caps are stored, so every later start uses them. Resolves once the resize has finished, with per resource
+     * when it applies (`now`, `resume` or `next_start` with the `reason`); the handle's view is refreshed. See
+     * WorkspacesApi.resize for the errors. A file-first workspace (no VM to resize) is refused locally with
+     * NotSupportedForModeError.
+     *
+     *   const r = await workspace.resize({ memoryMib: 6144, cpuMillis: 4000 });
+     *   r.memory?.applies_at; // 'now'
+     *   r.cpu?.applies_at;    // 'next_start' (reason 'boot_vcpus': more vCPUs than it booted with)
+     */
+    async resize(params) {
+        const refusal = this.#needsVm('resize');
+        if (refusal)
+            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);
+        return out;
+    }
     resume(opts = {}) {
         const refusal = this.#needsVm('resume');
         if (refusal)

package/package.json

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