@shardflux/sdk 0.5.0 → 0.6.1

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

@@ -585,10 +585,14 @@ export interface paths {
         /**
          * Idle policy, activity and the projected automatic suspend
          * @description `idle_since` = max(`last_tool_at`, `last_attach_at`, `keepalive_until`,
-         *     `running_since`) (null when none is known; in the future while a
-         *     keepalive is active). `suspend_at` = `idle_since` + `idle_minutes` when
+         *     `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
+         *     activity (contracts §20.6). `suspend_at` = `idle_since` + `idle_minutes` when
          *     the policy is `suspend_after` and automatic suspend is enabled, else
-         *     null. Activity lags tool traffic by up to `ACTIVITY_FLUSH_MS`. Any
+         *     null; the idle loop acts within `2 x ACTIVITY_FLUSH_MS` after it.
+         *     Activity lags tool traffic by up to `ACTIVITY_FLUSH_MS`. Any
          *     tool granted by the token authorizes the call; the tool gate does not
          *     apply and the call is not tool activity.
          */
@@ -601,6 +605,49 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspace_id}/changes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * The workspace's changes against its template (layered workspaces)
+         * @description Templates v2 (contracts §19.10). Lists what the workspace changed
+         *     relative to its template chain: the guest walks its workspace layer's
+         *     overlay upper directory in raw path-byte order and classifies each
+         *     entry against the template: `added` (absent in the template),
+         *     `modified` (a regular file or symlink that exists in both),
+         *     `metadata` (only with `hash=true`, when the content equals the
+         *     template's), `deleted` (a whiteout over an existing template path) and
+         *     `replaced` (an opaque directory hiding the template's contents).
+         *     Directories that exist in both appear only when their mode or owner
+         *     differ, or when they are opaque; ancestors copied up because a child
+         *     changed are not reported.
+         *
+         *     Requires a tool token with the `files` tool. It is a read-only action
+         *     (served while a snapshot holds the tool gate `read_only`) and counts as
+         *     tool activity. `hash=true` hashes regular files of 16 MiB or less;
+         *     larger ones get `sha256: null, hash_skipped: true`.
+         *
+         *     Errors: `409 workspace_not_running` (not running; a suspended
+         *     workspace's changes are not served), `409 conflict` with
+         *     `details.reason = legacy_disk_layout` (a legacy workspace has no
+         *     workspace layer) or `guest_feature_unavailable` (the template's guest
+         *     agent lacks `layer_changes.v1`).
+         */
+        get: operations["workspaceChanges"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -818,6 +865,49 @@ export interface components {
             entries: components["schemas"]["FileInfo"][];
             truncated: boolean;
         };
+        WorkspaceChange: {
+            path: string;
+            /** @enum {string} */
+            change: "added" | "modified" | "metadata" | "deleted" | "replaced";
+            /**
+             * @description The upper entry's type; for `deleted`, the template entry's type.
+             * @enum {string}
+             */
+            type: "file" | "dir" | "symlink" | "char" | "block" | "fifo";
+            /** Format: int64 */
+            size_bytes: number;
+            /** @description Octal permission bits, e.g. "0644". */
+            mode: string;
+            uid: number;
+            gid: number;
+            /** Format: date-time */
+            modified_at: string | null;
+            /** @description Only with hash=true, for regular files of 16 MiB or less. */
+            sha256: string | null;
+            hash_skipped: boolean;
+            link_target: string | null;
+        };
+        WorkspaceChangesSummary: {
+            /** Format: int64 */
+            added: number;
+            /** Format: int64 */
+            modified: number;
+            /** Format: int64 */
+            deleted: number;
+            /** Format: int64 */
+            replaced: number;
+            /**
+             * Format: int64
+             * @description Sum of the sizes of added and modified regular files.
+             */
+            bytes: number;
+        };
+        WorkspaceChangesPage: {
+            data: components["schemas"]["WorkspaceChange"][];
+            /** @description Opaque; null when there are no more changes under path_prefix. */
+            next_cursor: string | null;
+            summary?: components["schemas"]["WorkspaceChangesSummary"];
+        };
         FileWriteResult: {
             path: string;
             /** Format: int64 */
@@ -927,15 +1017,25 @@ export interface components {
             keepalive_until: string;
         };
         IdlePolicy: {
-            /** @enum {string} */
-            mode: "hot" | "suspend_after";
-            /** @description Set when mode is suspend_after. */
+            /**
+             * @description adaptive = the learned timeout (contracts §20.7, the default); suspend_after = a fixed timeout;
+             *     never (or the legacy hot) = no automatic suspend.
+             * @enum {string}
+             */
+            mode: "hot" | "suspend_after" | "adaptive" | "never";
+            /** @description Set when mode is suspend_after (rounded up from idle_seconds). */
             idle_minutes: number | null;
+            /** @description The fixed timeout in seconds when mode is suspend_after. */
+            idle_seconds?: number | null;
+            /** @description The timeout applied to the current idle period (adaptive or fixed); null while none applies. */
+            timeout_seconds?: number | null;
+            /** @description What the timeout comes from, e.g. "learned from 37 idle periods (active-hours)", "template prior", "default". */
+            basis?: string | null;
             /**
-             * @description workspace = the workspace's own policy; default = the cell default (IDLE_DEFAULT_MODE / IDLE_DEFAULT_MINUTES).
+             * @description workspace = the workspace's own policy; template = the template's default; default = the cell default (IDLE_DEFAULT_MODE).
              * @enum {string}
              */
-            source: "workspace" | "default";
+            source: "workspace" | "template" | "default";
         };
         IdleAutoSuspend: {
             /** @description Policy is suspend_after and automatic suspend was not disabled (e.g. after repeated failures). */
@@ -1829,4 +1929,36 @@ export interface operations {
             default: components["responses"]["Error"];
         };
     };
+    workspaceChanges: {
+        parameters: {
+            query?: {
+                /** @description Absolute path; only entries at or below it. */
+                path_prefix?: string;
+                limit?: number;
+                /** @description `next_cursor` of the previous page. */
+                cursor?: string;
+                hash?: boolean;
+                /** @description Also return totals over everything under path_prefix. */
+                summary?: boolean;
+            };
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description One page of changes, in raw path-byte order. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkspaceChangesPage"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
 }

package/dist/http.d.ts

@@ -1,4 +1,5 @@
-export declare const SDK_VERSION = "0.5.0";
+import type { RetryRecord } from './progress.js';
+export declare const SDK_VERSION = "0.6.1";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -10,6 +11,8 @@ export interface RequestOptions {
     signal?: AbortSignal;
     /** Override the client's default request timeout (ms); 0 disables it (streams). */
     timeoutMs?: number;
+    /** Called before each retry of a transient failure (lifecycle timing records these). */
+    onRetry?: (retry: Omit<RetryRecord, 'atMs'>) => void;
 }
 export interface HttpOptions {
     baseUrl: string;
@@ -21,6 +24,16 @@ export interface HttpOptions {
     sleep?: (ms: number) => Promise<void>;
 }
 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.
+ */
+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;
 /** 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>;
@@ -30,10 +43,26 @@ export declare class HttpClient {
     /** Performs the request and returns the raw Response (2xx), throwing structured errors otherwise. */
     raw(method: string, path: string, init?: RequestOptions, authorization?: string): Promise<Response>;
     json<T>(method: string, path: string, init?: RequestOptions, authorization?: string): Promise<T>;
+    /** Like json() but also returns the status and the response headers (bounded waits read Preference-Applied). */
+    jsonWithHeaders<T>(method: string, path: string, init?: RequestOptions, authorization?: string): Promise<{
+        status: number;
+        headers: Headers;
+        body: T;
+    }>;
     /** Like json() but also returns the HTTP status (open() distinguishes 200 from 202). */
     jsonWithStatus<T>(method: string, path: string, init?: RequestOptions, authorization?: string): Promise<{
         status: number;
         body: T;
     }>;
 }
+/** Longest server-side wait the SDK asks for (contracts §3: 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
+ * 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<{
+    body: T;
+    applied: boolean;
+}>;
 export declare function randomId(prefix?: string): string;

package/dist/http.js

@@ -5,8 +5,29 @@
  * requests carrying an Idempotency-Key).
  */
 import { ShardfluxApiError, ShardfluxProtocolError, isErrorBody } from "./errors.js";
-export const SDK_VERSION = '0.5.0';
+import { describeFailure } from "./progress.js";
+export const SDK_VERSION = '0.6.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.
+ */
+export function defaultFetch(env = globalThis.process?.env, undiciVersion = globalThis.process?.versions?.undici) {
+    const base = (input, init) => fetch(input, init);
+    const major = Number((undiciVersion ?? '').split('.')[0]);
+    if (!(major >= 8) || env?.SHARDFLUX_HTTP_KEEPALIVE === '1')
+        return base;
+    return (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set('connection', 'close');
+        return fetch(input, { ...init, headers });
+    };
+}
 export function buildUrl(base, path, query) {
     const u = new URL(base.replace(/\/+$/, '') + path);
     for (const [k, v] of Object.entries(query ?? {})) {
@@ -76,7 +97,9 @@ export class HttpClient {
                     throw err;
                 if (!retriable || attempt >= this.opts.maxRetries)
                     throw err;
-                await sleep(Math.min(2_000, 200 * 2 ** attempt));
+                const delayMs = Math.min(2_000, 200 * 2 ** attempt);
+                init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(err, timeoutMs), delayMs });
+                await sleep(delayMs);
                 continue;
             }
             if (res.ok)
@@ -87,7 +110,9 @@ export class HttpClient {
             if (!retriable || !retryableError || attempt >= this.opts.maxRetries)
                 throw error;
             const hinted = error instanceof ShardfluxApiError ? error.retryAfterSeconds : undefined;
-            await sleep(Math.min(5_000, hinted !== undefined ? hinted * 1000 : 200 * 2 ** attempt));
+            const delayMs = Math.min(5_000, hinted !== undefined ? hinted * 1000 : 200 * 2 ** attempt);
+            init.onRetry?.({ request: `${method} ${path}`, attempt: attempt + 1, cause: describeFailure(error), delayMs });
+            await sleep(delayMs);
         }
     }
     async json(method, path, init = {}, authorization) {
@@ -104,6 +129,17 @@ export class HttpClient {
             throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
         }
     }
+    /** Like json() but also returns the status and the response headers (bounded waits read Preference-Applied). */
+    async jsonWithHeaders(method, path, init = {}, authorization) {
+        const res = await this.raw(method, path, init, authorization);
+        const text = await res.text();
+        try {
+            return { status: res.status, headers: res.headers, body: (text.length === 0 ? undefined : JSON.parse(text)) };
+        }
+        catch {
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+        }
+    }
     /** Like json() but also returns the HTTP status (open() distinguishes 200 from 202). */
     async jsonWithStatus(method, path, init = {}, authorization) {
         const res = await this.raw(method, path, init, authorization);
@@ -116,6 +152,24 @@ export class HttpClient {
         }
     }
 }
+/** Longest server-side wait the SDK asks for (contracts §3: 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
+ * 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) {
+    const s = Math.min(SERVER_WAIT_MAX_S, Math.floor(waitS));
+    const init = { ...(signal ? { signal } : {}), ...(onRetry ? { onRetry } : {}) };
+    if (s >= 1) {
+        init.headers = { prefer: `wait=${s}` };
+        // The held response may take the whole wait: the request timeout must outlast it.
+        init.timeoutMs = Math.max(http.opts.timeoutMs, s * 1000 + 10_000);
+    }
+    const res = await http.jsonWithHeaders('GET', path, init, authorization);
+    const pa = res.headers.get('preference-applied');
+    return { body: res.body, applied: s >= 1 && pa !== null && /\bwait\s*=/i.test(pa) };
+}
 export function randomId(prefix = '') {
     return `${prefix}${crypto.randomUUID()}`;
 }

package/dist/index.d.ts

@@ -11,14 +11,17 @@
  */
 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 } from './client.js';
-export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, Entitlements, Invoice, InvoicePage, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, ShardfluxOptions, WaitOptions, WorkspaceView, } from './client.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, ShardfluxOptions, UpdatePolicy, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export type { FinishedOperation, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
+export { formatTiming } from './progress.js';
+export type { LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
 export { UsageApi } from './usage.js';
 export type { Grants, Spend, SpendPolicy, UsageEstimate, UsageMeter, UsageSeries, UsageSeriesParams, UsageSummary } from './usage.js';
-export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplatesApi, buildSettled } from './templates.js';
-export type { BuilderAvailability, CreateTemplateBuildParams, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRegistrationState, TemplateBuildState, TemplateDetail, TemplateOwner, TemplateRecipe, TemplateSummary, TemplateVersion, TemplateVersionState, WaitForBuildOptions, } from './templates.js';
-export { SecretsApi } from './secrets.js';
-export type { CreateSecretParams, Secret, SecretPermissions, SecretScope, SecretVersion, UpdateSecretParams } from './secrets.js';
+export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatesApi, buildSettled, saveAsTemplateBody } from './templates.js';
+export type { BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, DraftOpened, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRegistrationState, TemplateBuildState, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateOwner, TemplateRecipe, TemplateSource, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateVersion, TemplateVersionState, WaitForBuildOptions, } 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';
 export type { EffectiveEgressPolicy, EgressEnforcement, EgressMode, EgressPolicyInput, EgressPolicyVersion, EgressRule, EgressRuleInput, OrganizationEgressOverride, ProjectEgressPolicy, WorkspaceEgressPolicy, } from './egress.js';
 export { VolumesApi } from './volumes.js';
@@ -26,12 +29,13 @@ export type { AttachVolumeParams, AttachmentResult, CreateVolumeParams, DeleteVo
 export { AuditApi, auditQuery, parseAuditNdjson } from './audit.js';
 export type { AuditActorType, AuditEvent, AuditFilters, AuditListParams, AuditOutcome, AuditSource } from './audit.js';
 export { Workspace } from './workspace.js';
-export { CellClient, cellPath, ndjson } from './cell.js';
-export type { BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, FileInfo, FileList, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, RunOptions, RunResult, Signal, } from './cell.js';
+export type { WakeOptions } from './workspace.js';
+export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from './cell.js';
+export type { BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, FileInfo, FileList, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, RunOptions, RunResult, Signal, 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';
 export type { JsonSchema, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
 export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from './errors.js';
-export type { AppErrorCode, CellErrorCode, ErrorCode } from './errors.js';
+export type { AppErrorCode, CellErrorCode, ErrorCode, ErrorReason, KnownErrorReason } from './errors.js';
 export { SDK_VERSION } from './http.js';

package/dist/index.js

@@ -1,12 +1,13 @@
-export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog } from "./client.js";
+export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
+export { formatTiming } from "./progress.js";
 export { UsageApi } from "./usage.js";
-export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplatesApi, buildSettled } from "./templates.js";
-export { SecretsApi } from "./secrets.js";
+export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatesApi, buildSettled, saveAsTemplateBody } from "./templates.js";
+export { SecretsApi, WorkspaceSecrets } from "./secrets.js";
 export { EgressPolicyApi } from "./egress.js";
 export { VolumesApi } from "./volumes.js";
 export { AuditApi, auditQuery, parseAuditNdjson } from "./audit.js";
 export { Workspace } from "./workspace.js";
-export { CellClient, cellPath, ndjson } from "./cell.js";
+export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from "./cell.js";
 export { ToolTokenManager } from "./tokens.js";
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from "./tools.js";
 export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Lifecycle calls (suspend, resume, snapshot, fork, delete, close, reset): "requested" or "finished".
+ *
+ * Every lifecycle endpoint answers once the operation is accepted, while it is usually still `queued`. By default the
+ * SDK returns that operation: the call resolves when the change is REQUESTED. With `wait`, it waits for the operation
+ * and resolves when the change has FINISHED, returning the succeeded operation (typed FinishedOperation) and, on a
+ * workspace handle, the refreshed view. Both paths are traced (see progress.ts).
+ */
+import type { ClientContext, Operation, WaitOptions } from './client.js';
+import type { RequestOptions } from './http.js';
+import { Trace } from './progress.js';
+import type { LifecycleAction, ProgressListener } from './progress.js';
+/** An operation that has finished successfully: what a lifecycle call with `wait` resolves to. */
+export type FinishedOperation = Operation & {
+    state: 'succeeded';
+    completed_at: string;
+};
+export interface LifecycleOptions {
+    idempotencyKey?: string;
+    /**
+     * Default (false): resolve once the change is requested; the returned operation is usually still `queued`.
+     * `true` or WaitOptions: resolve once it has finished (the operation `succeeded`); throws OperationFailedError when it
+     * fails and OperationTimeoutError after `timeoutMs` (default 5 minutes; the operation continues server side).
+     */
+    wait?: boolean | WaitOptions;
+    /** Progress events of this call (phases, retries, and `done` with its timing). */
+    onProgress?: ProgressListener;
+}
+/** Lifecycle options the options of a waited call narrow to. */
+export type WaitedLifecycleOptions = LifecycleOptions & {
+    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). */
+export declare const AFTER_WAIT: unique symbol;
+export type InternalWaitOptions = WaitOptions & {
+    [TRACE]?: Trace;
+};
+export type InternalLifecycleOptions = LifecycleOptions & {
+    [AFTER_WAIT]?: (trace: Trace, operation: Operation) => Promise<void>;
+};
+export declare function waitOptionsOf(opts: LifecycleOptions): WaitOptions | null;
+/**
+ * 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): Promise<Operation>;

package/dist/lifecycle.js

@@ -0,0 +1,33 @@
+import { OperationFailedError } from "./errors.js";
+import { Trace, combineListeners, traced } from "./progress.js";
+/** Internal: the trace a wait continues instead of starting its own (open(), wake() and waited lifecycle calls). */
+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');
+export function waitOptionsOf(opts) {
+    if (opts.wait === undefined || opts.wait === false)
+        return null;
+    return opts.wait === true ? {} : opts.wait;
+}
+/**
+ * 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 async function runLifecycle(ctx, kind, workspaceId, start, opts) {
+    const waitOpts = waitOptionsOf(opts);
+    const trace = new Trace(kind, combineListeners(ctx.onProgress, opts.onProgress, waitOpts?.onProgress), { workspaceId });
+    return traced(trace, async () => {
+        trace.phase('request');
+        const operation = await start({ onRetry: trace.onRetry });
+        trace.observe(operation);
+        if (!waitOpts)
+            return operation;
+        let final = operation;
+        if (operation.state === 'failed' || operation.state === 'canceled')
+            throw new OperationFailedError(operation);
+        if (operation.state !== 'succeeded')
+            final = await ctx.workspaces.waitForOperation(operation.id, { ...waitOpts, [TRACE]: trace });
+        await opts[AFTER_WAIT]?.(trace, final);
+        return final;
+    });
+}