@shardflux/sdk 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,116 @@
 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.

package/README.md

@@ -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
@@ -206,6 +207,12 @@ means depends on `wait`:
 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
@@ -334,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)
@@ -569,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
@@ -603,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
@@ -859,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):
@@ -990,7 +1080,7 @@ 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. Older hosts/guests explicitly refuse this feature until upgraded (`exec_stdin` / `exec_stdin.v1`). Running sessions count as work within the documented idle-command window; long-running services should declare keepalives or choose `never`.
+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';

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,24 @@ 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'];
@@ -223,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;
@@ -254,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 {
@@ -308,6 +348,10 @@ export declare class CellClient {
             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

package/dist/cell.js

@@ -2,6 +2,9 @@ import { ExecStartError, NotSupportedForModeError, ShardfluxApiError, ShardfluxP
 import { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 import { HttpClient, defaultSleep, randomId, treeRevisionOf } from "./http.js";
 import { describeFailure, emitTo } from "./progress.js";
+/** Error codes of a burst's own failure: the burst's terminal outcome, never a dropped stream. */
+const BURST_FAILURES = new Set(['burst_unavailable', 'burst_apply_failed']);
+const TERMINAL = Symbol('shardflux.terminal');
 /** Fills a path template that must exist in cell-api.yaml. */
 export function cellPath(template, params) {
     return template.replace(/\{([a-z_]+)\}/g, (_, name) => {
@@ -19,6 +22,13 @@ export const DEFAULT_TRANSITION_TIMEOUT_MS = 120_000;
 export const CAPTURE_BARRIER = Symbol('shardflux.captureBarrier');
 /** Wakes per call at most: a workspace that keeps being suspended again surfaces the refusal. */
 const MAX_WAKES = 3;
+/** exec.cancel grace: the workspace waits 5 s without one and takes at most 60 s. */
+const DEFAULT_CANCEL_GRACE_MS = 5_000;
+const MAX_CANCEL_GRACE_MS = 60_000;
+/** The API error of a burst's recorded failure (`burst.error` of its session). Internal (the agent tools use it too). */
+export function burstFailure(e) {
+    return new ShardfluxApiError(409, { error: { code: e.code, message: e.message, request_id: '', retryable: e.retryable, ...(e.details ? { details: e.details } : {}) } }, 'cell');
+}
 const b64 = (bytes) => Buffer.from(typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : bytes).toString('base64');
 const unb64 = (s) => (s ? new Uint8Array(Buffer.from(s, 'base64')) : new Uint8Array());
 /** Parses an NDJSON byte stream into objects (tolerates CRLF and a final unterminated line). */
@@ -349,11 +359,18 @@ export class CellClient {
                 return Promise.reject(refusal);
             return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/signal', { session_id: sessionId }), { json: { signal, only_leader: onlyLeader } });
         },
+        /**
+         * 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, graceMs) => {
             const refusal = this.#noSessions('exec.cancel');
             if (refusal)
                 return Promise.reject(refusal);
-            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/cancel', { session_id: sessionId }), { json: graceMs === undefined ? {} : { grace_ms: graceMs } });
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/cancel', { session_id: sessionId }), {
+                json: graceMs === undefined ? {} : { grace_ms: graceMs },
+                timeoutMs: Math.max(this.#opts.timeoutMs, (graceMs || DEFAULT_CANCEL_GRACE_MS) + 15_000),
+            });
         },
         /**
          * Starts (or re-attaches to) a session and collects its output until it exits, reconnecting
@@ -382,21 +399,53 @@ export class CellClient {
                 req.kill_grace_ms = opts.killGraceMs;
             if (opts.secretRefs !== undefined)
                 req.secret_refs = opts.secretRefs;
-            const started = await this.exec.start(req, opts.signal);
-            if (started.state === 'failed_to_start')
-                throw new ExecStartError(started);
+            if (opts.burst !== undefined)
+                req.burst = opts.burst;
+            if (opts.burstVcpus !== undefined)
+                req.burst_vcpus = opts.burstVcpus;
+            if (opts.burstMemoryMib !== undefined)
+                req.burst_memory_mib = opts.burstMemoryMib;
+            const burst = opts.burst === 'always';
+            // One request starts the command and follows its output (0.13.0+). Each attempt's response headers are bounded
+            // like the old start request; the output stream then runs as long as the command. `initialAbort` ends that
+            // stream once it is drained.
+            const initialAbort = new AbortController();
+            const signal = opts.signal ? AbortSignal.any([opts.signal, initialAbort.signal]) : initialAbort.signal;
+            const res = await this.request('POST', this.#p('/v1/workspaces/{workspace_id}/exec'), {
+                json: req, accept: 'application/x-ndjson', timeoutMs: 0, headersTimeoutMs: this.#opts.timeoutMs, signal,
+            });
+            const streamed = res.headers.get('content-type')?.includes('application/x-ndjson') === true;
+            let started;
+            if (!streamed) {
+                // A cell without the combined start, and a start that failed, answer with the session JSON: start, then output.
+                const text = await res.text();
+                try {
+                    started = JSON.parse(text);
+                }
+                catch {
+                    throw new ShardfluxProtocolError('POST exec: response is not JSON', res.status, 'cell');
+                }
+                if (started.state === 'failed_to_start')
+                    throw started.burst?.error ? burstFailure(started.burst.error) : new ExecStartError(started);
+            }
             try {
-                return await this.#collect(sessionId, opts);
+                const r = await this.#collect(sessionId, opts, streamed ? { response: res, abort: initialAbort } : undefined);
+                // The start's session carries the grow (a combined stream carries it on its exit event); later reads may not.
+                const grow = started?.memory_grow ?? r.session.memory_grow;
+                return grow ? { ...r, memoryGrow: grow } : r;
             }
             catch (e) {
                 // Aborting the caller must stop the command too, not only our HTTP calls (MCP cancellation, timeouts):
-                // best-effort cancel (SIGTERM, SIGKILL after the grace), bounded so the abort stays prompt.
-                if (opts.signal?.aborted && opts.cancelOnAbort !== false) {
+                // best-effort cancel (SIGTERM, SIGKILL after the grace), bounded so the abort stays prompt. A burst cannot be
+                // canceled (it runs to its end or its timeout).
+                if (opts.signal?.aborted && opts.cancelOnAbort !== false && !burst) {
                     let timer;
                     const bound = new Promise((resolve) => {
                         timer = setTimeout(resolve, 5_000);
                     });
-                    await Promise.race([this.exec.cancel(sessionId, opts.killGraceMs).then(() => undefined, () => undefined), bound]);
+                    // killGraceMs goes up to 600000; a cancel takes at most 60000.
+                    const grace = opts.killGraceMs === undefined ? undefined : Math.min(opts.killGraceMs, MAX_CANCEL_GRACE_MS);
+                    await Promise.race([this.exec.cancel(sessionId, grace).then(() => undefined, () => undefined), bound]);
                     clearTimeout(timer);
                 }
                 throw e;
@@ -404,7 +453,7 @@ export class CellClient {
         },
     };
     /** exec.run's output loop: offsets, reconnects, exit. */
-    async #collect(sessionId, opts) {
+    async #collect(sessionId, opts, initial) {
         let session;
         const max = opts.maxOutputBytes ?? 1_048_576;
         const out = new ByteSink(max);
@@ -415,11 +464,15 @@ export class CellClient {
         const maxReconnects = opts.maxReconnects ?? 10;
         for (;;) {
             let exited;
-            const streamAbort = new AbortController();
+            const first = initial;
+            initial = undefined; // A dropped combined response reconnects only by GET, never re-starting the command.
+            const streamAbort = first?.abort ?? new AbortController();
             const signal = opts.signal ? AbortSignal.any([opts.signal, streamAbort.signal]) : streamAbort.signal;
             let drainTimer;
             try {
-                const events = await this.exec.output(sessionId, { stdoutOffset: so, stderrOffset: se, follow: true, signal });
+                if (first && !first.response.body)
+                    throw new ShardfluxProtocolError('exec output: empty body', first.response.status, 'cell');
+                const events = first ? ndjson(first.response.body) : await this.exec.output(sessionId, { stdoutOffset: so, stderrOffset: se, follow: true, signal });
                 for await (const ev of events) {
                     if (exited)
                         continue;
@@ -447,12 +500,15 @@ export class CellClient {
                         drainTimer = setTimeout(() => streamAbort.abort(), 250);
                     }
                     else if (ev.type === 'error' && ev.error) {
+                        // A burst's failure is its terminal outcome, not a dropped stream: never reconnect.
+                        if (BURST_FAILURES.has(ev.error.error.code))
+                            throw Object.assign(new ShardfluxApiError(409, ev.error, 'cell'), { [TERMINAL]: true });
                         throw new ShardfluxApiError(502, ev.error, 'cell');
                     }
                 }
             }
             catch (e) {
-                if (opts.signal?.aborted || this.closed)
+                if (opts.signal?.aborted || this.closed || (e instanceof ShardfluxApiError && TERMINAL in e))
                     throw e;
                 const transient = !(e instanceof ShardfluxApiError) || e.retryable;
                 if (!exited && (!transient || reconnects >= maxReconnects))
@@ -478,6 +534,9 @@ export class CellClient {
                 break;
             }
         }
+        // A burst that failed after its start answered (the session ended with burst.error).
+        if (session.burst?.error)
+            throw burstFailure(session.burst.error);
         // A start answered while the session was still starting can end without starting the command.
         if (session.state === 'failed_to_start')
             throw new ExecStartError(session);
@@ -494,6 +553,8 @@ export class CellClient {
             truncated: out.total > out.kept || err.total > err.kept,
             session,
             reconnects,
+            memoryGrow: null,
+            burst: session.burst ?? null,
         };
     }
     // ---- executions (file-first workspaces) -----------------------------

package/dist/client.d.ts

@@ -22,7 +22,7 @@ import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.j
 import { UsageApi } from './usage.js';
 import { VolumesApi } from './volumes.js';
 import type { VersionCheckOption } from './version-check.js';
-import type { FinishedOperation, InternalLifecycleOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
+import type { FinishedOperation, ForkOptions, InternalLifecycleOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 import type { ProgressListener } from './progress.js';
 import { CaptureRegistry } from './capture.js';
 import type { FeedbackReceipt, SendFeedbackParams } from './feedback.js';
@@ -34,8 +34,6 @@ export type WorkspaceLifetime = components['schemas']['WorkspaceLifetime'];
 export type DiskLayout = components['schemas']['DiskLayout'];
 /** standard, template_draft (a template's dev-mode draft) or template_test (a test instance of a draft state). */
 export type WorkspacePurpose = components['schemas']['WorkspacePurpose'];
-/** Reserved (T2): always `pinned` in T1. */
-export type UpdatePolicy = components['schemas']['UpdatePolicy'];
 /** Where the workspace's disk came from: null, a fork, or a draft state (test instances). */
 export type WorkspaceOrigin = components['schemas']['WorkspaceOrigin'];
 export type ResetWorkspaceBody = components['schemas']['ResetWorkspaceBody'];
@@ -143,10 +141,35 @@ export interface ShardfluxOptions {
      */
     versionCheck?: VersionCheckOption;
 }
+/**
+ * How a workspace holds its memory (0.13.0): `fixed` boots `memory_mib` and holds it; `elastic` makes
+ * `memory_mib` a promise: the VM holds `memory_mib_held` while idle and the host grows it when a command needs it.
+ */
+export type AllocationMode = 'fixed' | 'elastic';
+/**
+ * Memory of a workspace (0.13.0): `promised_mib` (what it may grow to), `held_mib` (the idle floor;
+ * for a fixed workspace the same as the promise) and `plugged_mib` (plugged above the held floor on the live
+ * allocation, refreshed about every 60 s; null without one). `allocation_mode` is the running VM's, else the next start's.
+ */
+export type WorkspaceMemory = WorkspaceView['memory'];
 export interface Caps {
     cpu_millis?: number;
+    /** Memory in MiB; for an elastic workspace the promise (what it may grow to). */
     memory_mib?: number;
     disk_gib?: number;
+    /**
+     * `fixed` (default) or `elastic` (0.13.0). Given caps replace the stored ones: caps without it make
+     * the workspace fixed again; omitted caps keep the stored layout. Elastic needs the organization's entitlement, else
+     * ShardfluxApiError 422 `validation_failed` reason `allocation_mode_not_available` (nothing is created or changed);
+     * a file-first workspace gets `not_supported_for_mode`. A promise that does not exceed the held floor by at least
+     * 512 MiB is fixed at the promise (the returned `caps.allocation_mode` says which). Takes effect at the next VM start.
+     */
+    allocation_mode?: AllocationMode;
+    /**
+     * Elastic only (0.13.0): the memory held while idle, in MiB (at least 512, default 1024 server side, at most
+     * `memory_mib`). Without elastic: 422 reason `requires_elastic`; above `memory_mib`: 422 `exceeds_memory_mib`.
+     */
+    memory_mib_held?: number;
 }
 export interface ForkTarget {
     key: string;
@@ -420,13 +443,14 @@ export declare class WorkspacesApi {
     /**
      * Forks into a new key. `lifetime` is the fork's own (default persistent): forking a session is how it is kept.
      * Resolves when the fork is requested (the copy's handle is returned at once); with `wait`, once the copy exists,
-     * with its handle refreshed.
+     * with its handle ready. From 0.13.0, a supporting API returns the target view and final-epoch token together.
+     * `agentLabel`/`tools` choose that token; an older API ignoring Prefer falls back to polling and refreshing.
      */
-    fork(workspaceId: string, target: ForkTarget, opts: WaitedLifecycleOptions): Promise<{
+    fork(workspaceId: string, target: ForkTarget, opts: WaitedForkOptions): Promise<{
         operation: FinishedOperation;
         workspace: Workspace;
     }>;
-    fork(workspaceId: string, target: ForkTarget, opts?: LifecycleOptions): Promise<{
+    fork(workspaceId: string, target: ForkTarget, opts?: ForkOptions): Promise<{
         operation: Operation;
         workspace: Workspace;
     }>;

package/dist/client.js

@@ -543,17 +543,45 @@ export class WorkspacesApi {
     }
     async fork(workspaceId, target, opts = {}) {
         let copy;
-        const operation = await runLifecycle(this.#ctx(), 'fork', workspaceId, async (init) => {
-            const out = await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/fork`, target, opts.idempotencyKey, init);
-            copy = this.#wrap(out.workspace);
+        let heldReady = false;
+        const requestedWait = waitOptionsOf(opts);
+        const wait = requestedWait ? { ...requestedWait } : null;
+        const timeoutMs = wait?.timeoutMs ?? 300_000;
+        const started = Date.now();
+        const operation = await runLifecycle(this.#ctx(), 'fork', workspaceId, async (init, trace) => {
+            const waitS = wait && wait.serverWait !== false ? Math.min(SERVER_WAIT_MAX_S, Math.floor(timeoutMs / 1000)) : 0;
+            const body = { ...target };
+            if (waitS >= 1 && opts.agentLabel !== undefined)
+                body.agent_label = opts.agentLabel;
+            if (waitS >= 1 && opts.tools !== undefined)
+                body.tools = [...opts.tools];
+            const res = await this.#http.jsonWithHeaders('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/fork`, {
+                ...init, json: body, idempotencyKey: opts.idempotencyKey ?? randomId('op-'),
+                ...(wait?.signal ? { signal: wait.signal } : {}),
+                ...(waitS >= 1 ? { headers: { prefer: `wait=${waitS}` }, timeoutMs: Math.max(this.#http.opts.timeoutMs, waitS * 1000 + 10_000) } : {}),
+            }, this.#auth);
+            const out = res.body;
+            if (!out?.workspace || !out.operation)
+                throw new ShardfluxProtocolError('fork: response has no workspace or operation', res.status, 'api');
+            heldReady = waitS >= 1 && res.status === 200 && /\bwait\s*=/i.test(res.headers.get('preference-applied') ?? '');
+            if (heldReady && (out.operation.state !== 'succeeded' || out.workspace.observed_state !== 'running')) {
+                throw new ShardfluxProtocolError('fork: held response is not a succeeded running target', res.status, 'api');
+            }
+            const token = heldReady ? out.tool_token ?? null : null;
+            this.#noteToken(token);
+            copy = this.#wrap(out.workspace, { agentLabel: opts.agentLabel, tools: opts.tools, token, trace });
+            if (wait && waitS >= 1)
+                wait.timeoutMs = Math.max(1, timeoutMs - (Date.now() - started));
             return out.operation;
         }, {
             ...opts,
+            ...(wait ? { wait } : {}),
             [AFTER_WAIT]: async (trace, op) => {
-                await trace.span('view', () => copy.refresh());
+                if (!heldReady)
+                    await trace.span('view', () => copy.refresh());
                 await opts[AFTER_WAIT]?.(trace, op);
             },
-        }, { settle: true });
+        }, { settle: true, requestReason: wait && wait.serverWait !== false && timeoutMs >= 1000 ? 'held' : null });
         return { operation, workspace: copy };
     }
     /** The workspace's text inputs `{NAME: value}` (0.7.0). Secret inputs are bound secrets, never listed. */