@shardflux/sdk 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,12 +1,54 @@
 # Changelog
 
+Every API the README shows is available from the version named here. Breaking changes ship in minor releases and are
+marked **Breaking**.
+
+## 0.15.0 (not yet published)
+
+### Workspaces by key
+
+Additive (contracts §46). A workspace named by its key, created on its first use, with no lifecycle code:
+
+```ts
+import { workspace } from '@shardflux/sdk';
+const run = await workspace('acme/thread-42', { template: 'default' }).exec('python3 -c "print(40 + 2)"');
+```
+
+- `cloud.workspace(key, params)` and module-level `workspace(key, params)` return a `WorkspaceRef` without a request.
+  Its first call opens the key (one held request); concurrent first calls share it, a failed open is retried by the
+  next call, and a workspace deleted under the ref is opened again by the call after the one that met the deletion.
+- `WorkspaceRef`: `exec(command)` (a string runs through `bash -lc`, an argv array without a shell), `files`,
+  `executions`, `tools()` (definitions from the key's grants before any VM; the first tool call opens), `open()` (the
+  `Workspace`), `cell()`, `hint()` (starts the open), `key`, `created`, `mode`. `create: false` never creates (404
+  `not_found` for an unknown key).
+- `new Shardflux()` reads `SHARDFLUX_API_KEY` and `SHARDFLUX_API_URL` when `apiKey` / `baseUrl` are not passed.
+- `workspace.created`: whether the `open()` that returned it created the workspace (the API's new `created` field).
+- `template: 'default'` opens the platform default template (`python-node-browser`) on any client version.
+- `workspaceTools()` takes a `ToolTarget`: a `Workspace` or a `WorkspaceRef`.
+
+### Computer use
+
+Additive. A desktop in the workspace that agents drive with screenshots, clicks and keystrokes (contracts §45).
+
+- `workspace.computer`: `act(actions, { screenshot, settleMs, format, quality })` runs a batch of Claude's computer
+  toolset actions in order (the first failure stops it; the rest come back `skipped`), `screenshot()`, `status()`,
+  `start({ width, height })`, `stop()`, `stream({ interactive, ttlSeconds })` (a signed link to the viewer; it exposes
+  port 61002, or 61003 when interactive) and `stopStream()`.
+- `computerToolset(workspace)` / `COMPUTER_TOOLSET`: answers Claude's `computer_toolset_20260801` calls of a model turn
+  with one batch; every `tool_result` echoes `toolset_name: "computer"`.
+- `workspaceTools()` adds, when the token grants `computer`, the `computer` tool (one action per call) and
+  `computer_batch` (up to 50 actions in one call, with each action's result, a zoom's image and one screenshot after
+  them). Both take `screenshot: false`, `settle_ms`, and `format: "jpeg"` with `quality`.
+- `open({ computerUse })`, `workspace.setComputerUse(true | false | null)`, `workspace.computerUse`,
+  `cloud.workspaces.setComputerUse(id, enabled)`. Tool tokens carry `computer` while the switch is on; a computer call
+  whose cached token predates the switch is sent again with a fresh token.
+- `cloud.templates.setComputerUse(slug, enabled, { organizationId })` switches it for every workspace of one of your
+  templates. `ToolName` includes `computer`; template views carry `computer_use`.
+
 ## 0.14.0 — 2026-10-04 (not yet published)
 
 - Opt-in `workspaceTools(workspace, { prewake: true })` input-start hooks prepare VM tools while their input streams. Default tools, offline reads and file-first workspaces install no hook.
 
-Every API the README shows is available from the version named here. Breaking changes ship in minor releases and are
-marked **Breaking**.
-
 ## 0.14.0 (not yet published)
 
 ### Sign up from an agent

package/README.md

@@ -10,8 +10,9 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 > **Compatibility.** The API is versioned (`/v1`). Breaking changes ship only in minor releases and are marked
 > **Breaking** in the changelog (see [Compatibility](#compatibility)).
 
-> **Versions.** This README describes 0.11.0. Anything marked **(0.11.0+)** is not in 0.10.x, **(0.10.0+)** not in 0.9.0, **(0.9.0+)** not in 0.8.x, **(0.8.0+)** not in 0.7.x,
-> **(0.7.0+)** not in 0.6.x and **(0.6.0+)** not in 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
+> **Versions.** This README describes 0.15.0. Anything marked **(0.15.0+)** is not in 0.14.x, **(0.14.0+)** not in 0.13.x,
+> **(0.13.0+)** not in 0.12.x, **(0.12.0+)** not in 0.11.x, **(0.11.0+)** not in 0.10.x, **(0.10.0+)** not in 0.9.0, **(0.9.0+)** not in 0.8.x,
+> **(0.8.0+)** not in 0.7.x, **(0.7.0+)** not in 0.6.x and **(0.6.0+)** not in 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
 > `npm ls @shardflux/sdk` or the exported `SDK_VERSION`.
 
 - ESM only, Node.js 24 or later. Reading a YAML template file uses the optional peer
@@ -41,6 +42,33 @@ npm install @shardflux/sdk
 Create a project API key in the Shardflux console (`sfk_<key id>_<secret>`) and keep it on the
 server. API keys are server credentials: never put one in a browser bundle.
 
+```ts
+import { workspace } from '@shardflux/sdk';
+
+const ws = workspace('customer-42/main', { template: 'default' }); // reads SHARDFLUX_API_KEY; no request yet
+
+// 1. Run a command: the first call creates the workspace. Check that it worked.
+const run = await ws.exec('python3 -c "print(40 + 2)"');
+if (run.exitCode !== 0) throw new Error(`python3 exited ${run.exitCode}: ${run.stderr}`);
+console.log(run.stdout.trim()); // 42
+
+// 2. Write a file, then suspend the workspace and wait until the suspend has finished.
+await ws.files.write('/home/user/notes.txt', 'hello from the SDK\n');
+await (await ws.open()).suspend({ wait: true }); // resolves once suspended
+
+// 3. The same key again: the workspace wakes, and the file is still there.
+const again = workspace('customer-42/main', { template: 'default' });
+console.log(await again.files.readText('/home/user/notes.txt')); // hello from the SDK
+```
+
+The key names the workspace **(0.15.0+)**: the first call creates it, later calls (from any process) reuse it, and it
+suspends when idle and wakes on the next call with its files, packages and processes. There is no create call and no
+lifecycle code to write. See [Workspaces by key](#workspaces-by-key-0150).
+
+### Open, suspend and resume
+
+The same workspace with every step explicit:
+
 ```ts
 import { Shardflux, formatTiming } from '@shardflux/sdk';
 
@@ -70,6 +98,48 @@ installed packages and running processes are still there. The same program is in
 With 0.5.0, wait for the suspend by its operation instead:
 `await cloud.workspaces.waitForOperation((await workspace.suspend()).id)`.
 
+## Workspaces by key (0.15.0+)
+
+`workspace(key, params)` (or `cloud.workspace(key, params)` on your own client) names a workspace by the identifier your
+application already has: a user, a thread, a repository, a customer. It makes no request. Its first call opens the key:
+the workspace is created from `params.template` on first use and resumed afterwards, in one request that also brings
+back its tool token. Later calls go straight to the workspace.
+
+```ts
+import { workspace } from '@shardflux/sdk';
+
+const ws = workspace(`acme/${threadId}`, { template: 'default' });
+
+await ws.exec('pip install requests && python3 app.py');            // a string runs through bash -lc
+await ws.exec(['python3', '-c', 'print(42)']);                        // an argv array runs without a shell
+await ws.files.write('/home/user/notes.txt', 'hello\n');
+console.log(await ws.files.readText('/home/user/notes.txt'));
+
+ws.created;                                    // true when this ref's open created the workspace
+const full = await ws.open();                  // the Workspace: suspend, fork, ports, computer, capture
+```
+
+- `params` are `open()`'s without the key: `template` is required (`'default'` is the platform default template,
+  `python-node-browser`), plus `secrets`, `inputs`, `caps`, `labels`, `idlePolicy`, `lifetime`, `computerUse`,
+  `agentLabel`, `tools`.
+- Calls made while the first open runs share it. A failed open is not kept: the next call opens again.
+- `create: false` never creates: the first call finds the key's workspace and fails with 404 `not_found` when it has
+  none.
+- A workspace deleted under the ref (`isWorkspaceGone(err)`, 409 `workspace_deleted`) fails the call that meets it;
+  the next call opens the key again, which creates a new workspace.
+- `ws.hint()` starts the open early, for example when your model starts a tool call.
+
+**In an agent.** The tools exist before the workspace does; the model's first tool call creates it:
+
+```ts
+import { toAnthropicTools, executeToolCall, workspace } from '@shardflux/sdk';
+
+const tools = await workspace(`acme/${threadId}`, { template: 'default' }).tools();  // reads the key's grants
+const anthropicTools = toAnthropicTools(tools);
+// for each tool_use block the model returns:
+const output = await executeToolCall(tools, block);
+```
+
 ## Configuration
 
 ```ts
@@ -82,8 +152,9 @@ const cloud = new Shardflux({
 });
 ```
 
-The SDK reads nothing from the environment by itself (except the version check's opt-out). `SHARDFLUX_API_KEY` and
-`SHARDFLUX_API_URL` are the conventional names (the `shard` CLI reads them); pass them in as shown.
+`new Shardflux()` with no `apiKey` reads `SHARDFLUX_API_KEY`, and with no `baseUrl` reads `SHARDFLUX_API_URL`
+**(0.15.0+)**; options you pass win. A missing key throws when the client is created. The module-level `workspace()`
+uses such a client, created on its first call.
 
 ## Commands and files
 
@@ -451,6 +522,53 @@ const hook = await ws.ports.createCallbackUrl(3000);            // register `${h
 - `close(port)` stops the port's tokens, links and callback URL at once (also when the port is exposed again).
 - By id, without reading the workspace: `cloud.workspaces.ports(id)`.
 
+### Computer use (0.15.0+)
+
+A desktop in the workspace for agents that operate GUI software: a screen, a mouse and a keyboard. Switch it on for a
+workspace (or for every workspace of your template); the platform starts the desktop on the first call that needs it.
+
+```ts
+const ws = await cloud.workspaces.open({ key: 'agent/42', template: 'python-node-browser', computerUse: true });
+
+const shot = await ws.computer.screenshot();              // { format: 'png', width: 1280, height: 800, data }
+await ws.computer.act([
+  { action: 'left_click', coordinate: [640, 400] },
+  { action: 'type', text: 'hello' },
+  { action: 'key', text: 'Return' },
+], { screenshot: true });                                 // one round trip for the whole batch and a look
+
+const { url } = await ws.computer.stream();               // a private link to watch the screen live
+```
+
+With Claude, answer the computer toolset directly:
+
+```ts
+import { computerToolset } from '@shardflux/sdk';
+
+const computer = computerToolset(ws);
+const msg = await anthropic.messages.create({ model: 'claude-opus-5-5', max_tokens: 16000, tools: [computer.definition], messages });
+messages.push({ role: 'assistant', content: msg.content });
+messages.push({ role: 'user', content: await computer.run(msg.content) });
+```
+
+- The actions are Claude's computer toolset members with their parameters: `screenshot`, `zoom`, `left_click`,
+  `right_click`, `middle_click`, `double_click`, `triple_click`, `left_click_drag`, `mouse_move`, `left_mouse_down`,
+  `left_mouse_up`, `cursor_position`, `scroll`, `type`, `key`, `hold_key`, `wait`. A batch runs in order and stops at
+  the first failure; later actions come back `skipped`.
+- `computer.run(content)` sends every computer call of a model turn as one batch and returns one `tool_result` per call
+  (each with `toolset_name: "computer"`), with a screenshot on the last one when the turn did not end with a look.
+- `workspaceTools()` includes, for any model while the workspace's computer use is on, a `computer` tool (one action
+  per call, answered with a screenshot) and `computer_batch` (several actions in one call, with each action's result
+  and one screenshot after them). Both take `screenshot: false` to skip the image, `settle_ms`, and `format: "jpeg"`
+  with `quality` for smaller images.
+- `act(actions, { screenshot, settleMs, format, quality })` takes the same options.
+- Commands the agent runs see the desktop: `exec` of `chromium https://example.com &` opens the browser on it.
+- `stream({ interactive })` returns a signed link (view only by default; `interactive: true` lets the viewer use the
+  mouse and keyboard); `stopStream()` ends every view. Streaming uses inbound ports.
+- `ws.setComputerUse(true | false | null)` sets the workspace's own switch (null follows the template);
+  `ws.computerUse` reads `{ enabled, workspace, template, available }`. `status()`, `start({ width, height })` and
+  `stop()` manage the desktop directly.
+
 ### Timing and progress (0.6.0+)
 
 Every open, wake and waited lifecycle call is traced. `workspace.lastTiming` (and `err.timing` when the call fails)
@@ -710,7 +828,9 @@ it: add paths, never remove them. A build reports the list its version declares
 ## Agent tools
 
 `workspaceTools(workspace)` returns tools with a name, a description, a JSON Schema for the
-parameters and an `execute` function. Export them for your model provider and dispatch its tool
+parameters and an `execute` function. It takes a `Workspace` or **(0.15.0+)** a `WorkspaceRef`, whose
+`await ref.tools(opts)` builds them from the API key's grants before the workspace exists (see
+[Workspaces by key](#workspaces-by-key-0150)). Export them for your model provider and dispatch its tool
 calls:
 
 ```ts
@@ -735,7 +855,8 @@ Your agent loop and model calls stay in your application; the workspace is the c
 act on.
 
 The tools are `exec`, `read_file`, `write_file`, `list_files`, `search_files` and `edit_file` (0.9.0+), the process,
-terminal, git and browser tools, filtered by the tools your key grants. `edit_file` replaces exact text; when the
+terminal, git and browser tools, and `computer` (0.15.0+, while the workspace's computer use is on), filtered by the
+tools your key grants. `edit_file` replaces exact text; when the
 model passes no `expected_revision` it reads the file's revision first, so a change made in between fails the edit
 instead of being overwritten. Each call first sends `workspace.hint()` without waiting for it (`hint: false` turns
 that off, e.g. when you send the hint yourself as the model starts a tool call), except `read_file`, `list_files` and

package/dist/cell.d.ts

@@ -147,6 +147,16 @@ export type GitCommitRequest = S['GitCommitRequest'];
 export type GitResult = S['GitResult'];
 export type GitStatus = S['GitStatus'];
 export type BrowserScreenshotRequest = S['BrowserScreenshotRequest'];
+/** Contracts §45 (0.15.0+): the workspace desktop. */
+export type ComputerAction = S['ComputerAction'];
+export type ComputerActionName = ComputerAction['action'];
+export type ComputerActionsRequest = S['ComputerActionsRequest'];
+export type ComputerActionsResult = S['ComputerActionsResult'];
+export type ComputerActionResult = S['ComputerActionResult'];
+export type ComputerImage = S['ComputerImage'];
+export type ComputerStatus = S['ComputerStatus'];
+export type ComputerStartRequest = S['ComputerStartRequest'];
+export type ComputerStreamInfo = S['ComputerStream'];
 export type BrowserContentRequest = S['BrowserContentRequest'];
 export type BrowserContent = S['BrowserContent'];
 export type Signal = S['SignalValue'];
@@ -530,6 +540,21 @@ export declare class CellClient {
         status: (path: string) => Promise<GitStatus>;
         commit: (req: GitCommitRequest) => Promise<GitResult>;
     };
+    readonly computer: {
+        status: () => Promise<ComputerStatus>;
+        start: (req?: ComputerStartRequest) => Promise<ComputerStatus>;
+        stop: () => Promise<void>;
+        /**
+         * Runs a batch of actions in order (the first failure stops it; the rest are reported `skipped`), then a screenshot
+         * when `screenshot` is set. Waits and key holds may take up to 300 s per batch.
+         */
+        act: (req: ComputerActionsRequest, signal?: AbortSignal) => Promise<ComputerActionsResult>;
+        /** Starts the viewer in the guest; expose the returned port and open a link to `path` (Workspace.computer.stream does both). */
+        streamStart: (req?: {
+            interactive?: boolean;
+        }) => Promise<ComputerStreamInfo>;
+        streamStop: () => Promise<void>;
+    };
     readonly browser: {
         screenshot: (req: BrowserScreenshotRequest) => Promise<Uint8Array>;
         content: (req: BrowserContentRequest) => Promise<BrowserContent>;

package/dist/cell.js

@@ -1065,6 +1065,75 @@ export class CellClient {
             return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/git/commit'), { json: req });
         },
     };
+    // ---- computer (contracts §45, 0.15.0+) ---------------------------------------------------------
+    /**
+     * The workspace desktop. The platform starts it on the first call that needs it (actions, start, stream); status
+     * never starts it. Needs the `computer` tool, which tool tokens carry while the workspace's computer use is on.
+     */
+    /**
+     * A computer call with one retry on a fresh token when the cached one lacks the computer tool: computer use may have
+     * been switched on after the token was issued (tokens live up to 15 minutes).
+     */
+    async #computer(call) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            if (!(err instanceof ShardfluxApiError && err.status === 403 && err.details?.tool === 'computer'))
+                throw err;
+            this.tokens.invalidate();
+            return call();
+        }
+    }
+    computer = {
+        status: () => {
+            const refusal = this.#needsVm('computer.status');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#computer(() => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/computer')));
+        },
+        start: (req = {}) => {
+            const refusal = this.#needsVm('computer.start');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#computer(() => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/computer'), { json: req, timeoutMs: 90_000 }));
+        },
+        stop: async () => {
+            const refusal = this.#needsVm('computer.stop');
+            if (refusal)
+                throw refusal;
+            await this.#computer(() => this.#json('DELETE', this.#p('/v1/workspaces/{workspace_id}/computer')));
+        },
+        /**
+         * Runs a batch of actions in order (the first failure stops it; the rest are reported `skipped`), then a screenshot
+         * when `screenshot` is set. Waits and key holds may take up to 300 s per batch.
+         */
+        act: (req, signal) => {
+            const refusal = this.#needsVm('computer.actions');
+            if (refusal)
+                return Promise.reject(refusal);
+            const waits = req.actions.reduce((sum, a) => sum + (a.duration ?? 0), 0);
+            const typing = req.actions.reduce((sum, a) => sum + (a.action === 'type' ? (a.text?.length ?? 0) : 0), 0);
+            return this.#computer(() => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/computer/actions'), {
+                json: req,
+                timeoutMs: 120_000 + waits * 1000 + typing * 25,
+                ...(signal ? { signal } : {}),
+            }));
+        },
+        /** Starts the viewer in the guest; expose the returned port and open a link to `path` (Workspace.computer.stream does both). */
+        streamStart: (req = {}) => {
+            const refusal = this.#needsVm('computer.stream');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#computer(() => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/computer/stream'), { json: req, timeoutMs: 90_000 }));
+        },
+        streamStop: async () => {
+            const refusal = this.#needsVm('computer.stream_stop');
+            if (refusal)
+                throw refusal;
+            await this.#computer(() => this.#json('DELETE', this.#p('/v1/workspaces/{workspace_id}/computer/stream')));
+        },
+    };
     // ---- browser ---------------------------------------------------------------------------
     browser = {
         screenshot: (req) => {

package/dist/client.d.ts

@@ -14,6 +14,8 @@ import { HttpClient } from './http.js';
 import type { RequestOptions } from './http.js';
 import type { ToolName, ToolToken } from './tokens.js';
 import { Workspace } from './workspace.js';
+import { WorkspaceRef } from './workspace-ref.js';
+import type { WorkspaceRefParams } from './workspace-ref.js';
 import { AuditApi } from './audit.js';
 import { EgressPolicyApi } from './egress.js';
 import { WorkspacePorts } from './ports.js';
@@ -28,6 +30,8 @@ import type { ProgressListener } from './progress.js';
 import { CaptureRegistry } from './capture.js';
 import type { FeedbackReceipt, SendFeedbackParams } from './feedback.js';
 export type WorkspaceView = components['schemas']['Workspace'];
+/** Contracts §45.1 (0.15.0+): the workspace's computer use switch. */
+export type ComputerUse = components['schemas']['ComputerUse'];
 export type Operation = components['schemas']['Operation'];
 /** persistent (kept until deleted) or session (discarded when the session ends: close(), idle timeout). */
 export type WorkspaceLifetime = components['schemas']['WorkspaceLifetime'];
@@ -116,9 +120,9 @@ export interface SuspendWhenIdleResult {
     workspace: Workspace;
 }
 export interface ShardfluxOptions {
-    /** Project API key: sfk_<key_id>_<secret>. */
-    apiKey: string;
-    /** Default https://api.shardflux.dev (override with `baseUrl`). */
+    /** Project API key: sfk_<key_id>_<secret>. Default (0.15.0+): the `SHARDFLUX_API_KEY` environment variable. */
+    apiKey?: string;
+    /** Default (0.15.0+): `SHARDFLUX_API_URL`, else https://api.shardflux.dev. */
     baseUrl?: string;
     /** Default: pooled HTTP/1.1 on Node 26+, native fetch on other runtimes (see defaultFetch in http.ts). */
     fetch?: typeof fetch;
@@ -260,6 +264,12 @@ export interface OpenParams {
     /** Searchable metadata; supplied labels replace the existing map. */
     labels?: Record<string, string>;
     idlePolicy?: IdlePolicy;
+    /**
+     * Computer use (0.15.0+, contracts §45.1): true or false sets the workspace's own switch, null follows the template;
+     * omitted leaves it unchanged. While it is on, tool tokens carry the `computer` tool and `workspace.computer` drives
+     * the workspace desktop. 409 `computer_use_unavailable` when the template version cannot run a desktop.
+     */
+    computerUse?: boolean | null;
     key: string;
     template: string;
     caps?: Caps;
@@ -403,6 +413,8 @@ export declare class WorkspacesApi {
     /** Replace labels. An empty map clears them. */
     setLabels(workspaceId: string, labels: Record<string, string>): Promise<Workspace>;
     /** null clears the override, restoring the template or platform policy. */
+    /** Computer use (0.15.0+): the workspace's own switch; null follows the template. Returns the switch. */
+    setComputerUse(workspaceId: string, enabled: boolean | null): Promise<ComputerUse>;
     setIdlePolicy(workspaceId: string, idlePolicy: IdlePolicy | null): Promise<Workspace>;
     list(params?: ListParams): Promise<Page<Workspace>>;
     /** Iterates every page. */
@@ -585,7 +597,14 @@ export declare class Shardflux {
     readonly audit: AuditApi;
     /** Shared volumes: persistent storage attached to workspaces at a mount path. */
     readonly volumes: VolumesApi;
-    constructor(opts: ShardfluxOptions);
+    /** Reads `SHARDFLUX_API_KEY` and `SHARDFLUX_API_URL` (0.15.0+) for an `apiKey` or `baseUrl` that is not passed. */
+    constructor(opts?: ShardfluxOptions);
+    /**
+     * A workspace named by its key (0.15.0+, contracts §46): no request until its first call, which opens the key
+     * (created on first use with `params.template`, resumed afterwards). `workspace(key, { template: 'default' })
+     * .exec('...')` is a whole integration; see `WorkspaceRef`.
+     */
+    workspace(key: string, params: WorkspaceRefParams): WorkspaceRef;
     /** The authenticated principal (the API key, its organization and project). */
     me(): Promise<Me>;
     entitlements(organizationId: string): Promise<Entitlements>;
@@ -601,4 +620,10 @@ export declare class Shardflux {
     /** Raw access to any /v1 endpoint with the SDK's authentication and error handling. */
     request<T>(method: string, path: string, init?: Parameters<HttpClient['json']>[2]): Promise<T>;
 }
+/**
+ * A workspace named by its key, on a client from the environment (0.15.0+): `new Shardflux()` reads
+ * `SHARDFLUX_API_KEY` (and `SHARDFLUX_API_URL`) on the first call. `workspace(key, { template: 'default' }).exec('...')`
+ * creates the workspace on first use and resumes it afterwards. Use `cloud.workspace()` for a client of your own.
+ */
+export declare function workspace(key: string, params: WorkspaceRefParams): WorkspaceRef;
 export { ShardfluxApiError };

package/dist/client.js

@@ -1,6 +1,7 @@
 import { DurabilityLostError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
 import { HttpClient, SDK_VERSION, SERVER_WAIT_MAX_S, defaultFetch, defaultSleep, pollWithWait, randomId } from "./http.js";
 import { Workspace } from "./workspace.js";
+import { WorkspaceRef } from "./workspace-ref.js";
 import { AuditApi } from "./audit.js";
 import { EgressPolicyApi } from "./egress.js";
 import { WorkspacePorts } from "./ports.js";
@@ -165,6 +166,8 @@ export class WorkspacesApi {
             body.labels = params.labels;
         if (params.idlePolicy !== undefined)
             body.idle_policy = params.idlePolicy;
+        if (params.computerUse !== undefined)
+            body.computer_use = params.computerUse;
         if (params.lifetime !== undefined)
             body.lifetime = params.lifetime;
         if (params.mode !== undefined)
@@ -193,7 +196,9 @@ export class WorkspacesApi {
             if (res.body.operation)
                 trace.observe(res.body.operation);
             this.#noteToken(res.body.tool_token);
-            const wrapOpts = { agentLabel: params.agentLabel, tools: params.tools, token: res.body.tool_token, trace };
+            // An API before contracts §46.2 does not say whether the open created the workspace.
+            const created = res.body.created ?? null;
+            const wrapOpts = { agentLabel: params.agentLabel, tools: params.tools, token: res.body.tool_token, trace, created };
             if (res.status === 200 || params.wait === false || res.body.operation === null)
                 return this.#wrap(res.body.workspace, wrapOpts);
             if (TERMINAL.has(res.body.operation.state)) {
@@ -390,6 +395,10 @@ export class WorkspacesApi {
         return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/labels`, { json: { labels } }, this.#auth));
     }
     /** null clears the override, restoring the template or platform policy. */
+    /** Computer use (0.15.0+): the workspace's own switch; null follows the template. Returns the switch. */
+    async setComputerUse(workspaceId, enabled) {
+        return this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/computer-use`, { json: { enabled } }, this.#auth);
+    }
     async setIdlePolicy(workspaceId, idlePolicy) {
         return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/idle-policy`, { json: { idle_policy: idlePolicy } }, this.#auth));
     }
@@ -793,8 +802,13 @@ export class Shardflux {
     /** Shared volumes: persistent storage attached to workspaces at a mount path. */
     volumes;
     #ctx;
-    constructor(opts) {
-        if (!/^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/.test(opts.apiKey))
+    #toolGrants = new GrantsCache(() => this.me());
+    /** Reads `SHARDFLUX_API_KEY` and `SHARDFLUX_API_URL` (0.15.0+) for an `apiKey` or `baseUrl` that is not passed. */
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? envVar('SHARDFLUX_API_KEY');
+        if (apiKey === undefined)
+            throw new Error('Missing API key: pass apiKey or set SHARDFLUX_API_KEY (a project key, sfk_<key_id>_<secret>)');
+        if (!/^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/.test(apiKey))
             throw new Error('apiKey must be a Shardflux project key (sfk_<key_id>_<secret>)');
         const f = opts.fetch ?? defaultFetch();
         const userAgent = opts.userAgent ?? `shardflux-sdk-ts/${SDK_VERSION}`;
@@ -807,10 +821,10 @@ export class Shardflux {
         this.egress = new EgressPolicyApi(() => this.#ctx);
         this.audit = new AuditApi(() => this.#ctx);
         this.volumes = new VolumesApi(() => this.#ctx);
-        const baseUrl = opts.baseUrl ?? 'https://api.shardflux.dev';
+        const baseUrl = opts.baseUrl ?? envVar('SHARDFLUX_API_URL') ?? 'https://api.shardflux.dev';
         this.#ctx = {
             http: new HttpClient({ baseUrl, fetch: f, userAgent, timeoutMs: opts.timeoutMs ?? 30_000, maxRetries: opts.maxRetries ?? 2, source: 'api', sleep, onSuccess: versionCheckHook(opts.versionCheck, baseUrl, f, userAgent) }),
-            authorization: `Bearer ${opts.apiKey}`,
+            authorization: `Bearer ${apiKey}`,
             fetch: f,
             userAgent,
             sleep,
@@ -819,6 +833,14 @@ export class Shardflux {
             captures: new CaptureRegistry(),
         };
     }
+    /**
+     * A workspace named by its key (0.15.0+, contracts §46): no request until its first call, which opens the key
+     * (created on first use with `params.template`, resumed afterwards). `workspace(key, { template: 'default' })
+     * .exec('...')` is a whole integration; see `WorkspaceRef`.
+     */
+    workspace(key, params) {
+        return new WorkspaceRef(this.workspaces, key, params, () => this.#toolGrants.get());
+    }
     /** The authenticated principal (the API key, its organization and project). */
     me() {
         return this.#ctx.http.json('GET', '/v1/me', {}, this.#ctx.authorization);
@@ -842,4 +864,34 @@ export class Shardflux {
         return this.#ctx.http.json(method, path, init, this.#ctx.authorization);
     }
 }
+/** The client of the module-level `workspace()`: created on first use from the environment. */
+let defaultClient = null;
+/**
+ * A workspace named by its key, on a client from the environment (0.15.0+): `new Shardflux()` reads
+ * `SHARDFLUX_API_KEY` (and `SHARDFLUX_API_URL`) on the first call. `workspace(key, { template: 'default' }).exec('...')`
+ * creates the workspace on first use and resumes it afterwards. Use `cloud.workspace()` for a client of your own.
+ */
+export function workspace(key, params) {
+    defaultClient ??= new Shardflux();
+    return defaultClient.workspace(key, params);
+}
+/** An environment variable, trimmed; undefined when unset, empty or outside Node-like runtimes. */
+function envVar(name) {
+    return globalThis.process?.env?.[name]?.trim() || undefined;
+}
+/** The API key's tool permissions (GET /v1/me), read once; a failed read is not kept. Null for a non-key principal. */
+class GrantsCache {
+    #load;
+    #value = null;
+    constructor(load) {
+        this.#load = load;
+    }
+    get() {
+        this.#value ??= this.#load().then((me) => (me.api_key ? [...me.api_key.tool_permissions] : null), (err) => {
+            this.#value = null;
+            throw err;
+        });
+        return this.#value;
+    }
+}
 export { ShardfluxApiError };