@shardflux/sdk 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,148 @@
 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)
+
+### Elastic memory
+
+Additive. A workspace may be promised more memory than it holds while idle, and the host grows it when a command needs
+it (opt-in per workspace).
+
+- `Caps.allocation_mode` (`'fixed' | 'elastic'`, type `AllocationMode`) and `Caps.memory_mib_held` on `open()`,
+  `workspaces.fork()` and `workspace.fork()`. Given caps replace the stored ones (caps without `allocation_mode` make
+  the workspace fixed); omitted caps keep the stored layout.
+- `workspace.memory` (`WorkspaceMemory`: `{allocation_mode, promised_mib, held_mib, plugged_mib}`, null on an older
+  API) and `workspace.allocationMode` (`'fixed'` on an older API). `WorkspaceView` carries `caps.allocation_mode`,
+  `caps.memory_mib_held` and `memory` (regenerated contract types).
+- `RunResult.memoryGrow` (`MemoryGrow | null`): the grow the exec's start waited for (`outcome` delivered, partial,
+  missed or failed; `from_mib`, `want_mib`, `got_mib`, `deliver_ms`), from the start's session. `ExecSession`
+  carries `memory_grow`. The `exec` agent tool adds `memory_grow` to its result when a grow ran.
+- `KnownErrorReason` adds `allocation_mode_not_available`, `requires_elastic` and `exceeds_memory_mib` (422
+  `validation_failed`; elastic with file-first is the existing `not_supported_for_mode`).
+
+### Burst execution
+
+Additive. One heavy, run-to-completion command can run on a larger, short-lived burst VM on the workspace's host, and
+its file changes are applied back.
+
+- `RunOptions.burst` (`'never' | 'always'`), `burstVcpus` and `burstMemoryMib` on `exec.run()`; `ExecStartRequest`
+  carries `burst`, `burst_vcpus` and `burst_memory_mib` (regenerated contract types).
+- `RunResult.burst` (`BurstSummary | null`): host, size, method, whether the changes were applied, the change counts,
+  `leftover_killed`, `overhead_ms`, `excluded_paths`, `timings`, `replayed`. `ExecSession.burst` carries it; types
+  `BurstSummary` and `BurstError` are exported.
+- `exec.run()` rejects with `ShardfluxApiError` 409 `burst_unavailable` or `burst_apply_failed` also when the burst
+  fails after its start (the output stream's final error event, or `burst.error` on the ended session), without
+  reconnecting; it does not try to cancel a burst when its `signal` aborts (a burst cannot be canceled).
+- `ErrorCode` adds `burst_unavailable` and `burst_apply_failed`; `KnownErrorReason` adds `burst_mode_not_supported`,
+  `burst_not_supported`, `burst_size_exceeds_plan`, `not_available`, `shared_volumes`, `fence_not_drained`,
+  `apply_pending`, `park_failed`, `workspace_resumed`, `interrupted`, `burst_lost`, `disk_full`, `apply_failed`,
+  `reverted` and `revert_failed`.
+- `workspaceTools(ws, { burst: true })` (opt-in, default off) gives the processful `exec` tool the inputs `burst`,
+  `burst_vcpus` and `burst_memory_mib`, and its result adds `burst`. The default tool schemas are unchanged.
+
+### Background commands in the agent tools
+
+Additive. An agent can start a long command, keep working with the other tools, read its progress and stop it.
+
+- The processful `exec` tool takes `background: true`: it starts the command and returns `{session_id, state}` at
+  once (a failed start adds `error: {code, message, reason}`, as the foreground `exec` gives it). `timeout_ms` goes up
+  to 86400000 (a day); with `background` it is sent only when given. The file-first `exec` is unchanged.
+- New tool `exec_read` (permission `exec`): the session's `state`, `exit_code`, `term_signal`, `timed_out`,
+  `canceled` and output. Without offsets it returns the last `maxOutputBytes` of each stream; `stdout_offset` /
+  `stderr_offset` read from there, and the result's `next_stdout_offset` / `next_stderr_offset` continue where it
+  stopped (`truncated` when more output follows). Text is cut at character boundaries only. `wait_ms` (up to 60000)
+  waits for the command to exit and returns as soon as it does. `burst` and `error` when the session has them.
+- New tool `exec_cancel` (permission `exec`): SIGTERM, then SIGKILL after `grace_ms` (1-60000, default 5000);
+  returns `{session_id, state, exit_code, canceled}`.
+- With `workspaceTools(ws, { burst: true })`, `background: true` together with `burst: 'always'` is refused with
+  `ToolArgumentError` before any request (a burst holds the workspace until it applies its changes); `burst: 'never'`
+  with `background` is an ordinary background start.
+- `exec_read` and `exec_cancel` follow `exec` in `workspaceTools()` on processful workspaces; a file-first workspace
+  does not offer them. Both send the wake hint like the other tools.
+
+### Held fork
+
+Additive. A waited fork returns the running copy and its tool token in one request.
+
+- `workspaces.fork()` and `workspace.fork()` with `wait`: when the API holds the fork (`Prefer: wait`, answered 200
+  with `Preference-Applied`), the copy's handle adopts the returned running view and final-epoch tool token, with no
+  operation poll, view refresh or token request. The request's time counts against `wait.timeoutMs`.
+- `ForkOptions` and `WaitedForkOptions` (exported) add `agentLabel` and `tools`, which choose that token. They are sent
+  only on a server-held fork and need an API with held fork. `wait: { serverWait: false }` keeps polling.
+- An API that does not apply `Prefer` answers 202 as before; the call then polls the operation and refreshes the copy.
+- The fork's progress `request` phase has reason `held` when it asks the server to wait.
+
+### Exec start and output in one request
+
+- `exec.run()` starts the command and follows its output in one request: the start asks for NDJSON
+  (`Accept: application/x-ndjson`) and a cell that supports it answers with the output stream. A dropped stream
+  reconnects by session and byte offsets, never starting the command again. A cell that answers the start with the
+  session JSON gets the output request after it, as before; a start that failed still rejects with `ExecStartError`
+  (or the burst's error).
+- `RunResult.memoryGrow` and `burst` are unchanged: the combined stream's exit event carries the start's
+  `memory_grow`.
+
+### Immutable paths
+
+A template may declare directories as immutable: every workspace of the template mounts them read-only from the
+template's newest published version, picked up at its next cold boot or resume.
+
+- Recipe v2 `immutable` (`TemplateRecipeV2.immutable`, regenerated): the list in `template.yaml`, sent as written by
+  `buildFromFile()`, `buildFromRecipe()` and `builds.create()`. The stored recipe v2 of a build
+  (`TemplateBuildRecipeV2`) and an exported recipe (`versions.recipe()`) carry it.
+- `TemplateVersion.immutable` (`TemplateVersionImmutable`: `{paths, bytes}`, or null when the version declares none),
+  on every version of `templates.get()` and on `open_version`.
+- `TemplateBuild.immutable_paths`: the list the produced version declares (the recipe's, else the open version's).
+  `TemplateBuild.failure.details` carries code-specific fields: `immutable_path_missing` names `details.path`.
+- `workspace.immutableVersion` (`template.immutable_version` of the view): the template version whose immutable paths
+  the workspace has mounted, which can be newer than `template.version`; null when it mounts none.
+- `KnownErrorReason` adds `immutable_path_removed` (422; `details.removed`, `details.open_version`),
+  `immutable_paths_unsupported_base` (422; `details.base`, `details.required_feature`, `details.paths`) and
+  `read_only_path` (409 `conflict` from the files API for a write under an immutable path).
+- **Breaking:** the update policy left the API. Removed: the `UpdatePolicy` type, `TemplateSummary.update_policy`, the
+  regenerated `update_policy` of the workspace view, of `TemplateDefaults` and of the `defaults` inputs, and the reason
+  `update_policy_not_available`. It was always `pinned`; code that read it drops the read.
+
+### Exec cancel grace
+
+- `exec.cancel(id, graceMs?)` takes `graceMs` 0 to 60000 (0 or omitted: 5000), as the cell API now enforces (422
+  `validation_failed` outside it), and waits for the answer up to the grace plus 15 s when that is longer than the
+  client's `timeoutMs`: a command that ignores SIGTERM is answered after the grace and the SIGKILL, not a timeout.
+- 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)
+
+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
+after. This release reads that from the result and can wait for it.
+
+- `suspend({ durable: true })` (`SuspendOptions.durable`, also `cloud.workspaces.suspend(id, { durable: true })`):
+  resolves once `result.durable` is `true`. It implies `wait` and uses the same `timeoutMs`/`signal` (one budget for
+  the suspend and the copy). Rejects with `DurabilityLostError` (new; `durability` with the reason) when the copy
+  cannot be made, and `OperationTimeoutError` with `durable: true` when the time runs out (the copy continues).
+  `suspend({ wait: true })` still resolves when the suspend succeeds, without waiting for the copy.
+- `cloud.workspaces.waitForDurable(operationOrId, waitOptions)`: the same wait for an operation you hold (a suspend, or
+  a fork of a running workspace).
+- `isDurable(op)`, `durabilityOf(op)` (`Durability`: `state` `pending` | `durable` | `lost`, `checkpointId`,
+  `generationId`, `localCommitAt`, `durableBy`, `durableAt`, `localCommitToDurableMs`, `overdueAt`, `reason`) and
+  `lostSuspendOf(op)` (`LostSuspend`, on a resume result). `ServerTiming` gains `durable`, `suspendPath`, `durability`
+  and `lostSuspend`; progress phase `durable` (reason `overdue` past `durableBy`); `formatTiming()` prints them.
+- `Operation.result` is typed with `durable`, `suspend_path`, `durability` and `lost_suspend` (OpenAPI).
+- `OperationFailedError.workspaceActive`: a suspend-when-idle canceled with `workspace_active` (the workspace was in
+  use; nothing changed and it keeps running). `workspace.waitUntilReady()` resolves for it instead of throwing, as
+  `wake()` already did.
+
+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
 
 Wording: messages and JSDoc say what to do, without internals (no behaviour change).

package/README.md

@@ -14,7 +14,7 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 > **(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, no runtime dependencies, Node.js 24 or later. Reading a YAML template file uses the optional peer
+- ESM only, Node.js 24 or later. Reading a YAML template file uses the optional peer
   dependency `yaml` (`npm install yaml`); JSON template files need nothing.
 - Typed from the published OpenAPI documents.
 - Retries, idempotency keys, operation polling and tool-token refresh are handled for you.
@@ -108,8 +108,9 @@ const listing = await cell.files.list('/home/user');
 await cell.files.remove('/home/user/data.bin');
 ```
 
-`exec.run()` resumes from byte offsets if the output stream drops; it never starts the command
-twice. Aborting its `signal` also cancels the command in the workspace. File writes are atomic
+`exec.run()` starts the command and streams its output in one request **(0.13.0+)**, resumes from
+byte offsets if the output stream drops, and never starts the command twice. Aborting its `signal`
+also cancels the command in the workspace. File writes are atomic
 and durable (acknowledged after fsync).
 
 `cwd` is an absolute path (commands start in `/home/user` without one). The API refuses a relative
@@ -187,7 +188,7 @@ await workspace.resume({ wait: true });       // or simply open() the key again
 
 const { workspace: copy } = await workspace.fork({ key: 'customer-42/experiment' }, { wait: true });
 
-await copy.delete();                          // tool access ends immediately; keys are never reused
+await copy.delete();                          // tool access ends immediately; the key can be reused after deletion finishes
 ```
 
 ### Requested or finished
@@ -199,12 +200,40 @@ means depends on `wait`:
 | --- | --- | --- |
 | `await workspace.suspend()` | the suspend is **requested** (usually `queued`; the workspace is still running) | the operation (`Operation`) |
 | `await workspace.suspend({ wait: true })` **(0.6.0+)** | the suspend has **finished** (`workspace.state` is then `suspended`) | the succeeded operation (`FinishedOperation`) |
+| `await workspace.suspend({ durable: true })` **(0.12.0+)** | the suspend has finished **and** its copy is in durable storage (`result.durable` is `true`) | the succeeded operation (`FinishedOperation`) |
 
 `wait` also takes `WaitOptions` (`timeoutMs`, default 5 minutes; `signal`; `onProgress`). A failed operation throws
 `OperationFailedError`. Running out of time throws `OperationTimeoutError`, and the operation continues server side:
 wait again with `cloud.workspaces.waitForOperation(err.operationId)`. Without `wait`, the returned operation is the
 handle for the work in progress: pass its `id` to `waitForOperation()` when you need it finished.
 
+**A waited fork is one request (0.13.0+).** `fork(target, { wait: true })` asks the API to hold the fork until the
+copy runs, and the answer carries the running copy and a tool token for it: the copy's handle is ready with no
+operation poll, view refresh or token request. `agentLabel` and `tools` pick the token it brings back. Its timing is one
+`request` phase with reason `held`; `wait: { serverWait: false }` polls instead. An API without the held fork answers
+at once, and the SDK then waits for the operation and refreshes the copy, as before.
+
+**Durable storage (0.12.0+).** A suspend returns as soon as the workspace is sealed on its host, typically in a few
+hundred ms, and its RAM and CPU are released at that moment. `result.durable` turns `true` when the copy lands in
+durable storage, typically within a second; until then it is `false` and `result.durability` shows the copy's
+progress. Most code needs nothing more: a suspended workspace resumes, is read and is forked the same way either way.
+When your code must know the copy is durable (before deleting a local artifact, or at the end of a job), ask for it:
+
+```ts
+import { durabilityOf } from '@shardflux/sdk';
+
+const op = await workspace.suspend({ durable: true }); // resolves once result.durable is true
+durabilityOf(op);   // { state: 'durable', checkpointId, localCommitAt, durableAt, localCommitToDurableMs, ... }
+```
+
+- `durable: true` implies `wait` and shares its `timeoutMs` and `signal` (e.g. `{ durable: true, wait: { timeoutMs: 60_000 } }`).
+  If the time runs out first, `OperationTimeoutError` has `durable: true` and the copy continues server side.
+- `cloud.workspaces.waitForDurable(operationOrId)` does the same for an operation you already hold, such as a
+  finished fork of a running workspace, whose result carries `durable` and `durability` the same way.
+- `isDurable(op)`, `durabilityOf(op)` and `lastTiming.server.durable` / `.durability` read the fields; `formatTiming()`
+  prints `sealed on host, durable 435 ms later`. Results from before 0.12.0 servers count as durable.
+- The errors reference on docs.shardflux.dev lists what `durable: true` can reject with.
+
 **Start deadlines.** A queued open, resume, restore or fork (`capacity_pending`) has a deadline 15 minutes after it
 was created. Its `error.details.deadline_at` carries the deadline; the `phase` progress event carries it as
 `deadlineAt` **(0.6.2+)**, and so does `OperationTimeoutError` when your wait ends first. A start still pending at the
@@ -295,8 +324,7 @@ 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.
 
-On Node 26 the default fetch uses a fresh connection for every request (`Connection: close`);
-`SHARDFLUX_HTTP_KEEPALIVE=1`, or your own `fetch`, reuses connections.
+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.
 
 List and look up workspaces:
 
@@ -313,6 +341,46 @@ sessions, template drafts and test instances. `findByKey()` searches every lifet
 workspace, and a tombstone only when no live workspace has the key. Use it rather than `listAll({ keyPrefix })` for
 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.
+
+```ts
+const ws = await cloud.workspaces.open({
+  key: 'customer-42/repo-7',
+  template: 'node',
+  caps: { memory_mib: 8192, allocation_mode: 'elastic' },
+});
+ws.memory;           // { allocation_mode: 'elastic', promised_mib: 8192, held_mib: 1024, plugged_mib: 3072 }
+
+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 }
+```
+
+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.
+
+### Burst execution (0.13.0+)
+
+Run one heavy command, such as a cold build or a full test suite, on a larger VM without resizing the workspace. With
+`burst: 'always'` the command runs on a short-lived burst VM over a copy of the workspace, output streams as usual,
+and its file changes are applied back byte for byte when it exits.
+
+```ts
+const r = await ws.cell().exec.run(['go', 'build', './...'], { burst: 'always', burstVcpus: 16 });
+r.exitCode;          // 0
+r.burst;             // { host: 'local', vcpus: 16, memory_mib: 8192, method: 'layer', applied: true,
+                     //   written_files: 3, written_dirs: 1, removed: 1, written_bytes: 40960, overhead_ms: 641, ... }
+```
+
+A burst carries back the command's file changes; processes it started and tmpfs content stay in the burst VM, and the
+workspace's own processes resume where they were. A burst is not signalled or canceled. If applying the changes
+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 })`.
+
 ### Timing and progress (0.6.0+)
 
 Every open, wake and waited lifecycle call is traced. `workspace.lastTiming` (and `err.timing` when the call fails)
@@ -548,6 +616,27 @@ workspace keeps running so you can inspect it, and `workspace.startup` names the
 The next open runs the failed step again. Versions report their `settings`, platform templates their `category`
 (`os` or `stack`), builds the `denied_hosts` their build network refused (add them to `build.network.extra_hosts`).
 
+### Immutable paths (0.13.0+)
+
+Directories a template declares `immutable` follow the template: every workspace of it mounts them read-only from the
+template's newest published version, so the tools, models or data you ship there reach existing workspaces with your
+next version, at their next cold boot or resume. Everything else in a workspace stays its own.
+
+```yaml
+# template.yaml
+immutable: [/opt/acme]        # read-only in every workspace; follows the newest version
+```
+
+```ts
+const t = await cloud.templates.get('acme-dev');
+console.log(t.open_version?.immutable);              // { paths: ['/opt/acme'], bytes: 100663296 }
+const ws = await cloud.workspaces.open({ key: 'customer-42/main', template: 'acme-dev' });
+console.log(ws.template.version, ws.immutableVersion); // created from v1; /opt/acme shows v2
+```
+
+A build without `immutable` keeps the list of the template's open version, and each new version keeps every path of
+it: add paths, never remove them. A build reports the list its version declares in `immutable_paths`.
+
 ## Agent tools
 
 `workspaceTools(workspace)` returns tools with a name, a description, a JSON Schema for the
@@ -582,6 +671,20 @@ instead of being overwritten. Each call first sends `workspace.hint()` without w
 that off, e.g. when you send the hint yourself as the model starts a tool call), except `read_file`, `list_files` and
 `search_files`: a sleeping workspace answers them from its disk without waking.
 
+**Background commands (0.13.0+).** On a processful workspace `exec` takes `background: true` for anything that runs
+longer than a few minutes (a build, a test suite, a training run, a server): it returns `{ session_id, state }` at
+once and the model keeps using the other tools. `exec_read` reads the command's state, exit code and output (the end
+of each stream, or from the `next_stdout_offset` / `next_stderr_offset` of the previous read; `wait_ms` waits for the
+exit and returns as soon as it happens), and `exec_cancel` stops it. `timeout_ms` (up to a day) sets the longest the
+command may run; the workspace stays awake while it does. A burst (`burst: 'always'`) runs in the foreground.
+
+```ts
+const tools = workspaceTools(workspace);
+const { session_id } = (await executeToolCall(tools, { name: 'exec', input: { command: 'make -j8 test', background: true, timeout_ms: 7_200_000 } })) as { session_id: string };
+// ... other tool calls ...
+const progress = await executeToolCall(tools, { name: 'exec_read', input: { session_id, wait_ms: 30_000 } });
+```
+
 For a file-first workspace (0.9.0+) the tools are `exec` and the files tools only: `exec` runs each command as an
 execution and adds `execution_id`, `state`, `tree_revision` and `changed` to its result, and the process, terminal,
 git and browser tools are not offered. `workspaceTools(ws, { mode })` builds the definitions without touching the
@@ -838,6 +941,14 @@ A read of a sleeping workspace that its disk cannot answer (409 `workspace_not_r
 `host_feature_unavailable` (search or patches are not available for the workspace, `details.feature`) is neither
 retried nor woken: run `grep` with `exec`, or read then write the file, instead.
 
