@shardflux/sdk 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -3,8 +3,72 @@
 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.
+
 ## 0.14.0 (not yet published)
 
+### Sign up from an agent
+
+Additive (API contracts §44).
+
+- `ShardfluxAccount.signup({ email?, displayName?, codexIdToken? })` (POST /v1/auth/signup): a working account and
+  its session in one call, with no browser and no email round-trip. Returns `{ account, result }`; `result.access`
+  is `verified`, `provisional` (works at once on the Free plan; the trial starts when the email is verified) or
+  `verification_required`, and `result.created` is false when a Codex proof signed in to an existing account.
+- `codexIdentityProof(opts?)` (Node): the OpenAI ID token of the Codex CLI signed in on this machine, refreshed by
+  Codex itself (`codex app-server`, `account/read {refreshToken: true}`) and read from `$CODEX_HOME/auth.json`. Only
+  the ID token is returned. Never throws: `{ ok: false, reason: 'codex_not_found' | 'not_signed_in' |
+  'api_key_login' | 'stale', message }`.
+- `account.auth.requestEmailCode()` and `account.auth.verifyEmailCode(code)` (POST /v1/auth/verify-email/code):
+  verify with a 6-digit emailed code; nothing is signed out.
+- `account.auth.stepUp({ codexIdToken })`: a step-up with the linked Codex login instead of the password.
+- New types `SignupResult`, `SignupAccess`, `EmailCodeResult`, `CodexIdentityProof`, `CodexProofOptions`,
+  `CodexProofUnavailable`.
+
 ### Workspaces working at once
 
 Additive. The plan's workspace number caps workspaces working at the same moment; stored workspaces are bounded by
@@ -25,6 +89,76 @@ Retained state.
 - Regenerated contract types: `ErrorCode` includes `quota_exceeded` for the workspace gateway; allowance
   `enforcement` adds `storage_block`, `cap_state` adds `storage_blocked`.
 
