@shardflux/sdk 0.8.0 → 0.10.0

package/dist/cell.d.ts

@@ -14,8 +14,17 @@
  * Exec output is retained in the guest and addressed by byte offsets, so
  * `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
+ * 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
+ * have before sending them (NotSupportedForModeError).
  */
 import type { components, paths } from './generated/cell-api.js';
+import type { WorkspaceMode } from './errors.js';
+import { ExecutionResult } from './executions.js';
+import type { ExecutionGetOptions, ExecutionRunOptions } from './executions.js';
 import type { RequestOptions } from './http.js';
 import type { ProgressListener } from './progress.js';
 import type { ToolTokenManager } from './tokens.js';
@@ -30,6 +39,81 @@ 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). */
+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. */
+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 Residency = WakeHintResult['residency'];
+/** `X-Served-From`: `disk` when a read was served from a suspended or hibernated workspace's disk (contracts §26.4). */
+export type ServedFrom = 'guest' | 'disk';
+/** `files.readWithInfo()`: the bytes plus what the gateway reported about the file. */
+export interface FileReadResult {
+    data: Uint8Array;
+    /** `X-File-Size`: the file's size when the read started (null when the gateway did not send it). */
+    size: number | null;
+    /**
+     * `X-File-Revision`: SHA-256 of the whole file (regular files of 16 MiB or less), usable as `expectedRevision` of
+     * `files.patch()`. Null when absent, and when a read continued over several requests saw different revisions (the
+     * file changed while it was read).
+     */
+    revision: string | null;
+    /** `X-Served-From`: `disk` for a read of a sleeping workspace's disk (the state at suspension); null when absent. */
+    servedFrom: ServedFrom | null;
+}
+export interface FileSearchOptions {
+    /** RE2 syntax when true; a literal substring otherwise (default false). */
+    regex?: boolean;
+    caseInsensitive?: boolean;
+    /**
+     * Globs (`*`, `**`, `?`, `[...]`), gitignore-style: without `/` a pattern matches a name at any depth (`*.py`); with
+     * `/` it matches the path relative to the searched directory (`src/**\/*.ts`; a leading `/` anchors it there, a
+     * trailing `/` matches directories only). A file must match one.
+     */
+    include?: string[];
+    /** Globs skipped, same syntax (e.g. `build/`; default `.git` and `node_modules` anywhere; `[]` searches everything). */
+    exclude?: string[];
+    /** 1-5000 (gateway default 200). */
+    maxMatches?: number;
+    /** Files above this size are skipped (gateway default 1 MiB, at most 64 MiB). */
+    maxFileBytes?: number;
+    /** Lines of context before and after each match, 0-5. */
+    contextLines?: number;
+    signal?: AbortSignal;
+}
+/** `files.search()`: the gateway's result plus `served_from` (`X-Served-From`; null when the gateway sent none). */
+export type FileSearchResponse = FileSearchResult & {
+    served_from: ServedFrom | null;
+};
+/** One edit of `files.patch()`: `oldText` must occur exactly once in the file, or any number of times with `replaceAll`. */
+export interface FilePatchEdit {
+    oldText: string;
+    newText: string;
+    replaceAll?: boolean;
+}
+interface FilePatchCommon {
+    path: string;
+    /** The file's current revision (`files.stat(path, { revision: true })`, a read, write or patch result), or `absent`. */
+    expectedRevision?: FileRevision;
+    createParents?: boolean;
+    /** Permission bits for a new file (an existing file keeps its mode and owner). */
+    mode?: string;
+}
+/** `files.patch()`: exactly one of `edits` (applied in order to UTF-8 text) or `content` (the whole new file). */
+export type FilePatchParams = (FilePatchCommon & {
+    edits: FilePatchEdit[];
+    content?: undefined;
+}) | (FilePatchCommon & {
+    content: string;
+    edits?: undefined;
+});
 export type GitCloneRequest = S['GitCloneRequest'];
 export type GitCommitRequest = S['GitCommitRequest'];
 export type GitResult = S['GitResult'];