+Immutable paths **(0.13.0+)**: a files write under an immutable path is 409 `conflict` with `reason` `read_only_path`
+(not retried; write elsewhere, or change the template). A build is refused with 422 `validation_failed` and `reason`
+`immutable_path_removed` when its recipe drops a path of the template's open version (`details.removed`; keep them),
+`immutable_paths_unsupported_base` when its base cannot carry immutable paths (`details.base`; build on a newer version
+of that base), or `invalid_path` (`details.field` `recipe.immutable[<i>]`). A build that fails on them has
+`failure.code` `immutable_path_missing` (`failure.details.path` is not a directory in the built filesystem) or
+`immutable_image_too_large`.
+
 ## Usage and overage
 
 `cloud.usage` reads the organization's usage (API keys see organization totals and their own project's workspaces):
@@ -941,3 +1052,44 @@ or no longer supported, it emits one warning:
 ## License
 
 Apache-2.0
+
+
+## Workspace integrations (0.12.0+)
+
+```ts
+const ws = await cloud.workspaces.open({ key: 'qm/project-42', template: 'python-node-browser',
+  labels: { scope: 'project-42', owner: 'qm' }, idlePolicy: 'never' });
+const matches = await cloud.workspaces.list({ labels: { scope: 'project-42' } });
+await ws.setLabels({ scope: 'project-42', owner: 'qm' }); // replaces all labels; {} clears
+await ws.setIdlePolicy('adaptive'); // null restores the inherited policy
+const idle = await ws.idle(); // read-only, does not wake or record activity
+await ws.keepalive(60); // seconds; never shortens an existing keepalive
+await ws.suspendWhenIdle({ afterSeconds: 2 }); // one safe server-side request; no /idle + suspend race
+```
+
+Labels are exact string pairs (at most 50, keys 1–64 and values 0–256 characters); they are metadata, not secrets.
+A failed workspace is recoverable: `await ws.wake()` and ordinary auto-waking calls restart that ID using its existing disk. They do not create a replacement workspace. A failed attempt still raises its operation error; there is no unbounded restart loop.
+After `await ws.delete({ wait: true })`, opening its key creates a **new ID**. The old ID, tokens and history remain deleted. A key stays reserved while deletion is in progress.
+
+For a background command with a pipe (no PTY):
+
+```ts
+const cell = ws.cell();
+const session = await cell.exec.start({ session_id: 'qm-worker-1', argv: ['cat'], stdin_open: true });
+let ack = await cell.exec.input(session.session_id, 'hello\n', { offset: 0 });
+ack = await cell.exec.input(session.session_id, '', { offset: ack.offset, close: true });
+```
+
+Input frames are at most 64 KiB. The acknowledged offset counts bytes accepted into the pipe, not bytes consumed by the program. A blocked writer may receive a partial acknowledgement; continue from the returned offset. Retrying the identical last frame is safe. `close` sends EOF only once the entire frame is accepted. Do not combine `stdin_open` with the existing one-shot `stdin` option. The transport writes no separate input log or payload file; program output and full-state snapshots retain their normal persistence. Full-state suspend preserves the pipe. Where a workspace does not offer it, the start is refused with 409 `conflict`, `reason` `host_feature_unavailable` and `details.feature: 'exec_stdin'`, not retryable. Running sessions count as work within the documented idle-command window; long-running services should declare keepalives or choose `never`.
+
+```ts
+import { isWorkspaceGone, ShardfluxProtocolError } from '@shardflux/sdk';
+// isWorkspaceGone(error) is true only for an explicit API workspace_deleted refusal.
+// A protocol error, a cell 404, a scoped API 404 or a network failure is never deletion evidence.
+```
+
+`ShardfluxProtocolError.source` is `api` or `cell` for SDK responses (`unknown` only for an error constructed without a source by older caller code). It remains a protocol failure even when `status === 404`. Never delete local data based on an HTTP status alone.
+
+### 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.

