@shardflux/sdk 0.10.2 → 0.11.1

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.10.2";
+export declare const SDK_VERSION = "0.11.1";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -29,17 +29,13 @@ export interface HttpOptions {
 }
 export declare const defaultSleep: (ms: number) => Promise<void>;
 /**
- * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends
- * `Connection: close`: undici 8.9 intermittently stalls a request on a reused keep-alive connection after the
- * connection sat idle for a few seconds (measured against the staging API: 20.9 s and 26.3 s stalls in 50 requests
- * with 0.2-12 s gaps; Node 22 / undici 6.28 max 351 ms; Node 26 with `Connection: close` max 435 ms; node:http2 on the
- * same load balancer and gaps max 193 ms, and the load balancer's idle timeout is 3600 s, so it is not an idle-timeout
- * interaction). The CLI and MCP server do the same. Other runtimes keep the runtime's keep-alive pooling.
- * `SHARDFLUX_HTTP_KEEPALIVE=1` disables the workaround.
+ * The fetch the SDK uses when none is given. On Node 26 every request uses a fresh connection (`Connection: close`),
+ * as in the CLI and the MCP server; other runtimes reuse connections. `SHARDFLUX_HTTP_KEEPALIVE=1` reuses connections
+ * on Node 26 too.
  */
 export declare function defaultFetch(env?: Record<string, string | undefined> | undefined, undiciVersion?: string | undefined): typeof fetch;
 export declare function buildUrl(base: string, path: string, query?: RequestOptions['query']): string;
-/** `X-Tree-Revision` (file-first workspaces, contracts §29.8): a non-negative integer, else null. */
+/** `X-Tree-Revision` (file-first workspaces): a non-negative integer, else null. */
 export declare function treeRevisionOf(headers: Headers): number | null;
 /** Turns a non-2xx response into a ShardfluxApiError (or a protocol error for undocumented bodies). */
 export declare function errorFrom(res: Response, source: 'api' | 'cell'): Promise<Error>;
@@ -61,10 +57,10 @@ export declare class HttpClient {
         body: T;
     }>;
 }