@@ -72,7 +156,8 @@ export interface CellClientOptions {
      * 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.
+     * the refusal instead. A wake that put a new token into this client's manager (the held resume, contracts §22.6;
+     * `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;
     /**
@@ -88,11 +173,32 @@ export interface CellClientOptions {
     onProgress?: ProgressListener;
     /** 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
+     * 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.
+     */
+    mode?: WorkspaceMode | (() => WorkspaceMode | undefined);
+    /** 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. */
+export interface TreeRevisionOptions {
+    /**
+     * Sent as `If-Match`: the call applies only while the tree is at this revision (`workspace.treeRevision`, or a
+     * revision an earlier call or execution reported), else it fails with TreeRevisionMismatchError (409 `conflict`,
+     * `tree_revision_mismatch`, `currentTreeRevision`) and nothing changes. File-first only: a processful workspace would
+     * ignore it, so the SDK refuses it there (NotSupportedForModeError).
+     */
+    ifTreeRevision?: number;
 }
 /** Per-request transition handling (internal to CellClient). */
 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). */
+    busy?: boolean;
 }
 export declare const DEFAULT_TRANSITION_TIMEOUT_MS = 120000;
 /**
@@ -117,6 +223,10 @@ export interface RunResult {
 }
 export interface RunOptions {
     sessionId?: string;
+    /**
+     * Absolute working directory (default the workspace's, /home/user). The API refuses a relative path with 422
+     * `validation_failed`, details.reason `invalid_cwd`; one that is not a directory rejects with ExecStartError.
+     */
     cwd?: string;
     env?: Record<string, string>;
     user?: string;
@@ -149,6 +259,13 @@ export declare class CellClient {
     readonly workspaceId: string;
     readonly tokens: ToolTokenManager;
     constructor(workspaceId: string, tokens: ToolTokenManager, opts?: CellClientOptions);
+    /** The workspace's mode when known (CellClientOptions.mode), else undefined. */
+    get mode(): WorkspaceMode | undefined;
+    /**
+     * The newest tree revision this client has seen (file-first workspaces: `X-Tree-Revision` of any response, execution
+     * results, `tree_revision_mismatch` refusals); null before the first. `workspace.treeRevision` combines every client's.
+     */
+    get treeRevision(): number | null;
     /** True after close(): every request (and stream) of this client is aborted. */
     get closed(): boolean;
     /**
@@ -164,6 +281,10 @@ export declare class CellClient {
      * Refused calls were never executed, so retrying is safe. When the budget is spent the refusal surfaces.
      */
     request(method: string, path: string, init?: RequestOptions & TransitionOptions): Promise<Response>;
+    /**
+     * Exec sessions of a processful workspace. On a file-first workspace these are refused (409 not_supported_for_mode;
+     * locally when the mode is known): use `executions.run()`.
+     */
     readonly exec: {
         /** Starts argv (no shell). Idempotent by session_id: an existing session is returned, never re-run. */
         start: (req: ExecStartRequest, signal?: AbortSignal) => Promise<ExecSession>;
@@ -180,9 +301,37 @@ export declare class CellClient {
         /**
          * Starts (or re-attaches to) a session and collects its output until it exits, reconnecting
          * with offsets after dropped streams. Never issues a second start for the same session_id.
+         * A command that could not start (a cwd that is not a directory, a program not on PATH, an unknown user) rejects
+         * with ExecStartError (0.10.0+): nothing ran, so there is no exit code to return.
+         * A file-first workspace has no sessions: use `executions.run()` (refused locally when the mode is known).
          */
         run: (argv: string[], opts?: RunOptions) => Promise<RunResult>;
     };
+    readonly executions: {
+        /**
+         * Runs argv (no shell; `['bash', '-lc', line]` for shell syntax) as an execution of this file-first workspace: a
+         * fresh VM on the latest tree revision, answered when the command ended. The files it changed under /home/user are
+         * 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
+         * 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
+         * `failed` or `lost` (nothing published; `error.details.reason` says why) is returned, and running it again is the
+         * caller's decision. Processful workspaces: NotSupportedForModeError (locally when the mode is known).
+         */
+        run: (argv: string[], opts?: ExecutionRunOptions) => Promise<ExecutionResult>;
+        /**
+         * The execution `executionId` of this file-first workspace (`GET /executions/{id}`): its result once it ended, or a
+         * pending result (`pending`, state `queued`/`running`, no output yet) while it runs; with `waitMs`, polls until it
+         * ended or the wait elapsed. Results are kept 7 days; an unknown id is 404 `not_found`. `replayed` is true.
+         */
+        get: (executionId: string, opts?: ExecutionGetOptions) => Promise<ExecutionResult>;
+    };
+    /** PTY sessions of a processful workspace (file-first: NotSupportedForModeError). */
     readonly pty: {
         open: (req?: PtyOpenRequest) => Promise<PtySession>;
         get: (sessionId: string) => Promise<PtySession>;
@@ -224,33 +373,79 @@ export declare class CellClient {
             offset?: number;
             length?: number;
         }) => Promise<Uint8Array>;
+        /**
+         * 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+.
+         */
+        readWithInfo: (path: string, opts?: {
+            offset?: number;
+            length?: number;
+        }) => Promise<FileReadResult>;
         readText: (path: string, opts?: {
             offset?: number;
             length?: number;
         }) => Promise<string>;
-        /** Atomic replace (or append), acknowledged after fsync of file and parent directory. */
+        /**
+         * Atomic replace (or append), acknowledged after fsync of file and parent directory (file-first: once the new tree
+         * revision is published). `ifTreeRevision` (file-first) applies it only at that tree revision.
+         */
         write: (path: string, data: string | Uint8Array, opts?: {
             mode?: string;
             createParents?: boolean;
             append?: boolean;
             idempotencyKey?: string;
-        }) => Promise<FileWriteResult>;
+        } & TreeRevisionOptions) => Promise<FileWriteResult>;
         remove: (path: string, opts?: {
             recursive?: boolean;
-        }) => Promise<void>;
-        stat: (path: string) => Promise<FileInfo>;
+        } & TreeRevisionOptions) => Promise<void>;
+        /** `revision: true` (0.9.0+) adds `revision`, the SHA-256 of a regular file's content (files of up to 256 MiB). */
+        stat: (path: string, opts?: {
+            revision?: boolean;
+        }) => Promise<FileInfo>;
         list: (path: string, opts?: {
             limit?: number;
         }) => Promise<FileList>;
         mkdir: (path: string, opts?: {
             parents?: boolean;
             mode?: string;
-        }) => Promise<FileInfo>;
+        } & TreeRevisionOptions) => Promise<FileInfo>;
         move: (from: string, to: string, opts?: {
             overwrite?: boolean;
-        }) => Promise<FileInfo>;
+        } & TreeRevisionOptions) => Promise<FileInfo>;
+        /**
+         * Searches file contents under `path`, a directory or one file (contracts §26.1; 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
+         * disk a host still holds is searched there without waking it (`served_from: 'disk'`).
+         */
+        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
+         * 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
+         * content goes through `write()`), files of up to 64 MiB, no symlink targets. Always sends an Idempotency-Key, so
+         * a retried call is applied once (a replay returns the recorded result, refusals included). `ifTreeRevision`
+         * (file-first) applies it only at that tree revision.
+         */
+        patch: (params: FilePatchParams, opts?: {
+            idempotencyKey?: string;
+            signal?: AbortSignal;
+        } & TreeRevisionOptions) => Promise<FilePatchResult>;
     };
-    /** One page of the workspace's changes against its template (needs the `files` tool). */
+    /**
+     * `POST /wake-hint` (contracts §26.6; 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>;
+    /**
+     * 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).
+     */
     changes(params?: WorkspaceChangesParams): Promise<WorkspaceChangesPage>;
     /** Every change under `pathPrefix`, following next_cursor. */
     changesAll(params?: Omit<WorkspaceChangesParams, 'cursor' | 'summary'>): AsyncGenerator<WorkspaceChange>;