@shardflux/sdk 0.12.0 → 0.13.1

package/dist/progress.d.ts

@@ -74,9 +74,10 @@ export interface ServerTiming {
     warmFallback: string | null;
     /**
      * `result.resume_path`: `local_cache`, `prestaged` (copied to this host ahead of the resume),
-     * `download` (the checkpoint had to be fetched first), `cold_boot` (0.11.0+: the saved disk was booted after a
-     * platform runtime change; processes restarted; see `memoryRestored`) or `reset_blank_layer` (the first start after a
-     * reset).
+     * `download` (the checkpoint had to be fetched first), `cold_boot` (0.11.0+: the saved disk was booted instead of
+     * restoring memory, see `coldBootReason`; processes restarted; see `memoryRestored`), `reset_blank_layer` (the first
+     * start after a reset) or `thaw` (0.13.1+: resumed while its suspend was still being written; the same VM continued
+     * in place).
      */
     resumePath: string | null;
     /**
@@ -87,10 +88,11 @@ export interface ServerTiming {
      */
     memoryRestored?: boolean | null;
     /**
-     * `result.cold_boot_reason` (0.11.0+), with `resumePath` `cold_boot`: why the memory could not be restored, e.g.
-     * `runtime_changed` (the platform's VM runtime changed after the suspend). Null otherwise.
+     * `result.cold_boot_reason` (0.11.0+), with `resumePath` `cold_boot`: why the memory could not be restored:
+     * `runtime_changed` (the platform's VM runtime changed after the suspend) or `host_lost` (0.13.1+: the machine the
+     * workspace ran on failed; it booted from its disk, files kept, see `hostLost`). Null otherwise.
      */
-    coldBootReason?: string | null;
+    coldBootReason?: ColdBootReason | 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).
@@ -105,6 +107,12 @@ export interface ServerTiming {
      * checkpoint before it (`restoredCheckpointId`, state as of `stateAsOf`). Null otherwise.
      */
     lostSuspend?: LostSuspend | null;
+    /**
+     * `result.host_lost` (0.13.1+): the machine the workspace ran on failed. A resume (or open) that restored the
+     * workspace says from what (`restoredFrom` `disk`, or `checkpoint` with `stateAsOf`); a suspend that found it so
+     * succeeds with only `detectedAt`. Null otherwise.
+     */
+    hostLost?: HostLost | 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, …). */
@@ -143,6 +151,30 @@ export interface LostSuspend {
     /** The restored state is as of this time (RFC 3339). */
     stateAsOf: string | null;
 }
+/**
+ * `result.cold_boot_reason` (0.11.0+): `runtime_changed` (the platform's VM runtime changed after the suspend) or
+ * `host_lost` (0.13.1+: the machine the workspace ran on failed). Any other string is a reason this version does not
+ * know.
+ */
+export type ColdBootReason = 'runtime_changed' | 'host_lost' | (string & {});
+/**
+ * `result.host_lost` (0.13.1+), camelCased: the machine the workspace ran on failed. The workspace was moved to
+ * `suspended` at that moment, and its next use (a resume, a tool call's wake, an open) restored it. See the lifecycle
+ * reference.
+ */
+export interface HostLost {
+    /** When the failure was detected (RFC 3339). */
+    detectedAt: string | null;
+    /**
+     * What the resume restored: `disk` (the workspace's own disk, files kept; `coldBootReason` `host_lost`, processes
+     * restarted) or `checkpoint` (its newest checkpoint, see `stateAsOf`). Null on a suspend's result.
+     */
+    restoredFrom: 'disk' | 'checkpoint' | null;
+    /** `checkpoint`: the checkpoint the resume restored. */
+    restoredCheckpointId: string | null;
+    /** `checkpoint`: the restored state is as of this time (RFC 3339); changes after it are not in the workspace. */
+    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).
@@ -150,6 +182,11 @@ export interface LostSuspend {
 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;
+/**
+ * An operation's `result.host_lost` camelCased (0.13.1+), or null: on a resume or open that restored a workspace whose
+ * machine failed, and on a suspend that found it so (`detectedAt` only).
+ */
+export declare function hostLostOf(op: Pick<Operation, 'result'>): HostLost | 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.
@@ -255,7 +292,10 @@ export declare function traced<T>(trace: Trace, fn: () => Promise<T>): Promise<T
  *
  * A call that retried a request adds `retries: <n> (<request>, <cause>, after <delay>)`.
  * A resume that booted the workspace instead of restoring its memory (0.11.0+) says so in the server line:
- * `resume from cold_boot: processes restarted (runtime_changed)`.
+ * `resume from cold_boot: processes restarted (runtime_changed)`, or `(host_lost)` (0.13.1+) when the machine the
+ * workspace ran on failed and it booted from its disk. A resume that restored the newest checkpoint after such a
+ * failure adds `restored checkpoint <id> (host_lost; state as of <time>)`; a suspend that found the machine failed
+ * adds `host_lost (detected <time>)`.
  */
 export declare function formatTiming(t: LifecycleTiming): string;
 export {};

package/dist/progress.js

@@ -40,6 +40,22 @@ export function lostSuspendOf(op) {
         stateAsOf: str(r.state_as_of),
     };
 }
