@shardflux/sdk 0.8.0 → 0.10.0

package/dist/cell.js

@@ -1,5 +1,6 @@
-import { ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
-import { HttpClient, defaultSleep, randomId } from "./http.js";
+import { ExecStartError, NotSupportedForModeError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
+import { HttpClient, defaultSleep, randomId, treeRevisionOf } 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) {
@@ -73,6 +74,40 @@ class ByteSink {
         return new TextDecoder().decode(Buffer.concat(this.#chunks));
     }
 }
+const REVISION = /^[0-9a-f]{64}$/;
+const revisionOf = (h) => {
+    const v = h.get('x-file-revision');
+    return v !== null && REVISION.test(v) ? v : null;
+};
+const servedFromOf = (h) => {
+    const v = h.get('x-served-from');
+    return v === 'disk' || v === 'guest' ? v : null;
+};
+async function parseJson(res, what) {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ShardfluxProtocolError(`${what}: response is not JSON`, res.status);
+    }
+}
+/** Delay before a retry of an execution: Retry-After (at most 30 s), else 0.5 s doubling to 8 s. */
+const executionRetryDelayMs = (failures, retryAfterSeconds) => retryAfterSeconds !== undefined ? Math.min(30_000, retryAfterSeconds * 1000) : Math.min(8_000, 500 * 2 ** (failures - 1));
+/** An attempt of `executions.run()` whose own wait ran out (AbortSignal.timeout), not the caller's signal. */
+const attemptTimedOut = (err) => err instanceof Error && err.name === 'TimeoutError';
+/** A transport failure or a retryable 429/5xx: the execution request may be sent again with the same id. */
+function transientExecutionFailure(err) {
+    if (err instanceof ShardfluxApiError) {
+        const status = err.status === 429 || err.status === 502 || err.status === 503 || err.status === 504;
+        return status && err.retryable ? { retryAfterSeconds: err.retryAfterSeconds } : null;
+    }
+    // A proxy's error page (no error body): the gateway may never have seen the request.
+    if (err instanceof ShardfluxProtocolError)
+        return err.status === 502 || err.status === 503 || err.status === 504 ? { retryAfterSeconds: undefined } : null;
+    // fetch rejects with TypeError (connection refused/reset, DNS) or a DOMException; anything else is a bug: surface it.
+    return err instanceof TypeError || (err instanceof Error && err.name === 'NetworkError') ? { retryAfterSeconds: undefined } : null;
+}
 export class CellClient {
     workspaceId;
     tokens;
@@ -83,6 +118,9 @@ export class CellClient {
     #transitionTimeoutMs;
     #clients = new Map();
     #closer = new AbortController();
+    #mode;
+    #onTreeRevision;
+    #treeRevision = null;
     constructor(workspaceId, tokens, opts = {}) {
         this.workspaceId = workspaceId;
         this.tokens = tokens;
@@ -97,6 +135,49 @@ export class CellClient {
         this.#transitionTimeoutMs = opts.transitionTimeoutMs ?? DEFAULT_TRANSITION_TIMEOUT_MS;
         this.#listener = opts.onProgress;
         this.#barrier = opts[CAPTURE_BARRIER];
+        this.#mode = opts.mode;
+        this.#onTreeRevision = opts.onTreeRevision;
+    }
+    /** The workspace's mode when known (CellClientOptions.mode), else undefined. */
+    get mode() {
+        return typeof this.#mode === 'function' ? this.#mode() : this.#mode;
+    }
+    /**
+     * 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() {
+        return this.#treeRevision;
+    }
+    #noteTreeRevision(rev) {
+        if (rev === null || rev === undefined || !Number.isSafeInteger(rev) || rev < 0)
+            return;
+        if (this.#treeRevision === null || rev > this.#treeRevision)
+            this.#treeRevision = rev;
+        this.#onTreeRevision?.(rev);
+    }
+    /** A call processful workspaces have: refused locally on a known file-first workspace. */
+    #processfulOnly(operation, instead) {
+        if (this.mode !== 'file_first')
+            return null;
+        return NotSupportedForModeError.local('file_first', operation, 'cell', `${operation} is not available for a file-first workspace: it has no VM between executions. ${instead}`);
+    }
+    /** A call only file-first workspaces have: refused locally on a known processful workspace. */
+    #fileFirstOnly(operation) {
+        if (this.mode !== 'processful')
+            return null;
+        return NotSupportedForModeError.local('processful', operation, 'cell', `${operation} is only available for file-first workspaces (open with mode 'file_first'); this workspace is processful.`);
+    }
+    /** `If-Match` for `ifTreeRevision`, or the local refusal on a processful workspace. */
+    #ifMatch(operation, opts) {
+        if (opts.ifTreeRevision === undefined)
+            return {};
+        if (!Number.isSafeInteger(opts.ifTreeRevision) || opts.ifTreeRevision < 0)
+            throw new TypeError('ifTreeRevision must be a non-negative integer');
+        const refusal = this.#fileFirstOnly(`${operation} with ifTreeRevision`);
+        if (refusal)
+            throw refusal;
+        return { 'if-match': String(opts.ifTreeRevision) };
     }
     #http(endpoint) {
         let c = this.#clients.get(endpoint);
@@ -135,7 +216,7 @@ export class CellClient {
             await barrier;
         if (closer.aborted)
             throw closer.reason;
-        const { wake: wakeAllowed = true, ...reqInit } = init;
+        const { wake: wakeAllowed = true, busy: busyAllowed = true, ...reqInit } = init;
         const signal = reqInit.signal ? AbortSignal.any([reqInit.signal, closer]) : closer;
         const deadline = Date.now() + this.#transitionTimeoutMs;
         const t0 = performance.now();
@@ -150,9 +231,17 @@ export class CellClient {
         for (;;) {
             try {
                 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}`);
+                const res = await this.#http(token.cell_endpoint).raw(method, path, { ...reqInit, signal, ...(emit ? { onRetry: (r) => retry(r.cause, r.delayMs, (attempts += 1)) } : {}) }, `Bearer ${token.token}`);
+                this.#noteTreeRevision(treeRevisionOf(res.headers));
+                return res;
             }
             catch (err) {
+                if (err instanceof ShardfluxApiError) {
+                    this.#noteTreeRevision(err.treeRevision);
+                    const cur = err.details?.current_tree_revision;
+                    if (err.reason === 'tree_revision_mismatch' && typeof cur === 'number')
+                        this.#noteTreeRevision(cur);
+                }
                 if (!(err instanceof ShardfluxApiError) || signal.aborted)
                     throw err;
                 if ((err.code === 'stale_epoch' || (err.status === 401 && err.source === 'cell')) && !refreshed) {
@@ -162,7 +251,7 @@ export class CellClient {
                     continue;
                 }
                 const left = deadline - Date.now();
-                if (err.code === 'workspace_busy' && left > 0) {
+                if (err.code === 'workspace_busy' && busyAllowed && 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;
@@ -170,9 +259,13 @@ export class CellClient {
                 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;
+                    const before = this.tokens.current;
                     if ((await this.#wake(left, signal)) === false)
                         throw err; // running per the API: nothing to wait for
-                    this.tokens.invalidate();
+                    // A held resume (contracts §22.6) 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();
                     refreshed = false;
                     continue;
                 }
@@ -199,13 +292,34 @@ export class CellClient {
     #p(template, extra = {}) {
         return cellPath(template, { workspace_id: this.workspaceId, ...extra });
     }
+    /** The local refusal of an exec-session call on a file-first workspace (they run executions instead). */
+    #noSessions(operation) {
+        return this.#processfulOnly(operation, 'Run commands with executions.run(argv) (workspace.executions.run): each runs in a fresh VM on the latest tree and returns its output and the files it changed.');
+    }
     // ---- exec --------------------------------------------------------------------------
+    /**
+     * 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()`.
+     */
     exec = {
         /** Starts argv (no shell). Idempotent by session_id: an existing session is returned, never re-run. */
-        start: (req, signal) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec'), { json: { session_id: randomId('x').replace(/-/g, '').slice(0, 32), ...req }, ...(signal ? { signal } : {}) }),
-        get: (sessionId) => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}', { session_id: sessionId })),
+        start: (req, signal) => {
+            const refusal = this.#noSessions('exec.start');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec'), { json: { session_id: randomId('x').replace(/-/g, '').slice(0, 32), ...req }, ...(signal ? { signal } : {}) });
+        },
+        get: (sessionId) => {
+            const refusal = this.#noSessions('exec.get');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}', { session_id: sessionId }));
+        },
         /** Output events from byte offsets (NDJSON). `follow` keeps the stream open until `exit`. */
         output: async (sessionId, opts = {}) => {
+            const refusal = this.#noSessions('exec.output');
+            if (refusal)
+                throw refusal;
             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,
@@ -218,13 +332,29 @@ export class CellClient {
                 throw new ShardfluxProtocolError('exec output: empty body', res.status);
             return ndjson(res.body);
         },
-        signal: (sessionId, signal, onlyLeader = false) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/signal', { session_id: sessionId }), { json: { signal, only_leader: onlyLeader } }),
-        cancel: (sessionId, graceMs) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/cancel', { session_id: sessionId }), { json: graceMs === undefined ? {} : { grace_ms: graceMs } }),
+        signal: (sessionId, signal, onlyLeader = false) => {
+            const refusal = this.#noSessions('exec.signal');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/signal', { session_id: sessionId }), { json: { signal, only_leader: onlyLeader } });
+        },
+        cancel: (sessionId, graceMs) => {
+            const refusal = this.#noSessions('exec.cancel');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/exec/{session_id}/cancel', { session_id: sessionId }), { json: graceMs === undefined ? {} : { grace_ms: graceMs } });
+        },
         /**
          * 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: async (argv, opts = {}) => {
+            const refusal = this.#noSessions('exec.run');
+            if (refusal)
+                throw refusal;
             const sessionId = opts.sessionId ?? `run-${randomId().replace(/-/g, '').slice(0, 24)}`;
             const req = { session_id: sessionId, argv };
             if (opts.cwd !== undefined)
@@ -241,7 +371,9 @@ export class CellClient {
                 req.kill_grace_ms = opts.killGraceMs;
             if (opts.secretRefs !== undefined)
                 req.secret_refs = opts.secretRefs;
-            await this.exec.start(req, opts.signal);
+            const started = await this.exec.start(req, opts.signal);
+            if (started.state === 'failed_to_start')
+                throw new ExecStartError(started);
             try {
                 return await this.#collect(sessionId, opts);
             }
@@ -325,6 +457,9 @@ export class CellClient {
                 break;
             }
         }
+        // A start answered while the session was still starting can end without starting the command.
+        if (session.state === 'failed_to_start')
+            throw new ExecStartError(session);
         return {
             sessionId,
             exitCode: session.exit_code ?? null,
@@ -340,15 +475,174 @@ export class CellClient {
             reconnects,
         };
     }
+    // ---- executions (file-first workspaces, contracts §29.8) -----------------------------
+    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: async (argv, opts = {}) => {
+            const refusal = this.#fileFirstOnly('executions.run');
+            if (refusal)
+                throw refusal;
+            if (!Array.isArray(argv) || argv.length === 0)
+                throw new TypeError('argv must be a non-empty array of strings');
+            const executionId = opts.executionId ?? newExecutionId();
+            if (!EXECUTION_ID.test(executionId))
+                throw new TypeError(`executionId must match ${EXECUTION_ID.source}`);
+            const body = { argv, execution_id: executionId };
+            if (opts.cwd !== undefined)
+                body.cwd = opts.cwd;
+            if (opts.env !== undefined)
+                body.env = opts.env;
+            if (opts.user !== undefined)
+                body.user = opts.user;
+            if (opts.stdin !== undefined)
+                body.stdin = b64(opts.stdin);
+            if (opts.timeoutMs !== undefined)
+                body.timeout_ms = opts.timeoutMs;
+            if (opts.killGraceMs !== undefined)
+                body.kill_grace_ms = opts.killGraceMs;
+            if (opts.secretRefs !== undefined)
+                body.secret_refs = opts.secretRefs;
+            if (opts.outputLimitBytes !== undefined)
+                body.output_limit_bytes = opts.outputLimitBytes;
+            const path = this.#p('/v1/workspaces/{workspace_id}/exec');
+            const maxRetries = opts.maxRetries ?? 5;
+            const attemptTimeoutMs = opts.attemptTimeoutMs ?? 300_000;
+            const t0 = performance.now();
+            let failures = 0;
+            let attempt = 0;
+            for (;;) {
+                if (opts.signal?.aborted)
+                    throw opts.signal.reason;
+                attempt += 1;
+                let res;
+                try {
+                    // The same body every time: a different request with this id would be 409 execution_id_reused.
+                    res = await this.request('POST', path, { json: body, timeoutMs: attemptTimeoutMs, ...(opts.signal ? { signal: opts.signal } : {}) });
+                }
+                catch (err) {
+                    if (opts.signal?.aborted || this.closed)
+                        throw err;
+                    if (attemptTimedOut(err)) {
+                        this.#emitRetry(t0, `POST ${path}`, attempt, `no answer within ${attemptTimeoutMs} ms; re-attaching to execution ${executionId}`, 0);
+                        continue;
+                    }
+                    const transient = transientExecutionFailure(err);
+                    if (!transient || failures >= maxRetries)
+                        throw err;
+                    failures += 1;
+                    const delayMs = executionRetryDelayMs(failures, transient.retryAfterSeconds);
+                    this.#emitRetry(t0, `POST ${path}`, attempt, `${describeFailure(err)} (same execution id ${executionId})`, delayMs);
+                    await this.#opts.sleep(delayMs);
+                    continue;
+                }
+                const result = new ExecutionResult(await parseJson(res, `POST ${path}`), res.status !== 201);
+                this.#noteTreeRevision(result.treeRevision);
+                // The cell answers when the command ended; should it ever answer earlier, follow the execution to its end.
+                return result.pending ? this.#followExecution(executionId, opts.signal) : result;
+            }
+        },
+        /**
+         * 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: async (executionId, opts = {}) => {
+            const refusal = this.#fileFirstOnly('executions.get');
+            if (refusal)
+                throw refusal;
+            if (!EXECUTION_ID.test(executionId))
+                throw new TypeError(`executionId must match ${EXECUTION_ID.source}`);
+            const path = this.#p('/v1/workspaces/{workspace_id}/executions/{execution_id}', { execution_id: executionId });
+            const deadline = Date.now() + Math.max(0, opts.waitMs ?? 0);
+            let budget = Math.max(0, opts.waitMs ?? 0);
+            let delay = 250;
+            for (;;) {
+                const res = await this.request('GET', path, opts.signal ? { signal: opts.signal } : {});
+                const result = new ExecutionResult(await parseJson(res, `GET ${path}`), true);
+                this.#noteTreeRevision(result.treeRevision);
+                const left = Math.min(budget, deadline - Date.now());
+                if (!result.pending || left <= 0)
+                    return result;
+                const d = Math.min(delay, left);
+                await this.#opts.sleep(d);
+                budget -= d;
+                delay = Math.min(2_000, delay * 2);
+                if (opts.signal?.aborted)
+                    throw opts.signal.reason;
+            }
+        },
+    };
+    /** Polls an execution until it ended (only when the cell answered a run before the command ended). */
+    async #followExecution(executionId, signal) {
+        for (;;) {
+            const r = await this.executions.get(executionId, { waitMs: 60_000, ...(signal ? { signal } : {}) });
+            if (!r.pending)
+                return r;
+        }
+    }
+    #emitRetry(t0, request, attempt, cause, delayMs) {
+        const listener = this.#listener;
+        if (!listener)
+            return;
+        const atMs = Math.round((performance.now() - t0) * 10) / 10;
+        emitTo([listener], { action: 'tool', workspaceId: this.workspaceId, operationId: null, atMs, type: 'retry', retry: { atMs, request, attempt, cause, delayMs } });
+    }
+    /** The local refusal of a call that needs the workspace's VM (PTY, processes, version control, browser, changes). */
+    #needsVm(operation) {
+        return this.#processfulOnly(operation, 'Processes, terminals and sessions live within one execution only: run the command with executions.run().');
+    }
     // ---- PTY ---------------------------------------------------------------------------
+    /** PTY sessions of a processful workspace (file-first: NotSupportedForModeError). */
     pty = {
-        open: (req = {}) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/pty'), { json: { session_id: `pty-${randomId().replace(/-/g, '').slice(0, 24)}`, ...req } }),
-        get: (sessionId) => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}', { session_id: sessionId })),
-        close: (sessionId) => this.#json('DELETE', this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}', { session_id: sessionId })),
-        resize: (sessionId, rows, cols) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}/resize', { session_id: sessionId }), { json: { rows, cols } }),
-        input: (sessionId, data) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}/input', { session_id: sessionId }), { json: { data: b64(data) } }),
+        open: (req = {}) => {
+            const refusal = this.#needsVm('pty.open');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/pty'), { json: { session_id: `pty-${randomId().replace(/-/g, '').slice(0, 24)}`, ...req } });
+        },
+        get: (sessionId) => {
+            const refusal = this.#needsVm('pty.get');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}', { session_id: sessionId }));
+        },
+        close: (sessionId) => {
+            const refusal = this.#needsVm('pty.close');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('DELETE', this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}', { session_id: sessionId }));
+        },
+        resize: (sessionId, rows, cols) => {
+            const refusal = this.#needsVm('pty.resize');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}/resize', { session_id: sessionId }), { json: { rows, cols } });
+        },
+        input: (sessionId, data) => {
+            const refusal = this.#needsVm('pty.input');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}/input', { session_id: sessionId }), { json: { data: b64(data) } });
+        },
         /** wss:// URL of the attach WebSocket (send the tool token as `Authorization: Bearer`). */
         attachUrl: async (sessionId, offset = 0) => {
+            const refusal = this.#needsVm('pty.attach');
+            if (refusal)
+                throw refusal;
             const token = await this.tokens.get();
             const u = new URL(token.cell_endpoint + this.#p('/v1/workspaces/{workspace_id}/pty/{session_id}/attach', { session_id: sessionId }));
             u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
@@ -426,8 +720,16 @@ export class CellClient {
     };
     // ---- processes -----------------------------------------------------------------------
     processes = {
-        list: () => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/processes')),
+        list: () => {
+            const refusal = this.#needsVm('process.list');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/processes'));
+        },
         signal: async (pid, signal) => {
+            const refusal = this.#needsVm('process.signal');
+            if (refusal)
+                throw refusal;
             await this.request('POST', this.#p('/v1/workspaces/{workspace_id}/processes/{pid}/signal', { pid }), { json: { signal } });
         },
     };
@@ -438,20 +740,31 @@ export class CellClient {
          * (FILE_MAX_READ_BYTES) and reports the size at read start in `X-File-Size`, so shorter reads
          * are continued from the next offset until that size (a file that shrinks ends the loop early).
          */
-        read: async (path, opts = {}) => {
+        read: async (path, opts = {}) => (await this.files.readWithInfo(path, opts)).data,
+        /**
+         * 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: async (path, opts = {}) => {
             const url = this.#p('/v1/workspaces/{workspace_id}/files');
             const first = await this.request('GET', url, { query: { path, offset: opts.offset, length: opts.length }, accept: 'application/octet-stream' });
             const head = new Uint8Array(await first.arrayBuffer());
             const sizeHeader = first.headers.get('x-file-size');
             const size = sizeHeader !== null && /^\d+$/.test(sizeHeader) ? Number(sizeHeader) : null;
+            const servedFrom = servedFromOf(first.headers);
+            let revision = revisionOf(first.headers);
             const start = opts.offset ?? 0;
             if (opts.length !== undefined || size === null || start + head.byteLength >= size || head.byteLength === 0)
-                return head;
+                return { data: head, size, revision, servedFrom };
             const parts = [head];
             let offset = start + head.byteLength;
             while (offset < size) {
                 const res = await this.request('GET', url, { query: { path, offset }, accept: 'application/octet-stream' });
                 const chunk = new Uint8Array(await res.arrayBuffer());
+                // The revision describes the bytes returned only when every part was read from that same content.
+                if (revisionOf(res.headers) !== revision)
+                    revision = null;
                 if (chunk.byteLength === 0)
                     break;
                 parts.push(chunk);
@@ -463,27 +776,114 @@ export class CellClient {
                 out.set(p, at);
                 at += p.byteLength;
             }
-            return out;
+            return { data: out, size, revision, servedFrom };
         },
         readText: async (path, opts = {}) => new TextDecoder().decode(await this.files.read(path, opts)),
-        /** Atomic replace (or append), acknowledged after fsync of file and parent directory. */
-        write: (path, data, opts = {}) => this.#json('PUT', this.#p('/v1/workspaces/{workspace_id}/files'), {
+        /**
+         * 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: async (path, data, opts = {}) => this.#json('PUT', this.#p('/v1/workspaces/{workspace_id}/files'), {
             query: { path, mode: opts.mode, create_parents: opts.createParents, append: opts.append },
             body: typeof data === 'string' ? new TextEncoder().encode(data) : data,
             contentType: 'application/octet-stream',
             idempotencyKey: opts.idempotencyKey ?? randomId('w-').slice(0, 40),
+            headers: this.#ifMatch('files.write', opts),
         }),
         remove: async (path, opts = {}) => {
-            await this.request('DELETE', this.#p('/v1/workspaces/{workspace_id}/files'), { query: { path, recursive: opts.recursive } });
+            await this.request('DELETE', this.#p('/v1/workspaces/{workspace_id}/files'), { query: { path, recursive: opts.recursive }, headers: this.#ifMatch('files.remove', opts) });
         },
-        stat: (path) => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/files/stat'), { query: { path } }),
+        /** `revision: true` (0.9.0+) adds `revision`, the SHA-256 of a regular file's content (files of up to 256 MiB). */
+        stat: (path, opts = {}) => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/files/stat'), { query: { path, revision: opts.revision } }),
         list: (path, opts = {}) => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/files/list'), { query: { path, limit: opts.limit } }),
-        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 } : {}) } }),
+        mkdir: async (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 } : {}) },
+            headers: this.#ifMatch('files.mkdir', opts),
+        }),
+        move: async (from, to, opts = {}) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/files/move'), {
+            json: { from, to, ...(opts.overwrite !== undefined ? { overwrite: opts.overwrite } : {}) },
+            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
+         * 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: async (path, pattern, opts = {}) => {
+            const body = { path, pattern };
+            if (opts.regex !== undefined)
+                body.regex = opts.regex;
+            if (opts.caseInsensitive !== undefined)
+                body.case_insensitive = opts.caseInsensitive;
+            if (opts.include !== undefined)
+                body.include = opts.include;
+            if (opts.exclude !== undefined)
+                body.exclude = opts.exclude;
+            if (opts.maxMatches !== undefined)
+                body.max_matches = opts.maxMatches;
+            if (opts.maxFileBytes !== undefined)
+                body.max_file_bytes = opts.maxFileBytes;
+            if (opts.contextLines !== undefined)
+                body.context_lines = opts.contextLines;
+            const url = this.#p('/v1/workspaces/{workspace_id}/files/search');
+            const res = await this.request('POST', url, { json: body, idempotent: true, ...(opts.signal ? { signal: opts.signal } : {}) });
+            return { ...(await parseJson(res, `POST ${url}`)), served_from: servedFromOf(res.headers) };
+        },
+        /**
+         * 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: async (params, opts = {}) => {
+            if ((params.edits === undefined) === (params.content === undefined))
+                throw new TypeError('files.patch needs exactly one of edits or content');
+            const headers = this.#ifMatch('files.patch', opts);
+            const body = { path: params.path };
+            if (params.edits !== undefined)
+                body.edits = params.edits.map((e) => ({ old_text: e.oldText, new_text: e.newText, ...(e.replaceAll !== undefined ? { replace_all: e.replaceAll } : {}) }));
+            if (params.content !== undefined)
+                body.content = params.content;
+            if (params.expectedRevision !== undefined)
+                body.expected_revision = params.expectedRevision;
+            if (params.createParents !== undefined)
+                body.create_parents = params.createParents;
+            if (params.mode !== undefined)
+                body.mode = params.mode;
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/files/patch'), {
+                json: body,
+                idempotencyKey: opts.idempotencyKey ?? randomId('p-').slice(0, 40),
+                headers,
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+        },
     };
+    /**
+     * `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) {
+        // Nothing of a file-first workspace sleeps: the cell would answer `resident` (contracts §29.8).
+        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) ------------------
-    /** One page of the workspace's changes against its template (needs the `files` tool). */
+    /**
+     * 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 = {}) {
+        const refusal = this.#processfulOnly('files.changes', 'Each execution result lists what the command changed (changed).');
+        if (refusal)
+            return Promise.reject(refusal);
         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 },
         });
@@ -499,13 +899,38 @@ export class CellClient {
     }
     // ---- 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 }),
-        status: (path) => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/git/status'), { query: { path } }),
-        commit: (req) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/git/commit'), { json: req }),
+        clone: (req) => {
+            const refusal = this.#needsVm('git.clone');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/git/clone'), { json: req, timeoutMs: (req.timeout_ms ?? 600_000) + 30_000 });
+        },
+        status: (path) => {
+            const refusal = this.#needsVm('git.status');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/git/status'), { query: { path } });
+        },
+        commit: (req) => {
+            const refusal = this.#needsVm('git.commit');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/git/commit'), { json: req });
+        },
     };
     // ---- browser ---------------------------------------------------------------------------
     browser = {
-        screenshot: (req) => this.#bytes('POST', this.#p('/v1/workspaces/{workspace_id}/browser/screenshot'), { json: req, accept: 'image/png', timeoutMs: (req.timeout_ms ?? 30_000) + 15_000 }),
-        content: (req) => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/browser/content'), { json: req, timeoutMs: (req.timeout_ms ?? 30_000) + 15_000 }),
+        screenshot: (req) => {
+            const refusal = this.#needsVm('browser.screenshot');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#bytes('POST', this.#p('/v1/workspaces/{workspace_id}/browser/screenshot'), { json: req, accept: 'image/png', timeoutMs: (req.timeout_ms ?? 30_000) + 15_000 });
+        },
+        content: (req) => {
+            const refusal = this.#needsVm('browser.content');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/browser/content'), { json: req, timeoutMs: (req.timeout_ms ?? 30_000) + 15_000 });
+        },
     };
 }