@shardflux/sdk 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,13 +1,77 @@
 # Changelog
 
-## 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)
+## 0.16.0 (not yet published)
+
+- Add `@shardflux/sdk/testing`: `createFakeShardflux` supplies an isolated in-memory transport beneath real SDK handles, refs and errors, with scripted commands, a virtual clock, fault controls and captured response shapes. A shared scenario manifest runs against the fake and live API.
+
+- Add opt-in persistent workspace idle deletion retention, workspace/project setters and projected deletion times.
+
+- Accelerate reverse tunnels with a bounded, acknowledged binary WebSocket stream, 64 KiB frames and batched credits. Select `auto`, `pty` or `exec` transport; reconnect preserves byte offsets. Opt-in binary PTY output accepts larger blocks for file transfers.
+
+- Add opt-in resize controls to grow named resources only and return the held server answer without polling a pending operation.
+- Expose typed stored workspace caps and preserve nullable grants. Fixed memory without an explicit size uses the template default.
+
+- `WorkspaceRef.turn(fn, { afterSeconds: 0 })` and `Workspace.turn()` hint without waiting and request idle suspension when the body settles, including errors.
+- Computer `act()` avoids an extra screenshot after `screenshot`/`zoom`. Viewer links are reused by kind with more than 60 seconds left; `fresh: true` remints, and `stopStream()` clears them.
+- `computerToolset(ws, { beforeAction })` and `workspaceTools(ws, { computer: { beforeAction } })` check each action immediately before execution; refusal answers that action with an error and skips the rest.
+- The default pooled transport honors environment HTTP(S) proxies and NO_PROXY. `SHARDFLUX_BASE_URL` aliases `SHARDFLUX_API_URL`, which takes precedence.
+- Exec and execution results expose `exitCodePosix`. Missing cell file paths with `path_not_found` raise `FileNotFoundError`, distinct from workspace deletion and protocol errors.
+- Embed live desktop viewers and port previews in a web app with an explicit HTTPS origin allowlist and partitioned browser sessions.
+
+- Add `workspace.tunnels.reverse({ remotePort, target, bindAddress?, signal? })`: a private workspace TCP listener forwarded to this machine, with binary multiplexing, bounded backpressure, half-close, transport reconnection, suspend/resume, statistics and deterministic close.
+
+- Add `ws.upgrade({ at })`, `upgradeAvailable` and `upgradePending`. An opt-in cold start preserves the workspace disk; `next_resume` schedules it. Lifecycle cold boot reasons include `upgraded`.
+
+### Integration testing
+
+## 0.15.0 — 2026-10-04
+
+### 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
+
+- 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.
 
 ### Sign up from an agent
 
@@ -117,7 +181,7 @@ gives a static allocation of `memory_mib`. Reopening an existing workspace with
 keeps its stored mode; a fork without caps inherits its source's. The SDK's requests do not change;
 `workspace.memory` and `workspace.allocationMode` report the mode the workspace got.
 
-## 0.13.1 (not yet published)
+## 0.13.1 — 2026-10-03
 
 Patch, additive: the transport, a documented value, a fix for tool calls across a move and self-healing workspaces.
 `@shardflux/cli` 0.8.1, `@shardflux/mcp` 0.7.1 and the `shardflux` bundle 0.10.1 follow (`^0.13.1`).
