@shardflux/sdk 0.11.1 → 0.13.0

package/dist/lifecycle.js

@@ -19,15 +19,17 @@ export function waitOptionsOf(opts) {
  * the request, every observed state, and `AFTER_WAIT`; it ends with `done` either way.
  */
 export async function runLifecycle(ctx, kind, workspaceId, start, opts, capture = {}) {
-    const waitOpts = waitOptionsOf(opts);
+    // `durable` (suspend) waits for the durable copy, so it implies `wait`.
+    const waitOpts = waitOptionsOf(opts) ?? (opts.durable ? {} : null);
+    const started = Date.now();
     const trace = new Trace(kind, combineListeners(ctx.onProgress, opts.onProgress, waitOpts?.onProgress), { workspaceId });
     return traced(trace, async () => {
         // Tool-call capture writes recorded before this call land first (snapshot, fork, suspend and close include them).
         const pending = capture.settle ? ctx.captures.settle(workspaceId) : undefined;
         if (pending)
             await trace.span('capture_flush', () => pending);
-        trace.phase('request');
-        const operation = await start({ onRetry: trace.onRetry });
+        trace.phase('request', capture.requestReason ?? null);
+        const operation = await start({ onRetry: trace.onRetry }, trace);
         trace.observe(operation);
         if (!waitOpts)
             return operation;
@@ -36,6 +38,11 @@ export async function runLifecycle(ctx, kind, workspaceId, start, opts, capture
             throw new OperationFailedError(operation);
         if (operation.state !== 'succeeded')
             final = await ctx.workspaces.waitForOperation(operation.id, { ...waitOpts, [TRACE]: trace });
+        if (opts.durable) {
+            // One budget for the whole call: what the suspend itself left.
+            const timeoutMs = Math.max(1, (waitOpts.timeoutMs ?? 300_000) - (Date.now() - started));
+            final = await ctx.workspaces.waitForDurable(final, { ...waitOpts, timeoutMs, [TRACE]: trace });
+        }
         await opts[AFTER_WAIT]?.(trace, final);
         return final;
     });

package/dist/progress.d.ts

@@ -28,8 +28,10 @@ export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork
  * - `busy`: a tool call waiting out `workspace_busy` (only in `tool` events).
  * - `capture_flush` (0.7.0+): a lifecycle call waiting for tool-call capture writes recorded before it (only when some
  *   were pending).
+ * - `durable` (0.12.0+): `suspend({ durable: true })` or `waitForDurable()` waiting for the durable copy after the
+ *   operation succeeded (reason `overdue` once the result has `durability.overdue_at`).
  */
-export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy' | 'capture_flush';
+export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy' | 'capture_flush' | 'durable';
 export interface TimingPhase {
     phase: LifecyclePhase;
     /** The server's state_reason, or why the SDK entered the phase (`held`, `initial`, `expiring`, `invalidated`). */
@@ -89,11 +91,70 @@ export interface ServerTiming {
      * `runtime_changed` (the platform's VM runtime changed after the suspend). Null otherwise.
      */
     coldBootReason?: string | null;
+    /**
+     * `result.durable` (0.12.0+), suspend and fork: `true` when the capture is in durable storage, `false` while its
+     * durable copy is being written (see `durability`). `null` when the result does not say (other kinds, an older API).
+     */
+    durable?: boolean | null;
+    /** `result.suspend_path` (0.12.0+): `local_commit` when the suspend returned as soon as it was sealed on its host. */
+    suspendPath?: string | null;
+    /** `result.durability` (0.12.0+): the durable copy's state and timestamps. Null when the result has none. */
+    durability?: Durability | null;
+    /**
+     * `result.lost_suspend` (0.12.0+), resume: the workspace's latest suspend could not be kept and this resume restored the
+     * checkpoint before it (`restoredCheckpointId`, state as of `stateAsOf`). Null otherwise.
+     */
+    lostSuspend?: LostSuspend | null;
     /** `result.boot_to_ready_ms`: VM start until the guest agent answered. */
     bootToReadyMs: number | null;
     /** `result.host_timings_ms`: the host's own steps (restore: load, after_restore, ready, …). */
     hostTimingsMs: Record<string, number> | null;
 }
+/**
+ * `result.durability` of a suspend or fork (0.12.0+), camelCased. A suspend returns as soon as the workspace is sealed on
+ * its host (`pending`); `durable` follows when the copy lands in durable storage (`durableAt`). Timestamps are RFC 3339.
+ */
+export interface Durability {
+    /** `pending` (the durable copy is being written), `durable` (it committed) or `lost` (see the lifecycle reference). */
+    state: 'pending' | 'durable' | 'lost';
+    checkpointId: string | null;
+    generationId: string | null;
+    /** When the suspend (or fork) completed on its host. */
+    localCommitAt: string | null;
+    /** When the durable copy is expected by. */
+    durableBy: string | null;
+    /** When the durable copy committed (state `durable`). */
+    durableAt: string | null;
+    /** Local commit to durable commit, in milliseconds (state `durable`). */
+    localCommitToDurableMs: number | null;
+    /** Set once `durableBy` passed while the copy was still being written; it keeps going. */
+    overdueAt: string | null;
+    /** State `lost`: why (e.g. `host_lost`). */
+    reason: string | null;
+}
+/** `result.lost_suspend` of a resume (0.12.0+), camelCased. See the lifecycle reference. */
+export interface LostSuspend {
+    checkpointId: string;
+    generationId: string | null;
+    reason: string | null;
+    suspendedAt: string | null;
+    /** The earlier checkpoint this resume restored. */
+    restoredCheckpointId: string | null;
+    /** The restored state is as of this time (RFC 3339). */
+    stateAsOf: string | null;
+}
+/**
+ * The durable copy of a suspend or fork operation (0.12.0+): `result.durability` camelCased, or null when the result has
+ * none (the suspend was stored durably before it completed, or another kind).
+ */
+export declare function durabilityOf(op: Pick<Operation, 'result'>): Durability | null;
+/** A resume operation's `result.lost_suspend` camelCased (0.12.0+), or null. */
+export declare function lostSuspendOf(op: Pick<Operation, 'result'>): LostSuspend | null;
+/**
+ * Whether a suspend or fork operation's capture is in durable storage (0.12.0+): `result.durable`, else `true` for a
+ * succeeded suspend or fork whose result predates the field, else null.
+ */
+export declare function isDurable(op: Pick<Operation, 'result' | 'kind' | 'state'>): boolean | null;
 export type TimingOutcome = 'succeeded' | 'failed' | 'timed_out' | 'error';
 export interface LifecycleTiming {
     action: LifecycleAction;

package/dist/progress.js

@@ -1,3 +1,55 @@
+const DURABILITY_STATES = new Set(['pending', 'durable', 'lost']);
+/**
+ * The durable copy of a suspend or fork operation (0.12.0+): `result.durability` camelCased, or null when the result has
+ * none (the suspend was stored durably before it completed, or another kind).
+ */
+export function durabilityOf(op) {
+    const d = op.result?.durability;
+    if (typeof d !== 'object' || d === null)
+        return null;
+    const r = d;
+    if (typeof r.state !== 'string' || !DURABILITY_STATES.has(r.state))
+        return null;
+    return {
+        state: r.state,
+        checkpointId: str(r.checkpoint_id),
+        generationId: str(r.generation_id),
+        localCommitAt: str(r.local_commit_at),
+        durableBy: str(r.durable_by),
+        durableAt: str(r.durable_at),
+        localCommitToDurableMs: num(r.local_commit_to_durable_ms),
+        overdueAt: str(r.overdue_at),
+        reason: str(r.reason),
+    };
+}
+/** A resume operation's `result.lost_suspend` camelCased (0.12.0+), or null. */
+export function lostSuspendOf(op) {
+    const l = op.result?.lost_suspend;
+    if (typeof l !== 'object' || l === null)
+        return null;
+    const r = l;
+    const checkpointId = str(r.checkpoint_id);
+    if (!checkpointId)
+        return null;
+    return {
+        checkpointId,
+        generationId: str(r.generation_id),
+        reason: str(r.reason),
+        suspendedAt: str(r.suspended_at),
+        restoredCheckpointId: str(r.restored_checkpoint_id),
+        stateAsOf: str(r.state_as_of),
+    };
+}
+/**
+ * Whether a suspend or fork operation's capture is in durable storage (0.12.0+): `result.durable`, else `true` for a
+ * succeeded suspend or fork whose result predates the field, else null.
+ */
+export function isDurable(op) {
+    const v = op.result?.durable;
+    if (typeof v === 'boolean')
+        return v;
+    return op.state === 'succeeded' && (op.kind === 'suspend' || op.kind === 'fork') ? true : null;
+}
 /** Calls every listener; a listener that throws never breaks the SDK call. */
 export function emitTo(listeners, event) {
     for (const l of listeners) {
@@ -66,6 +118,10 @@ export function serverTiming(op) {
         // Unknown (null) unless the result says so: a result without the field is never read as "not restored".
         memoryRestored: typeof r.memory_restored === 'boolean' ? r.memory_restored : null,
         coldBootReason: str(r.cold_boot_reason),
+        durable: typeof r.durable === 'boolean' ? r.durable : null,
+        suspendPath: str(r.suspend_path),
+        durability: durabilityOf(op),
+        lostSuspend: lostSuspendOf(op),
         bootToReadyMs: num(r.boot_to_ready_ms),
         hostTimingsMs,
     };
@@ -76,6 +132,8 @@ function outcomeOf(err) {
         return 'failed';
     if (name === 'OperationTimeoutError')
         return 'timed_out';
+    if (name === 'DurabilityLostError')
+        return 'failed';
     return 'error';
 }
 /** Why a request failed, in one short phrase (for retry records). */
@@ -249,6 +307,9 @@ export function formatTiming(t) {
         const how = [
             s.startPath ? `start ${s.startPath}${s.warmFallback ? ` (warm fallback: ${s.warmFallback})` : ''}` : null,
             s.resumePath ? `resume from ${s.resumePath}${s.memoryRestored === false ? `: processes restarted${s.coldBootReason ? ` (${s.coldBootReason})` : ''}` : ''}` : null,
+            s.lostSuspend ? `restored ${s.lostSuspend.restoredCheckpointId ?? 'no checkpoint'} (latest suspend ${s.lostSuspend.checkpointId} ${s.lostSuspend.reason ?? 'lost'})` : null,
+            s.suspendPath === 'local_commit' ? 'sealed on host' : null,
+            s.durability?.state === 'durable' ? `durable${s.durability.localCommitToDurableMs !== null ? ` ${fmt(s.durability.localCommitToDurableMs)} later` : ''}` : s.durability ? `durable copy ${s.durability.state}` : null,
             s.bootToReadyMs !== null ? `boot to ready ${fmt(s.bootToReadyMs)}` : null,
             s.hostTimingsMs ? `host ${Object.entries(s.hostTimingsMs).map(([k, v]) => `${k} ${fmt(v)}`).join(', ')}` : null,
         ].filter(Boolean);

package/dist/templates.d.ts

@@ -176,6 +176,17 @@ export interface TemplateVersion {
         introduced_in_version: number | null;
     }>;
     storage: TemplateStorage;
+    /**
+     * Immutable paths (0.13.0): the directories this version declares read-only and the size of its image, or null when
+     * it declares none. Workspaces of the template mount these paths from the template's newest published version (the
+     * open version) and pick up a newer one when they cold-boot or resume.
+     */
+    immutable: TemplateVersionImmutable | null;
+}
+/** A version's immutable paths (0.13.0): the read-only directories (byte order) and the bytes of their image. */
+export interface TemplateVersionImmutable {
+    paths: string[];
+    bytes: number;
 }
 /** Summary of an organization template's live draft on the template view (null when none). */
 export interface TemplateDraftSummary {
@@ -207,8 +218,6 @@ export interface TemplateSummary {
     open_version: TemplateVersion | null;
     /** The live draft (organization templates in dev mode), or null. */
     draft: TemplateDraftSummary | null;
-    /** Reserved (T2): always `pinned` in T1. */
-    update_policy: 'pinned' | 'auto';
     /** Platform templates: `os` or `stack` (0.7.0); organization templates: null. */
     category: TemplateCategory | null;
 }
@@ -333,9 +342,14 @@ export interface TemplateBuild {
             archived_at: string | null;
         } | null;
     };
+    /**
+     * Why the build failed. `details` carries code-specific fields (0.13.0): `immutable_path_missing` (an immutable path is
+     * not a directory in the built filesystem) names it in `details.path`; `immutable_image_too_large` has none.
+     */
     failure: {
         code: string;
         message: string;
+        details?: Record<string, unknown>;
     } | null;
     log: {
         state: 'none' | 'available' | 'expired';
@@ -361,6 +375,12 @@ export interface TemplateBuild {
     squashed: boolean | null;
     /** Organization bytes of the produced chain (limit: the plan's template_org_bytes_max). */
     org_bytes: number | null;
+    /**
+     * The immutable paths the produced version declares (0.13.0), in byte order: the recipe's `immutable`, else the list
+     * of the template's open version (a save from a workspace: the target template's open version's, else the
+     * workspace's version's). Empty for none.
+     */
+    immutable_paths: string[];
 }
 export interface TemplateRecipe {
     /** `<template slug>@<version>`, referenced in the Dockerfile as `FROM shardflux-base`. */
@@ -386,7 +406,9 @@ export interface CreateTemplateBuildParams {
     /**
      * Recipe v1 (a Dockerfile) or recipe v2 (0.7.0; `schema: "shardflux.template-recipe.v2"`: languages, packages,
      * uploaded files, steps, auto network and settings). Recipe v2 files reference uploads
-     * (`templates.uploads.put()`); `buildFromFile()` / `buildFromRecipe()` upload local `from` paths for you.
+     * (`templates.uploads.put()`); `buildFromFile()` / `buildFromRecipe()` upload local `from` paths for you. A recipe v2
+     * may declare `immutable` (0.13.0): up to 8 directories every workspace of the template mounts read-only from its
+     * newest published version (omitted: the open version's list; a new version keeps every path of it).
      */
     recipe: TemplateRecipe | TemplateRecipeV2;
     /** Publish the produced version as soon as it is registered (default true); false leaves it for the owner/admin publish route. */

package/dist/tools.d.ts

@@ -85,6 +85,13 @@ export interface WorkspaceToolsOptions {
      * with `workspace.executions.get(id)`.
      */
     onExecution?: (executionId: string) => void;
+    /**
+     * Offer burst execution on the processful `exec` tool (0.13.0; off by default: it needs the
+     * organization's burst execution entitlement). The tool then takes `burst`
+     * (`'always'` runs the command on a larger, short-lived burst VM and applies its file changes back), `burst_vcpus`
+     * and `burst_memory_mib`, and its result adds `burst` (the summary) for a burst. The file-first `exec` is unchanged.
+     */
+    burst?: boolean;
 }
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
 export declare function workspaceTools(workspace: Workspace, opts?: WorkspaceToolsOptions): WorkspaceTool[];

package/dist/tools.js

@@ -10,8 +10,8 @@
  * application; toOpenAITools/toAnthropicTools export the definitions in those
  * providers' formats and executeToolCall dispatches a model's tool call.
  */
-import { CAPTURE_BARRIER } from "./cell.js";
-import { ExecStartError } from "./errors.js";
+import { CAPTURE_BARRIER, burstFailure } from "./cell.js";
+import { ExecStartError, ShardfluxApiError } from "./errors.js";
 import { newExecutionId } from "./executions.js";
 export class ToolArgumentError extends Error {
     tool;
@@ -98,6 +98,144 @@ function clip(text, max) {
         return { text, truncated: false };
     return { text: bytes.subarray(0, max).toString('utf8'), truncated: true };
 }
+const toolError = (e) => ({ code: e.code, message: e.message, reason: e.reason });
+/**
+ * Why a session ended without running to an exit code, as the exec tools report it: a burst's recorded failure, a
+ * command that could not start (as ExecStartError says it), or the session's own reason (e.g. lost). Null otherwise.
+ */
+function sessionError(s) {
+    if (s.burst?.error)
+        return toolError(burstFailure(s.burst.error));
+    if (s.state === 'failed_to_start')
+        return toolError(new ExecStartError(s));
+    if (s.error)
+        return { code: 'internal_error', message: `The command ended without an exit status: ${s.error}`, reason: undefined };
+    return null;
+}
+const running = (s) => s.state === 'starting' || s.state === 'running';
+/** A UTF-8 continuation byte (10xxxxxx). */
+const continuation = (b) => (b & 0xc0) === 0x80;
+/** The length of the UTF-8 sequence a lead byte starts (0 for a byte that cannot start one). */
+const sequenceLength = (b) => (b < 0x80 ? 1 : (b & 0xe0) === 0xc0 ? 2 : (b & 0xf0) === 0xe0 ? 3 : (b & 0xf8) === 0xf0 ? 4 : 0);
+/** `end`, moved back to the start of the UTF-8 sequence it would cut (unchanged when it cuts none). */
+function utf8End(bytes, end) {
+    for (let i = end - 1; i >= Math.max(0, end - 3); i--) {
+        const b = bytes[i];
+        if (continuation(b))
+            continue;
+        const n = sequenceLength(b);
+        return n > 0 && i + n > end ? i : end;
+    }
+    return end;
+}
+/**
+ * One stream of an exec_read: the bytes from `start`, kept up to the tools' limit plus one byte (which says that more
+ * follows). Chunks are byte ranges of the stream (`offset` is the stream offset of their first byte), split anywhere,
+ * also inside a character: the text is decoded once, from the bytes joined.
+ */
+class OutputWindow {
+    start;
+    #max;
+    #chunks = [];
+    #kept = 0;
+    /** How far the stream is known to reach: the session's size, or the end of a chunk seen after it. */
+    #end;
+    constructor(start, max, size) {
+        this.start = start;
+        this.#max = max;
+        this.#end = size;
+    }
+    get full() {
+        return this.#kept > this.#max;
+    }
+    push(offset, data) {
+        this.#end = Math.max(this.#end, offset + data.length);
+        const at = this.start + this.#kept;
+        if (this.full || offset > at || offset + data.length <= at)
+            return;
+        const part = data.subarray(at - offset, at - offset + this.#max + 1 - this.#kept);
+        this.#chunks.push(part);
+        this.#kept += part.length;
+    }
+    /**
+     * The text from the first character boundary at or after `start` (`offset`) to `next`: at most the limit, never a
+     * cut character (the cut moves back to its first byte, and a running command's last, incomplete character waits for
+     * the next read). `truncated`: the stream holds more than the limit past `start`.
+     */
+    result(ended) {
+        const bytes = Buffer.concat(this.#chunks);
+        let skip = 0;
+        if (this.start > 0)
+            while (skip < 3 && skip < bytes.length && continuation(bytes[skip]))
+                skip += 1;
+        const truncated = this.#end - this.start > this.#max;
+        let end = Math.min(bytes.length, this.#max);
+        if (truncated || !ended) {
+            const cut = utf8End(bytes, end);
+            // A limit too small for one character still makes progress.
+            end = cut > skip || !truncated ? Math.max(cut, skip) : Math.max(end, skip);
+        }
+        return { text: new TextDecoder().decode(bytes.subarray(skip, end)), offset: this.start + skip, next: this.start + end, truncated };
+    }
+}
+/** A failure event of an exec output stream: a burst's recorded outcome (on its session too), or a stream failure. */
+const BURST_FAILURES = new Set(['burst_unavailable', 'burst_apply_failed']);
+/**
+ * Reads the output that exists (follow=false) into the windows given, stopping once they are full. Returns the
+ * session of an `exit` event (the session ended meanwhile), else null.
+ */
+async function drainOutput(c, id, from, into, signal) {
+    const windows = [into.stdout, into.stderr].filter((w) => w !== undefined);
+    for await (const ev of await c.exec.output(id, { stdoutOffset: from.stdout, stderrOffset: from.stderr, follow: false, ...(signal ? { signal } : {}) })) {
+        if (ev.type === 'output' && ev.data !== undefined) {
+            const w = ev.stream === 'stderr' ? into.stderr : into.stdout;
+            w?.push(ev.offset ?? 0, Buffer.from(ev.data, 'base64'));
+            if (windows.every((x) => x.full))
+                return null;
+        }
+        else if (ev.type === 'exit' && ev.session) {
+            return ev.session;
+        }
+        else if (ev.type === 'error' && ev.error && !BURST_FAILURES.has(ev.error.error.code)) {
+            throw new ShardfluxApiError(502, ev.error, 'cell');
+        }
+    }
+    return null;
+}
+/**
+ * Waits up to `waitMs` for a running session to end and returns it as it is then. Follows the output from the current
+ * sizes, so only what the command writes meanwhile flows, and answers on the `exit` event; a dropped stream is
+ * followed again while time is left.
+ */
+async function waitForExit(c, s, waitMs, signal) {
+    const deadline = Date.now() + waitMs;
+    let current = s;
+    for (let attempt = 0; attempt < 5 && running(current) && Date.now() < deadline; attempt++) {
+        const timer = new AbortController();
+        const t = setTimeout(() => timer.abort(), Math.max(0, deadline - Date.now()));
+        const sig = signal ? AbortSignal.any([signal, timer.signal]) : timer.signal;
+        try {
+            for await (const ev of await c.exec.output(current.session_id, { stdoutOffset: current.stdout_size, stderrOffset: current.stderr_size, follow: true, signal: sig })) {
+                if (ev.type === 'exit')
+                    return ev.session ?? (await c.exec.get(current.session_id));
+                if (ev.type === 'error')
+                    break;
+            }
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw e;
+            // A refusal (e.g. an unknown session) is the answer; the end of the wait or a dropped stream is not.
+            if (!timer.signal.aborted && e instanceof ShardfluxApiError && !e.retryable)
+                throw e;
+        }
+        finally {
+            clearTimeout(t);
+        }
+        current = await c.exec.get(current.session_id);
+    }
+    return current;
+}
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
 export function workspaceTools(workspace, opts = {}) {
     const cell = () => workspace.cell({
@@ -117,6 +255,30 @@ export function workspaceTools(workspace, opts = {}) {
         timeout_ms: { type: 'integer', minimum: 1000, maximum: 3_600_000, description: 'Kill the command after this long (default 600000).' },
         stdin: { type: 'string', maxLength: 1_000_000, description: 'Text written to stdin.' },
     }, ['command']);
+    // The processful exec: background sessions (0.13.0; read with exec_read, stopped with exec_cancel), a timeout up to a
+    // day, and with burst execution (opt-in) its extra inputs.
+    const sessionId = { type: 'string', minLength: 1, maxLength: 64 };
+    const processfulExecParameters = obj({
+        command: execParameters.properties.command,
+        cwd: execParameters.properties.cwd,
+        timeout_ms: { type: 'integer', minimum: 1000, maximum: 86_400_000, description: 'Kill the command after this long (default 600000; with background, none unless set).' },
+        stdin: execParameters.properties.stdin,
+        background: {
+            type: 'boolean',
+            description: 'Start the command and return its session_id at once instead of waiting for it to exit (default false). Use it for anything that may run longer than a few minutes, such as a build, a test suite, a training run or a server. Keep using the other tools meanwhile, read it with exec_read and stop it with exec_cancel. Set timeout_ms to the longest it may run: the workspace stays awake until the command ends or that time passes (1 hour when unset).',
+        },
+        ...(opts.burst
+            ? {
+                burst: {
+                    type: 'string',
+                    enum: ['never', 'always'],
+                    description: 'always: run this heavy, self-terminating command (a cold build, a large test suite) on a larger, short-lived burst VM over a copy of the workspace, and apply its file changes back when it exits. Processes it starts do not survive; not with stdin. Default never.',
+                },
+                burst_vcpus: { type: 'integer', minimum: 1, maximum: 32, description: 'With burst always: the burst VM’s vCPUs (default 8, or the plan’s ceiling when lower).' },
+                burst_memory_mib: { type: 'integer', minimum: 512, maximum: 65536, description: 'With burst always: the burst VM’s memory in MiB (default 8192, or the plan’s ceiling when lower).' },
+            }
+            : {}),
+    }, ['command']);
     const defs = [
         fileFirst
             ? {
@@ -158,15 +320,42 @@ export function workspaceTools(workspace, opts = {}) {
             : {
                 name: 'exec',
                 permission: 'exec',
-                description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls.',
-                parameters: execParameters,
+                description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls. A command that may run longer than a few minutes can run in the background (background: true).',
+                parameters: processfulExecParameters,
+                // A burst fences the workspace until it applies its changes: the other tools could not run meanwhile.
+                refuse: (a) => a.background === true && opts.burst && a.burst === 'always'
+                    ? ['background cannot be combined with burst always: a burst holds the workspace until it applies its changes; run it without background']
+                    : [],
                 run: async (a, o) => {
+                    const burst = opts.burst && (a.burst === 'always' || a.burst === 'never') ? a.burst : undefined;
+                    const burstVcpus = opts.burst && typeof a.burst_vcpus === 'number' ? a.burst_vcpus : undefined;
+                    const burstMemoryMib = opts.burst && typeof a.burst_memory_mib === 'number' ? a.burst_memory_mib : undefined;
+                    const cwd = typeof a.cwd === 'string' ? a.cwd : opts.defaultCwd;
+                    if (a.background === true) {
+                        // A session of its own: the start answers at once, and exec_read / exec_cancel find it by session_id.
+                        // The command runs until it exits or its timeout_ms, if one is set. (Never a burst: refused above.)
+                        const s = await cell().exec.start({
+                            argv: ['bash', '-lc', String(a.command)],
+                            ...(cwd !== undefined ? { cwd } : {}),
+                            ...(typeof a.timeout_ms === 'number' ? { timeout_ms: a.timeout_ms } : {}),
+                            ...(typeof a.stdin === 'string' ? { stdin: Buffer.from(a.stdin, 'utf8').toString('base64') } : {}),
+                            ...(burst !== undefined ? { burst } : {}),
+                            ...(burstVcpus !== undefined ? { burst_vcpus: burstVcpus } : {}),
+                            ...(burstMemoryMib !== undefined ? { burst_memory_mib: burstMemoryMib } : {}),
+                        }, o.signal);
+                        // Nothing ran (e.g. a cwd that is not a directory): the reason, as the foreground exec gives it.
+                        const error = s.state === 'failed_to_start' ? sessionError(s) : null;
+                        return { session_id: s.session_id, state: s.state, ...(error ? { error } : {}) };
+                    }
                     let r;
                     try {
                         r = await cell().exec.run(['bash', '-lc', String(a.command)], {
-                            ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
+                            ...(cwd !== undefined ? { cwd } : {}),
                             timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
                             ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                            ...(burst !== undefined ? { burst } : {}),
+                            ...(burstVcpus !== undefined ? { burstVcpus } : {}),
+                            ...(burstMemoryMib !== undefined ? { burstMemoryMib } : {}),
                             maxOutputBytes: max,
                             ...(o.signal ? { signal: o.signal } : {}),
                         });
@@ -183,12 +372,89 @@ export function workspaceTools(workspace, opts = {}) {
                             stderr: '',
                             truncated: false,
                             session_id: e.sessionId,
-                            error: { code: e.code, message: e.message, reason: e.reason },
+                            error: toolError(e),
                         };
                     }
-                    return { exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, session_id: r.sessionId };
+                    return {
+                        exit_code: r.exitCode,
+                        term_signal: r.termSignal,
+                        timed_out: r.timedOut,
+                        stdout: r.stdout,
+                        stderr: r.stderr,
+                        truncated: r.truncated,
+                        session_id: r.sessionId,
+                        // Elastic workspaces (0.13.0): the memory grow the command waited for, when one ran.
+                        ...(r.memoryGrow ? { memory_grow: r.memoryGrow } : {}),
+                        // Burst execution (0.13.0, opt-in): what the burst VM ran and applied.
+                        ...(r.burst ? { burst: r.burst } : {}),
+                    };
                 },
             },
+        // Background sessions (0.13.0): exec_read and exec_cancel need exec sessions, which a file-first workspace has none of.
+        ...(fileFirst
+            ? []
+            : [
+                {
+                    name: 'exec_read',
+                    permission: 'exec',
+                    description: 'Read a command started with exec background: true: its state, exit code and output. Without offsets it returns the end of each stream; pass next_stdout_offset and next_stderr_offset back to read only new output. wait_ms waits up to that long for the command to exit and returns as soon as it does.',
+                    parameters: obj({ session_id: sessionId, stdout_offset: { type: 'integer', minimum: 0 }, stderr_offset: { type: 'integer', minimum: 0 }, wait_ms: { type: 'integer', minimum: 0, maximum: 60_000 } }, ['session_id']),
+                    run: async (a, o) => {
+                        const c = cell();
+                        const id = String(a.session_id);
+                        let s = await c.exec.get(id);
+                        if (typeof a.wait_ms === 'number' && a.wait_ms > 0 && running(s))
+                            s = await waitForExit(c, s, a.wait_ms, o.signal);
+                        // Each stream from the offset given, else its last `max` bytes (as they are after the wait).
+                        const out = new OutputWindow(typeof a.stdout_offset === 'number' ? a.stdout_offset : Math.max(0, s.stdout_size - max), max, s.stdout_size);
+                        const err = new OutputWindow(typeof a.stderr_offset === 'number' ? a.stderr_offset : Math.max(0, s.stderr_size - max), max, s.stderr_size);
+                        if (out.start < s.stdout_size || err.start < s.stderr_size) {
+                            // The guest sends one stream's output up to its end before the other's: when stdout holds more than
+                            // a window past its offset, stderr is read by a request of its own.
+                            const ended = err.start < s.stderr_size && s.stdout_size - out.start > max
+                                ? (await Promise.all([
+                                    drainOutput(c, id, { stdout: out.start, stderr: s.stderr_size }, { stdout: out }, o.signal),
+                                    drainOutput(c, id, { stdout: s.stdout_size, stderr: err.start }, { stderr: err }, o.signal),
+                                ])).find((x) => x !== null)
+                                : await drainOutput(c, id, { stdout: out.start, stderr: err.start }, { stdout: out, stderr: err }, o.signal);
+                            if (ended)
+                                s = ended;
+                        }
+                        const done = !running(s);
+                        const so = out.result(done);
+                        const se = err.result(done);
+                        const error = sessionError(s);
+                        return {
+                            session_id: s.session_id,
+                            state: s.state,
+                            exit_code: done ? (s.exit_code ?? null) : null,
+                            term_signal: s.term_signal ?? null,
+                            timed_out: s.timed_out ?? false,
+                            canceled: s.canceled ?? false,
+                            stdout: so.text,
+                            stderr: se.text,
+                            stdout_offset: so.offset,
+                            stderr_offset: se.offset,
+                            next_stdout_offset: so.next,
+                            next_stderr_offset: se.next,
+                            truncated: so.truncated || se.truncated,
+                            ...(error ? { error } : {}),
+                            ...(s.burst ? { burst: s.burst } : {}),
+                        };
+                    },
+                },
+                {
+                    name: 'exec_cancel',
+                    permission: 'exec',
+                    description: 'Stop a command started with exec background: true: SIGTERM, then SIGKILL after grace_ms (default 5000).',
+                    // The workspace waits 5 s without a grace and at most 60 s.
+                    parameters: obj({ session_id: sessionId, grace_ms: { type: 'integer', minimum: 1, maximum: 60_000 } }, ['session_id']),
+                    run: async (a) => {
+                        const s = await cell().exec.cancel(String(a.session_id), typeof a.grace_ms === 'number' ? a.grace_ms : undefined);
+                        return { session_id: s.session_id, state: s.state, exit_code: running(s) ? null : (s.exit_code ?? null), canceled: s.canceled ?? false };
+                    },
+                },
+            ]),
         {
             name: 'read_file',
             permission: 'files',
@@ -434,6 +700,8 @@ export function workspaceTools(workspace, opts = {}) {
         permission: d.permission,
         execute: async (args, options = {}) => {
             const issues = validateArgs(d.parameters, args);
+            if (issues.length === 0 && d.refuse)
+                issues.push(...d.refuse(args));
             if (issues.length > 0)
                 throw new ToolArgumentError(`${prefix}${d.name}`, issues);
             // Fire and forget: a parked workspace starts restoring while this call is prepared. Not for