+### Inbound ports
+
+Additive. A TCP port of a processful workspace can be served at its own private HTTPS URL,
+`https://<port>-<handle>.<domain>`; a request wakes a parked or suspended workspace and is answered once it runs.
+
+- `workspace.ports` and `cloud.workspaces.ports(id)` (class `WorkspacePorts`): `expose(port)` →
+  `{port, url, createdAt, callback, created}` (`ExposePortResult`; idempotent, `created` false when it already was),
+  `list()` → `ExposedPort[]`, `close(port)`, `token(port, {ttlSeconds?})` → `{token, expiresAt, url}` (`PortToken`),
+  `link(port, {ttlSeconds?, path?})` → `{url, expiresAt}` (`PortLink`), `createCallbackUrl(port)` →
+  `{url, createdAt}` (`PortCallbackUrl`) and `revokeCallbackUrl(port)`. `expose`, `close` and `revokeCallbackUrl` are
+  retried on transient failures; minting calls are not.
+- Types `ExposedPort`, `ExposePortResult`, `PortToken`, `PortLink`, `PortCallbackUrl`, `PortTokenOptions`,
+  `PortLinkOptions` and the raw API shapes `PortView`, `PortTokenResponse`, `PortLinkResponse`, `PortCallbackResponse`
+  (regenerated contract types).
+- `KnownErrorReason` adds `inbound_ports_not_available`, `port_not_exposed` and `port_limit`.
+
+### Memory across platform upgrades
+
+Additive. A resume keeps the workspace's memory and running processes across host kernel, CPU generation and
+Firecracker upgrades of the platform.
+
+- `ColdBootReason` gains `runtime_retired`, and `COLD_BOOT_REASONS` lists every reason this version knows
+  (`runtime_changed`, `host_lost`, `runtime_retired`). `runtime_retired`: the runtime the workspace was suspended on
+  was retired after an announced window; the resume booted the saved disk (`resumePath` `cold_boot`,
+  `memoryRestored` false). A reason this version does not know is still passed through as a string.
+
+### Resize a workspace
+
+Additive. Change the memory, CPU and disk of any workspace, running or suspended, fixed or elastic, without a restart
+or a fork.
+
+- `workspace.resize({ memoryMib, memoryMibHeld, allocationMode, cpuMillis, diskGib })` and
+  `cloud.workspaces.resize(id, params)` send `PATCH /v1/workspaces/{id}/caps` with the given caps (snake_case, at
+  least one; none throws `TypeError` before any request), an `Idempotency-Key` (`idempotencyKey`, default a fresh key
+  per call, so a retried request replays) and `Prefer: wait` (up to 20 s, within `timeoutMs`). They resolve once the
+  resize has finished: a resize the server answers with `202` is waited for like any operation (`timeoutMs`, default
+  300 000 ms; `signal`; `onProgress`, action `resize`). A resize that meets another lifecycle operation (409
+  `operation_in_progress`) waits for it and is sent again with the same `Idempotency-Key`, within `timeoutMs`. A failed
+  resize is its error: `ShardfluxApiError` 409 with `operationId` (reason `resize_failed`, ...) when the server held
+  the request until then, `OperationFailedError` when the SDK waited for the operation.
+- `ResizeResult`: `workspaceId`, `operationId`, `state`, `caps` (the stored caps every later start uses),
+  `operation` (the finished operation after a `202`, else null) and, for each resource the request named,
+  `memory` / `cpu` / `disk` (`ResizeMemory`, `ResizeCpu`, `ResizeDisk`): `applies_at` (`now`, `resume` or
+  `next_start`), `requested_*`, `target_*`, `previous_*`, `applied_*`, `limit_reason` (`plan`, `template`,
+  `host_capacity`, `shrink_stalled`) and `reason` (`suspended`, `stopped`, `boot_vcpus`, `region`, `below_base`,
+  `legacy_layout`); memory adds `allocation_mode`, `held_mib` and `converged`. Types `ResizeParams`,
+  `ResizeAppliesAt`, `ResizeLimitReason` and `ResizeDeferReason` are exported.
+- The handle refreshes its view after a resize. A file-first workspace is refused locally with
+  `NotSupportedForModeError`.
+- A finished operation's `result` (the cell's) is returned in the held answer's shape: each named resource with its
+  documented keys, a key left out taken from the operation's input or null, other keys dropped.
+- `KnownErrorReason` adds `resize_not_available` (409 `conflict`), `resize_failed` (409 `conflict`, a failed resize)
+  and `shrink_not_supported` (422 `validation_failed`, `details.current_disk_gib`). `LifecycleAction` adds `resize`.
+
+### Memory hint for commands
+
+Additive. `RunOptions.resourceHint` (`'auto' | 'light' | 'heavy'`, type `ResourceHint`) on `exec.run()`, and
+`resource_hint` on `exec.start()` requests: `heavy` gives an elastic workspace its memory before the command starts,
+`light` starts it at once, `auto` (the default) decides from the command. Sent only when set, so other requests are
+unchanged. The processful `exec` agent tool takes `resource_hint` with the same values.
+
+### Elastic by default
+
+With elastic-by-default enabled for the organization, an open of a new processful workspace without
+`caps.allocation_mode` is elastic: it holds the memory its commands use and grows up to `memory_mib` (when not given,
+the plan's largest workspace, bounded by the template); billing counts the memory it holds. `allocation_mode: 'fixed'`
+gives a static allocation of `memory_mib`. Reopening an existing workspace with caps that omit `allocation_mode` then
+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)
 
 Patch, additive: the transport, a documented value, a fix for tool calls across a move and self-healing workspaces.

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
 
@@ -360,10 +431,11 @@ lookups by key.
 
 ### Elastic memory (0.13.0+)
 
-Promise a workspace a lot of memory while it holds only what it uses. An elastic workspace idles at its held floor
-(`memory_mib_held`, default 1024) and grows before each command starts, so compilers, test runners and V8 size
-themselves from the memory they will actually get. After 30 s without work it shrinks back. The layout takes effect at
-the workspace's next start.
+A workspace can hold only the memory its commands use and grow up to `memory_mib` when they need more; billing counts
+the memory it holds. An elastic workspace idles at its held floor (`memory_mib_held`, default 1024) and shrinks back
+after 30 s without work. Package installs, test runners, compilers, type checkers and bundlers get their memory before
+they start, so they size their heaps and workers from what they will actually get; everything else starts at once and
+the workspace grows while it runs.
 
 ```ts
 const ws = await cloud.workspaces.open({
@@ -375,10 +447,32 @@ ws.memory;           // { allocation_mode: 'elastic', promised_mib: 8192, held_m
 
 const r = await ws.cell().exec.run(['npm', 'test']);
 r.memoryGrow;        // { outcome: 'delivered', from_mib: 1024, want_mib: 4096, got_mib: 4096, deliver_ms: 175 }
+
+await ws.cell().exec.run(['python3', 'train.py'], { resourceHint: 'heavy' });   // 0.14.0+: memory first, then the command
 ```
 