@@ -174,7 +238,7 @@ failing with `409 conflict` (`workspace_not_running`).
   runs; new token)`.
 - The CLI, the MCP server and the `shardflux` bundle get it through their `^0.13.0` dependency.
 
-## 0.13.0
+## 0.13.0 — 2026-10-02
 
 ### Elastic memory
 
@@ -284,14 +348,12 @@ template's newest published version, picked up at its next cold boot or resume.
 - The cancel that `exec.run` sends when its `signal` aborts passes `killGraceMs` capped at 60000, so a larger
   `killGraceMs` still cancels the command.
 
-## 0.12.0 (release candidate)
+## 0.12.0 — 2026-09-30
 
 Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
 
 Pooled HTTP/1.1 on Node 26 with pinned undici 8.10.2; custom fetch stays unchanged. Labels on open/list and setLabels, typed idle(), keepalive() and setIdlePolicy(). Protocol errors carry source; isWorkspaceGone recognizes only an explicit API workspace_deleted refusal. Exec sessions accept stdin_open and offset-addressed exec.input. Failed workspaces recover through resume/auto-wake with the same ID. Completed deletions free keys for new IDs.
 
-Requires the QM integration backend release for labels, failed recovery, key reuse and pipe stdin. No production deployment has occurred from this branch.
-
 ### Instant suspend: durable storage in the result
 
 Additive. A suspend returns as soon as the workspace is sealed on its host; the copy lands in durable storage right
@@ -316,7 +378,7 @@ after. This release reads that from the result and can wait for it.
 Requires the instant-suspend cell release for `durable: false` results; against other servers every succeeded suspend
 is already durable and `durable: true` resolves at once.
 
-## 0.11.1
+## 0.11.1 — 2026-09-30
 
 Wording: messages and JSDoc say what to do, without internals (no behaviour change).
 
@@ -330,7 +392,7 @@ Wording: messages and JSDoc say what to do, without internals (no behaviour chan
   `SHARDFLUX_HTTP_KEEPALIVE=1`.
 - The `formatTiming()` example is a production resume (413 ms).
 
-## 0.11.0
+## 0.11.0 — 2026-09-29
 
 ### A resume that restarted processes says so (cold boot)
 
@@ -353,17 +415,17 @@ the resume's result through; this release reads it.
 - The new `ServerTiming` fields are optional in the type (always set by the SDK), so timings built by hand still
   type-check. No return type or behaviour changes: a wake that cold-booted still resolves `true`.
 
-## 0.10.2
+## 0.10.2 — 2026-09-29
 
 Fix: the SDK reports 0.10.2. 0.10.1 was published reporting 0.10.0, its previous version; the build now
 fails when `SDK_VERSION` differs from package.json.
 
-## 0.10.1
+## 0.10.1 — 2026-09-29
 
 Public support: package metadata and the README now link to the [shared bug tracker](https://github.com/shardfluxdev/community/issues),
 feature requests, and private support/security reporting.
 
-## 0.10.0
+## 0.10.0 — 2026-09-29
 
 ### A command that could not start rejects exec.run() (ExecStartError)
 
@@ -411,7 +473,7 @@ from the API's OpenAPI); the account client's `setSpendPolicy()` gains the overa
 
 - `workspace.suspendWhenIdle({ afterSeconds, idempotencyKey? })` and `cloud.workspaces.suspendWhenIdle(id, {
   afterSeconds })` (POST /v1/workspaces/{id}/suspend-when-idle): the workspace is suspended once it has been idle for
-  `afterSeconds` (30..3600), counted from the later of its last work and the request. Meant for the end of an agent
+  `afterSeconds` (0..3600 since the 2026-09-30 API release, commit `2b2f5e658`; originally 30..3600), counted from the later of its last work and the request. Meant for the end of an agent
   turn. A running command, an attached stream or a keepalive postpones it; the next tool call or a resume cancels it.
   Resolves with `{ suspendRequest, operation, workspace }`: `operation` is the suspend already in progress, if any
   (then nothing is recorded).
@@ -421,7 +483,7 @@ from the API's OpenAPI); the account client's `setSpendPolicy()` gains the overa
   count as the next turn and cancel the request.
 - Types `SuspendRequest`, `SuspendWhenIdleOptions`, `SuspendWhenIdleResult`, `SuspendWhenIdleResponse`.
 
-## 0.9.0
+## 0.9.0 — 2026-09-29
 
 Elastic compute (decision 0007): file tools and wake hints for parked workspaces. Additive; older APIs and cell
 gateways keep working (the new calls answer 404 there).
@@ -617,7 +679,7 @@ behavior is the automatic version check (below), which makes one background requ
 - New exports: `FeedbackCategory`, `FeedbackContext`, `FeedbackReceipt`, `SendFeedbackParams`, `AccountFeedbackParams`,
   `FEEDBACK_CATEGORIES`, `FEEDBACK_MESSAGE_MAX_LENGTH`.
 
-## 0.8.0 (2026-09-28)
+## 0.8.0 — 2026-09-28
 
 Types only; nothing changes at run time and the API is unchanged.
 
@@ -637,7 +699,7 @@ Types only; nothing changes at run time and the API is unchanged.
 - Checked at compile time against `@anthropic-ai/sdk` 0.128.0 and `openai` 7.23.0 (devDependencies only; the SDK still
   has no runtime dependencies).
 
-## 0.7.0 (2026-09-28)
+## 0.7.0 — 2026-09-28
 
 Needs an API with the template editor; every new field is additive and older fields are unchanged.
 
@@ -725,7 +787,7 @@ docs/decisions/0006-tool-call-capture.md (shared with the Python SDK 0.3.0).
 - **Breaking (types only):** `LifecyclePhase` gains `capture_flush`; an exhaustive `switch` over phases without a
   `default` case needs the new member.
 
-## 0.6.2 (2026-09-28)
+## 0.6.2 — 2026-09-28
 
 ### Starts that wait for capacity end
 
@@ -740,7 +802,7 @@ boot (and bill) long after every wait had given up.
 - `onProgress`: a `capacity_pending` `phase` event carries `deadlineAt` when the API reports it.
 - Docs: waits no longer say a pending start continues indefinitely.
 
-## 0.6.1 (2026-09-28)
+## 0.6.1 — 2026-09-28
 
 - `formatTiming()` joined two phases that followed each other with `∥` (ran together) when their 0.1 ms times summed
   with a floating-point error (1000.2 + 300.1 > 1300.3); it now prints `→`.
@@ -750,7 +812,7 @@ boot (and bill) long after every wait had given up.
   belonged to no phase (a 1 s wait could show `queued 0 ms`).
 - README: the timing example is the formatter's real output (durations under a second print in ms).
 
-## 0.6.0 (2026-09-28)
+## 0.6.0 — 2026-09-28
 
 ### Lifecycle calls: requested or finished
 
@@ -801,7 +863,7 @@ boot (and bill) long after every wait had given up.
   create, capture state, test instances, publish, discard).
 - `ShardfluxApiError.reason` (`details.reason`), with `KnownErrorReason`.
 
-## 0.5.0 (2026-09-26)
+## 0.5.0 — 2026-09-26
 
 First public release: `Shardflux` client, `workspaces.open/get/list/listAll`, lifecycle calls returning operations,
 `waitForOperation()`, the cell client (`exec`, `files`, `pty`, `processes`, `git`, `browser`), `workspaceTools()` with

package/README.md

@@ -1,6 +1,6 @@
 # @shardflux/sdk
 
-TypeScript SDK for [Shardflux](https://shardflux.dev): cloud computers for AI agents.
+TypeScript SDK for [Shardflux](https://shardflux.dev): serverless VMs for AI agents.
 
 Open a persistent workspace by key, run commands and move files in it, suspend it when idle, resume
 it later with its disk and memory intact, and fork it. Hand your agent framework-neutral workspace
@@ -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
@@ -19,6 +20,34 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 - Typed from the published OpenAPI documents.
 - Retries, idempotency keys, operation polling and tool-token refresh are handled for you.
 
+## Test your integration (0.16.0+)
+
+Use the same client calls in fast, isolated tests with `@shardflux/sdk/testing`:
+
+```ts
+import { createFakeShardflux } from '@shardflux/sdk/testing';
+
+const cloud = createFakeShardflux({
+  onExec: (request) => ({ stdout: `ran ${request.argv.join(' ')}\n`, exitCode: 0 }),
+});
+const ref = cloud.workspace('acme/test', { template: 'python-node-browser' });
+const result = await ref.exec(['python3', '-V'], { sessionId: 'version-check' });
+await ref.files.write('/home/user/result.txt', result.stdout);
+```
+
+The fake returns real SDK workspace handles, refs and errors. Workspace lifecycle calls, labels, paginated lists,
+files, command output, desktop actions and port lists use an isolated in-memory store. Command results come from
+`onExec`; returning `null` leaves a command running for `cloud.testing.completeCommand(id, sessionId, result)`.
+Unscripted commands and unimplemented routes raise `FakeUnsupportedError`.
+
+Control state with `cloud.testing.setFaults(id, { busy: true, failed: true, legacyLayout: true })`,
+`computerUnavailable`, `deleted`, `resizeRefusal` (`shrink_not_supported` or `resize_not_available`), and
+`memoryLimitMib` (a plan clamp). Set `cloud.testing.quota` to `retained_state` or `concurrent_workspaces`.
+`cloud.testing.advance(milliseconds)` drives idle deadlines; `latencyMs` and `sleep` inject request latency.
+`cloud.testing.inspect(id)` returns a copy of the raw workspace view. Each fake has its own state.
+Import the testing subpath when building tests; the main SDK entry keeps its existing runtime dependencies.
+
+
 ## Support and bug reports
 
 [Report a bug](https://github.com/shardfluxdev/community/issues/new?template=bug_report.yml) or
@@ -30,6 +59,29 @@ For usage, account, billing, or private support, email [shardflux@heliosone.fi](
 Report vulnerabilities through [private security reporting](https://github.com/shardfluxdev/community/security/advisories/new).
 See the [support guide](https://github.com/shardfluxdev/community/blob/main/SUPPORT.md) for all reporting options.
 
+## Reverse tunnels (0.16.0+)
+
+Forward a workspace TCP port to a service on the machine running your SDK:
+
+```ts
+const tunnel = await workspace.tunnels.reverse({ remotePort: 8081, target: 'localhost:8081' });
+try {
+  // Commands in the workspace can call http://127.0.0.1:8081.
+  console.log(tunnel.stats);
+} finally {
+  await tunnel.close();
+}
+```
+
+The guest listener binds to `127.0.0.1` by default; `bindAddress: '0.0.0.0'` selects all guest interfaces.
+The target is dialed from this machine. TCP binary data, concurrent connections and half-close are preserved;
+network reconnection resumes the tunnel while the handle is open. `closed` reports completion or failure,
+`sessionId` identifies the forwarder, and `stats` counts connections, bytes in each direction and reconnects.
+An open tunnel keeps the workspace awake; close it when callbacks are finished. For persistent workspaces, explicit suspend/resume preserves
+an open tunnel. The caller needs `exec` and `files` access.
+
+The tunnel selects a streaming transport automatically when `pty` permission is granted. Choose `transport: 'pty'` or `transport: 'exec'` in the SDK, or `--transport pty|exec` in the CLI, to select it explicitly. The handle reports `transport`.
+
 ## Install
 
 ```sh
