@shardflux/sdk 0.11.0 → 0.12.0

package/dist/cell.d.ts

@@ -7,7 +7,7 @@
  * (token expired or revoked early) invalidates the token and retries once with
  * a fresh one; the retried request is safe because the gateway rejected the
  * first before any effect (and exec/PTY starts are idempotent by session_id).
- * The same holds for lifecycle refusals (contracts §20.4): `workspace_busy` is
+ * The same holds for lifecycle refusals: `workspace_busy` is
  * waited out and `workspace_not_running` wakes the workspace, then the call is
  * retried, all within one bounded transition budget per call.
  *
@@ -15,7 +15,7 @@
  * `exec.run()` survives gateway restarts/disconnects by reconnecting with the
  * offsets it already processed; it never starts the command a second time.
  *
- * File-first workspaces (contracts §29) serve the files routes from a
+ * File-first workspaces serve the files routes from a
  * versioned tree and run commands as executions (`executions.run()`); the
  * client tracks the tree revision every response reports (`X-Tree-Revision`)
  * and, when it knows the workspace's mode, refuses calls the mode does not
@@ -31,6 +31,7 @@ import type { ToolTokenManager } from './tokens.js';
 type S = components['schemas'];
 export type ExecStartRequest = S['ExecStartRequest'];
 export type ExecSession = S['ExecSession'];
+export type ExecInputResult = S['ExecInputResult'];
 export type OutputEvent = S['OutputEvent'];
 export type PtyOpenRequest = S['PtyOpenRequest'];
 export type PtySession = S['PtySession'];
@@ -39,20 +40,22 @@ export type ProcessList = S['ProcessList'];
 export type FileInfo = S['FileInfo'];
 export type FileList = S['FileList'];
 export type FileWriteResult = S['FileWriteResult'];
-/** Search request/result of `POST /files/search` (contracts §26.1). */
+/** Search request/result of `POST /files/search`. */
 export type FileSearchRequest = S['FileSearchRequest'];
 export type FileSearchMatch = S['FileSearchMatch'];
 export type FileSearchResult = S['FileSearchResult'];
-/** One text edit of `POST /files/patch` (contracts §26.2), as sent on the wire. */
+/** One text edit of `POST /files/patch`, as sent on the wire. */
 export type FileEdit = S['FileEdit'];
 export type FilePatchRequest = S['FilePatchRequest'];
 export type FilePatchResult = S['FilePatchResult'];
 /** A content SHA-256 (lowercase hex), or `absent` for a path that must not exist. */
 export type FileRevision = S['FileRevision'];
 export type WakeHintResult = S['WakeHintResult'];
-/** Where a running workspace's VM is (contracts §25.1): resident, frozen, hibernated or restoring. */
+export type IdleStatus = S['IdleStatus'];
+export type KeepaliveResult = S['KeepaliveResult'];
+/** Where a running workspace's VM is: resident, frozen, hibernated or restoring. */
 export type Residency = WakeHintResult['residency'];