-Given `caps` replace the stored ones, so send `allocation_mode` with every `caps` you pass; an open without `caps`
-keeps the stored layout. The exec agent tool adds `memory_grow` to its result when the command's start grew the VM.
+`resourceHint` (0.14.0+) is `'auto'` (the default: decided from the command), `'heavy'` or `'light'`; the exec agent
+tool takes `resource_hint`. `allocation_mode: 'fixed'` gives a static allocation of `memory_mib`. Send
+`allocation_mode` with every `caps` you pass to keep the mode you chose; an open without `caps` keeps the stored
+layout, and a fork without `caps` inherits its source's. The exec agent tool adds `memory_grow` to its result when the
+command's start grew the workspace.
+
+### Resize a workspace (0.14.0+)
+
+Change the memory, CPU and disk of any workspace, running or suspended, fixed or elastic, without a restart:
+
+```ts
+const r = await ws.resize({ memoryMib: 6144, diskGib: 20 });
+r.memory;   // { applies_at: 'now', previous_mib: 2048, applied_mib: 6144, converged: true, ... }
+r.disk;     // { applies_at: 'now', previous_gib: 10, applied_gib: 20, ... }
+
+await ws.resize({ allocationMode: 'elastic', memoryMibHeld: 1024 });   // switch modes live
+```
+
+Memory changes live, and disks grow online. A suspended workspace gets its new size when it resumes, before its first
+call. CPU changes live within the vCPUs the workspace booted with; a larger CPU size applies at the next start. Each
+resource says when it applies (`applies_at`: `now`, `resume` or `next_start`), and the new caps are stored, so every
+later start uses them.
 
 ### Burst execution (0.13.0+)
 
@@ -398,6 +492,83 @@ workspace's own processes resume where they were. A burst is not signalled or ca
 fails (`burst_apply_failed`), retry `exec.run` with the same `sessionId` to finish the apply. The agent tools offer
 bursts when asked: `workspaceTools(ws, { burst: true })`.
 
+### Inbound ports (0.14.0+)
+
+Serve a port of the workspace at its own HTTPS URL: a preview of the app your agent is building, a webhook receiver,
+an OAuth redirect, a live view. A request wakes a parked or suspended workspace and is answered once it runs, so the
+workspace can sleep between visits. Every port is private: a request carries a port token, a signed link's browser
+session, or arrives on the port's callback URL.
+
+```ts
+await ws.cell().exec.start({ argv: ['python3', '-m', 'http.server', '3000', '--bind', '0.0.0.0'] });
+const { url } = await ws.ports.expose(3000);   // https://3000-<handle>.shardflux.app
+
+const { token } = await ws.ports.token(3000);  // { token: 'sfp_…', expiresAt, url }, 1 h by default
+await fetch(url, { headers: { authorization: `Bearer ${token}` } });
+
+const link = await ws.ports.link(3000, { path: '/dashboard' }); // open link.url in a browser (24 h by default)
+const hook = await ws.ports.createCallbackUrl(3000);            // register `${hook.url}github` as a webhook URL
+```
+
+- The server inside the workspace listens on `0.0.0.0` (all interfaces), not only `127.0.0.1`.
+- `expose(port)` is idempotent: `created` is true when this call exposed the port; an exposed port keeps its URL, tokens,
+  links and callback URL. `list()` returns `{ port, url, createdAt, callback }` for each exposed port.
+- `token(port, { ttlSeconds })` (60-86400): send it as `Authorization: Bearer <token>`, or as `X-Shardflux-Token`
+  when the app reads `Authorization` itself. `link(port, { ttlSeconds, path })` (60-604800 s): anyone with the link can
+  open the port until it expires, so share it like a password.
+- `createCallbackUrl(port)`: a URL with a secret in its path for GitHub, Slack, Stripe or an OAuth provider; a request
+  to `<url><rest>` reaches `/<rest>` without a token header. Its secret is shown only once; calling it again replaces
+  it, `revokeCallbackUrl(port)` revokes it.
+- `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)
@@ -657,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
@@ -682,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
@@ -849,7 +1023,7 @@ await workspace.cell().exec.run(['python3', 'agent.py']);          // sees $OPEN
 
 `ShardfluxAccount` does what a person does in the web app, with a user session instead of an API key: sign up, sign
 in (with MFA), organizations, projects, API keys, members, invitations, billing, audit, data export and account
-deletion. Two steps stay human: opening the verification email, and paying in Stripe Checkout.
+deletion. Paying in Stripe Checkout is the step a person does.
 
 ```ts
 import { Shardflux, ShardfluxAccount } from '@shardflux/sdk';
