@shardflux/sdk 0.5.0 → 0.6.0

package/dist/cell.js

@@ -1,5 +1,6 @@
 import { ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
 import { HttpClient, defaultSleep, randomId } from "./http.js";
+import { describeFailure, emitTo } from "./progress.js";
 /** Fills a path template that must exist in cell-api.yaml. */
 export function cellPath(template, params) {
     return template.replace(/\{([a-z_]+)\}/g, (_, name) => {
@@ -9,6 +10,9 @@ export function cellPath(template, params) {
         return encodeURIComponent(String(v));
     });
 }
+export const DEFAULT_TRANSITION_TIMEOUT_MS = 120_000;
+/** Wakes per call at most: a workspace that keeps being suspended again surfaces the refusal. */
+const MAX_WAKES = 3;
 const b64 = (bytes) => Buffer.from(typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : bytes).toString('base64');
 const unb64 = (s) => (s ? new Uint8Array(Buffer.from(s, 'base64')) : new Uint8Array());
 /** Parses an NDJSON byte stream into objects (tolerates CRLF and a final unterminated line). */
@@ -68,7 +72,11 @@ export class CellClient {
     workspaceId;
     tokens;
     #opts;
+    #listener;
+    #wake;
+    #transitionTimeoutMs;
     #clients = new Map();
+    #closer = new AbortController();
     constructor(workspaceId, tokens, opts = {}) {
         this.workspaceId = workspaceId;
         this.tokens = tokens;
@@ -79,6 +87,9 @@ export class CellClient {
             maxRetries: opts.maxRetries ?? 2,
             sleep: opts.sleep ?? defaultSleep,
         };
+        this.#wake = opts.wake ?? null;
+        this.#transitionTimeoutMs = opts.transitionTimeoutMs ?? DEFAULT_TRANSITION_TIMEOUT_MS;
+        this.#listener = opts.onProgress;
     }
     #http(endpoint) {
         let c = this.#clients.get(endpoint);
@@ -88,18 +99,71 @@ export class CellClient {
         }
         return c;
     }
-    /** One authorized request; refreshes the token once on stale_epoch / 401. */
+    /** True after close(): every request (and stream) of this client is aborted. */
+    get closed() {
+        return this.#closer.signal.aborted;
+    }
+    /**
+     * Aborts every in-flight and future request of this client, including exec output streams and PTY reads (commands
+     * keep running in the workspace: nothing is canceled there). Workspace.close() calls it.
+     */
+    close() {
+        if (!this.#closer.signal.aborted)
+            this.#closer.abort(new DOMException('The workspace handle was closed.', 'AbortError'));
+    }
+    /**
+     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions (contracts §20.4),
+     * bounded in total by `transitionTimeoutMs`: a call refused with `workspace_busy` is retried after `Retry-After`; one
+     * refused with `workspace_not_running` (or whose token cannot be minted because the workspace is not running) wakes
+     * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call.
+     * Refused calls were never executed, so retrying is safe. When the budget is spent the refusal surfaces.
+     */
     async request(method, path, init = {}) {
-        for (let attempt = 0;; attempt += 1) {
-            const token = await this.tokens.get();
+        const closer = this.#closer.signal;
+        if (closer.aborted)
+            throw closer.reason;
+        const { wake: wakeAllowed = true, ...reqInit } = init;
+        const signal = reqInit.signal ? AbortSignal.any([reqInit.signal, closer]) : closer;
+        const deadline = Date.now() + this.#transitionTimeoutMs;
+        const t0 = performance.now();
+        const listener = this.#listener;
+        const emit = listener
+            ? (e) => emitTo([listener], { action: 'tool', workspaceId: this.workspaceId, operationId: null, atMs: Math.round((performance.now() - t0) * 10) / 10, ...e })
+            : undefined;
+        const retry = (cause, delayMs, attempt) => emit?.({ type: 'retry', retry: { atMs: Math.round((performance.now() - t0) * 10) / 10, request: `${method} ${path}`, attempt, cause, delayMs } });
+        let refreshed = false;
+        let wakes = 0;
+        let attempts = 0;
+        for (;;) {
             try {
-                return await this.#http(token.cell_endpoint).raw(method, path, init, `Bearer ${token.token}`);
+                const token = await this.tokens.get(listener);
+                return await this.#http(token.cell_endpoint).raw(method, path, { ...reqInit, signal, ...(emit ? { onRetry: (r) => retry(r.cause, r.delayMs, (attempts += 1)) } : {}) }, `Bearer ${token.token}`);
             }
             catch (err) {
-                const refreshable = err instanceof ShardfluxApiError && (err.code === 'stale_epoch' || err.status === 401);
-                if (!refreshable || attempt > 0)
+                if (!(err instanceof ShardfluxApiError) || signal.aborted)
                     throw err;
-                this.tokens.invalidate();
+                if ((err.code === 'stale_epoch' || (err.status === 401 && err.source === 'cell')) && !refreshed) {
+                    refreshed = true;
+                    this.tokens.invalidate();
+                    retry(err.code === 'stale_epoch' ? 'stale_epoch (the workspace moved or resumed; new token)' : `${describeFailure(err)} (new token)`, 0, (attempts += 1));
+                    continue;
+                }
+                const left = deadline - Date.now();
+                if (err.code === 'workspace_busy' && left > 0) {
+                    emit?.({ type: 'phase', phase: 'busy', reason: err.reason ?? 'workspace_busy' });
+                    await this.#opts.sleep(Math.min(left, 5_000, Math.max(250, (err.retryAfterSeconds ?? 1) * 1000)));
+                    continue;
+                }
+                const notRunning = err.code === 'workspace_not_running' || (err.code === 'conflict' && err.reason === 'workspace_not_running');
+                if (notRunning && wakeAllowed && this.#wake && wakes < MAX_WAKES && left > 0) {
+                    wakes += 1;
+                    if ((await this.#wake(left, signal)) === false)
+                        throw err; // running per the API: nothing to wait for
+                    this.tokens.invalidate();
+                    refreshed = false;
+                    continue;
+                }
+                throw err;
             }
         }
     }
@@ -130,6 +194,8 @@ export class CellClient {
         /** Output events from byte offsets (NDJSON). `follow` keeps the stream open until `exit`. */
         output: async (sessionId, opts = {}) => {
             const res = await this.request('GET', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/output', { session_id: sessionId }), {
+                // Following never wakes: a workspace suspended under a running command stays suspended (explicit suspend).
+                wake: opts.follow === false,
                 query: { stdout_offset: opts.stdoutOffset ?? 0, stderr_offset: opts.stderrOffset ?? 0, follow: opts.follow ?? true },
                 accept: 'application/x-ndjson',
                 timeoutMs: opts.follow === false ? undefined : 0,
@@ -223,7 +289,7 @@ export class CellClient {
                 }
             }
             catch (e) {
-                if (opts.signal?.aborted)
+                if (opts.signal?.aborted || this.closed)
                     throw e;
                 const transient = !(e instanceof ShardfluxApiError) || e.retryable;
                 if (!transient || reconnects >= maxReconnects)
@@ -234,6 +300,8 @@ export class CellClient {
                 break;
             }
             // Stream ended without `exit` (gateway restart, idle proxy, network): resume from offsets.
+            if (this.closed)
+                throw this.#closer.signal.reason;
             reconnects += 1;
             if (reconnects > maxReconnects)
                 throw new ShardfluxProtocolError(`exec ${sessionId}: output stream kept dropping`, 0);
@@ -288,6 +356,7 @@ export class CellClient {
             let session = null;
             let exited = false;
             await new Promise((resolve, reject) => {
+                const onClose = () => finish(this.#closer.signal.reason instanceof Error ? this.#closer.signal.reason : new Error('closed'));
                 const ws = new WS(url, { headers: { authorization: `Bearer ${token}` } });
                 let quiet;
                 const total = setTimeout(() => finish(), opts.timeoutMs ?? 5_000);
@@ -295,6 +364,7 @@ export class CellClient {
                     clearTimeout(total);
                     if (quiet)
                         clearTimeout(quiet);
+                    this.#closer.signal.removeEventListener('abort', onClose);
                     try {
                         ws.close(1000);
                     }
@@ -333,6 +403,10 @@ export class CellClient {
                 });
                 ws.addEventListener('error', () => finish(new ShardfluxProtocolError('pty attach WebSocket failed', 0)));
                 ws.addEventListener('close', () => finish());
+                if (this.closed)
+                    onClose();
+                else
+                    this.#closer.signal.addEventListener('abort', onClose, { once: true });
             });
             return { output: sink.text(), nextOffset: next, session, exited };
         },
@@ -394,6 +468,22 @@ export class CellClient {
         mkdir: (path, opts = {}) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/files/mkdir'), { json: { path, ...(opts.parents !== undefined ? { parents: opts.parents } : {}), ...(opts.mode !== undefined ? { mode: opts.mode } : {}) } }),
         move: (from, to, opts = {}) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/files/move'), { json: { from, to, ...(opts.overwrite !== undefined ? { overwrite: opts.overwrite } : {}) } }),
     };
+    // ---- changes against the template (layered workspaces, contracts §19.10) ------------------
+    /** One page of the workspace's changes against its template (needs the `files` tool). */
+    changes(params = {}) {
+        return this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/changes'), {
+            query: { path_prefix: params.pathPrefix, limit: params.limit, cursor: params.cursor, hash: params.hash, summary: params.summary },
+        });
+    }
+    /** Every change under `pathPrefix`, following next_cursor. */
+    async *changesAll(params = {}) {
+        let cursor;
+        do {
+            const page = await this.changes({ ...params, ...(cursor === undefined ? {} : { cursor }) });
+            yield* page.data;
+            cursor = page.next_cursor ?? undefined;
+        } while (cursor !== undefined);
+    }
     // ---- git -------------------------------------------------------------------------------
     git = {
         clone: (req) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/git/clone'), { json: req, timeoutMs: (req.timeout_ms ?? 600_000) + 30_000 }),

package/dist/client.d.ts

@@ -16,10 +16,28 @@ import { AuditApi } from './audit.js';
 import { EgressPolicyApi } from './egress.js';
 import { SecretsApi } from './secrets.js';
 import { TemplatesApi } from './templates.js';
+import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.js';
 import { UsageApi } from './usage.js';
 import { VolumesApi } from './volumes.js';
+import type { FinishedOperation, InternalLifecycleOptions, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
+import type { ProgressListener } from './progress.js';
 export type WorkspaceView = components['schemas']['Workspace'];
 export type Operation = components['schemas']['Operation'];
+/** persistent (kept until deleted) or session (discarded when the session ends: close(), idle timeout; contracts §19.11). */
+export type WorkspaceLifetime = components['schemas']['WorkspaceLifetime'];
+/** legacy (one disk) or layered (the template chain read-only plus a workspace layer; contracts §19.2). */
+export type DiskLayout = components['schemas']['DiskLayout'];
+/** standard, template_draft (a template's dev-mode draft) or template_test (a test instance of a draft state). */
+export type WorkspacePurpose = components['schemas']['WorkspacePurpose'];
+/** Reserved (T2): always `pinned` in T1. */
+export type UpdatePolicy = components['schemas']['UpdatePolicy'];
+/** Where the workspace's disk came from: null, a fork, or a draft state (test instances). */
+export type WorkspaceOrigin = components['schemas']['WorkspaceOrigin'];
+export type ResetWorkspaceBody = components['schemas']['ResetWorkspaceBody'];
+/** List filter: a lifetime or `any` (the list default is `persistent`). */
+export type LifetimeFilter = WorkspaceLifetime | 'any';
+/** List filter: a purpose or `any` (the list default is `standard`). */
+export type PurposeFilter = WorkspacePurpose | 'any';
 type JsonOf<R> = R extends {
     content: {
         'application/json': infer T;
@@ -48,6 +66,7 @@ export interface ShardfluxOptions {
     apiKey: string;
     /** Default https://api.shardflux.dev (override with `baseUrl`). */
     baseUrl?: string;
+    /** Default: the runtime's fetch, with `Connection: close` on Node 26 (undici 8 keep-alive stalls; see defaultFetch in http.ts). */
     fetch?: typeof fetch;
     userAgent?: string;
     /** Per-request timeout (ms), default 30 s. */
@@ -56,19 +75,36 @@ export interface ShardfluxOptions {
     maxRetries?: number;
     /** Injected for tests; defaults to setTimeout. */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Progress of every traced call made through this client (open, lifecycle calls, waits, wakes, tool tokens, and
+     * retries and busy waits of tool calls): for logs or telemetry. Per-call `onProgress` listeners get their own events too.
+     */
+    onProgress?: ProgressListener;
 }
 export interface Caps {
     cpu_millis?: number;
     memory_mib?: number;
     disk_gib?: number;
 }
+export interface ForkTarget {
+    key: string;
+    caps?: Caps;
+    lifetime?: WorkspaceLifetime;
+}
 export interface WaitOptions {
     /** Give up waiting after this long (default 300 000 ms); the operation continues server side. */
     timeoutMs?: number;
-    /** First poll delay (default 250 ms); doubles up to `maxPollIntervalMs` with jitter. */
+    /** First poll delay (default 250 ms); doubles up to `maxPollIntervalMs` with jitter. Used when the server does not wait. */
     pollIntervalMs?: number;
     maxPollIntervalMs?: number;
+    /**
+     * Ask the server to hold each poll until the state changes (`Prefer: wait`, contracts §3; default true). A server
+     * that does not wait answers at once and the SDK falls back to the backoff above.
+     */
+    serverWait?: boolean;
     signal?: AbortSignal;
+    /** Progress while waiting: each observed state (queued, capacity_pending, running with its reason), retries, and `done` with the timing. */
+    onProgress?: ProgressListener;
 }
 export interface OpenParams {
     key: string;
@@ -80,10 +116,28 @@ export interface OpenParams {
     agentLabel?: string;
     /** Tools to request in tool tokens (subset of the key's permissions); default all permitted. */
     tools?: ToolName[];
+    /**
+     * Secret names to bind to the workspace (max 50): injected into every exec and PTY start. Sets the binding of a
+     * new key and replaces it on an existing key; omitted leaves it unchanged. An unknown or unusable name is
+     * ShardfluxApiError 422 (details.reason `secret_not_available`, details.names) and nothing is created or changed.
+     */
+    secrets?: string[];
+    /**
+     * `session`: the workspace is discarded when its session ends (workspace.close(), or the idle timeout); the key then
+     * opens a NEW workspace. Omitted: the template version's default, else `persistent`. Immutable: reopening a live key
+     * with another value is ShardfluxApiError 409 (details.reason `lifetime_mismatch`).
+     */
+    lifetime?: WorkspaceLifetime;
     /** `false`: return immediately (possibly not ready). Default: wait until ready. */
     wait?: false | WaitOptions;
     /** Defaults to a fresh key per open() call so transport retries replay instead of duplicating. */
     idempotencyKey?: string;
+    /**
+     * Progress of the open: the request, each operation state observed while waiting (with the server's reason), the
+     * view read and first tool token, and retries. The final `done` event carries the timing, also on
+     * `workspace.lastTiming` (and on the error's `timing` when the open fails).
+     */
+    onProgress?: ProgressListener;
 }
 export interface ListParams {
     state?: WorkspaceView['observed_state'];
@@ -92,9 +146,28 @@ export interface ListParams {
     projectId?: string;
     organizationId?: string;
     includeDeleted?: boolean;
+    /** Default (server side) `persistent`: sessions are hidden unless `session` or `any`. */
+    lifetime?: LifetimeFilter;
+    /** Default (server side) `standard`: drafts and test instances are hidden unless named or `any`. */
+    purpose?: PurposeFilter;
     limit?: number;
     cursor?: string;
 }
+export interface FindByKeyOptions {
+    /** Also consider tombstones (deleted workspaces and ended sessions) when no live workspace has the key (default true). */
+    includeDeleted?: boolean;
+    projectId?: string;
+    organizationId?: string;
+    agentLabel?: string;
+    tools?: ToolName[];
+    signal?: AbortSignal;
+}
+/**
+ * The workspace a key names (contracts §19.11): the live row (deleted_at null) when there is one, since at most one live
+ * workspace holds a key; otherwise the newest tombstone (ended sessions leave tombstones with the same key, and a
+ * deleted persistent key keeps its tombstone). Null when no row has exactly this key. Rows need not be sorted.
+ */
+export declare function pickByKey<T extends Pick<WorkspaceView, 'id' | 'workspace_key' | 'deleted_at'>>(rows: Iterable<T>, key: string): T | null;
 export interface Page<T> {
     data: T[];
     nextCursor: string | null;
@@ -107,6 +180,8 @@ export interface ClientContext {
     userAgent: string;
     sleep: (ms: number) => Promise<void>;
     workspaces: WorkspacesApi;
+    /** The client-level progress listener (ShardfluxOptions.onProgress). */
+    onProgress?: ProgressListener | undefined;
 }
 export declare class WorkspacesApi {
     #private;
@@ -115,12 +190,17 @@ export declare class WorkspacesApi {
      * Opens a workspace by key: creates it from the template's latest published version on first
      * use, reconnects (or resumes) afterwards; never resets an existing workspace. Waits until it is
      * ready unless `wait: false`; on timeout throws OperationTimeoutError carrying the operation id.
+     * The timing of the open (client phases, retries, the operation's server timing) is on `workspace.lastTiming`, on
+     * `onProgress` as it happens, and on the error's `timing` when the open fails.
      */
     open(params: OpenParams): Promise<Workspace>;
     /**
-     * Polls GET /v1/operations/{id} with bounded exponential backoff (+-20 % jitter) until it
-     * succeeds (resolves), fails or is canceled (OperationFailedError), or `timeoutMs` passes
-     * (OperationTimeoutError; the operation keeps running and can be awaited again).
+     * Waits for an operation: each GET /v1/operations/{id} asks the server to hold the response until the state changes
+     * (`Prefer: wait`, at most 20 s, contracts §3), so completion is seen within one notification of the commit. A server
+     * that does not wait is polled with bounded exponential backoff (+-20 % jitter). Resolves when the operation
+     * succeeds; throws OperationFailedError when it fails or is canceled, OperationTimeoutError after `timeoutMs` (the
+     * operation keeps running and can be awaited again). Both errors carry the wait's `timing`; `onProgress` sees each
+     * state change (queued, capacity_pending, running, with the server's reason) as it is observed.
      */
     waitForOperation(operationId: string, opts?: WaitOptions): Promise<Operation>;
     /** One operation (GET /v1/operations/{id}); lifecycle operations stay pollable after a workspace is deleted. */
@@ -134,26 +214,72 @@ export declare class WorkspacesApi {
     list(params?: ListParams): Promise<Page<Workspace>>;
     /** Iterates every page. */
     listAll(params?: Omit<ListParams, 'cursor'>): AsyncGenerator<Workspace>;
-    /** Tombstones the workspace now (tool access revoked); storage cleanup happens asynchronously. */
-    delete(workspaceId: string, opts?: {
-        idempotencyKey?: string;
-    }): Promise<Operation>;
-    suspend(workspaceId: string, opts?: {
-        idempotencyKey?: string;
-    }): Promise<Operation>;
-    resume(workspaceId: string, opts?: {
-        idempotencyKey?: string;
-    }): Promise<Operation>;
-    snapshot(workspaceId: string, opts?: {
+    /**
+     * Looks a workspace up by its exact key across every lifetime and purpose (`lifetime=any&purpose=any`), preferring the
+     * live workspace over tombstones of ended sessions or deleted workspaces with the same key (see pickByKey). Null when
+     * no workspace of the project has the key. This is the lookup the CLI and the MCP server use.
+     */
+    findByKey(key: string, opts?: FindByKeyOptions): Promise<Workspace | null>;
+    /**
+     * Deletes the workspace: tombstoned at once (tool access revoked), storage cleaned up by the operation. Resolves when
+     * the delete is requested; with `wait`, when it has finished.
+     */
+    delete(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    delete(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
+    /**
+     * Suspends the workspace (memory and processes checkpointed). Resolves when the suspend is REQUESTED: the returned
+     * operation is usually still `queued`. Pass `{ wait: true }` to resolve once it has FINISHED (`succeeded`).
+     */
+    suspend(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    suspend(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
+    /** Resumes a suspended workspace. Resolves when the resume is requested; with `wait`, once the workspace runs. */
+    resume(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    resume(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
+    /** Takes a snapshot. Resolves when it is requested; with `wait`, once it is taken. */
+    snapshot(workspaceId: string, opts: WaitedLifecycleOptions & {
+        label?: string;
+    }): Promise<FinishedOperation>;
+    snapshot(workspaceId: string, opts?: LifecycleOptions & {
         label?: string;
-        idempotencyKey?: string;
     }): Promise<Operation>;
-    fork(workspaceId: string, target: {
-        key: string;
-        caps?: Caps;
-    }, opts?: {
-        idempotencyKey?: string;
-    }): Promise<{
+    /**
+     * Ends a session workspace now (contracts §19.11): the workspace is deleted exactly like delete() (ended_reason
+     * closed) and returns the `delete` operation (input.reason session_closed); the key then opens a NEW workspace.
+     * Idempotent. A persistent workspace is ShardfluxApiError 409 (details.reason `not_session`): use
+     * `workspace.close()`, which calls this only for sessions. With `wait`, resolves once the delete has finished.
+     */
+    close(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    close(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
+    /** close() plus the workspace view after the close (a tombstone). */
+    closeWithView(workspaceId: string, opts?: InternalLifecycleOptions): Promise<{
+        operation: Operation;
+        workspace: WorkspaceView;
+    }>;
+    /**
+     * Resets a layered workspace to its template (contracts §19.12): every change in the workspace layer is wiped; key,
+     * id, template version, caps, secret bindings and volume attachments stay. Running: restarted on a blank layer
+     * (processes are gone; old tool tokens get 409 stale_epoch and the SDK refreshes them). Suspended: stays suspended and
+     * boots blank on the next resume. Returns the `reset` operation; its result names the recovery checkpoint (restorable
+     * for 7 days). Errors: 409 legacy_disk_layout, not_resettable, operation_in_progress.
+     */
+    reset(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    reset(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
+    /**
+     * Saves a layered workspace as the next version of an organization template (contracts §19.8). A running workspace is
+     * captured briefly (`operation`, layer_snapshot); poll `build` with templates.builds.waitForBuild. Owners/admins and
+     * API keys with a tool permission only.
+     */
+    saveAsTemplate(workspaceId: string, params: SaveAsTemplateParams): Promise<SaveAsTemplateResponse>;
+    /**
+     * Forks into a new key. `lifetime` is the fork's own (default persistent): forking a session is how it is kept.
+     * Resolves when the fork is requested (the copy's handle is returned at once); with `wait`, once the copy exists,
+     * with its handle refreshed.
+     */
+    fork(workspaceId: string, target: ForkTarget, opts: WaitedLifecycleOptions): Promise<{
+        operation: FinishedOperation;
+        workspace: Workspace;
+    }>;
+    fork(workspaceId: string, target: ForkTarget, opts?: LifecycleOptions): Promise<{
         operation: Operation;
         workspace: Workspace;
     }>;