@@ -41,6 +93,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 +149,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 +203,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 +573,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 +879,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 +906,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
@@ -1209,3 +1381,50 @@ const tools = workspaceTools(workspace, { prewake: true });
 // In your model stream's tool-input-start handler:
 tools.find(tool => tool.name === toolName)?.onInputStart?.();
 ```
+
+Resize controls (0.16.0+): `workspace.resize({ memoryMib: 6144, diskGib: 2, atLeast: true, wait: false })` grows
+only resources that need more capacity and returns the held server answer with its operation. `workspace.caps` exposes
+typed stored caps for later starts. A pending operation carries per-resource results once the resize has decided
+them. Fixed memory without `memory_mib` uses the template default, bounded by the plan and template.
+
+## New in 0.16.0
+
+`ref.turn(async (ref) => { ... })` (also `workspace.turn`) sends a wake hint without waiting, returns the body's result, and requests `suspendWhenIdle({ afterSeconds: 0 })` when it settles, including on error. Pass `{ afterSeconds: 60 }` to keep the workspace warm for a billed minute. Use persistent workspaces for resumable turns.
+
+Computer batches ending in `screenshot` or `zoom` return that action's image without an extra screenshot. `computer.stream()` reuses a link of the same kind with more than 60 seconds left; `{ fresh: true }` mints one, and `stopStream()` clears the cache. Gate each action with `computerToolset(ws, { beforeAction })` or `workspaceTools(ws, { computer: { beforeAction } })`: return `false`, a refusal string, or throw to answer that action with an error and skip the remaining actions. Hooks may be async.
+
+Exec results expose `exitCodePosix`: timeout 124, canceled 130, nonnegative exit code, 128 + signal, otherwise 1. `FileNotFoundError` is a `ShardfluxApiError` for cell `path_not_found` replies. The default transport honors `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and `NODE_USE_ENV_PROXY`. `SHARDFLUX_BASE_URL` aliases `SHARDFLUX_API_URL`; `SHARDFLUX_API_URL` wins.
+
+## Embed a live viewer (0.16.0+)
+
+Watch the desktop or a port preview inside your web app. Choose 1–10 distinct HTTPS origins, then use the returned URL as the iframe source.
+
+```ts
+const { url } = await ws.computer.stream({ embed: { origins: ['https://app.example.com'] } });
+const preview = await ws.ports.link(3000, { embed: { origins: ['https://app.example.com'] } });
+```
+
+```html
+<iframe src="RETURNED_LINK_URL" title="Watch the agent" style="width:100%;height:600px;border:0"></iframe>
+```
+
+The browser session is partitioned by the top-level site. Each origin is exactly a scheme and host with an optional port, such as `https://app.example.com:8443`. The viewer permits framing by those origins; interactive viewing uses the same allowlist.
+
+## Idle deletion retention (0.16.0+)
+
+Keep one persistent workspace per conversation and delete it automatically after 14 idle days:
+
+```ts
+const ws = await cloud.workspaces.open({ key: 'chat/42', template: 'python-node-browser', retention: { delete_after_idle_days: 14 } });
+await ws.setRetention({ delete_after_idle_days: 30 });
+await cloud.projects.setRetention((await cloud.me()).api_key!.project_id, { delete_after_idle_days: 14, labels: { app: 'chat' } });
+await ws.setRetention(null); // follow the project default
+```
+
+`cloud.workspace(key, { template, retention })` accepts the same policy. `ws.retention` shows its effective days
+and projected `delete_at`. All project selector labels must match exactly; a workspace's own policy wins.
+Calls and ongoing work postpone deletion. Without a policy, your workspace stays until you delete it.
+
+## Workspace upgrade (0.16.0+)
+
+`await ws.upgrade({ at: "now", wait: true })` keeps files, installed package files and home while cold starting on the supported current layout and base. `at: "next_resume"` schedules it for the next resume. Memory and running processes end at the cold start. Read `ws.upgradeAvailable` and `ws.upgradePending` for the target.