-/** Longest server-side wait the SDK asks for (contracts §3: servers cap `Prefer: wait` at 20 s). */
+/** Longest server-side wait the SDK asks for (servers cap `Prefer: wait` at 20 s). */
 export declare const SERVER_WAIT_MAX_S = 20;
 /**
- * One bounded-wait poll (contracts §3): GET `path` with `Prefer: wait=<s>` when `waitS` >= 1. `applied` is true only
+ * One bounded-wait poll: GET `path` with `Prefer: wait=<s>` when `waitS` >= 1. `applied` is true only
  * when the server says it waited (Preference-Applied); otherwise the caller keeps its own backoff.
  */
 export declare function pollWithWait<T>(http: HttpClient, path: string, authorization: string, waitS: number, signal?: AbortSignal, onRetry?: RequestOptions['onRetry']): Promise<{

package/dist/http.js

@@ -8,18 +8,15 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.10.2';
+export const SDK_VERSION = '0.11.1';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
- * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends
- * `Connection: close`: undici 8.9 intermittently stalls a request on a reused keep-alive connection after the
- * connection sat idle for a few seconds (measured against the staging API: 20.9 s and 26.3 s stalls in 50 requests
- * with 0.2-12 s gaps; Node 22 / undici 6.28 max 351 ms; Node 26 with `Connection: close` max 435 ms; node:http2 on the
- * same load balancer and gaps max 193 ms, and the load balancer's idle timeout is 3600 s, so it is not an idle-timeout
- * interaction). The CLI and MCP server do the same. Other runtimes keep the runtime's keep-alive pooling.
- * `SHARDFLUX_HTTP_KEEPALIVE=1` disables the workaround.
+ * The fetch the SDK uses when none is given. On Node 26 every request uses a fresh connection (`Connection: close`),
+ * as in the CLI and the MCP server; other runtimes reuse connections. `SHARDFLUX_HTTP_KEEPALIVE=1` reuses connections
+ * on Node 26 too.
  */
 export function defaultFetch(env = globalThis.process?.env, undiciVersion = globalThis.process?.versions?.undici) {
+    // Why a fresh connection on Node 26 (its bundled HTTP client, measured): docs/progress/startup-latency.md.
     const base = (input, init) => fetch(input, init);
     const major = Number((undiciVersion ?? '').split('.')[0]);
     if (!(major >= 8) || env?.SHARDFLUX_HTTP_KEEPALIVE === '1')
@@ -45,7 +42,7 @@ function retryAfterSeconds(res) {
     const n = Number(v);
     return Number.isFinite(n) && n >= 0 ? n : undefined;
 }
-/** `X-Tree-Revision` (file-first workspaces, contracts §29.8): a non-negative integer, else null. */
+/** `X-Tree-Revision` (file-first workspaces): a non-negative integer, else null. */
 export function treeRevisionOf(headers) {
     const v = headers.get('x-tree-revision');
     if (v === null || !/^\d{1,19}$/.test(v))
@@ -171,10 +168,10 @@ export class HttpClient {
         }
     }
 }
-/** Longest server-side wait the SDK asks for (contracts §3: servers cap `Prefer: wait` at 20 s). */
+/** Longest server-side wait the SDK asks for (servers cap `Prefer: wait` at 20 s). */
 export const SERVER_WAIT_MAX_S = 20;
 /**
- * One bounded-wait poll (contracts §3): GET `path` with `Prefer: wait=<s>` when `waitS` >= 1. `applied` is true only
+ * One bounded-wait poll: GET `path` with `Prefer: wait=<s>` when `waitS` >= 1. `applied` is true only
  * when the server says it waited (Preference-Applied); otherwise the caller keeps its own backoff.
  */
 export async function pollWithWait(http, path, authorization, waitS, signal, onRetry) {

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  *   const workspace = await cloud.workspaces.open({ key: `${customerId}/${projectId}`, template: 'python-node-browser' });
  *   await agent.run({ input: userMessage, tools: workspaceTools(workspace) });
  *
- * File-first workspaces (`mode: 'file_first'`, contracts §29) keep a versioned file tree and run each command as an
+ * File-first workspaces (`mode: 'file_first'`) keep a versioned file tree and run each command as an
  * execution: `await workspace.executions.run(['bash', '-lc', 'pytest -q'])`.
  *
  * Types come from the committed OpenAPI documents: application API

package/dist/lifecycle.d.ts

@@ -34,7 +34,7 @@ export type WaitedLifecycleOptions = LifecycleOptions & {
 };
 /**
  * `resume()` options (0.9.0). With `wait`, the server holds the resume until the workspace runs and returns a tool token
- * with it (contracts §22.6): `agentLabel` and `tools` choose that token (defaults: a workspace handle's own, those given
+ * with it: `agentLabel` and `tools` choose that token (defaults: a workspace handle's own, those given
  * to open(); `workspaces.resume(id)` otherwise the key's tools and label `default`). A handle keeps it for its `cell()`
  * clients of the same label and tools; `workspaces.resume(id)` only attributes it.
  */
@@ -50,7 +50,7 @@ export declare const TRACE: unique symbol;
 /** Internal: work a workspace handle does after the operation finished, inside the same trace (refreshing its view). */
 export declare const AFTER_WAIT: unique symbol;
 /**
- * Internal: a workspace handle's part in a held resume (contracts §22.6): the tool token to ask for, and how it takes the
+ * Internal: a workspace handle's part in a held resume: the tool token to ask for, and how it takes the
  * running workspace and that token from a 200 (instead of reading the view and fetching a token afterwards).
  */
 export declare const HELD_RESUME: unique symbol;

package/dist/lifecycle.js

@@ -5,7 +5,7 @@ export const TRACE = Symbol('shardflux.trace');
 /** Internal: work a workspace handle does after the operation finished, inside the same trace (refreshing its view). */
 export const AFTER_WAIT = Symbol('shardflux.afterWait');
 /**
- * Internal: a workspace handle's part in a held resume (contracts §22.6): the tool token to ask for, and how it takes the
+ * Internal: a workspace handle's part in a held resume: the tool token to ask for, and how it takes the
  * running workspace and that token from a 200 (instead of reading the view and fetching a token afterwards).
  */
 export const HELD_RESUME = Symbol('shardflux.heldResume');

package/dist/progress.d.ts

@@ -1,7 +1,7 @@
 /**
- * Lifecycle timing and progress. A slow open (0.8 s one day, 34 s the next) should say where the time went without a
- * packet capture: waiting for a host, the cell booting or restoring the VM, the network between the caller and the API,
- * the first tool token, or retries.
+ * Lifecycle timing and progress. Every open, resume and wake says where its time went, without a packet capture: the
+ * queue, the cell booting or restoring the VM, the network between the caller and the API, the first tool token, or
+ * retries.
  *
  * A Trace follows one SDK call (open, a lifecycle call with `wait`, a wake, a token fetch). It records two clocks and
  * never mixes them:
@@ -56,8 +56,8 @@ export interface ServerTiming {
     kind: Operation['kind'];
     state: Operation['state'];
     /**
-     * created_at → started_at: waiting until the cell began running the operation, including any wait for a host with
-     * capacity (started_at is set when the operation first enters `running`). Null when the API does not report
+     * created_at → started_at: waiting until the cell began running the operation, including any time in
+     * `capacity_pending` (started_at is set when the operation first enters `running`). Null when the API does not report
      * started_at or the operation has not run yet. An operation that finished without running (e.g. a failed dependency)
      * has started_at = completed_at, so all of its time shows here.
      */
@@ -70,8 +70,25 @@ export interface ServerTiming {
     startPath: string | null;
     /** `result.warm_fallback`: why a start that could be warm booted instead. */
     warmFallback: string | null;
-    /** `result.resume_path`: `local_cache`, `prestaged` (copied to this host ahead of the resume, contracts §23) or `download` (the checkpoint had to be fetched first). */
+    /**
+     * `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).
+     */
     resumePath: string | null;
+    /**
+     * `result.memory_restored` (0.11.0+): `true` when memory and running processes came back from the checkpoint;
+     * `false` when the workspace booted instead (`cold_boot`, `reset_blank_layer`): its files are as of the suspend, but
+     * every process was restarted, as after a reboot. `null` when the result does not say (an older API, or not a
+     * resume). Always set by `serverTiming()`; optional only so timings built by hand still type-check.
+     */
+    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.
+     */
+    coldBootReason?: string | 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, …). */
@@ -106,8 +123,8 @@ interface EventBase {
 }
 /**
  * - `phase`: a phase began (live progress: "capacity_pending: no_ready_host"). `tool` phases come from tool calls.
- *   A `capacity_pending` phase carries `deadlineAt` (0.6.2+, when the API reports it): when the start gives up waiting
- *   for a host and fails with `capacity_unavailable` (retryable; nothing was started).
+ *   A `capacity_pending` phase carries `deadlineAt` (0.6.2+, when the API reports it): the start's deadline, past which
+ *   it fails with `capacity_unavailable` (retryable; nothing was started).
  * - `retry`: a request is retried after a transient failure (also emitted for tool calls, action `tool`).
  * - `done`: the call ended, successfully or not, with its full timing.
  */
@@ -129,9 +146,9 @@ export declare function emitTo(listeners: ReadonlyArray<ProgressListener | undef
 /** Combines listeners (client-level and per call) into one; undefined when there are none. */
 export declare function combineListeners(...listeners: Array<ProgressListener | undefined>): ProgressListener | undefined;
 /**
- * When a start waiting in `capacity_pending` gives up: the operation's `error.details.deadline_at` (RFC 3339). A start no
- * host admits by then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or
- * from an API that does not report it.
+ * The deadline of a start in `capacity_pending`: the operation's `error.details.deadline_at` (RFC 3339). A start still
+ * queued then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or from an
+ * API that does not report it.
  */
 export declare function capacityDeadlineOf(op: Operation): string | null;
 /** Server timing from an operation as GET /v1/operations/{id} returns it. */
@@ -152,7 +169,7 @@ export declare class Trace {
     get finished(): LifecycleTiming | null;
     /**
      * Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase.
-     * `deadlineAt`: when a `capacity_pending` start gives up (added to the event only).
+     * `deadlineAt`: the deadline of a `capacity_pending` start (added to the event only).
      */
     phase(phase: LifecyclePhase, reason?: string | null, deadlineAt?: string | null): void;
     /** Runs `fn` as a phase that may overlap others (open() reads the view and issues the token together). */
@@ -168,13 +185,16 @@ export declare class Trace {
 /** Runs `fn` under `trace` and ends the trace either way (the error keeps its timing). */
 export declare function traced<T>(trace: Trace, fn: () => Promise<T>): Promise<T>;
 /**
- * A human-readable account of a timing, for logs and bug reports:
+ * A human-readable account of a timing, for logs and bug reports. A resume in production:
+ *
+ *   resume 413 ms, succeeded (workspace <id>, operation <id>)
+ *     client: request 218 ms → queued 195 ms
+ *     server: queued 51 ms, ran 290 ms, total 341 ms; resume from local_cache, boot to ready 211 ms, host disk 0 ms, load 6 ms, ready 62 ms, total 211 ms, after_restore 36 ms
+ *     outside the server: 72 ms
  *
- *   open 34.18 s, succeeded (workspace <id>, operation <id>)
- *     client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 590 ms → view 42 ms ∥ token 61 ms
- *     server: queued 33.40 s, ran 620 ms, total 34.02 s; start warm, boot to ready 79 ms
- *     outside the server: 161 ms
- *     retries: 1 (POST /v1/workspaces/open, HTTP 503 unavailable, after 200 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)`.
  */
 export declare function formatTiming(t: LifecycleTiming): string;
 export {};

package/dist/progress.js

@@ -31,9 +31,9 @@ function diffMs(from, to) {
 const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
 /**
- * When a start waiting in `capacity_pending` gives up: the operation's `error.details.deadline_at` (RFC 3339). A start no
- * host admits by then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or
- * from an API that does not report it.
+ * The deadline of a start in `capacity_pending`: the operation's `error.details.deadline_at` (RFC 3339). A start still
+ * queued then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or from an
+ * API that does not report it.
  */
 export function capacityDeadlineOf(op) {
     if (op.state !== 'capacity_pending')
@@ -63,6 +63,9 @@ export function serverTiming(op) {
         startPath: str(r.start_path),
         warmFallback: str(r.warm_fallback),
         resumePath: str(r.resume_path),
+        // 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),
         bootToReadyMs: num(r.boot_to_ready_ms),
         hostTimingsMs,
     };
@@ -128,7 +131,7 @@ export class Trace {
     }
     /**
      * Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase.
-     * `deadlineAt`: when a `capacity_pending` start gives up (added to the event only).
+     * `deadlineAt`: the deadline of a `capacity_pending` start (added to the event only).
      */
     phase(phase, reason = null, deadlineAt = null) {
         if (this.#timing)
@@ -215,13 +218,16 @@ export async function traced(trace, fn) {
 }
 const fmt = (ms) => (ms === null ? '?' : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`);
 /**
- * A human-readable account of a timing, for logs and bug reports:
+ * A human-readable account of a timing, for logs and bug reports. A resume in production:
  *
- *   open 34.18 s, succeeded (workspace <id>, operation <id>)
- *     client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 590 ms → view 42 ms ∥ token 61 ms
- *     server: queued 33.40 s, ran 620 ms, total 34.02 s; start warm, boot to ready 79 ms
- *     outside the server: 161 ms
- *     retries: 1 (POST /v1/workspaces/open, HTTP 503 unavailable, after 200 ms)
+ *   resume 413 ms, succeeded (workspace <id>, operation <id>)
+ *     client: request 218 ms → queued 195 ms
+ *     server: queued 51 ms, ran 290 ms, total 341 ms; resume from local_cache, boot to ready 211 ms, host disk 0 ms, load 6 ms, ready 62 ms, total 211 ms, after_restore 36 ms
+ *     outside the server: 72 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)`.
  */
 export function formatTiming(t) {
     const ids = [t.workspaceId ? `workspace ${t.workspaceId}` : null, t.operationId ? `operation ${t.operationId}` : null].filter(Boolean).join(', ');
@@ -242,7 +248,7 @@ export function formatTiming(t) {
         const parts = [s.queuedMs !== null ? `queued ${fmt(s.queuedMs)}` : null, s.runMs !== null ? `ran ${fmt(s.runMs)}` : null, s.totalMs !== null ? `total ${fmt(s.totalMs)}` : `still ${s.state}`];
         const how = [
             s.startPath ? `start ${s.startPath}${s.warmFallback ? ` (warm fallback: ${s.warmFallback})` : ''}` : null,
-            s.resumePath ? `resume from ${s.resumePath}` : null,
+            s.resumePath ? `resume from ${s.resumePath}${s.memoryRestored === false ? `: processes restarted${s.coldBootReason ? ` (${s.coldBootReason})` : ''}` : ''}` : 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/tar.d.ts

@@ -1,5 +1,5 @@
 /**
- * A small tar writer for build uploads of folders (contracts §24.2: uncompressed ustar/pax, extracted by the host's
+ * A small tar writer for build uploads of folders (uncompressed ustar/pax, extracted by the host's
  * static tool). Pure: no Node imports, so the browser bundle can carry it.
  *
  * The bytes equal CPython's `tarfile.open(mode="w", format=tarfile.PAX_FORMAT)` with every member added by hand (the

package/dist/tar.js

@@ -1,5 +1,5 @@
 /**
- * A small tar writer for build uploads of folders (contracts §24.2: uncompressed ustar/pax, extracted by the host's
+ * A small tar writer for build uploads of folders (uncompressed ustar/pax, extracted by the host's
  * static tool). Pure: no Node imports, so the browser bundle can carry it.
  *
  * The bytes equal CPython's `tarfile.open(mode="w", format=tarfile.PAX_FORMAT)` with every member added by hand (the

package/dist/template-file.d.ts

@@ -22,7 +22,7 @@ export declare class TemplateFileError extends Error {
     readonly path: string | undefined;
     constructor(message: string, path?: string);
 }
-/** Largest single upload (contracts §24.2: 5 GiB, one presigned PUT). */
+/** Largest single upload (5 GiB, one presigned PUT). */
 export declare const UPLOAD_BYTES_MAX = 5368709120;
 /** Most entries a folder tar may have (the host's extraction limit, §24.2). */
 export declare const TAR_ENTRIES_MAX = 200000;

package/dist/template-file.js

@@ -33,7 +33,7 @@ export class TemplateFileError extends Error {
         this.path = path;
     }
 }
-/** Largest single upload (contracts §24.2: 5 GiB, one presigned PUT). */
+/** Largest single upload (5 GiB, one presigned PUT). */
 export const UPLOAD_BYTES_MAX = 5_368_709_120;
 /** Most entries a folder tar may have (the host's extraction limit, §24.2). */
 export const TAR_ENTRIES_MAX = 200_000;

package/dist/templates.d.ts

@@ -1,5 +1,5 @@
 /**
- * Template registry, custom template builds (recipe v1 Dockerfiles and recipe v2, contracts §24.1), build uploads
+ * Template registry, custom template builds (recipe v1 Dockerfiles and recipe v2), build uploads
  * (§24.2), recipe export, version test instances, package search, the version file tree and diff, and template dev
  * mode (drafts and test instances) over the application API (/v1). Registry and build types are written by hand and
  * checked against the generated contract in type-checks.ts; the Templates v2 and template editor types alias the
@@ -15,7 +15,7 @@ import type { YamlParser } from './template-file.js';
 import type { ToolName } from './tokens.js';
 import { Workspace } from './workspace.js';
 type S = components['schemas'];
-/** Recipe v2 (contracts §24.1): the `recipe` of a build, the export's `recipe` and the document of template.yaml. */
+/** Recipe v2: the `recipe` of a build, the export's `recipe` and the document of template.yaml. */
 export type TemplateRecipeV2 = S['TemplateRecipeV2'];
 /** One `build.files[]` entry: an upload (`upload: "sha256:<hex>"`), or in template.yaml a local path (`from`). */
 export type TemplateRecipeV2File = NonNullable<TemplateRecipeV2['build']['files']>[number];
@@ -40,7 +40,7 @@ export type TemplateVersionRecipe = S['TemplateVersionRecipe'];
 export type TemplatePackage = S['TemplatePackage'];
 export type TemplatePackagePage = S['TemplatePackagePage'];
 export type TemplatePackageEcosystem = 'apt' | 'pip' | 'npm';
-/** The languages a base offers a recipe v2 (contracts §24.6 `GET …/template-languages`): the language table for its platform base. */
+/** The languages a base offers a recipe v2 (`GET …/template-languages`): the language table for its platform base. */
 export type TemplateLanguages = S['TemplateLanguages'];
 export type TemplateLanguage = TemplateLanguages['data'][number];
 export type CreateVersionTestInstanceBody = S['CreateVersionTestInstanceBody'];
@@ -52,18 +52,18 @@ export type TemplateBuildRecipeV2 = Extract<NonNullable<S['TemplateBuild']['reci
 }>;
 /** Start commands and services of a workspace's version (§24.4); null when it has none. */
 export type WorkspaceStartup = S['WorkspaceStartup'];
-/** Manifest v2 `defaults` of a version (contracts §19.7). */
+/** Manifest v2 `defaults` of a version. */
 export type TemplateDefaults = S['TemplateDefaults'];
 /** How a version was produced: a recipe build, a saved workspace (or draft publish), or git (reserved). */
 export type TemplateSource = S['TemplateSource'];
 /** The version's file list state (the tree and diff routes read it). */
 export type TemplateFilesSummary = S['TemplateFilesSummary'];
-/** Storage of a template version (contracts §19.13). */
+/** Storage of a template version. */
 export type TemplateStorage = S['TemplateStorage'];
 export type TemplateStorageWarning = S['TemplateStorageWarning'];
 /** Template storage of an organization (counts toward retained_state_gib). */
 export type OrgTemplateStorage = S['OrgTemplateStorage'];
-/** One inode path of a template version (contracts §19.10). */
+/** One inode path of a template version. */
 export type TemplateFileEntry = S['TemplateFileEntry'];
 /** One directory level of a version's tree (keyset-paginated). */
 export type TemplateFilePage = S['TemplateFilePage'];
@@ -72,7 +72,7 @@ export type TemplateDiffEntry = S['TemplateDiffEntry'];
 export type TemplateDiffChange = TemplateDiffEntry['change'];
 /** One page of a version diff; the first page (no cursor) carries `summary`. */
 export type TemplateDiffPage = S['TemplateDiffPage'];
-/** The live draft of an organization template (contracts §19.9). */
+/** The live draft of an organization template. */
 export type TemplateDraft = S['TemplateDraft'];
 /** A disk-only capture of the draft (a test instance or a publish starts from one). */
 export type DraftState = S['DraftState'];
@@ -164,7 +164,7 @@ export interface TemplateVersion {
         rootfs_sha256: string | null;
     } | null;
     defaults: TemplateDefaults;
-    /** What a workspace of this version gets when it opens (0.7.0; contracts §24.3). `defaults` equals `settings.defaults`. */
+    /** What a workspace of this version gets when it opens (0.7.0). `defaults` equals `settings.defaults`. */
     settings: TemplateSettings;
     /** The file list the tree and diff read (`loaded` when files() and diff() can answer). */
     files: TemplateFilesSummary;
@@ -199,7 +199,7 @@ export interface TemplateSummary {
     created_at: string;
     archived_at: string | null;
     shadowed_by_organization_template: boolean;
-    /** Mutable template-level defaults (contracts §20.5, §20.7): the size of a start without caps.memory_mib, and the idle policy of a workspace that sets none. */
+    /** Mutable template-level defaults: the size of a start without caps.memory_mib, and the idle policy of a workspace that sets none. */
     defaults: {
         memory_mib: number | null;
         idle_policy: string | null;
@@ -347,7 +347,7 @@ export interface TemplateBuild {
     };
     publishable: boolean;
     builder_availability: BuilderAvailability;
-    /** `recipe` (Dockerfile dialect) or `workspace` (save-as-template, draft publish; contracts §19.8). */
+    /** `recipe` (Dockerfile dialect) or `workspace` (save-as-template, draft publish). */
     source_kind: 'recipe' | 'workspace';
     source_workspace_id: string | null;
     /** The captured checkpoint (null until the capture operation succeeded). */
@@ -385,7 +385,7 @@ export interface CreateTemplateBuildParams {
     displayName?: string;
     /**
      * Recipe v1 (a Dockerfile) or recipe v2 (0.7.0; `schema: "shardflux.template-recipe.v2"`: languages, packages,
-     * uploaded files, steps, auto network and settings; contracts §24.1). Recipe v2 files reference uploads
+     * uploaded files, steps, auto network and settings). Recipe v2 files reference uploads
      * (`templates.uploads.put()`); `buildFromFile()` / `buildFromRecipe()` upload local `from` paths for you.
      */
     recipe: TemplateRecipe | TemplateRecipeV2;
@@ -411,7 +411,7 @@ export interface WaitForBuildOptions {
     /** Backoff used when the server does not hold the poll (default 1 s doubling to 10 s). */
     pollIntervalMs?: number;
     maxPollIntervalMs?: number;
-    /** Ask the server to hold each poll until the build changes (`Prefer: wait`, contracts §3; default true). */
+    /** Ask the server to hold each poll until the build changes (`Prefer: wait`; default true). */
     serverWait?: boolean;
     signal?: AbortSignal;
     /** Called with each build view the wait observes whose state or registration changed (0.7.0), the settled one included. */
@@ -429,7 +429,7 @@ export interface SaveAsTemplateResponse {
     operation: Operation | null;
     build: TemplateBuild;
 }
-/** Save-as-template (contracts §19.8): everything in the workspace, minus the sf-scrub.v1 list, becomes one new org layer. */
+/** Save-as-template: everything in the workspace, minus the sf-scrub.v1 list, becomes one new org layer. */
 export interface SaveAsTemplateParams {
     /** Organization template to save into (created when absent; platform slugs are refused with platform_template_slug). */
     templateSlug: string;
@@ -440,7 +440,7 @@ export interface SaveAsTemplateParams {
     /** Defaults of the new version (default: the source version's, else persistent). */
     defaults?: TemplateDefaultsInput;
     /**
-     * Settings of the new version (0.7.0; contracts §24.3): each field given replaces that field of the source version's
+     * Settings of the new version (0.7.0): each field given replaces that field of the source version's
      * settings, each field left out is carried forward. `settings.defaults` together with `defaults` is 422 invalid_settings.
      */
     settings?: TemplateSettingsInput;
@@ -536,7 +536,7 @@ export interface DraftOpened {
     operation: Operation | null;
 }
 /**
- * Template dev mode for one organization template (contracts §19.9): the single live draft (a layered, persistent
+ * Template dev mode for one organization template: the single live draft (a layered, persistent
  * workspace on the draft base), its captured states, disposable test instances (session workspaces on a copy of a
  * state) and publishing the draft as the next version. Mutations need build access (owners/admins, API keys with a
  * tool permission); others get 403 forbidden with details.reason template_dev_mode_role.
@@ -654,7 +654,7 @@ export declare class TemplateUploadError extends Error {
     constructor(sha256: string, status: number, code: string | null, detail?: string);
 }
 /**
- * Build uploads (contracts §24.2): files and folders a recipe v2 copies into the template, stored once per
+ * Build uploads: files and folders a recipe v2 copies into the template, stored once per
  * organization and content (SHA-256). Needs build access (API keys with a tool permission). Uploads count toward the
  * organization's template storage while they exist; one nothing references is deleted 7 days later.
  */
@@ -795,7 +795,7 @@ export interface CreateVersionTestInstanceParams {
     idempotencyKey?: string;
 }
 /**
- * Test instances of a version (contracts §24.6): a session workspace on a registered version of the organization's
+ * Test instances of a version: a session workspace on a registered version of the organization's
  * template, published or not, so a build can be tried before it is published. Owners, admins and API keys with a
  * tool permission (403 template_dev_mode_role otherwise).
  */
@@ -805,7 +805,7 @@ export declare class TemplateVersionTestInstancesApi {
     /** Opens one (202; waits until ready unless `wait: false`). It ends with close() or when idle. */
     create(slug: string, version: number, params?: CreateVersionTestInstanceParams): Promise<Workspace>;
 }
-/** Package names for the editor's pickers (contracts §24.6): apt (a base's index), pip (names only) and npm. */
+/** Package names for the editor's pickers: apt (a base's index), pip (names only) and npm. */
 export declare class TemplatePackagesApi {
     #private;
     constructor(ctx: () => ClientContext);
@@ -848,7 +848,7 @@ export declare class TemplatesApi {
         organizationId?: string;
     }): Promise<TemplateLanguages>;
     /**
-     * Node only: builds a template from template.yaml (or a .json file with the same document; contracts §24.1). The
+     * Node only: builds a template from template.yaml (or a .json file with the same document). The
      * file is recipe v2; each `build.files[]` entry may name a local `from` path (relative to the file): folders are
      * packed as the reproducible tar, files are sent as they are, both uploaded unless the organization already has
      * them, and the build is created (and awaited with `wait`). YAML needs the optional `yaml` package or `parseYaml`.
@@ -885,7 +885,7 @@ export declare class TemplatesApi {
         owner?: TemplateOwner;
     }): Promise<TemplateDetail | null>;
     /**
-     * One directory level of a version's file tree (contracts §19.10), sorted by name bytes. 409 conflict with
+     * One directory level of a version's file tree, sorted by name bytes. 409 conflict with
      * details.reason file_list_unavailable (no file list) or file_list_indexing (retryable); 404 path_not_found or
      * version_not_found; 422 invalid_path. File contents are not served: open a draft or test instance for that.
      */
@@ -901,7 +901,7 @@ export declare class TemplatesApi {
     diff(slug: string, params: TemplateDiffParams): Promise<TemplateDiffPage>;
     /** Every diff entry, following next_cursor. */
     diffAll(slug: string, params: Omit<TemplateDiffParams, 'cursor'>): AsyncGenerator<TemplateDiffEntry>;
-    /** Dev mode of one organization template: its draft, states, test instances and publish (contracts §19.9). */
+    /** Dev mode of one organization template: its draft, states, test instances and publish. */
     draft(slug: string, params?: {
         organizationId?: string;
     }): TemplateDraftApi;

package/dist/templates.js

@@ -53,7 +53,7 @@ async function openedWorkspace(ctx, res, p) {
     return { workspace: new Workspace(ctx, view, wrap), operation };
 }
 /**
- * Template dev mode for one organization template (contracts §19.9): the single live draft (a layered, persistent
+ * Template dev mode for one organization template: the single live draft (a layered, persistent
  * workspace on the draft base), its captured states, disposable test instances (session workspaces on a copy of a
  * state) and publishing the draft as the next version. Mutations need build access (owners/admins, API keys with a
  * tool permission); others get 403 forbidden with details.reason template_dev_mode_role.
@@ -369,7 +369,7 @@ async function sendUpload(ctx, meta, body, organizationId, signal) {
     return { upload: again.body.upload, ref, uploaded: true };
 }
 /**
- * Build uploads (contracts §24.2): files and folders a recipe v2 copies into the template, stored once per
+ * Build uploads: files and folders a recipe v2 copies into the template, stored once per
  * organization and content (SHA-256). Needs build access (API keys with a tool permission). Uploads count toward the
  * organization's template storage while they exist; one nothing references is deleted 7 days later.
  */
@@ -458,7 +458,7 @@ function uploadLocal(ctx, src, organizationId, signal) {
     return sendUpload(ctx, { sha256: src.sha256, size: src.size, kind: src.kind }, { open: () => fileBody(src.uploadPath), replayable: true }, organizationId, signal);
 }
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-// ---- recipe export, version test instances, package search (contracts §24.6) --------------------------------------------
+// ---- recipe export, version test instances, package search --------------------------------------------
 export class TemplateVersionsApi {
     #ctx;
     constructor(ctx) {
@@ -475,7 +475,7 @@ export class TemplateVersionsApi {
     }
 }
 /**
- * Test instances of a version (contracts §24.6): a session workspace on a registered version of the organization's
+ * Test instances of a version: a session workspace on a registered version of the organization's
  * template, published or not, so a build can be tried before it is published. Owners, admins and API keys with a
  * tool permission (403 template_dev_mode_role otherwise).
  */
@@ -504,7 +504,7 @@ export class TemplateVersionTestInstancesApi {
         return (await openedWorkspace(ctx, res, params)).workspace;
     }
 }
-/** Package names for the editor's pickers (contracts §24.6): apt (a base's index), pip (names only) and npm. */
+/** Package names for the editor's pickers: apt (a base's index), pip (names only) and npm. */
 export class TemplatePackagesApi {
     #ctx;
     constructor(ctx) {
@@ -574,7 +574,7 @@ export class TemplatesApi {
         return this.#organization;
     }
     /**
-     * Node only: builds a template from template.yaml (or a .json file with the same document; contracts §24.1). The
+     * Node only: builds a template from template.yaml (or a .json file with the same document). The
      * file is recipe v2; each `build.files[]` entry may name a local `from` path (relative to the file): folders are
      * packed as the reproducible tar, files are sent as they are, both uploaded unless the organization already has
      * them, and the build is created (and awaited with `wait`). YAML needs the optional `yaml` package or `parseYaml`.
@@ -705,7 +705,7 @@ export class TemplatesApi {
         }
     }
     /**
-     * One directory level of a version's file tree (contracts §19.10), sorted by name bytes. 409 conflict with
+     * One directory level of a version's file tree, sorted by name bytes. 409 conflict with
      * details.reason file_list_unavailable (no file list) or file_list_indexing (retryable); 404 path_not_found or
      * version_not_found; 422 invalid_path. File contents are not served: open a draft or test instance for that.
      */
@@ -741,7 +741,7 @@ export class TemplatesApi {
             cursor = page.next_cursor ?? undefined;
         } while (cursor !== undefined);
     }
-    /** Dev mode of one organization template: its draft, states, test instances and publish (contracts §19.9). */
+    /** Dev mode of one organization template: its draft, states, test instances and publish. */
     draft(slug, params = {}) {
         return new TemplateDraftApi(this.#ctx, slug, params.organizationId);
     }

package/dist/tools.d.ts

@@ -49,7 +49,7 @@ export declare function validateArgs(schema: JsonSchema, value: unknown, path?:
 export interface WorkspaceToolsOptions {
     /**
      * Tool permissions to expose (default: the tools of the workspace's last token, else all). A file-first workspace
-     * (`workspace.mode`, contracts §29) gets only the `exec` and `files` tools: `exec` runs each command as an execution
+     * (`workspace.mode`) gets only the `exec` and `files` tools: `exec` runs each command as an execution
      * (a fresh VM on the workspace's files; the result adds `execution_id`, `state`, `changed` and `tree_revision`), and
      * the process, terminal, git and browser tools are not offered because nothing runs between executions.
      */
@@ -70,7 +70,7 @@ export interface WorkspaceToolsOptions {
      * Send `workspace.hint()` when a tool call starts, without waiting for it (default true; 0.9.0+), so a parked
      * workspace is being restored while the call is prepared. Pass false when you call `workspace.hint()` yourself
      * earlier (e.g. when the model starts streaming a tool call). `read_file`, `list_files` and `search_files` never send
-     * it: a sleeping workspace serves them from its disk without waking (contracts §26.4), and the hint would wake a
+     * it: a sleeping workspace serves them from its disk without waking, and the hint would wake a
      * suspended workspace (or restore a hibernated one) that the read does not need.
      */
     hint?: boolean;
@@ -81,7 +81,7 @@ export interface WorkspaceToolsOptions {
     mode?: WorkspaceMode;
     /**
      * File-first workspaces: called with the execution id before the `exec` tool sends its execution (0.9.0+). An
-     * execution cannot be canceled, so a caller that stops waiting (an aborted signal) can still fetch its result later
+     * execution runs to completion, so a caller that stops waiting (an aborted signal) can still fetch its result later
      * with `workspace.executions.get(id)`.
      */
     onExecution?: (executionId: string) => void;