@@ -887,6 +1061,37 @@ const cloud = new Shardflux({ apiKey: secret });
 - `parseEmailToken(input)` returns the `token` of a link's `#token=` fragment or `?token=` query (else the trimmed
   input), and throws for a link without one.
 
+### Sign up from an agent (0.14.0+)
+
+One call gives a working account, with no browser and no email round-trip. With the Codex CLI signed in with ChatGPT
+on the machine, the account is verified by that login and starts with its trial:
+
+```ts
+import { ShardfluxAccount, codexIdentityProof } from '@shardflux/sdk';
+
+const proof = await codexIdentityProof();            // asks Codex to refresh its login, returns the ID token
+const { account, result } = proof.ok
+  ? await ShardfluxAccount.signup({ codexIdToken: proof.idToken, onSessionToken: (s) => save(s.token) })
+  : await ShardfluxAccount.signup({ email: 'ada@example.com', onSessionToken: (s) => save(s.token) });
+// result.access: 'verified' | 'provisional' | 'verification_required'; result.created: false when it signed in
+
+if (result.access !== 'verified') {
+  await account.auth.requestEmailCode();             // a 6-digit code to the inbox (15 minutes)
+  await account.auth.verifyEmailCode('123456');      // verified; the session and keys keep working
+}
+```
+
+- `codexIdentityProof()` (Node) reads only the ID token from `$CODEX_HOME/auth.json` (default `~/.codex`), after
+  `codex app-server` refreshes it; it never throws: `{ ok: false, reason }` is `codex_not_found`, `not_signed_in`,
+  `api_key_login` or `stale`. The token proves the ChatGPT account's verified email and is not a credential to
+  OpenAI.
+- With a Codex proof, `signup` signs in to the account of that ChatGPT identity or email when there is one, else
+  creates it. `result.status` `mfa_required`: `account.auth.completeMfa({ code })`.
+- With an email only, a `provisional` account works at once on the Free plan; verifying the email starts the trial.
+  An address that has an account is 409 `conflict` (`details.reason` `email_registered`).
+- `account.auth.stepUp({ codexIdToken })` confirms a sensitive action with the linked Codex login instead of a
+  password.
+
 Upgrading a plan: a person pays at the Checkout `url`; the code waits for the subscription.
 
 ```ts
@@ -966,6 +1171,11 @@ of that base), or `invalid_path` (`details.field` `recipe.immutable[<i>]`). A bu
 `failure.code` `immutable_path_missing` (`failure.details.path` is not a directory in the built filesystem) or
 `immutable_image_too_large`.
 
+Inbound ports **(0.14.0+)**: 403 `forbidden` with `reason` `inbound_ports_not_available` (inbound ports are not enabled
+for the organization), 404 `not_found` with `reason` `port_not_exposed` (a token, link or callback URL of a port that is
+not exposed: expose it first; `details.port`), 409 `conflict` with `reason` `port_limit` (close a port first;
+`details.limit`), and 422 `validation_failed` for a port outside 1-65535 or an option out of range.
+
 ## Usage and overage
 
 `cloud.usage` reads the organization's usage (API keys see organization totals and their own project's workspaces):
@@ -1110,3 +1320,13 @@ import { isWorkspaceGone, ShardfluxProtocolError } from '@shardflux/sdk';
 ### Repositories with a minimum release age
 
 Keep your repository's age policy. Pin an exact version that has aged enough; do not exempt the entire `@shardflux/*` scope. The first SDK, 0.5.0, was published September 26, 2026 at 21:13:52 UTC and reaches seven days on October 3 at that time. New versions, including 0.12.0, need their own seven days after publication. Before then no registry setting on our side can make them eligible. `npm view @shardflux/sdk time --json` shows publication times. A targeted exception for an inspected exact release is a repository-owner decision, not an installation requirement we bypass. Older versions do not contain this release's fixes.
+
+### Prepare tool input (0.14.0+)
+
+`workspaceTools(workspace, { prewake: true })` adds an optional `onInputStart()` callback to tools that need the VM. Call the matching tool's callback when the model starts streaming its input, then execute the tool normally once its arguments are complete. The callback returns immediately and prepares the workspace in the background. Without `prewake`, tools have no input-start callback. File reads served from disk and file-first tools have no callback.
+
+```ts
+const tools = workspaceTools(workspace, { prewake: true });
+// In your model stream's tool-input-start handler:
+tools.find(tool => tool.name === toolName)?.onInputStart?.();
+```

package/dist/account.d.ts

@@ -2,6 +2,8 @@
  * The account plane with a user session (0.9.0): what a person does in the web app, from code.
  *
  *   // Before a session exists (no token needed)
+ *   const proof = await codexIdentityProof();                       // 0.14.0+: this machine's Codex login
+ *   const { account } = await ShardfluxAccount.signup(proof.ok ? { codexIdToken: proof.idToken } : { email });
  *   await ShardfluxAccount.register({ email, password, displayName });
  *   await ShardfluxAccount.verifyEmail(linkFromTheEmail);
  *   const { account, result } = await ShardfluxAccount.login({ email, password, onSessionToken: (s) => save(s.token) });
@@ -44,6 +46,14 @@ type Ok<Op> = Op extends {
     [K in keyof R]: K extends 200 | 201 | 202 ? JsonOf<R[K]> : never;
 }[keyof R] : never;
 export type RegisterResult = Ok<operations['postV1AuthRegister']>;
+/**
+ * Agent signup (0.14.0+): `status`, `created`, `access` (`verified` | `provisional` | `verification_required`), the
+ * user, and the new `session_token`.
+ */
+export type SignupResult = Ok<operations['postV1AuthSignup']>;
+export type SignupAccess = SignupResult['access'];
+/** POST /v1/auth/verify-email/code: `{ status: 'accepted' }` (code sent) or `{ status: 'verified' }`. */
+export type EmailCodeResult = Ok<operations['postV1AuthVerifyEmailCode']>;
 export type VerifyEmailResult = Ok<operations['postV1AuthVerifyEmail']>;
 export type PasswordResetRequestResult = Ok<operations['postV1AuthPasswordResetRequest']>;
 export type PasswordResetConfirmResult = Ok<operations['postV1AuthPasswordResetConfirm']>;
