@shardflux/sdk 0.5.0

package/dist/cell.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Cell gateway client. Every path
+ * template is checked at compile time against the generated `paths` type, and
+ * request/response bodies use the generated schemas, so drift in the cell
+ * contract fails `tsc`. Authorization is a workspace tool token managed by a
+ * ToolTokenManager: a `409 stale_epoch` (workspace moved/re-owned) or `401`
+ * (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).
+ *
+ * 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.
+ */
+import type { components, paths } from './generated/cell-api.js';
+import type { RequestOptions } from './http.js';
+import type { ToolTokenManager } from './tokens.js';
+type S = components['schemas'];
+export type ExecStartRequest = S['ExecStartRequest'];
+export type ExecSession = S['ExecSession'];
+export type OutputEvent = S['OutputEvent'];
+export type PtyOpenRequest = S['PtyOpenRequest'];
+export type PtySession = S['PtySession'];
+export type PtyServerMessage = S['PtyServerMessage'];
+export type ProcessList = S['ProcessList'];
+export type FileInfo = S['FileInfo'];
+export type FileList = S['FileList'];
+export type FileWriteResult = S['FileWriteResult'];
+export type GitCloneRequest = S['GitCloneRequest'];
+export type GitCommitRequest = S['GitCommitRequest'];
+export type GitResult = S['GitResult'];
+export type GitStatus = S['GitStatus'];
+export type BrowserScreenshotRequest = S['BrowserScreenshotRequest'];
+export type BrowserContentRequest = S['BrowserContentRequest'];
+export type BrowserContent = S['BrowserContent'];
+export type Signal = S['SignalValue'];
+type CellPath = keyof paths;
+/** Fills a path template that must exist in cell-api.yaml. */
+export declare function cellPath<P extends CellPath>(template: P, params: Record<string, string | number>): string;
+export interface CellClientOptions {
+    fetch?: typeof fetch;
+    userAgent?: string;
+    timeoutMs?: number;
+    /** Retries for idempotent calls on transient failures (default 2). */
+    maxRetries?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface RunResult {
+    sessionId: string;
+    exitCode: number | null;
+    termSignal: number | null;
+    timedOut: boolean;
+    canceled: boolean;
+    stdout: string;
+    stderr: string;
+    stdoutBytes: number;
+    stderrBytes: number;
+    truncated: boolean;
+    session: ExecSession;
+    /** Output-stream reconnections performed (gateway restarts, network drops). */
+    reconnects: number;
+}
+export interface RunOptions {
+    sessionId?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    user?: string;
+    stdin?: string | Uint8Array;
+    timeoutMs?: number;
+    killGraceMs?: number;
+    /** Bytes of stdout and of stderr kept in memory (the rest is counted, not kept); default 1 MiB. */
+    maxOutputBytes?: number;
+    onOutput?: (stream: 'stdout' | 'stderr', chunk: Uint8Array) => void;
+    signal?: AbortSignal;
+    /**
+     * When `signal` aborts, also cancel the command (SIGTERM, SIGKILL after the grace; default true). Pass false when the
+     * command must outlive the caller (e.g. a client that may re-attach to the session later).
+     */
+    cancelOnAbort?: boolean;
+    /** 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
+     * 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.
+     */
+    secretRefs?: string[];
+}
+/** Parses an NDJSON byte stream into objects (tolerates CRLF and a final unterminated line). */
+export declare function ndjson<T>(body: ReadableStream<Uint8Array>): AsyncGenerator<T>;
+export declare class CellClient {
+    #private;
+    readonly workspaceId: string;
+    readonly tokens: ToolTokenManager;
+    constructor(workspaceId: string, tokens: ToolTokenManager, opts?: CellClientOptions);
+    /** One authorized request; refreshes the token once on stale_epoch / 401. */
+    request(method: string, path: string, init?: RequestOptions): Promise<Response>;
+    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>;
+        get: (sessionId: string) => Promise<ExecSession>;
+        /** Output events from byte offsets (NDJSON). `follow` keeps the stream open until `exit`. */
+        output: (sessionId: string, opts?: {
+            stdoutOffset?: number;
+            stderrOffset?: number;
+            follow?: boolean;
+            signal?: AbortSignal;
+        }) => Promise<AsyncGenerator<OutputEvent>>;
+        signal: (sessionId: string, signal: Signal, onlyLeader?: boolean) => Promise<ExecSession>;
+        cancel: (sessionId: string, graceMs?: number) => Promise<ExecSession>;
+        /**
+         * 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.
+         */
+        run: (argv: string[], opts?: RunOptions) => Promise<RunResult>;
+    };
+    readonly pty: {
+        open: (req?: PtyOpenRequest) => Promise<PtySession>;
+        get: (sessionId: string) => Promise<PtySession>;
+        close: (sessionId: string) => Promise<PtySession>;
+        resize: (sessionId: string, rows: number, cols: number) => Promise<PtySession>;
+        input: (sessionId: string, data: string | Uint8Array) => Promise<PtySession>;
+        /** wss:// URL of the attach WebSocket (send the tool token as `Authorization: Bearer`). */
+        attachUrl: (sessionId: string, offset?: number) => Promise<{
+            url: string;
+            token: string;
+        }>;
+        /**
+         * Reads PTY output from `offset` over the attach WebSocket until `quietMs` without output or
+         * `timeoutMs` in total (request/response helper for agents). Returns the next offset to resume.
+         */
+        read: (sessionId: string, opts?: {
+            offset?: number;
+            quietMs?: number;
+            timeoutMs?: number;
+            maxBytes?: number;
+        }) => Promise<{
+            output: string;
+            nextOffset: number;
+            session: PtySession | null;
+            exited: boolean;
+        }>;
+    };
+    readonly processes: {
+        list: () => Promise<ProcessList>;
+        signal: (pid: number, signal: Signal) => Promise<void>;
+    };
+    readonly files: {
+        /**
+         * Reads a file. Without `length` the whole file is returned: the gateway caps one read
+         * (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: (path: string, opts?: {
+            offset?: number;
+            length?: number;
+        }) => Promise<Uint8Array>;
+        readText: (path: string, opts?: {
+            offset?: number;
+            length?: number;
+        }) => Promise<string>;
+        /** Atomic replace (or append), acknowledged after fsync of file and parent directory. */
+        write: (path: string, data: string | Uint8Array, opts?: {
+            mode?: string;
+            createParents?: boolean;
+            append?: boolean;
+            idempotencyKey?: string;
+        }) => Promise<FileWriteResult>;
+        remove: (path: string, opts?: {
+            recursive?: boolean;
+        }) => Promise<void>;
+        stat: (path: string) => Promise<FileInfo>;
+        list: (path: string, opts?: {
+            limit?: number;
+        }) => Promise<FileList>;
+        mkdir: (path: string, opts?: {
+            parents?: boolean;
+            mode?: string;
+        }) => Promise<FileInfo>;
+        move: (from: string, to: string, opts?: {
+            overwrite?: boolean;
+        }) => Promise<FileInfo>;
+    };
+    readonly git: {
+        clone: (req: GitCloneRequest) => Promise<GitResult>;
+        status: (path: string) => Promise<GitStatus>;
+        commit: (req: GitCommitRequest) => Promise<GitResult>;
+    };
+    readonly browser: {
+        screenshot: (req: BrowserScreenshotRequest) => Promise<Uint8Array>;
+        content: (req: BrowserContentRequest) => Promise<BrowserContent>;
+    };
+}
+export {};