package/dist/account.d.ts

@@ -277,6 +277,8 @@ export declare class AccountProjectsApi {
         name: string;
         slug?: string;
     }): Promise<Project>;
+    getRetention(projectId: string): Promise<import('./client.js').ProjectRetentionPolicy | null>;
+    setRetention(projectId: string, policy: import('./client.js').ProjectRetentionPolicy | null): Promise<import('./client.js').ProjectRetentionPolicy | null>;
     get(projectId: string): Promise<Project>;
 }
 /** Every tool permission an API key can carry (pass it as `toolPermissions` for a key with every tool). */

package/dist/account.js

@@ -280,6 +280,12 @@ export class AccountProjectsApi {
     create(organizationId, params) {
         return json(this.#core, 'POST', `/v1/organizations/${enc(organizationId)}/projects`, { json: { name: params.name, ...(params.slug === undefined ? {} : { slug: params.slug }) } });
     }
+    getRetention(projectId) {
+        return json(this.#core, 'GET', `/v1/projects/${enc(projectId)}/retention`);
+    }
+    setRetention(projectId, policy) {
+        return json(this.#core, 'PUT', `/v1/projects/${enc(projectId)}/retention`, { json: policy });
+    }
     get(projectId) {
         return json(this.#core, 'GET', `/v1/projects/${enc(projectId)}`);
     }

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'];
@@ -238,6 +248,8 @@ export declare const CAPTURE_BARRIER: unique symbol;
 export interface RunResult {
     sessionId: string;
     exitCode: number | null;
+    /** POSIX status: timeout 124, canceled 130, exit code, 128 + signal, otherwise 1. */
+    exitCodePosix: number;
     termSignal: number | null;
     timedOut: boolean;
     canceled: boolean;
@@ -530,6 +542,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>;