@shardflux/sdk 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,9 +1,180 @@
 # 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.13.0 (not yet published)
+## 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
+Retained state.
+
+- A tool call that finds every workspace the plan allows to work at once busy is refused with 429 `quota_exceeded`
+  (retryable, `Retry-After`; `details.limit` `concurrent_workspaces`, `limit_value`, `current`,
+  `retry_after_seconds`). The call did not run, so the SDK sends the same request again after `Retry-After` (at most
+  5 s) within `maxRetries`, for every call: exec starts, stdin, PTY create, keepalive and process signals included.
+  A refusal that outlasts the retries is a `ShardfluxApiError` with `retryAfterSeconds`. `executions.run()` keeps
+  these retries and does not add its own on top; the wake hint is not retried (it never waits).
+- `pty.read()` rejects with the refusal (`ShardfluxApiError`, e.g. 429 `quota_exceeded`, retryable) when an accepted
+  attach is closed with an error body and a 4xxx close code, instead of returning empty output.
+- The API's 403 `quota_exceeded` is not retried, as before. New `details.limit`: `retained_state` (`limit_value` and
+  `current` in GiB): opening a new key and forking are refused while the plan's Retained state is used up; existing
+  workspaces keep running, waking, suspending and resuming. Usage summaries report that allowance with `enforcement`
+  `storage_block` and `cap_state` `storage_blocked`.
+- 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.
+`@shardflux/cli` 0.8.1, `@shardflux/mcp` 0.7.1 and the `shardflux` bundle 0.10.1 follow (`^0.13.1`).
+
+### Workspaces recover by themselves
+
+Additive. When the machine a workspace runs on fails, the workspace is suspended, and its next use (a tool call's wake,
+`resume()`, `open()`) restores it: from its own disk, files kept, or from its newest checkpoint. Nothing changes for
+code that already handles a cold resume.
+
+- `cold_boot_reason` / `ServerTiming.coldBootReason` can be `host_lost`: the resume booted the workspace's disk
+  (`resumePath` `cold_boot`, `memoryRestored` false, processes restarted). New type `ColdBootReason`
+  (`'runtime_changed' | 'host_lost'`, open to other strings; the field still accepts any string).
+- `hostLostOf(op)` and `ServerTiming.hostLost`: `result.host_lost` camelCased (`HostLost`: `detectedAt`,
+  `restoredFrom` `'disk' | 'checkpoint'`, `restoredCheckpointId`, `stateAsOf`). A resume from the checkpoint has its
+  state as of `stateAsOf`; a suspend that found the machine failed succeeds with `durable: true` and only
+  `detectedAt` (`restoredFrom` null).
+- `formatTiming()` prints `processes restarted (host_lost)` for the disk, `restored checkpoint <id> (host_lost; state as
+  of <time>)` for the checkpoint, and `host_lost (detected <time>)` for the suspend.
+- Documented operation error codes: `resume_required` (a fork or snapshot of such a workspace before its resume; resume
+  it first; not retryable) and `workspace_storage_unavailable` with `details.reason` `host_lost` (not retryable).
+  `KnownErrorReason` gains `host_lost`.
+
+### Connection reuse
+
+Additive. The call after an agent's pause between tool calls reuses its connection instead of opening a new one.
+
+- On Node 26 the pooled transport keeps an idle connection reusable for 5 minutes (was 4 s), so a request seconds or
+  minutes after the last one skips the TCP and TLS handshake. Pooled sockets send TCP keepalive probes after 60 s
+  idle, so NATs and firewalls along the way keep the connection open. Idle connections never keep a process alive. A
+  supplied `fetch`, other runtimes and `SHARDFLUX_HTTP_KEEPALIVE` work as before.
+- A request the SDK retries (GET, a request with an `Idempotency-Key`, a read-only POST such as files search) whose
+  connection closes before the response arrives is sent again at once on a new connection. That one resend has no
+  backoff and does not count against `maxRetries`; timing records and progress `retry` events list it with
+  `delayMs: 0`. A further failure follows `maxRetries` and backoff as before, and a POST without an
+  `Idempotency-Key` is never sent twice.
+
+### Faster suspend and resume
+
+Additive. `resumePath` / `resume_path` can be `thaw`: a resume that arrives while its suspend is still being
+written continues the same VM in place. Nothing else changes for your code.
+
+### Tool calls across a move
+
+Fix. A tool call made while its workspace finishes a resume or a move now runs once the workspace runs, instead of
+failing with `409 conflict` (`workspace_not_running`).
+
+- When the call's tool token was refused as not running and the wake then found the workspace already running (the
+  resume or move committed in between; `wake` resolves `false`), the call is retried with a current token: the held
+  resume's, or a new one. A refused call never ran, so the retry cannot run it twice. Before, the refusal surfaced.
+- A refusal that comes back while the API keeps reporting the workspace running is retried after 500 ms, within the
+  same 3 wakes and `transitionTimeoutMs`, then surfaces as before.
+- `onProgress` sees the retry as a `tool` event of type `retry`, cause `conflict workspace_not_running (the workspace
+  runs; new token)`.
+- The CLI, the MCP server and the `shardflux` bundle get it through their `^0.13.0` dependency.
+
+## 0.13.0
 
 ### Elastic memory
 
