@shardflux/sdk 0.12.0 → 0.13.0

package/dist/generated/cell-api.d.ts

@@ -80,6 +80,45 @@ export interface paths {
          *     `503 service_unavailable` (`no_execution_host`: no host with
          *     protocol feature `file_first` has room; retry), secret resolution
          *     errors as for processful starts.
+         *
+         *     Burst execution (contracts §33, not public yet): `burst: always` runs
+         *     the command on a larger, short-lived burst VM on the workspace's
+         *     host over a copy of the workspace disk and applies its file changes
+         *     back when it exits. The session is read, streamed and attached like
+         *     any other; it carries `burst` (BurstSummary) and cannot be signalled
+         *     or canceled (`409 conflict`, `details.reason burst_not_supported`).
+         *     Refusals: `422 validation_failed` with `details.reason`
+         *     `burst_mode_not_supported` (`auto`), `burst_not_supported` (stdin),
+         *     `burst_size_exceeds_plan` (`burst_vcpus`/`burst_memory_mib` above the
+         *     plan's per-workspace ceilings; `details.field`, `details.limit`);
+         *     `409 burst_unavailable` with `details.reason` `not_available` (no
+         *     entitlement `policy.burst_exec`, or the host lacks protocol feature
+         *     `burst_exec`), `layout_unsupported`, `shared_volumes`,
+         *     `host_capacity`, `fence_not_drained`, `workspace_fenced`,
+         *     `apply_pending`, `park_failed`, `workspace_resumed`, `interrupted`;
+         *     `409 burst_apply_failed` (`details.reason` `disk_full` or
+         *     `apply_failed`, `details.applied_entries`, `details.pending_entries`;
+         *     the workspace refuses writes until a retry with the same
+         *     `session_id` completes the apply). A refusal the host gives within
+         *     the first seconds is the start's answer; a later one ends the
+         *     session (`failed_to_start` for `burst_unavailable`, `lost` for
+         *     `burst_apply_failed`), is recorded in `burst.error`, and is the
+         *     output stream's final `error` event. A retry with the same
+         *     `session_id` replays the recorded outcome (the host journals the
+         *     burst by the exec's operation id) or resumes an unfinished apply.
+         *
+         *     Start and follow in one request: a processful start sent with
+         *     `Accept: application/x-ndjson` (or `text/event-stream`) answers 200
+         *     with the session's output stream, as `GET .../output?follow=true`
+         *     from offset 0 (output events, `exit`, a final `error`), and
+         *     `X-Exec-Session-Id` names the session. The stream slot is taken
+         *     before the command starts (`503 service_unavailable` when the
+         *     gateway has no stream slot: nothing ran). Headers are sent as soon
+         *     as the command started, before any output. A `failed_to_start`
+         *     session, a refusal and a file-first execution keep their JSON
+         *     answers. A replayed `session_id` streams the existing session and
+         *     never runs it again; after a dropped stream, reconnect with
+         *     `GET .../output` from the byte offsets already read.
          */
         post: operations["execStart"];
         delete?: never;
@@ -225,7 +264,16 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** SIGTERM the process group, SIGKILL after grace */
+        /**
+         * SIGTERM the process group, SIGKILL after grace
+         * @description Sends SIGTERM to the session's process group and SIGKILL after
+         *     `grace_ms` (0 to 60000; 0 or omitted is 5000). Answers when the
+         *     command has ended: at once when SIGTERM ends it, otherwise after the
+         *     grace and the SIGKILL. A `grace_ms` outside the range is `422
+         *     validation_failed`
+         *     (`details.field` `grace_ms`, `details.minimum`, `details.maximum`).
+         *     An ended session is returned as it is.
+         */
         post: operations["execCancel"];
         delete?: never;
         options?: never;
@@ -293,7 +341,11 @@ export interface paths {
         get: operations["ptyGet"];
         put?: never;
         post?: never;
-        /** Close (SIGHUP, then SIGKILL after grace) */
+        /**
+         * Close (SIGHUP, then SIGKILL after grace)
+         * @description Sends SIGHUP to the session's process group and SIGKILL 2 s later
+         *     if it is still running; answers once it has ended.
+         */
         delete: operations["ptyClose"];
         options?: never;
         head?: never;
@@ -744,8 +796,9 @@ export interface paths {
          * @description `idle_since` = max(`last_tool_at`, `last_attach_at`, `keepalive_until`,
          *     `running_since`, the work horizon of running exec commands) (null when
          *     none is known; in the future while a keepalive or a running command is
-         *     active). A running exec command counts as work until min(its start +
-         *     `IDLE_COMMAND_MAX_SECONDS`, its start + `timeout_ms`), and its end is
+         *     active). A running exec command counts as work until it ends or its
+         *     timeout passes: its start + `timeout_ms` when it has one, else its
+         *     start + `IDLE_COMMAND_MAX_SECONDS` (1 hour by default). Its end is
          *     activity (contracts §20.6): an end seen without a client call is
          *     recorded in `last_attach_at`, which is work but not a tool call.
          *     `suspend_at` = `idle_since` + `idle_minutes` when
@@ -823,7 +876,7 @@ export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
         /** @enum {string} */
-        ErrorCode: "bad_request" | "unauthenticated" | "forbidden" | "not_found" | "conflict" | "stale_epoch" | "workspace_not_running" | "validation_failed" | "payload_too_large" | "range_not_satisfiable" | "rate_limited" | "capacity_pending" | "dependency_unavailable" | "timeout" | "internal_error" | "service_unavailable" | "workspace_busy";
+        ErrorCode: "bad_request" | "unauthenticated" | "forbidden" | "not_found" | "conflict" | "stale_epoch" | "workspace_not_running" | "validation_failed" | "payload_too_large" | "range_not_satisfiable" | "rate_limited" | "capacity_pending" | "dependency_unavailable" | "timeout" | "internal_error" | "service_unavailable" | "workspace_busy" | "burst_unavailable" | "burst_apply_failed";
         ErrorBody: {
             error: {
                 code: components["schemas"]["ErrorCode"];
@@ -872,7 +925,10 @@ export interface components {
             stdin?: string;
             /** Format: int64 */
             timeout_ms?: number;
-            /** Format: int64 */
+            /**
+             * Format: int64
+             * @description Time between the SIGTERM and the SIGKILL when timeout_ms ends the command; 0 or omitted is 5000.
+             */
             kill_grace_ms?: number;
             secret_refs?: components["schemas"]["SecretRefs"];
             /** @description File-first workspaces (required there, refused otherwise) — the execution's idempotency key. */
@@ -883,6 +939,16 @@ export interface components {
              * @default 1048576
              */
             output_limit_bytes?: number;
+            /**
+             * @description Burst execution (contracts §33): `always` runs this run-to-completion command on a larger, short-lived burst VM and applies its file changes back. Needs entitlement `policy.burst_exec` and a layered processful workspace; not with stdin. `auto` is reserved (422 validation_failed, details.reason burst_mode_not_supported).
+             * @default never
+             * @enum {string}
+             */
+            burst?: "never" | "always";
+            /** @description The burst VM's vCPUs (burst always only; default the host's, 8), at most the plan's workspace CPU ceiling. */
+            burst_vcpus?: number;
+            /** @description The burst VM's memory in MiB (burst always only; default the host's, 8192), at most the plan's workspace memory ceiling. */
+            burst_memory_mib?: number;
         };
         /** @description Names of customer secrets (contracts §17) to inject as environment variables NAME=value of this process only. The cell resolves them at session start through the API with the caller's tool token (permission-checked and audited by the API); values are never logged, persisted or returned by the cell. Any name the caller may not use (unknown, not permitted for this workspace/project/tool) refuses the whole start with 403 forbidden (details.reason secret_not_available, details.names); nothing is started. A name that is also a key of `env` is refused (422 validation_failed). Requires a workspace tool token (browser stream tickets cannot resolve secrets: 403, details.reason secret_refs_require_tool_token). Resolution failures: 401 (token revoked/expired), 409 stale_epoch, 429 rate_limited, 503 dependency_unavailable. A retried start with the same session_id re-resolves the names; if a value changed since the first start the host refuses the different request (409 conflict). */
         SecretRefs: string[];
@@ -980,6 +1046,88 @@ export interface components {
             ended_at?: string | null;
             /** @description Why the session ended without an exit code. For failed_to_start the command never ran and this names the cause, e.g. `working directory "/home/user/app" is not a directory` or `executable "foo" not found in PATH`. */
             error?: string;
+            memory_grow?: components["schemas"]["MemoryGrow"];
+            burst?: components["schemas"]["BurstSummary"];
+        };
+        /** @description Burst execution (contracts §33.5): present on every session started with `burst: always`. The size, method and counts are set once the burst ended (the host's result); while it runs only host, applied and the requested size are known. */
+        BurstSummary: {
+            /**
+             * @description Where the burst VM ran; `local` = the workspace's host (`remote` is reserved).
+             * @enum {string}
+             */
+            host: "local" | "remote";
+            /** @description The burst VM's vCPUs (the requested count while it runs, absent for the host default). */
+            vcpus?: number;
+            /** @description The burst VM's memory in MiB (the requested size while it runs, absent for the host default). */
+            memory_mib?: number;
+            /**
+             * @description How the burst VM got the workspace copy.
+             * @enum {string}
+             */
+            method?: "layer" | "clone";
+            /** @description The command's file changes were applied to the workspace. */
+            applied: boolean;
+            /** Format: int64 */
+            written_files?: number;
+            /** Format: int64 */
+            written_dirs?: number;
+            /** Format: int64 */
+            removed?: number;
+            /** Format: int64 */
+            written_bytes?: number;
+            /** @description Processes the command left behind in the burst VM (killed; they do not survive a burst). */
+            leftover_killed?: number;
+            /**
+             * Format: int64
+             * @description Wall time of the burst minus the command's own run time.
+             */
+            overhead_ms?: number;
+            /** @description The burst VM's own paths whose changes are never carried back (the host's denylist). */
+            excluded_paths?: string[];
+            /** @description The host's phase timings (ms) and counters. */
+            timings?: {
+                [key: string]: number;
+            };
+            /** @description The recorded outcome of an earlier attempt with the same session_id. */
+            replayed?: boolean;
+            /** @description Set when the burst failed after the start answered: burst_unavailable (the workspace is unchanged) or burst_apply_failed (details.applied_entries, details.pending_entries). */
+            error?: components["schemas"]["BurstError"];
+        };
+        BurstError: {
+            code: components["schemas"]["ErrorCode"];
+            message: string;
+            retryable: boolean;
+            details?: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Elastic memory (contracts §32.3, §32.6): the host grew the workspace's memory before this exec started (the exec waited for it). Present only on the session returned by the start that grew the VM; absent when no grow ran (fixed workspaces, or already at the exec size). */
+        MemoryGrow: {
+            /**
+             * @description delivered: the whole grow; partial: less than wanted; missed: nothing could be plugged; failed: the plug did not converge or errored.
+             * @enum {string}
+             */
+            outcome: "delivered" | "partial" | "missed" | "failed";
+            /**
+             * Format: int64
+             * @description Guest memory before the grow (MiB).
+             */
+            from_mib: number;
+            /**
+             * Format: int64
+             * @description Guest memory the grow aimed for (MiB).
+             */
+            want_mib: number;
+            /**
+             * Format: int64
+             * @description Guest memory after the grow (MiB).
+             */
+            got_mib: number;
+            /**
+             * Format: int64
+             * @description Trigger to plugged and guest MemTotal settled (ms, rounded).
+             */
+            deliver_ms: number;
         };
         OutputEvent: {
             /** @enum {string} */
@@ -999,7 +1147,10 @@ export interface components {
             /** @enum {string} */
             type: "signal" | "cancel";
             signal?: components["schemas"]["SignalValue"];
-            /** Format: int64 */
+            /**
+             * Format: int64
+             * @description For cancel, as CancelRequest.grace_ms; out of range is an `error` event (validation_failed).
+             */
             grace_ms?: number;
         };
         /** @description Signal number (1-64) or name (e.g. "SIGTERM", "TERM"). */
@@ -1026,7 +1177,10 @@ export interface components {
             only_leader?: boolean;
         };
         CancelRequest: {
-            /** Format: int64 */
+            /**
+             * Format: int64
+             * @description Time between the SIGTERM and the SIGKILL; 0 or omitted is 5000.
+             */
             grace_ms?: number;
         };
         PtyOpenRequest: {
@@ -1545,12 +1699,16 @@ export interface operations {
             };
         };
         responses: {
-            /** @description The session already existed; nothing was run again (processful), or the recorded result of an existing execution (file-first). */
+            /** @description An existing session/result, or followed output when a processful start accepts NDJSON/SSE. A failed-to-start session stays JSON. */
             200: {
                 headers: {
+                    /** @description The streamed session id; replay/reconnect use the same session and byte offsets. */
+                    "X-Exec-Session-Id"?: string;
                     [name: string]: unknown;
                 };
                 content: {
+                    "application/x-ndjson": string;
+                    "text/event-stream": string;
                     "application/json": components["schemas"]["ExecSession"] | components["schemas"]["ExecutionResult"];
                 };
             };

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.12.0";
+export declare const SDK_VERSION = "0.13.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -13,6 +13,11 @@ export interface RequestOptions {
     signal?: AbortSignal;
     /** Override the client's default request timeout (ms); 0 disables it (streams). */
     timeoutMs?: number;
+    /**
+     * Bounds each attempt until the response headers arrive (ms), leaving the body unbounded: a stream that answers a
+     * start (exec.run's combined start and output). Usually with `timeoutMs: 0`.
+     */
+    headersTimeoutMs?: number;
     /** Called before each retry of a transient failure (lifecycle timing records these). */
     onRetry?: (retry: Omit<RetryRecord, 'atMs'>) => void;
 }

package/dist/http.js

@@ -8,7 +8,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.12.0';
+export const SDK_VERSION = '0.13.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** One private HTTP/1.1 pool on Node 26+, shared by SDK clients. No global dispatcher changes. */
 let nodeFetch;
@@ -108,7 +108,13 @@ export class HttpClient {
             }
             const timeoutMs = init.timeoutMs ?? this.opts.timeoutMs;
             const timeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
-            const signal = timeout && init.signal ? AbortSignal.any([timeout, init.signal]) : (timeout ?? init.signal);
+            const headersMs = init.headersTimeoutMs ?? 0;
+            const headersAbort = headersMs > 0 ? new AbortController() : undefined;
+            const headersTimer = headersAbort
+                ? setTimeout(() => headersAbort.abort(new DOMException('The response headers timed out.', 'TimeoutError')), headersMs)
+                : undefined;
+            const signals = [timeout, init.signal, headersAbort?.signal].filter((s) => s !== undefined);
+            const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
             let res;
             try {
                 res = await this.opts.fetch(url, { method, headers, ...(body === undefined ? {} : { body: body }), ...(signal ? { signal } : {}) });
@@ -119,10 +125,13 @@ export class HttpClient {
                 if (!retriable || attempt >= this.opts.maxRetries)
                     throw err;
                 const delayMs = Math.min(2_000, 200 * 2 ** attempt);
-                init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(err, timeoutMs), delayMs });
+                init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(err, headersAbort?.signal.aborted ? headersMs : timeoutMs), delayMs });
                 await sleep(delayMs);
                 continue;
             }
+            finally {
+                clearTimeout(headersTimer);
+            }
             if (res.ok) {
                 if (this.opts.onSuccess) {
                     try {

package/dist/index.d.ts

@@ -15,8 +15,8 @@
 export type { components, operations, paths } from './generated/app-api.js';
 export type { components as CellComponents, paths as CellPaths } from './generated/cell-api.js';
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from './client.js';
-export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, UpdatePolicy, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
-export type { FinishedOperation, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
+export type { AgentSession, AllocationMode, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export type { FinishedOperation, ForkOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 export { durabilityOf, formatTiming, isDurable, lostSuspendOf } from './progress.js';
 export type { Durability, LostSuspend, LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
 export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from './feedback.js';
@@ -28,7 +28,7 @@ export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile }
 export type { PackedFile, YamlParser } from './template-file.js';
 export { tarEnd, tarHeader, tarPadding } from './tar.js';
 export type { TarEntry, TarEntryType } from './tar.js';
-export type { BuildFromFileEvent, BuildFromFileOptions, BuildFromFileResult, BuildFromRecipeOptions, BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, CreateVersionTestInstanceBody, CreateVersionTestInstanceParams, DraftOpened, LocalUpload, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, PutUploadOptions, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRecipeV2, TemplateBuildRegistrationState, TemplateBuildState, TemplateCategory, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateEgressDefault, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateInput, TemplateLanguage, TemplateLanguages, TemplateOwner, TemplatePackage, TemplatePackageEcosystem, TemplatePackagePage, TemplateRecipe, TemplateRecipeV2, TemplateRecipeV2File, TemplateService, TemplateSettings, TemplateSettingsInput, TemplateSource, TemplateStartCommand, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateUpload, TemplateUploadRequest, TemplateUploadResponse, TemplateUploadResult, TemplateVersion, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
+export type { BuildFromFileEvent, BuildFromFileOptions, BuildFromFileResult, BuildFromRecipeOptions, BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, CreateVersionTestInstanceBody, CreateVersionTestInstanceParams, DraftOpened, LocalUpload, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, PutUploadOptions, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRecipeV2, TemplateBuildRegistrationState, TemplateBuildState, TemplateCategory, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateEgressDefault, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateInput, TemplateLanguage, TemplateLanguages, TemplateOwner, TemplatePackage, TemplatePackageEcosystem, TemplatePackagePage, TemplateRecipe, TemplateRecipeV2, TemplateRecipeV2File, TemplateService, TemplateSettings, TemplateSettingsInput, TemplateSource, TemplateStartCommand, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateUpload, TemplateUploadRequest, TemplateUploadResponse, TemplateUploadResult, TemplateVersion, TemplateVersionImmutable, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
 export { SecretsApi, WorkspaceSecrets } from './secrets.js';
 export type { BoundSecretStatus, CreateOrganizationSecretParams, CreateSecretParams, Secret, SecretAccessEvent, SecretPermissions, SecretScope, SecretVersion, UpdateSecretParams, WorkspaceSecretBindings, } from './secrets.js';
 export { EgressPolicyApi } from './egress.js';
@@ -42,7 +42,7 @@ export type { HintOptions, HintResult, WakeOptions } from './workspace.js';
 export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from './cell.js';
 export { EXECUTION_ID, ExecutionResult, newExecutionId } from './executions.js';
 export type { ExecutionChange, ExecutionError, ExecutionGetOptions, ExecutionResultBody, ExecutionRunOptions, ExecutionState } from './executions.js';
-export type { TreeRevisionOptions, BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, RunOptions, RunResult, ServedFrom, Signal, WakeHintResult, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
+export type { TreeRevisionOptions, BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, MemoryGrow, BurstSummary, BurstError, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, RunOptions, RunResult, ServedFrom, Signal, WakeHintResult, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
 export { ToolTokenManager } from './tokens.js';
 export type { ToolName, ToolToken, ToolTokenOptions } from './tokens.js';
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from './tools.js';

package/dist/lifecycle.d.ts

@@ -61,6 +61,11 @@ export interface ResumeOptions extends LifecycleOptions {
 export type WaitedResumeOptions = ResumeOptions & {
     wait: true | WaitOptions;
 };
+/** A waited fork (0.13.0+) returns the target view and token together when the API supports it. */
+export type ForkOptions = ResumeOptions;
+export type WaitedForkOptions = ForkOptions & {
+    wait: true | WaitOptions;
+};
 /** Internal: the trace a wait continues instead of starting its own (open(), wake() and waited lifecycle calls). */
 export declare const TRACE: unique symbol;
 /** Internal: work a workspace handle does after the operation finished, inside the same trace (refreshing its view). */
@@ -88,6 +93,7 @@ export declare function waitOptionsOf(opts: LifecycleOptions): WaitOptions | nul
  * Starts a lifecycle operation with `start` and, when `opts.wait` asks for it, waits for it to finish. The trace covers
  * the request, every observed state, and `AFTER_WAIT`; it ends with `done` either way.
  */
-export declare function runLifecycle(ctx: ClientContext, kind: LifecycleAction, workspaceId: string, start: (init: Pick<RequestOptions, 'onRetry'>) => Promise<Operation>, opts: InternalLifecycleOptions, capture?: {
+export declare function runLifecycle(ctx: ClientContext, kind: LifecycleAction, workspaceId: string, start: (init: Pick<RequestOptions, 'onRetry'>, trace: Trace) => Promise<Operation>, opts: InternalLifecycleOptions, capture?: {
     settle?: boolean;
+    requestReason?: string | null;
 }): Promise<Operation>;

package/dist/lifecycle.js

@@ -28,8 +28,8 @@ export async function runLifecycle(ctx, kind, workspaceId, start, opts, capture
         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;

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[];