-/** `X-Served-From`: `disk` when a read was served from a suspended or hibernated workspace's disk (contracts §26.4). */
+/** `X-Served-From`: `disk` when a read was served from a suspended or hibernated workspace's disk. */
 export type ServedFrom = 'guest' | 'disk';
 /** `files.readWithInfo()`: the bytes plus what the gateway reported about the file. */
 export interface FileReadResult {
@@ -122,7 +125,7 @@ export type BrowserScreenshotRequest = S['BrowserScreenshotRequest'];
 export type BrowserContentRequest = S['BrowserContentRequest'];
 export type BrowserContent = S['BrowserContent'];
 export type Signal = S['SignalValue'];
-/** One entry of a workspace's changes against its template (contracts §19.10). */
+/** One entry of a workspace's changes against its template. */
 export type WorkspaceChange = S['WorkspaceChange'];
 export type WorkspaceChangeKind = WorkspaceChange['change'];
 export type WorkspaceChangesSummary = S['WorkspaceChangesSummary'];
@@ -155,8 +158,8 @@ export interface CellClientOptions {
      * resolves `false` when there was nothing to wake (the API already reports it running), and the refusal then
      * surfaces. It throws when the wake fails (OperationFailedError) or outlasts `timeoutMs` (OperationTimeoutError).
      * Workspace.cell() supplies `workspace.wake()`. A call refused with `workspace_not_running` wakes the workspace and is
-     * retried; a refused call was never executed (contracts §20.4), so the retry cannot duplicate it. `null` surfaces
-     * the refusal instead. A wake that put a new token into this client's manager (the held resume, contracts §22.6;
+     * retried; a refused call was never executed, so the retry cannot duplicate it. `null` surfaces
+     * the refusal instead. A wake that put a new token into this client's manager (the held resume;
      * `workspace.wake({ agentLabel, tools })`) is retried with it; otherwise the token is replaced before the retry.
      */
     wake?: ((timeoutMs: number, signal?: AbortSignal) => Promise<boolean | void>) | null;
@@ -174,7 +177,7 @@ export interface CellClientOptions {
     /** Internal: see CAPTURE_BARRIER. */
     [CAPTURE_BARRIER]?: (() => Promise<unknown> | undefined) | undefined;
     /**
-     * The workspace's mode (contracts §29), or a function returning it (undefined: unknown). When known, calls the mode
+     * The workspace's mode, or a function returning it (undefined: unknown). When known, calls the mode
      * does not have fail at once with NotSupportedForModeError (`local` true) instead of a request: exec sessions, PTY,
      * processes, version control, browser and changes on a file-first workspace; executions and `ifTreeRevision` on a
      * processful one. Workspace.cell() supplies the workspace's.
@@ -183,7 +186,7 @@ export interface CellClientOptions {
     /** Called with every tree revision a response reports (`X-Tree-Revision`, execution results, mismatch refusals). */
     onTreeRevision?: (revision: number) => void;
 }
-/** `ifTreeRevision` (file-first workspaces, contracts §29.8): the tree revision a mutating files call applies to. */
+/** `ifTreeRevision` (file-first workspaces): the tree revision a mutating files call applies to. */
 export interface TreeRevisionOptions {
     /**
      * Sent as `If-Match`: the call applies only while the tree is at this revision (`workspace.treeRevision`, or a
@@ -197,7 +200,7 @@ export interface TreeRevisionOptions {
 interface TransitionOptions {
     /** Wake a suspended workspace for this call (default true; exec output follow reconnects pass false). */
     wake?: boolean;
-    /** Wait out `workspace_busy` (default true; the wake hint passes false: it is best effort). */
+    /** Wait out `workspace_busy` (default true; the wake hint passes false: it never waits). */
     busy?: boolean;
 }
 export declare const DEFAULT_TRANSITION_TIMEOUT_MS = 120000;
@@ -245,7 +248,7 @@ export interface RunOptions {
     /** Output reconnect attempts after a dropped stream (default 10). */
     maxReconnects?: number;
     /**
-     * Names of customer secrets (contracts §17) the cell injects as environment variables `NAME=value` of this
+     * Names of customer secrets the cell injects as environment variables `NAME=value` of this
      * process only (sent as `secret_refs`). Values are resolved at session start with this workspace's tool token and
      * never returned. A name the caller may not use refuses the whole start with 403 `forbidden`
      * (details.reason `secret_not_available`, details.names) and nothing runs; a name also present in `env` is 422.
@@ -274,7 +277,7 @@ export declare class CellClient {
      */
     close(): void;
     /**
-     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions (contracts §20.4),
+     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions,
      * 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.
@@ -296,6 +299,14 @@ export declare class CellClient {
             follow?: boolean;
             signal?: AbortSignal;
         }) => Promise<AsyncGenerator<OutputEvent>>;
+        /** Write at the acknowledged offset (initially 0); a repeated identical last frame cannot duplicate input.
+         * At most 64 KiB per call. A partial acknowledgement requires continuing from the returned offset.
+         * Start with stdin_open: true. close sends EOF after this frame is fully accepted. */
+        input: (sessionId: string, data: string | Uint8Array, opts: {
+            offset: number;
+            close?: boolean;
+            signal?: AbortSignal;
+        }) => Promise<ExecInputResult>;
         signal: (sessionId: string, signal: Signal, onlyLeader?: boolean) => Promise<ExecSession>;
         cancel: (sessionId: string, graceMs?: number) => Promise<ExecSession>;
         /**
@@ -314,9 +325,9 @@ export declare class CellClient {
          * the next revision (`treeRevision`, `changed`); processes, memory and files elsewhere do not survive it.
          *
          * The execution id (`executionId`, default a fresh `ex-<uuid>`) is the idempotency key: network failures and
-         * retryable 429/5xx answers (503 `no_execution_host`: no host has room, with Retry-After) are retried with the same
-         * id and request, at most `maxRetries` times, and an attempt that waits longer than `attemptTimeoutMs` re-attaches
-         * with the same id. The cell answers 201 for the call that ran the command and 200 (`replayed`) with the recorded
+         * retryable 429/5xx answers (503 `no_execution_host`: the execution cannot be placed right now, with Retry-After) are
+         * retried with the same id and request, at most `maxRetries` times, and an attempt that waits longer than
+         * `attemptTimeoutMs` re-attaches with the same id. The cell answers 201 for the call that ran the command and 200 (`replayed`) with the recorded
          * result otherwise, so the command runs at most once. `workspace_busy` (`execution_in_progress`: another execution
          * holds the workspace) is waited out within `transitionTimeoutMs`; `execution_id_reused` (the id with another
          * request) and validation errors are thrown at once. The SDK never retries with a new id: a result whose `state` is
@@ -376,7 +387,7 @@ export declare class CellClient {
         /**
          * Like `read()`, plus the file's size, `revision` (SHA-256 of the whole file, `X-File-Revision`, for regular files of
          * 16 MiB or less; pass it as `expectedRevision` to `patch()`) and `servedFrom` (`disk` when a sleeping workspace was
-         * read from its disk without waking it, contracts §26.4). 0.9.0+.
+         * read from its disk without waking it). 0.9.0+.
          */
         readWithInfo: (path: string, opts?: {
             offset?: number;
@@ -414,7 +425,7 @@ export declare class CellClient {
             overwrite?: boolean;
         } & TreeRevisionOptions) => Promise<FileInfo>;
         /**
-         * Searches file contents under `path`, a directory or one file (contracts §26.1; 0.9.0+): matching lines in path
+         * Searches file contents under `path`, a directory or one file (0.9.0+): matching lines in path
          * order, bounded by `maxMatches`, a 10 s budget and 4 MiB of results (`truncated`, `stop_reason` `max_matches`,
          * `budget` or `max_bytes`). Binary files, symbolic links, special files and files above `maxFileBytes` are
          * skipped. Read-only, so transient failures (e.g. 503 `host_capacity`) are retried; a suspended workspace whose
@@ -423,7 +434,7 @@ export declare class CellClient {
         search: (path: string, pattern: string, opts?: FileSearchOptions) => Promise<FileSearchResponse>;
         /**
          * Applies text `edits` (each `oldText` must occur exactly once unless `replaceAll`; in order) or replaces the whole
-         * file with `content`, atomically and durably (contracts §26.2; 0.9.0+). With `expectedRevision` the file must
+         * file with `content`, atomically and durably (0.9.0+). With `expectedRevision` the file must
          * still have that revision (`absent`: must not exist), else 409 `conflict` `revision_mismatch` with
          * `details.current_revision`. Edits that do not apply: 422 `validation_failed` `edit_not_found` / `edit_ambiguous`
          * (`details.index`), `edit_not_text`. Limits: a request of up to 7 MiB (else 413 `payload_too_large`; larger
@@ -437,11 +448,15 @@ export declare class CellClient {
         } & TreeRevisionOptions) => Promise<FilePatchResult>;
     };
     /**
-     * `POST /wake-hint` (contracts §26.6; 0.9.0+): announces an imminent tool call so a hibernated workspace is restored
+     * `POST /wake-hint` (0.9.0+): announces an imminent tool call so a hibernated workspace is restored
      * ahead of it. It never wakes a suspended workspace, never waits out `workspace_busy` and is not retried: a suspended
      * workspace answers 409 `workspace_not_running` (`Workspace.hint()` then wakes it in the background).
      */
     wakeHint(signal?: AbortSignal): Promise<WakeHintResult>;
+    /** Read idle signals without recording activity or waking the workspace. */
+    idle(signal?: AbortSignal): Promise<IdleStatus>;
+    /** Declare work for seconds (1..the server maximum). Never shortens a previous keepalive. */
+    keepalive(seconds: number, signal?: AbortSignal): Promise<KeepaliveResult>;
     /**
      * One page of the workspace's changes against its template (needs the `files` tool). File-first workspaces: each
      * execution's result lists what it changed (`changed`); this route is refused (NotSupportedForModeError).

package/dist/cell.js

@@ -89,7 +89,7 @@ async function parseJson(res, what) {
         return JSON.parse(text);
     }
     catch {
-        throw new ShardfluxProtocolError(`${what}: response is not JSON`, res.status);
+        throw new ShardfluxProtocolError(`${what}: response is not JSON`, res.status, 'cell');
     }
 }
 /** Delay before a retry of an execution: Retry-After (at most 30 s), else 0.5 s doubling to 8 s. */
@@ -200,7 +200,7 @@ export class CellClient {
             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),
+     * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions,
      * 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.
@@ -262,7 +262,7 @@ export class CellClient {
                     const before = this.tokens.current;
                     if ((await this.#wake(left, signal)) === false)
                         throw err; // running per the API: nothing to wait for
-                    // A held resume (contracts §22.6) handed this client a token of the woken workspace: use it. Otherwise the
+                    // A held resume handed this client a token of the woken workspace: use it. Otherwise the
                     // old token is of the previous epoch: fetch a new one.
                     if (this.tokens.current === before)
                         this.tokens.invalidate();
@@ -282,7 +282,7 @@ export class CellClient {
             return (text.length === 0 ? undefined : JSON.parse(text));
         }
         catch {
-            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status, 'cell');
         }
     }
     async #bytes(method, path, init = {}) {
@@ -329,9 +329,20 @@ export class CellClient {
                 ...(opts.signal ? { signal: opts.signal } : {}),
             });
             if (!res.body)
-                throw new ShardfluxProtocolError('exec output: empty body', res.status);
+                throw new ShardfluxProtocolError('exec output: empty body', res.status, 'cell');
             return ndjson(res.body);
         },
+        /** Write at the acknowledged offset (initially 0); a repeated identical last frame cannot duplicate input.
+         * At most 64 KiB per call. A partial acknowledgement requires continuing from the returned offset.
+         * Start with stdin_open: true. close sends EOF after this frame is fully accepted. */
+        input: (sessionId, data, opts) => {
+            const refusal = this.#noSessions('exec.input');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/stdin', { session_id: sessionId }), {
+                json: { data: b64(data), offset: opts.offset, close: opts.close ?? false }, ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+        },
         signal: (sessionId, signal, onlyLeader = false) => {
             const refusal = this.#noSessions('exec.signal');
             if (refusal)
@@ -404,9 +415,14 @@ export class CellClient {
         const maxReconnects = opts.maxReconnects ?? 10;
         for (;;) {
             let exited;
+            const streamAbort = new AbortController();
+            const signal = opts.signal ? AbortSignal.any([opts.signal, streamAbort.signal]) : streamAbort.signal;
+            let drainTimer;
             try {
-                const events = await this.exec.output(sessionId, { stdoutOffset: so, stderrOffset: se, follow: true, ...(opts.signal ? { signal: opts.signal } : {}) });
+                const events = await this.exec.output(sessionId, { stdoutOffset: so, stderrOffset: se, follow: true, signal });
                 for await (const ev of events) {
+                    if (exited)
+                        continue;
                     if (ev.type === 'output' && ev.data !== undefined) {
                         const bytes = unb64(ev.data);
                         const start = ev.offset ?? (ev.stream === 'stderr' ? se : so);
@@ -426,7 +442,9 @@ export class CellClient {
                     }
                     else if (ev.type === 'exit') {
                         exited = ev.session ?? (await this.exec.get(sessionId));
-                        break;
+                        // Consume the terminal HTTP framing so the connection can be reused.
+                        // A peer that never closes after exit must not hold the completed run forever.
+                        drainTimer = setTimeout(() => streamAbort.abort(), 250);
                     }
                     else if (ev.type === 'error' && ev.error) {
                         throw new ShardfluxApiError(502, ev.error, 'cell');
@@ -437,9 +455,12 @@ export class CellClient {
                 if (opts.signal?.aborted || this.closed)
                     throw e;
                 const transient = !(e instanceof ShardfluxApiError) || e.retryable;
-                if (!transient || reconnects >= maxReconnects)
+                if (!exited && (!transient || reconnects >= maxReconnects))
                     throw e;
             }
+            finally {
+                clearTimeout(drainTimer);
+            }
             if (exited) {
                 session = exited;
                 break;
@@ -449,7 +470,7 @@ export class CellClient {
                 throw this.#closer.signal.reason;
             reconnects += 1;
             if (reconnects > maxReconnects)
-                throw new ShardfluxProtocolError(`exec ${sessionId}: output stream kept dropping`, 0);
+                throw new ShardfluxProtocolError(`exec ${sessionId}: output stream kept dropping`, 0, 'cell');
             await this.#opts.sleep(Math.min(2_000, 100 * 2 ** reconnects));
             const now = await this.exec.get(sessionId);
             if (now.state !== 'starting' && now.state !== 'running' && so >= now.stdout_size && se >= now.stderr_size) {
@@ -475,7 +496,7 @@ export class CellClient {
             reconnects,
         };
     }
-    // ---- executions (file-first workspaces, contracts §29.8) -----------------------------
+    // ---- executions (file-first workspaces) -----------------------------
     executions = {
         /**
          * Runs argv (no shell; `['bash', '-lc', line]` for shell syntax) as an execution of this file-first workspace: a
@@ -483,9 +504,9 @@ export class CellClient {
          * the next revision (`treeRevision`, `changed`); processes, memory and files elsewhere do not survive it.
          *
          * The execution id (`executionId`, default a fresh `ex-<uuid>`) is the idempotency key: network failures and
-         * retryable 429/5xx answers (503 `no_execution_host`: no host has room, with Retry-After) are retried with the same
-         * id and request, at most `maxRetries` times, and an attempt that waits longer than `attemptTimeoutMs` re-attaches
-         * with the same id. The cell answers 201 for the call that ran the command and 200 (`replayed`) with the recorded
+         * retryable 429/5xx answers (503 `no_execution_host`: the execution cannot be placed right now, with Retry-After) are
+         * retried with the same id and request, at most `maxRetries` times, and an attempt that waits longer than
+         * `attemptTimeoutMs` re-attaches with the same id. The cell answers 201 for the call that ran the command and 200 (`replayed`) with the recorded
          * result otherwise, so the command runs at most once. `workspace_busy` (`execution_in_progress`: another execution
          * holds the workspace) is waited out within `transitionTimeoutMs`; `execution_id_reused` (the id with another
          * request) and validation errors are thrown at once. The SDK never retries with a new id: a result whose `state` is
@@ -708,7 +729,7 @@ export class CellClient {
                         finish(new ShardfluxApiError(502, m.error, 'cell'));
                     }
                 });
-                ws.addEventListener('error', () => finish(new ShardfluxProtocolError('pty attach WebSocket failed', 0)));
+                ws.addEventListener('error', () => finish(new ShardfluxProtocolError('pty attach WebSocket failed', 0, 'cell')));
                 ws.addEventListener('close', () => finish());
                 if (this.closed)
                     onClose();
@@ -744,7 +765,7 @@ export class CellClient {
         /**
          * Like `read()`, plus the file's size, `revision` (SHA-256 of the whole file, `X-File-Revision`, for regular files of
          * 16 MiB or less; pass it as `expectedRevision` to `patch()`) and `servedFrom` (`disk` when a sleeping workspace was
-         * read from its disk without waking it, contracts §26.4). 0.9.0+.
+         * read from its disk without waking it). 0.9.0+.
          */
         readWithInfo: async (path, opts = {}) => {
             const url = this.#p('/v1/workspaces/{workspace_id}/files');
@@ -805,7 +826,7 @@ export class CellClient {
             headers: this.#ifMatch('files.move', opts),
         }),
         /**
-         * Searches file contents under `path`, a directory or one file (contracts §26.1; 0.9.0+): matching lines in path
+         * Searches file contents under `path`, a directory or one file (0.9.0+): matching lines in path
          * order, bounded by `maxMatches`, a 10 s budget and 4 MiB of results (`truncated`, `stop_reason` `max_matches`,
          * `budget` or `max_bytes`). Binary files, symbolic links, special files and files above `maxFileBytes` are
          * skipped. Read-only, so transient failures (e.g. 503 `host_capacity`) are retried; a suspended workspace whose
@@ -833,7 +854,7 @@ export class CellClient {
         },
         /**
          * Applies text `edits` (each `oldText` must occur exactly once unless `replaceAll`; in order) or replaces the whole
-         * file with `content`, atomically and durably (contracts §26.2; 0.9.0+). With `expectedRevision` the file must
+         * file with `content`, atomically and durably (0.9.0+). With `expectedRevision` the file must
          * still have that revision (`absent`: must not exist), else 409 `conflict` `revision_mismatch` with
          * `details.current_revision`. Edits that do not apply: 422 `validation_failed` `edit_not_found` / `edit_ambiguous`
          * (`details.index`), `edit_not_text`. Limits: a request of up to 7 MiB (else 413 `payload_too_large`; larger
@@ -865,17 +886,25 @@ export class CellClient {
         },
     };
     /**
-     * `POST /wake-hint` (contracts §26.6; 0.9.0+): announces an imminent tool call so a hibernated workspace is restored
+     * `POST /wake-hint` (0.9.0+): announces an imminent tool call so a hibernated workspace is restored
      * ahead of it. It never wakes a suspended workspace, never waits out `workspace_busy` and is not retried: a suspended
      * workspace answers 409 `workspace_not_running` (`Workspace.hint()` then wakes it in the background).
      */
     wakeHint(signal) {
-        // Nothing of a file-first workspace sleeps: the cell would answer `resident` (contracts §29.8).
+        // Nothing of a file-first workspace sleeps: the cell would answer `resident`.
         if (this.mode === 'file_first')
             return Promise.resolve({ residency: 'resident' });
         return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/wake-hint'), { wake: false, busy: false, timeoutMs: 10_000, ...(signal ? { signal } : {}) });
     }
-    // ---- changes against the template (layered workspaces, contracts §19.10) ------------------
+    /** Read idle signals without recording activity or waking the workspace. */
+    idle(signal) {
+        return this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/idle'), { wake: false, ...(signal ? { signal } : {}) });
+    }
+    /** Declare work for seconds (1..the server maximum). Never shortens a previous keepalive. */
+    keepalive(seconds, signal) {
+        return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/keepalive'), { json: { seconds }, wake: false, ...(signal ? { signal } : {}) });
+    }
+    // ---- changes against the template (layered workspaces) ------------------
     /**
      * One page of the workspace's changes against its template (needs the `files` tool). File-first workspaces: each
      * execution's result lists what it changed (`changed`); this route is refused (NotSupportedForModeError).