@@ -446,7 +617,6 @@ 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)
 
 Types only; nothing changes at run time and the API is unchanged.

package/README.md

@@ -296,10 +296,10 @@ await cell.exec.run(['make', 'test']);                         // resumes the wo
 ```
 
 **Detecting a cold resume (0.11.0+).** A resume restores memory and running processes from the checkpoint. After a
-platform runtime update, a resume can boot from the saved disk instead of restoring memory (a cold boot), also when a
-tool call wakes the workspace; check `memoryRestored`. The workspace runs with its files as of the suspend, and its
-processes start fresh, as after a reboot: start dev servers, databases and background jobs again. The resume's timing
-says which it was:
+platform runtime update, or after the machine the workspace ran on failed (0.13.1+), a resume can boot from the saved
+disk instead of restoring memory (a cold boot), also when a tool call wakes the workspace; check `memoryRestored`. The
+workspace runs with its files kept, and its processes start fresh, as after a reboot: start dev servers, databases and
+background jobs again. The resume's timing says which it was:
 
 ```ts
 const t = workspace.lastTiming; // after resume({ wait: true }), wake(), or a tool call that woke the workspace
@@ -310,11 +310,20 @@ if (t?.server?.memoryRestored === false) {
 
 - `ServerTiming.memoryRestored`: `true` when memory and processes came back, `false` when the workspace booted
   (`resumePath` `cold_boot`, or `reset_blank_layer` after a reset), `null` when the API did not say (older APIs).
-- `ServerTiming.coldBootReason`: why it booted (`runtime_changed`), else null. `formatTiming()` prints
-  `resume from cold_boot: processes restarted (runtime_changed)`.
+- `ServerTiming.coldBootReason` (type `ColdBootReason`): why it booted, `runtime_changed` or `host_lost`
+  **(0.13.1+)**, else null. `formatTiming()` prints `resume from cold_boot: processes restarted (runtime_changed)`.
 - The finished resume operation carries the same in `result` (`memory_restored`, `cold_boot_reason`, and
   `cold_boot` with details such as `files_as_of`; it is informational and not part of the stable contract).
 
+**Workspaces recover by themselves (0.13.1+).** When the machine a workspace runs on fails, the workspace is suspended,
+and its next use (a tool call, `resume()`, `open()`) restores it; there is nothing extra to call.
+`hostLostOf(op)` and `lastTiming.server.hostLost` (`HostLost`) say how:
+
+- `restoredFrom: 'disk'`: it booted from its own disk, files kept (`coldBootReason` `host_lost`, processes restarted).
+- `restoredFrom: 'checkpoint'`: it resumed its newest checkpoint (`restoredCheckpointId`); its state is as of
+  `stateAsOf`. `formatTiming()` adds `restored checkpoint <id> (host_lost; state as of <time>)`.
+- A `suspend()` that finds the machine failed succeeds (`result.durable` true, `hostLost.detectedAt`).
+
 `suspend`, `resume`, `fork`, `snapshot` and `delete` return the lifecycle operation.
 `cloud.workspaces.waitForOperation(id)` waits for it (default timeout 5 minutes): each poll asks the API to hold
 the response until the operation changes (`Prefer: wait`, at most 20 s per request), so completion arrives within
@@ -324,7 +333,15 @@ operation keeps running server side (a queued start until its `deadlineAt`); wai
 same call. `templates.builds.waitForBuild()` waits the same way. A waited `open()` issues the first tool token
 together with the final workspace read, so the first tool call starts at once.
 
-From 0.12.0, Node 26 reuses TLS connections through a private HTTP/1.1 pool. Other runtimes keep native fetch. A supplied `fetch` stays unchanged. `SHARDFLUX_HTTP_KEEPALIVE=0` forces connection closure for diagnosis; `=1` opts into native pooling. No global dispatcher is installed.
+From 0.12.0, Node 26 reuses TLS connections through a private HTTP/1.1 pool. From 0.13.0, an idle connection stays
+reusable for 5 minutes, so the call after an agent's pause between tool calls skips the TCP and TLS handshake, and
+pooled sockets send TCP keepalive probes after 60 s idle. Idle connections never keep a process alive. Other runtimes
+keep native fetch. A supplied `fetch` stays unchanged. `SHARDFLUX_HTTP_KEEPALIVE=0` forces connection closure for
+diagnosis; `=1` opts into native pooling. No global dispatcher is installed.
+
+A request the SDK retries (safe methods, requests with an `Idempotency-Key`, read-only POSTs) whose connection closes
+before the response arrives is sent again at once on a new connection **(0.13.0+)**, without backoff and outside
+`maxRetries`; timing records list it with `delayMs: 0`.
 
 List and look up workspaces:
 
@@ -343,10 +360,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({
@@ -358,10 +376,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+)
 
@@ -381,6 +421,36 @@ 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)`.
+
 ### Timing and progress (0.6.0+)
 
 Every open, wake and waited lifecycle call is traced. `workspace.lastTiming` (and `err.timing` when the call fails)
@@ -412,7 +482,7 @@ This resume brought the workspace back from its host's local cache, memory and r
   running, including any time in `capacity_pending`; `ran` is the cell's work (placement, boot or restore, guest
   readiness). `start` / `resume from` and `boot to ready` / `host …` are what the cell reported. A resume that booted
   the saved disk instead of restoring memory reads `resume from cold_boot: processes restarted (runtime_changed)`
-  (0.11.0+).
+  (0.11.0+), or `(host_lost)` (0.13.1+) after the machine the workspace ran on failed.
 - **outside the server** is your total minus the operation's: network, TLS, polling latency, view and token. A large
   value with a small server total points at the connection between you and the API, not at the workspace.
 - **retries** lists transient failures the SDK retried (cause and backoff).
@@ -832,7 +902,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';
@@ -870,6 +940,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
@@ -949,6 +1050,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):
@@ -1093,3 +1199,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;

package/dist/cell.d.ts

@@ -30,6 +30,12 @@ import type { RequestOptions } from './http.js';
 import type { ProgressListener } from './progress.js';
 import type { ToolTokenManager } from './tokens.js';
 type S = components['schemas'];
+/**
+ * How much memory a command needs at its start (0.14.0; `resource_hint` of an exec start): `heavy` grows an elastic
+ * workspace's memory before the command starts (a build, a test suite, a package install), `light` starts it at once,
+ * `auto` (the default) decides from the command. A fixed workspace has its memory already.
+ */
+export type ResourceHint = NonNullable<S['ExecStartRequest']['resource_hint']>;
 export type ExecStartRequest = S['ExecStartRequest'];
 export type ExecSession = S['ExecSession'];
 /**
@@ -174,8 +180,9 @@ export interface CellClientOptions {
     sleep?: (ms: number) => Promise<void>;
     /**
      * Wakes a suspended workspace (resume, or join the active resume/open) within `timeoutMs` and resolves once it runs;
-     * resolves `false` when there was nothing to wake (the API already reports it running), and the refusal then
-     * surfaces. It throws when the wake fails (OperationFailedError) or outlasts `timeoutMs` (OperationTimeoutError).
+     * resolves `false` when there was nothing to wake (the API already reports it running): the refused call is then
+     * retried with a current token, since the transition that refused it ended meanwhile (0.13.1+). It throws when the
+     * wake fails (OperationFailedError) or outlasts `timeoutMs` (OperationTimeoutError).
      * Workspace.cell() supplies `workspace.wake()`. A call refused with `workspace_not_running` wakes the workspace and is
      * retried; a refused call was never executed, so the retry cannot duplicate it. `null` surfaces
      * the refusal instead. A wake that put a new token into this client's manager (the held resume;
@@ -292,6 +299,14 @@ export interface RunOptions {
     burstVcpus?: number;
     /** Burst VM memory in MiB (512-65536; default the host's, 8192, or the plan's ceiling when lower). */
     burstMemoryMib?: number;
+    /**
+     * How much memory the command needs at its start (0.14.0; sent as `resource_hint`, omitted when unset): `'heavy'`
+     * grows an elastic workspace's memory before the command starts, so a build, test suite or install sizes its heap and
+     * workers from the memory it gets; `'light'` starts it at once and the workspace grows while it runs; `'auto'` (the
+     * default) decides from the command (package installers, test runners, compilers, type checkers and bundlers are
+     * heavy). A value outside these is ShardfluxApiError 422 `validation_failed` (details.field `resource_hint`).
+     */
+    resourceHint?: ResourceHint;
 }
 /** The API error of a burst's recorded failure (`burst.error` of its session). Internal (the agent tools use it too). */
 export declare function burstFailure(e: BurstError): ShardfluxApiError;
@@ -320,8 +335,10 @@ export declare class CellClient {
      * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions,
      * bounded in total by `transitionTimeoutMs`: a call refused with `workspace_busy` is retried after `Retry-After`; one
      * refused with `workspace_not_running` (or whose token cannot be minted because the workspace is not running) wakes
-     * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call.
-     * Refused calls were never executed, so retrying is safe. When the budget is spent the refusal surfaces.
+     * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call. A
+     * wake that finds the workspace already running (`false`) is retried the same way: the transition that refused the
+     * call ended meanwhile (0.13.1+). Refused calls were never executed, so retrying is safe. When the budget is spent
+     * the refusal surfaces.
      */
     request(method: string, path: string, init?: RequestOptions & TransitionOptions): Promise<Response>;
     /**