package/dist/cell.js

@@ -0,0 +1,408 @@
+import { ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { HttpClient, defaultSleep, randomId } from "./http.js";
+/** Fills a path template that must exist in cell-api.yaml. */
+export function cellPath(template, params) {
+    return template.replace(/\{([a-z_]+)\}/g, (_, name) => {
+        const v = params[name];
+        if (v === undefined)
+            throw new Error(`missing path parameter ${name}`);
+        return encodeURIComponent(String(v));
+    });
+}
+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). */
+export async function* ndjson(body) {
+    const decoder = new TextDecoder();
+    const reader = body.getReader();
+    let buffer = '';
+    let finished = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let nl;
+            while ((nl = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, nl).replace(/\r$/, '');
+                buffer = buffer.slice(nl + 1);
+                if (line.trim().length > 0)
+                    yield JSON.parse(line);
+            }
+        }
+        buffer += decoder.decode();
+        if (buffer.trim().length > 0)
+            yield JSON.parse(buffer);
+        finished = true;
+    }
+    finally {
+        // A consumer that stops early (e.g. after `exit`) closes the HTTP stream instead of leaking it.
+        if (!finished)
+            await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+class ByteSink {
+    #max;
+    #chunks = [];
+    kept = 0;
+    total = 0;
+    constructor(max) {
+        this.#max = max;
+    }
+    push(b) {
+        this.total += b.length;
+        const room = this.#max - this.kept;
+        if (room <= 0)
+            return;
+        const part = b.length <= room ? b : b.subarray(0, room);
+        this.#chunks.push(part);
+        this.kept += part.length;
+    }
+    text() {
+        return new TextDecoder().decode(Buffer.concat(this.#chunks));
+    }
+}
+export class CellClient {
+    workspaceId;
+    tokens;
+    #opts;
+    #clients = new Map();
+    constructor(workspaceId, tokens, opts = {}) {
+        this.workspaceId = workspaceId;
+        this.tokens = tokens;
+        this.#opts = {
+            fetch: opts.fetch ?? fetch,
+            userAgent: opts.userAgent ?? 'shardflux-sdk-ts',
+            timeoutMs: opts.timeoutMs ?? 60_000,
+            maxRetries: opts.maxRetries ?? 2,
+            sleep: opts.sleep ?? defaultSleep,
+        };
+    }
+    #http(endpoint) {
+        let c = this.#clients.get(endpoint);
+        if (!c) {
+            c = new HttpClient({ baseUrl: endpoint, fetch: this.#opts.fetch, userAgent: this.#opts.userAgent, timeoutMs: this.#opts.timeoutMs, maxRetries: this.#opts.maxRetries, source: 'cell', sleep: this.#opts.sleep });
+            this.#clients.set(endpoint, c);
+        }
+        return c;
+    }
+    /** One authorized request; refreshes the token once on stale_epoch / 401. */
+    async request(method, path, init = {}) {
+        for (let attempt = 0;; attempt += 1) {
+            const token = await this.tokens.get();
+            try {
+                return await this.#http(token.cell_endpoint).raw(method, path, init, `Bearer ${token.token}`);
+            }
+            catch (err) {
+                const refreshable = err instanceof ShardfluxApiError && (err.code === 'stale_epoch' || err.status === 401);
+                if (!refreshable || attempt > 0)
+                    throw err;
+                this.tokens.invalidate();
+            }
+        }
+    }
+    async #json(method, path, init = {}) {
+        const res = await this.request(method, path, init);
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        try {
+            return (text.length === 0 ? undefined : JSON.parse(text));
+        }
+        catch {
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+        }
+    }
+    async #bytes(method, path, init = {}) {
+        const res = await this.request(method, path, init);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    #p(template, extra = {}) {
+        return cellPath(template, { workspace_id: this.workspaceId, ...extra });
+    }
+    // ---- exec --------------------------------------------------------------------------
+    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 })),
+        /** 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 }), {
+                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,
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+            if (!res.body)
+                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 } }),
+        /**
+         * 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.
+         */
+        run: async (argv, opts = {}) => {
+            const sessionId = opts.sessionId ?? `run-${randomId().replace(/-/g, '').slice(0, 24)}`;
+            const req = { session_id: sessionId, argv };
+            if (opts.cwd !== undefined)
+                req.cwd = opts.cwd;
+            if (opts.env !== undefined)
+                req.env = opts.env;
+            if (opts.user !== undefined)
+                req.user = opts.user;
+            if (opts.stdin !== undefined)
+                req.stdin = b64(opts.stdin);
+            if (opts.timeoutMs !== undefined)
+                req.timeout_ms = opts.timeoutMs;
+            if (opts.killGraceMs !== undefined)
+                req.kill_grace_ms = opts.killGraceMs;
+            if (opts.secretRefs !== undefined)
+                req.secret_refs = opts.secretRefs;
+            await this.exec.start(req, opts.signal);
+            try {
+                return await this.#collect(sessionId, opts);
+            }
+            catch (e) {
+                // Aborting the caller must stop the command too, not only our HTTP calls (MCP cancellation, timeouts):
+                // best-effort cancel (SIGTERM, SIGKILL after the grace), bounded so the abort stays prompt.
+                if (opts.signal?.aborted && opts.cancelOnAbort !== false) {
+                    let timer;
+                    const bound = new Promise((resolve) => {
+                        timer = setTimeout(resolve, 5_000);
+                    });
+                    await Promise.race([this.exec.cancel(sessionId, opts.killGraceMs).then(() => undefined, () => undefined), bound]);
+                    clearTimeout(timer);
+                }
+                throw e;
+            }
+        },
+    };
+    /** exec.run's output loop: offsets, reconnects, exit. */
+    async #collect(sessionId, opts) {
+        let session;
+        const max = opts.maxOutputBytes ?? 1_048_576;
+        const out = new ByteSink(max);
+        const err = new ByteSink(max);
+        let so = 0;
+        let se = 0;
+        let reconnects = 0;
+        const maxReconnects = opts.maxReconnects ?? 10;
+        for (;;) {
+            let exited;
+            try {
+                const events = await this.exec.output(sessionId, { stdoutOffset: so, stderrOffset: se, follow: true, ...(opts.signal ? { signal: opts.signal } : {}) });
+                for await (const ev of events) {
+                    if (ev.type === 'output' && ev.data !== undefined) {
+                        const bytes = unb64(ev.data);
+                        const start = ev.offset ?? (ev.stream === 'stderr' ? se : so);
+                        // Skip bytes already processed (a reconnect may resend an overlapping window).
+                        const already = (ev.stream === 'stderr' ? se : so) - start;
+                        const fresh = already > 0 ? bytes.subarray(Math.min(already, bytes.length)) : bytes;
+                        if (ev.stream === 'stderr') {
+                            err.push(fresh);
+                            se = Math.max(se, start + bytes.length);
+                        }
+                        else {
+                            out.push(fresh);
+                            so = Math.max(so, start + bytes.length);
+                        }
+                        if (fresh.length > 0)
+                            opts.onOutput?.(ev.stream === 'stderr' ? 'stderr' : 'stdout', fresh);
+                    }
+                    else if (ev.type === 'exit') {
+                        exited = ev.session ?? (await this.exec.get(sessionId));
+                        break;
+                    }
+                    else if (ev.type === 'error' && ev.error) {
+                        throw new ShardfluxApiError(502, ev.error, 'cell');
+                    }
+                }
+            }
+            catch (e) {
+                if (opts.signal?.aborted)
+                    throw e;
+                const transient = !(e instanceof ShardfluxApiError) || e.retryable;
+                if (!transient || reconnects >= maxReconnects)
+                    throw e;
+            }
+            if (exited) {
+                session = exited;
+                break;
+            }
+            // Stream ended without `exit` (gateway restart, idle proxy, network): resume from offsets.
+            reconnects += 1;
+            if (reconnects > maxReconnects)
+                throw new ShardfluxProtocolError(`exec ${sessionId}: output stream kept dropping`, 0);
+            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) {
+                session = now;
+                break;
+            }
+        }
+        return {
+            sessionId,
+            exitCode: session.exit_code ?? null,
+            termSignal: session.term_signal ?? null,
+            timedOut: session.timed_out ?? false,
+            canceled: session.canceled ?? false,
+            stdout: out.text(),
+            stderr: err.text(),
+            stdoutBytes: out.total,
+            stderrBytes: err.total,
+            truncated: out.total > out.kept || err.total > err.kept,
+            session,
+            reconnects,
+        };
+    }
+    // ---- PTY ---------------------------------------------------------------------------
+    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) } }),
+        /** wss:// URL of the attach WebSocket (send the tool token as `Authorization: Bearer`). */
+        attachUrl: async (sessionId, offset = 0) => {
+            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:';
+            u.searchParams.set('offset', String(offset));
+            return { url: u.toString(), token: token.token };
+        },
+        /**
+         * Reads PTY output from `offset` over the attach WebSocket until `quietMs` without output or
+         * `timeoutMs` in total (request/response helper for agents). Returns the next offset to resume.
+         */
+        read: async (sessionId, opts = {}) => {
+            const WS = globalThis.WebSocket;
+            if (!WS)
+                throw new Error('pty.read needs a global WebSocket (Node 22+); use pty.attachUrl with your own client');
+            const { url, token } = await this.pty.attachUrl(sessionId, opts.offset ?? 0);
+            const sink = new ByteSink(opts.maxBytes ?? 262_144);
+            let next = opts.offset ?? 0;
+            let session = null;
+            let exited = false;
+            await new Promise((resolve, reject) => {
+                const ws = new WS(url, { headers: { authorization: `Bearer ${token}` } });
+                let quiet;
+                const total = setTimeout(() => finish(), opts.timeoutMs ?? 5_000);
+                const finish = (err) => {
+                    clearTimeout(total);
+                    if (quiet)
+                        clearTimeout(quiet);
+                    try {
+                        ws.close(1000);
+                    }
+                    catch {
+                        // already closed
+                    }
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                };
+                const arm = () => {
+                    if (quiet)
+                        clearTimeout(quiet);
+                    quiet = setTimeout(() => finish(), opts.quietMs ?? 500);
+                };
+                ws.addEventListener('open', arm);
+                ws.addEventListener('message', (e) => {
+                    if (typeof e.data !== 'string')
+                        return;
+                    const m = JSON.parse(e.data);
+                    if (m.type === 'output' && m.data) {
+                        const bytes = unb64(m.data);
+                        sink.push(bytes);
+                        next = (m.offset ?? next) + bytes.length;
+                        arm();
+                    }
+                    else if (m.type === 'exit') {
+                        session = m.session ?? null;
+                        exited = true;
+                        finish();
+                    }
+                    else if (m.type === 'error' && m.error) {
+                        finish(new ShardfluxApiError(502, m.error, 'cell'));
+                    }
+                });
+                ws.addEventListener('error', () => finish(new ShardfluxProtocolError('pty attach WebSocket failed', 0)));
+                ws.addEventListener('close', () => finish());
+            });
+            return { output: sink.text(), nextOffset: next, session, exited };
+        },
+    };
+    // ---- processes -----------------------------------------------------------------------
+    processes = {
+        list: () => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/processes')),
+        signal: async (pid, signal) => {
+            await this.request('POST', this.#p('/v1/workspaces/{workspace_id}/processes/{pid}/signal', { pid }), { json: { signal } });
+        },
+    };
+    // ---- files ---------------------------------------------------------------------------
+    files = {
+        /**
+         * Reads a file. Without `length` the whole file is returned: the gateway caps one read
+         * (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 = {}) => {
+            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 start = opts.offset ?? 0;
+            if (opts.length !== undefined || size === null || start + head.byteLength >= size || head.byteLength === 0)
+                return head;
+            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());
+                if (chunk.byteLength === 0)
+                    break;
+                parts.push(chunk);
+                offset += chunk.byteLength;
+            }
+            const out = new Uint8Array(parts.reduce((n, p) => n + p.byteLength, 0));
+            let at = 0;
+            for (const p of parts) {
+                out.set(p, at);
+                at += p.byteLength;
+            }
+            return out;
+        },
+        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'), {
+            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),
+        }),
+        remove: async (path, opts = {}) => {
+            await this.request('DELETE', this.#p('/v1/workspaces/{workspace_id}/files'), { query: { path, recursive: opts.recursive } });
+        },
+        stat: (path) => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/files/stat'), { query: { path } }),
+        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 } : {}) } }),
+    };
+    // ---- 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 }),
+    };
+    // ---- 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 }),
+    };
+}