+/**
+ * An operation's `result.host_lost` camelCased (0.13.1+), or null: on a resume or open that restored a workspace whose
+ * machine failed, and on a suspend that found it so (`detectedAt` only).
+ */
+export function hostLostOf(op) {
+    const h = op.result?.host_lost;
+    if (typeof h !== 'object' || h === null || Array.isArray(h))
+        return null;
+    const r = h;
+    return {
+        detectedAt: str(r.detected_at),
+        restoredFrom: r.restored_from === 'disk' || r.restored_from === 'checkpoint' ? r.restored_from : null,
+        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.
@@ -122,6 +138,7 @@ export function serverTiming(op) {
         suspendPath: str(r.suspend_path),
         durability: durabilityOf(op),
         lostSuspend: lostSuspendOf(op),
+        hostLost: hostLostOf(op),
         bootToReadyMs: num(r.boot_to_ready_ms),
         hostTimingsMs,
     };
@@ -275,6 +292,19 @@ export async function traced(trace, fn) {
     }
 }
 const fmt = (ms) => (ms === null ? '?' : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`);
+/**
+ * The server-line part of `result.host_lost` (0.13.1+): the checkpoint a resume restored, or a suspend's detection time.
+ * A resume from the disk says nothing more here: its cold boot reads `processes restarted (host_lost)`.
+ */
+function hostLostText(h) {
+    if (!h)
+        return null;
+    if (h.restoredFrom === 'checkpoint')
+        return `restored checkpoint ${h.restoredCheckpointId ?? '?'} (host_lost; state as of ${h.stateAsOf ?? '?'})`;
+    if (h.restoredFrom === null)
+        return `host_lost${h.detectedAt ? ` (detected ${h.detectedAt})` : ''}`;
+    return null;
+}
 /**
  * A human-readable account of a timing, for logs and bug reports. A resume in production:
  *
@@ -285,7 +315,10 @@ const fmt = (ms) => (ms === null ? '?' : ms < 1000 ? `${Math.round(ms)} ms` : `$
  *
  * A call that retried a request adds `retries: <n> (<request>, <cause>, after <delay>)`.
  * A resume that booted the workspace instead of restoring its memory (0.11.0+) says so in the server line:
- * `resume from cold_boot: processes restarted (runtime_changed)`.
+ * `resume from cold_boot: processes restarted (runtime_changed)`, or `(host_lost)` (0.13.1+) when the machine the
+ * workspace ran on failed and it booted from its disk. A resume that restored the newest checkpoint after such a
+ * failure adds `restored checkpoint <id> (host_lost; state as of <time>)`; a suspend that found the machine failed
+ * adds `host_lost (detected <time>)`.
  */
 export function formatTiming(t) {
     const ids = [t.workspaceId ? `workspace ${t.workspaceId}` : null, t.operationId ? `operation ${t.operationId}` : null].filter(Boolean).join(', ');
@@ -308,6 +341,7 @@ export function formatTiming(t) {
             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,
+            hostLostText(s.hostLost),
             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,

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

package/dist/usage.d.ts

@@ -56,7 +56,9 @@ export declare class UsageApi {
     constructor(ctx: () => ClientContext);
     /**
      * Current-period usage per meter, allowances with enforcement and cap state (`overage` while opt-in overage covers
-     * usage past a CPU-hours or RAM GiB-hours allowance), measurement freshness, `exhausted_reason` (the 402
+     * usage past a CPU-hours or RAM GiB-hours allowance; `storage_blocked` (0.14.0+, enforcement `storage_block`) while
+     * the Retained state allowance is used up: opening a new key and forking are refused with 403 `quota_exceeded`,
+     * details.limit `retained_state`), measurement freshness, `exhausted_reason` (the 402
      * allowance_exhausted reason while starts are refused: `allowance_used`, `overage_paused`, `spend_cap_reached`) and
      * `spend_cap` (0.10.0).
      */

package/dist/usage.js

@@ -9,7 +9,9 @@ export class UsageApi {
     }
     /**
      * Current-period usage per meter, allowances with enforcement and cap state (`overage` while opt-in overage covers
-     * usage past a CPU-hours or RAM GiB-hours allowance), measurement freshness, `exhausted_reason` (the 402
+     * usage past a CPU-hours or RAM GiB-hours allowance; `storage_blocked` (0.14.0+, enforcement `storage_block`) while
+     * the Retained state allowance is used up: opening a new key and forking are refused with 403 `quota_exceeded`,
+     * details.limit `retained_state`), measurement freshness, `exhausted_reason` (the 402
      * allowance_exhausted reason while starts are refused: `allowance_used`, `overage_paused`, `spend_cap_reached`) and
      * `spend_cap` (0.10.0).
      */