package/dist/account.d.ts

@@ -102,7 +102,7 @@ export interface ShardfluxAccountOptions {
     sessionToken?: string;
     /** Default https://api.shardflux.dev. */
     baseUrl?: string;
-    /** Default: the runtime's fetch, with `Connection: close` on Node 26 (see defaultFetch in http.ts). */
+    /** Default: pooled HTTP/1.1 on Node 26+, native fetch on other runtimes (see defaultFetch in http.ts). */
     fetch?: typeof fetch;
     userAgent?: string;
     /** Per-request timeout (ms), default 30 s. */

package/dist/account.js

@@ -571,7 +571,7 @@ export class ShardfluxAccount {
         const b = body;
         if (b && typeof b === 'object' && typeof b.session_token === 'string') {
             if (!isSessionToken(b.session_token))
-                throw new ShardfluxProtocolError('the API returned a session_token that is not a CLI session token (sfu_...)', 200);
+                throw new ShardfluxProtocolError('the API returned a session_token that is not a CLI session token (sfu_...)', 200, 'api');
             this.#token = b.session_token;
             const expiresAt = typeof b.session_expires_at === 'string' ? b.session_expires_at : '';
             await this.#onSessionToken?.({ token: b.session_token, expiresAt });

package/dist/cell.d.ts

@@ -22,6 +22,7 @@
  * have before sending them (NotSupportedForModeError).
  */
 import type { components, paths } from './generated/cell-api.js';
+import { ShardfluxApiError } from './errors.js';
 import type { WorkspaceMode } from './errors.js';
 import { ExecutionResult } from './executions.js';
 import type { ExecutionGetOptions, ExecutionRunOptions } from './executions.js';
@@ -31,6 +32,25 @@ import type { ToolTokenManager } from './tokens.js';
 type S = components['schemas'];
 export type ExecStartRequest = S['ExecStartRequest'];
 export type ExecSession = S['ExecSession'];
+/**
+ * Elastic memory (0.13.0): the host grew the workspace's memory before an exec started, and the exec
+ * waited for it. `outcome` delivered | partial | missed | failed; `from_mib`, `want_mib`, `got_mib` are guest memory
+ * before, aimed for and after; `deliver_ms` the time to deliver. On the session the start returned; absent when no
+ * grow ran (fixed workspaces, or already at the exec size).
+ */
+export type MemoryGrow = S['MemoryGrow'];
+/**
+ * Burst execution (0.13.0; needs an organization entitlement): the session of
+ * an exec started with `burst: 'always'` ran on a larger, short-lived burst VM on the workspace's host, and its file
+ * changes were applied back (`applied`). `host`, `vcpus`, `memory_mib`, `method`, the change counts
+ * (`written_files`, `written_dirs`, `removed`, `written_bytes`), `leftover_killed` (processes the command left behind:
+ * they do not survive a burst), `overhead_ms`, `excluded_paths`, `timings`, `replayed`; `error` when the burst failed
+ * after the start answered.
+ */
+export type BurstSummary = S['BurstSummary'];
+/** The failure recorded on a burst session (`burst.error`): code `burst_unavailable` or `burst_apply_failed`. */
+export type BurstError = S['BurstError'];
+export type ExecInputResult = S['ExecInputResult'];
 export type OutputEvent = S['OutputEvent'];
 export type PtyOpenRequest = S['PtyOpenRequest'];
 export type PtySession = S['PtySession'];
@@ -50,6 +70,8 @@ export type FilePatchResult = S['FilePatchResult'];
 /** A content SHA-256 (lowercase hex), or `absent` for a path that must not exist. */
 export type FileRevision = S['FileRevision'];
 export type WakeHintResult = S['WakeHintResult'];
+export type IdleStatus = S['IdleStatus'];
+export type KeepaliveResult = S['KeepaliveResult'];
 /** Where a running workspace's VM is: resident, frozen, hibernated or restoring. */
 export type Residency = WakeHintResult['residency'];
 /** `X-Served-From`: `disk` when a read was served from a suspended or hibernated workspace's disk. */
@@ -220,6 +242,10 @@ export interface RunResult {
     session: ExecSession;
     /** Output-stream reconnections performed (gateway restarts, network drops). */
     reconnects: number;
+    /** The memory grow the start of this exec waited for (0.13.0; elastic workspaces), null when none ran. */
+    memoryGrow: MemoryGrow | null;
+    /** The burst summary (0.13.0; `burst: 'always'`), null for an ordinary exec. */
+    burst: BurstSummary | null;
 }
 export interface RunOptions {
     sessionId?: string;
@@ -251,7 +277,24 @@ export interface RunOptions {
      * (details.reason `secret_not_available`, details.names) and nothing runs; a name also present in `env` is 422.
      */
     secretRefs?: string[];
+    /**
+     * Burst execution (0.13.0; needs the organization entitlement `policy.burst_exec`): `'always'` runs this
+     * run-to-completion command on a larger, short-lived burst VM on the workspace's
+     * host over a copy of the workspace disk, and applies its file changes back when it exits (`result.burst`).
+     * Processes it starts and tmpfs content (/tmp when tmpfs, /dev/shm) do not survive; the workspace's own processes
+     * pause meanwhile and writes to it are refused (409). Not with `stdin` (422 burst_not_supported). Refusals: 409
+     * `burst_unavailable` (details.reason not_available, layout_unsupported, host_capacity, ...), 409
+     * `burst_apply_failed` (details.applied_entries/pending_entries; retry with the same `sessionId` to finish the apply).
+     * A burst cannot be canceled: `signal` stops following it, not the command.
+     */
+    burst?: 'never' | 'always';
+    /** Burst VM vCPUs (1-32; default the host's, 8, or the plan's ceiling when lower). */
+    burstVcpus?: number;
+    /** Burst VM memory in MiB (512-65536; default the host's, 8192, or the plan's ceiling when lower). */
+    burstMemoryMib?: number;
 }
+/** 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;
 /** Parses an NDJSON byte stream into objects (tolerates CRLF and a final unterminated line). */
 export declare function ndjson<T>(body: ReadableStream<Uint8Array>): AsyncGenerator<T>;
 export declare class CellClient {
@@ -296,7 +339,19 @@ export declare class CellClient {
             follow?: boolean;
             signal?: AbortSignal;
         }) => Promise<AsyncGenerator<OutputEvent>>;
+        /** Write at the acknowledged offset (initially 0); a repeated identical last frame cannot duplicate input.
+         * At most 64 KiB per call. A partial acknowledgement requires continuing from the returned offset.
+         * Start with stdin_open: true. close sends EOF after this frame is fully accepted. */
+        input: (sessionId: string, data: string | Uint8Array, opts: {
+            offset: number;
+            close?: boolean;
+            signal?: AbortSignal;
+        }) => Promise<ExecInputResult>;
         signal: (sessionId: string, signal: Signal, onlyLeader?: boolean) => Promise<ExecSession>;
+        /**
+         * SIGTERM to the process group, SIGKILL after `graceMs` (0 to 60000; 0 or omitted is 5000). Resolves once the
+         * command has ended; the request waits for the grace.
+         */
         cancel: (sessionId: string, graceMs?: number) => Promise<ExecSession>;
         /**
          * Starts (or re-attaches to) a session and collects its output until it exits, reconnecting
@@ -442,6 +497,10 @@ export declare class CellClient {
      * workspace answers 409 `workspace_not_running` (`Workspace.hint()` then wakes it in the background).
      */
     wakeHint(signal?: AbortSignal): Promise<WakeHintResult>;
+    /** Read idle signals without recording activity or waking the workspace. */
+    idle(signal?: AbortSignal): Promise<IdleStatus>;
+    /** Declare work for seconds (1..the server maximum). Never shortens a previous keepalive. */
+    keepalive(seconds: number, signal?: AbortSignal): Promise<KeepaliveResult>;
     /**
      * One page of the workspace's changes against its template (needs the `files` tool). File-first workspaces: each
      * execution's result lists what it changed (`changed`); this route is refused (NotSupportedForModeError).