@@ -178,11 +188,15 @@ export declare class AccountAuthApi {
     sessions(): Promise<AuthSessionPage>;
     revokeSession(sessionId: string): Promise<void>;
     /**
-     * Confirms the password (and a code when MFA is on) for the calls that need a recent check (403
+     * Confirms the password, or a Codex identity proof of the Codex login linked to the account (0.14.0+:
+     * `codexIdToken` from codexIdentityProof()), plus a code when MFA is on, for the calls that need a recent check (403
      * `step_up_required`). Rotates the session token.
      */
-    stepUp(params: {
+    stepUp(params: ({
         password: string;
+    } | {
+        codexIdToken: string;
+    }) & {
         code?: string;
         recoveryCode?: string;
     }): Promise<StepUpResult>;
@@ -195,6 +209,13 @@ export declare class AccountAuthApi {
     changeEmail(newEmail: string): Promise<EmailChangeResult>;
     /** Sends the verification email again. */
     resendVerification(): Promise<ResendVerificationResult>;
+    /**
+     * Emails a 6-digit verification code to the account address (0.14.0+; valid 15 minutes, once). Confirm it with
+     * verifyEmailCode: nothing is signed out, and an account from `signup` gets its trial.
+     */
+    requestEmailCode(): Promise<EmailCodeResult>;
+    /** Verifies the email with the 6-digit code (0.14.0+). A wrong code is 400 `token_invalid`; 5 wrong attempts end it. */
+    verifyEmailCode(code: string): Promise<EmailCodeResult>;
 }
 export declare class OrganizationExportsApi {
     #private;
@@ -458,6 +479,24 @@ export declare class ShardfluxAccount {
     sendFeedback(params: AccountFeedbackParams): Promise<FeedbackReceipt>;
     /** Raw access to any /v1 endpoint with the session's authentication and the SDK's error handling. */
     request<T>(method: string, path: string, init?: RequestOptions): Promise<T>;
+    /**
+     * Signs up from an agent with no browser or email round-trip (0.14.0+); `account` holds the new session.
+     *
+     * - `codexIdToken` (from codexIdentityProof()): the email is verified by the Codex login's ChatGPT account. Signs in
+     *   to the account of that identity or email when there is one (`result.created` false), else creates it.
+     *   `result.status` `mfa_required`: complete with `account.auth.completeMfa({ code })`.
+     * - `email` only: creates an unverified account. `result.access` `provisional`: it works now on the default plan,
+     *   and the trial comes with `auth.requestEmailCode()` + `auth.verifyEmailCode(code)`; `verification_required`:
+     *   verify first. An address that has an account is 409 `conflict` (`details.reason` `email_registered`).
+     */
+    static signup(params: PreSession<{
+        email?: string;
+        displayName?: string;
+        codexIdToken?: string;
+    }>): Promise<{
+        account: ShardfluxAccount;
+        result: SignupResult;
+    }>;
     /** Creates an account; a verification link is emailed (`{ status: 'accepted' }` also when the email is taken). */
     static register(params: PreSession<{
         email: string;

package/dist/account.js

@@ -149,11 +149,12 @@ export class AccountAuthApi {
         return json(this.#core, 'DELETE', `/v1/auth/sessions/${enc(sessionId)}`);
     }
     /**
-     * Confirms the password (and a code when MFA is on) for the calls that need a recent check (403
+     * Confirms the password, or a Codex identity proof of the Codex login linked to the account (0.14.0+:
+     * `codexIdToken` from codexIdentityProof()), plus a code when MFA is on, for the calls that need a recent check (403
      * `step_up_required`). Rotates the session token.
      */
     async stepUp(params) {
-        const body = { password: params.password };
+        const body = 'password' in params ? { password: params.password } : { codex_id_token: params.codexIdToken };
         if (params.code !== undefined)
             body.code = params.code;
         if (params.recoveryCode !== undefined)
@@ -173,6 +174,17 @@ export class AccountAuthApi {
     resendVerification() {
         return json(this.#core, 'POST', '/v1/auth/verify-email/resend');
     }
+    /**
+     * Emails a 6-digit verification code to the account address (0.14.0+; valid 15 minutes, once). Confirm it with
+     * verifyEmailCode: nothing is signed out, and an account from `signup` gets its trial.
+     */
+    requestEmailCode() {
+        return json(this.#core, 'POST', '/v1/auth/verify-email/code', { json: {} });
+    }
+    /** Verifies the email with the 6-digit code (0.14.0+). A wrong code is 400 `token_invalid`; 5 wrong attempts end it. */
+    verifyEmailCode(code) {
+        return json(this.#core, 'POST', '/v1/auth/verify-email/code', { json: { code: code.replace(/\s+/g, '') } });
+    }
 }
 export class OrganizationExportsApi {
     #core;
@@ -603,6 +615,28 @@ export class ShardfluxAccount {
         const account = ShardfluxAccount.#client(opts);
         return account.#ctx.http.json('POST', path, body === undefined ? {} : { json: body });
     }
+    /**
+     * Signs up from an agent with no browser or email round-trip (0.14.0+); `account` holds the new session.
+     *
+     * - `codexIdToken` (from codexIdentityProof()): the email is verified by the Codex login's ChatGPT account. Signs in
+     *   to the account of that identity or email when there is one (`result.created` false), else creates it.
+     *   `result.status` `mfa_required`: complete with `account.auth.completeMfa({ code })`.
+     * - `email` only: creates an unverified account. `result.access` `provisional`: it works now on the default plan,
+     *   and the trial comes with `auth.requestEmailCode()` + `auth.verifyEmailCode(code)`; `verification_required`:
+     *   verify first. An address that has an account is 409 `conflict` (`details.reason` `email_registered`).
+     */
+    static async signup(params) {
+        const { email, displayName, codexIdToken, ...opts } = params;
+        const account = ShardfluxAccount.#client(opts);
+        const body = {
+            ...(email === undefined ? {} : { email }),
+            ...(displayName === undefined ? {} : { display_name: displayName }),
+            ...(codexIdToken === undefined ? {} : { codex_id_token: codexIdToken }),
+        };
+        const result = await account.#ctx.http.json('POST', '/v1/auth/signup', { json: body });
+        await account.#adopt(result);
+        return { account, result };
+    }
     /** Creates an account; a verification link is emailed (`{ status: 'accepted' }` also when the email is taken). */
     static register(params) {
         const { email, password, displayName, ...opts } = params;