@shardflux/sdk 0.14.0 → 0.16.0

package/dist/tunnels.js

@@ -0,0 +1,454 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { gunzipSync } from 'node:zlib';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { TUNNEL_ASSETS } from "./tunnel-assets.js";
+import { PtyTunnelTransport } from "./tunnel-pty.js";
+const READY = 1, OPEN = 2, DATA = 3, FIN = 4, RESET = 5, CREDIT = 6;
+const CHUNK = 65536, WINDOW = 4194304;
+export function tunnelTarget(target) {
+    const m = /^(?:\[([^\]]+)\]|([^\s:[\]]+)):([0-9]+)$/.exec(target);
+    const port = Number(m?.[3]);
+    if (!m || !Number.isInteger(port) || port < 1 || port > 65535)
+        throw new TypeError('target must be host:port or [IPv6]:port (1..65535)');
+    return { host: m[1] ?? m[2], port };
+}
+function frame(kind, id, body = Buffer.alloc(0)) {
+    const h = Buffer.alloc(9);
+    h[0] = kind;
+    h.writeUInt32BE(id, 1);
+    h.writeUInt32BE(body.length, 5);
+    return Buffer.concat([h, body]);
+}
+function retryable(e) {
+    if (e instanceof ShardfluxApiError)
+        return e.retryable || e.code === 'workspace_not_running' || e.reason === 'workspace_not_running';
+    return e instanceof TypeError || (e instanceof ShardfluxProtocolError && e.status === 0);
+}
+/** An owned foreground connection to the developer machine. Close in finally. */
+export class ReverseTunnel {
+    sessionId;
+    remotePort;
+    target;
+    transport;
+    closed;
+    #resolve;
+    #reject;
+    #ready;
+    #readyError;
+    #transport;
+    #dir;
+    #target;
+    #controller = new AbortController();
+    #peers = new Map();
+    #writes = [];
+    #sending = false;
+    #inputOffset = 0;
+    #nextInputOffset = 0;
+    #newWrites;
+    #outputOffset = 0;
+    #stderrOffset = 0;
+    #buffer = Buffer.alloc(0);
+    #stderr = '';
+    #closing;
+    #stats = { connections: 0, activeConnections: 0, bytesToTarget: 0, bytesToWorkspace: 0, reconnects: 0 };
+    #abort;
+    #signal;
+    constructor(transport, sessionId, dir, opts) {
+        this.#transport = transport;
+        this.sessionId = sessionId;
+        this.#dir = dir;
+        this.remotePort = opts.remotePort;
+        this.target = opts.target;
+        this.#target = tunnelTarget(opts.target);
+        this.transport = transport.kind ?? 'exec';
+        this.closed = new Promise((resolve, reject) => { this.#resolve = resolve; this.#reject = reject; });
+        // Ownership remains with the handle even when the caller observes failure later through closed.
+        void this.closed.catch(() => { });
+    }
+    get stats() { return { ...this.#stats, activeConnections: this.#peers.size }; }
+    /** Internal transport entry point, also exercised against the real helper in tests. */
+    static async attach(transport, sessionId, dir, opts) {
+        const t = new ReverseTunnel(transport, sessionId, dir, opts);
+        const ready = new Promise((resolve, reject) => { t.#ready = resolve; t.#readyError = reject; });
+        const timer = setTimeout(() => t.#fail(new Error('reverse tunnel listener did not become ready within 30 seconds')), 30_000);
+        t.#signal = opts.signal;
+        t.#abort = () => { void t.close().catch(() => { }); };
+        opts.signal?.addEventListener('abort', t.#abort, { once: true });
+        void t.#read().catch(e => t.#fail(e));
+        if (opts.signal?.aborted)
+            t.#fail(opts.signal.reason);
+        try {
+            await ready;
+            return t;
+        }
+        catch (e) {
+            await t.close();
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    #fail(e) {
+        if (this.#closing)
+            return;
+        this.#readyError(e);
+        void this.#teardown(e).catch(() => { });
+    }
+    #send(kind, id, body) {
+        if (this.#closing)
+            return Promise.reject(new Error('reverse tunnel is closed'));
+        const result = new Promise((resolve, reject) => { this.#writes.push({ bytes: frame(kind, id, body), resolve, reject }); });
+        this.#newWrites?.();
+        if (!this.#sending) {
+            this.#sending = true;
+            queueMicrotask(() => { void this.#flush().catch(e => this.#fail(e)); });
+        }
+        return result;
+    }
+    async #flush() {
+        const active = new Set();
+        while ((this.#writes.length || active.size) && !this.#closing) {
+            while (this.#writes.length && active.size < (this.#transport.maxInputConcurrency ?? 1)) {
+                const batch = [], complete = [], parts = [];
+                let size = 0;
+                while (this.#writes.length && size < 65536) {
+                    const w = this.#writes[0];
+                    const n = Math.min(w.bytes.length, 65536 - size);
+                    batch.push(w);
+                    parts.push(w.bytes.subarray(0, n));
+                    size += n;
+                    if (n === w.bytes.length) {
+                        this.#writes.shift();
+                        complete.push(w);
+                    }
+                    else
+                        w.bytes = w.bytes.subarray(n);
+                }
+                const bytes = Buffer.concat(parts);
+                const offset = this.#nextInputOffset;
+                this.#nextInputOffset += bytes.length;
+                const work = this.#writeBatch(bytes, offset).then(() => { for (const w of complete)
+                    w.resolve(); }, (e) => {
+                    for (const w of batch)
+                        w.reject(e);
+                    this.#fail(e);
+                });
+                active.add(work);
+                void work.then(() => active.delete(work));
+            }
+            if (active.size)
+                await Promise.race([...active, new Promise(resolve => { this.#newWrites = resolve; })]);
+        }
+        this.#newWrites = undefined;
+        this.#sending = false;
+    }
+    async #writeBatch(bytes, start) {
+        let sent = 0;
+        while (sent < bytes.length && !this.#closing) {
+            try {
+                const ack = await this.#transport.exec.input(this.sessionId, bytes.subarray(sent), { offset: start + sent, signal: this.#controller.signal });
+                const n = ack.offset - (start + sent);
+                if (!Number.isInteger(n) || n < 0 || n > bytes.length - sent || ack.closed)
+                    throw new Error('invalid reverse tunnel stdin acknowledgement');
+                sent += n;
+                this.#inputOffset = Math.max(this.#inputOffset, ack.offset);
+                if (n === 0)
+                    await delay(25, undefined, { signal: this.#controller.signal });
+            }
+            catch (e) {
+                if (!retryable(e) || this.#closing)
+                    throw e;
+                this.#stats.reconnects++;
+                await delay(250, undefined, { signal: this.#controller.signal });
+            }
+        }
+    }
+    async #read() {
+        while (!this.#closing) {
+            try {
+                const events = await this.#transport.exec.output(this.sessionId, { stdoutOffset: this.#outputOffset, stderrOffset: this.#stderrOffset, signal: this.#controller.signal });
+                for await (const ev of events) {
+                    if (this.#closing)
+                        return;
+                    if (ev.type === 'exit')
+                        throw new Error(`reverse tunnel forwarder exited${this.#stderr ? ': ' + this.#stderr : ''}`);
+                    if (ev.type === 'error') {
+                        if (ev.error)
+                            throw new ShardfluxApiError(502, ev.error, 'cell');
+                        throw new Error('reverse tunnel output failed without an error envelope');
+                    }
+                    if (ev.type !== 'output')
+                        continue;
+                    const bytes = Buffer.from(ev.data ?? '', 'base64');
+                    const stderr = ev.stream === 'stderr';
+                    const offset = stderr ? this.#stderrOffset : this.#outputOffset;
+                    const start = ev.offset ?? offset;
+                    if (start > offset)
+                        throw new Error('reverse tunnel output has a byte gap');
+                    const fresh = bytes.subarray(Math.min(bytes.length, Math.max(0, offset - start)));
+                    if (stderr) {
+                        this.#stderrOffset += fresh.length;
+                        this.#stderr = (this.#stderr + fresh.toString()).slice(-4096);
+                    }
+                    else {
+                        this.#outputOffset += fresh.length;
+                        this.#decode(fresh);
+                    }
+                }
+            }
+            catch (e) {
+                if (this.#closing)
+                    return;
+                if (!retryable(e))
+                    throw e;
+            }
+            this.#stats.reconnects++;
+            await delay(250, undefined, { signal: this.#controller.signal });
+        }
+    }
+    #decode(bytes) {
+        this.#buffer = Buffer.concat([this.#buffer, bytes]);
+        while (this.#buffer.length >= 9) {
+            const n = this.#buffer.readUInt32BE(5);
+            if (n > 65536)
+                throw new Error('oversized reverse tunnel frame');
+            if (this.#buffer.length < n + 9)
+                return;
+            const kind = this.#buffer[0];
+            const id = this.#buffer.readUInt32BE(1);
+            const body = this.#buffer.subarray(9, n + 9);
+            this.#buffer = this.#buffer.subarray(n + 9);
+            this.#dispatch(kind, id, body);
+        }
+    }
+    #dispatch(kind, id, body) {
+        if (kind === READY && id === 0 && body.length === 0) {
+            this.#ready();
+            return;
+        }
+        if (kind === OPEN && id !== 0 && body.length === 0) {
+            if (this.#peers.has(id) || this.#peers.size >= 128)
+                throw new Error('invalid reverse tunnel connection');
+            const socket = createConnection({ ...this.#target, allowHalfOpen: true });
+            const p = { socket, credit: WINDOW, receiveCredit: WINDOW, pendingCredit: 0, remoteEnded: false, localEnded: false };
+            this.#peers.set(id, p);
+            this.#stats.connections++;
+            socket.on('error', () => this.#reset(id));
+            // Normal TCP EOF can close the socket while #pump still awaits acknowledgement of its final chunk.
+            socket.on('close', () => { if (!socket.readableEnded && this.#peers.get(id) === p)
+                this.#reset(id); });
+            void this.#pump(id, p).catch(() => this.#reset(id));
+            return;
+        }
+        const p = this.#peers.get(id);
+        if (!p) {
+            if (![DATA, FIN, RESET, CREDIT].includes(kind))
+                throw new Error('unknown reverse tunnel frame');
+            return;
+        }
+        if (kind === DATA) {
+            if (!body.length || p.remoteEnded || body.length > p.receiveCredit)
+                throw new Error('reverse tunnel receive window overflow');
+            p.receiveCredit -= body.length;
+            this.#stats.bytesToTarget += body.length;
+            p.socket.write(body, (e) => {
+                if (e || this.#peers.get(id) !== p)
+                    return;
+                p.pendingCredit += body.length;
+                if (p.pendingCredit >= 262144) {
+                    const credit = Buffer.alloc(4);
+                    credit.writeUInt32BE(p.pendingCredit);
+                    p.receiveCredit += p.pendingCredit;
+                    p.pendingCredit = 0;
+                    void this.#send(CREDIT, id, credit).catch(e => this.#fail(e));
+                }
+            });
+        }
+        else if (kind === CREDIT) {
+            if (body.length !== 4 || !body.readUInt32BE(0) || p.credit + body.readUInt32BE(0) > WINDOW)
+                throw new Error('invalid reverse tunnel credit');
+            p.credit += body.readUInt32BE(0);
+            p.wake?.();
+        }
+        else if (kind === FIN && body.length === 0) {
+            if (p.remoteEnded)
+                throw new Error('duplicate reverse tunnel fin');
+            p.remoteEnded = true;
+            p.socket.end();
+            this.#ended(id, p);
+        }
+        else if (kind === RESET && body.length === 0)
+            this.#reset(id, false);
+        else
+            throw new Error('invalid reverse tunnel frame');
+    }
+    async #pump(id, p) {
+        const pending = [];
+        for await (const value of p.socket) {
+            const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            let pos = 0;
+            while (pos < bytes.length && this.#peers.get(id) === p && !this.#closing) {
+                if (!p.credit)
+                    await new Promise(resolve => { p.wake = resolve; });
+                if (this.#peers.get(id) !== p || this.#closing)
+                    return;
+                const n = Math.min(CHUNK, p.credit, bytes.length - pos);
+                p.credit -= n;
+                if (this.#transport.kind === 'pty') {
+                    const write = this.#send(DATA, id, bytes.subarray(pos, pos + n));
+                    void write.catch(() => { });
+                    pending.push(write);
+                    if (pending.length >= 128)
+                        await Promise.all(pending.splice(0));
+                }
+                else
+                    await this.#send(DATA, id, bytes.subarray(pos, pos + n));
+                pos += n;
+                this.#stats.bytesToWorkspace += n;
+            }
+        }
+        if (this.#peers.get(id) !== p || this.#closing)
+            return;
+        await Promise.all(pending);
+        // A guest can release this connection and accept the next before the HTTP stdin acknowledgement arrives.
+        p.localEnded = true;
+        this.#ended(id, p);
+        await this.#send(FIN, id);
+    }
+    #ended(id, p) { if (p.localEnded && p.remoteEnded) {
+        this.#peers.delete(id);
+        p.wake?.();
+    } }
+    #reset(id, notify = true) {
+        const p = this.#peers.get(id);
+        if (!p)
+            return;
+        this.#peers.delete(id);
+        p.wake?.();
+        p.socket.destroy();
+        if (notify && !this.#closing)
+            void this.#send(RESET, id).catch(e => this.#fail(e));
+    }
+    close() { return this.#teardown(); }
+    #teardown(failure) {
+        if (this.#closing)
+            return this.#closing;
+        this.#closing = (async () => {
+            // Yield so #closing is set before output abort and socket callbacks run.
+            await Promise.resolve();
+            this.#readyError(failure ?? new Error('reverse tunnel closed before ready'));
+            this.#controller.abort();
+            this.#newWrites?.();
+            if (this.#abort)
+                this.#signal?.removeEventListener('abort', this.#abort);
+            for (const id of this.#peers.keys())
+                this.#reset(id, false);
+            for (const w of this.#writes.splice(0))
+                w.reject(new Error('reverse tunnel closed'));
+            const errors = failure === undefined ? [] : [failure];
+            try {
+                await this.#transport.exec.cancel(this.sessionId, 1000);
+            }
+            catch (e) {
+                errors.push(e);
+            }
+            try {
+                await this.#transport.files.remove(this.#dir, { recursive: true });
+            }
+            catch (e) {
+                errors.push(e);
+            }
+            if (errors.length) {
+                const e = new AggregateError(errors, 'reverse tunnel ended with errors');
+                this.#reject(e);
+                throw e;
+            }
+            this.#resolve();
+        })();
+        return this.#closing;
+    }
+}
+/** Workspace → this client's machine; unused workspaces pay no tunnel setup or lifecycle cost. */
+export class WorkspaceTunnels {
+    #cell;
+    #grants;
+    #owned = new Set();
+    constructor(cell, grants = () => null) { this.#cell = cell; this.#grants = grants; }
+    async reverse(opts) {
+        tunnelTarget(opts.target);
+        if (!Number.isInteger(opts.remotePort) || opts.remotePort < 1 || opts.remotePort > 65535)
+            throw new TypeError('remotePort must be 1..65535');
+        const bind = opts.bindAddress ?? '127.0.0.1';
+        if (bind !== '127.0.0.1' && bind !== '0.0.0.0')
+            throw new TypeError('bindAddress must be 127.0.0.1 or 0.0.0.0');
+        const choice = opts.transport ?? 'auto';
+        if (!['auto', 'pty', 'exec'].includes(choice))
+            throw new TypeError('transport must be auto, pty or exec');
+        opts.signal?.throwIfAborted();
+        const cell = this.#cell();
+        const archResult = await cell.exec.run(['uname', '-m'], { signal: opts.signal, timeoutMs: 5000 });
+        const arch = archResult.stdout.trim();
+        if (arch !== 'x86_64' && arch !== 'aarch64')
+            throw new Error(`reverse tunnel: unsupported guest architecture ${arch}`);
+        const asset = TUNNEL_ASSETS[arch];
+        const binary = gunzipSync(readFileSync(new URL(`./tunnel-assets/${asset.file}`, import.meta.url)));
+        if (createHash('sha256').update(binary).digest('hex') !== asset.sha256)
+            throw new Error('reverse tunnel helper checksum mismatch');
+        const dir = `/tmp/shardflux-tunnel-${randomUUID()}`;
+        const sessionId = randomUUID().replaceAll('-', '');
+        const fast = choice === 'pty' || (choice === 'auto' && this.#grants()?.includes('pty'));
+        const transport = fast ? new PtyTunnelTransport(cell) : cell;
+        let startAttempted = false, attached = false;
+        try {
+            await cell.files.mkdir(dir, { mode: '0700' });
+            await cell.files.write(`${dir}/forwarder`, binary, { mode: '0700' });
+            startAttempted = true;
+            const argv = [`${dir}/forwarder`, '--port', String(opts.remotePort), '--bind', bind];
+            const session = fast
+                ? await cell.pty.open({ session_id: sessionId, argv: ['bash', '-c', 'stty raw -echo; exec "$@"', 'sh', ...argv, '--packets'] })
+                : await cell.exec.start({ session_id: sessionId, argv, stdin_open: true }, opts.signal);
+            if (session.state === 'failed_to_start')
+                throw new Error(`reverse tunnel could not start: ${session.error ?? ''}`);
+            attached = true;
+            const tunnel = await ReverseTunnel.attach(transport, sessionId, dir, opts);
+            this.#owned.add(tunnel);
+            void tunnel.closed.finally(() => this.#owned.delete(tunnel)).catch(() => { });
+            return tunnel;
+        }
+        catch (e) {
+            if (attached)
+                throw e; // attach() already owns teardown and reports its errors.
+            // A start may have reached the guest even if its answer was lost.
+            const errors = [e];
+            if (startAttempted) {
+                try {
+                    await transport.exec.cancel(sessionId, 1000);
+                }
+                catch (cleanup) {
+                    if (!(cleanup instanceof ShardfluxApiError && cleanup.status === 404))
+                        errors.push(cleanup);
+                }
+            }
+            try {
+                await cell.files.remove(dir, { recursive: true });
+            }
+            catch (cleanup) {
+                if (!(cleanup instanceof ShardfluxApiError && cleanup.status === 404))
+                    errors.push(cleanup);
+            }
+            if (errors.length > 1)
+                throw new AggregateError(errors, 'reverse tunnel startup cleanup failed', { cause: e });
+            throw e;
+        }
+    }
+    async close() {
+        const results = await Promise.allSettled([...this.#owned].map(t => t.close()));
+        const errors = results.filter((r) => r.status === 'rejected').map(r => r.reason);
+        if (errors.length)
+            throw new AggregateError(errors, 'reverse tunnel cleanup failed');
+    }
+}

package/dist/workspace-ref.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Workspaces by key (0.15.0+, contracts §46). `cloud.workspace(key, { template })` names a workspace without a request.
+ * Its first call opens the key (the workspace is created on first use and resumed afterwards, one held request that
+ * returns it with a tool token), and later calls go straight to the workspace, which wakes on use.
+ */
+import type { CellClient, CellClientOptions, RunOptions, RunResult } from './cell.js';
+import { CAPTURE_BARRIER } from './cell.js';
+import type { OpenParams, WorkspacesApi } from './client.js';
+import type { WorkspaceMode } from './errors.js';
+import type { ExecutionGetOptions, ExecutionResult, ExecutionRunOptions } from './executions.js';
+import type { ToolName } from './tokens.js';
+import type { ToolTarget, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+import type { HintOptions, HintResult, Workspace } from './workspace.js';
+/**
+ * `cloud.workspace(key, params)`: the open's parameters without the key. `template` is required, unless `create: false`:
+ * then the first call finds the key's live workspace (a lookup, no VM start) and fails with ShardfluxApiError 404
+ * `not_found` when there is none. Default: the first call opens the key, creating the workspace.
+ */
+export type WorkspaceRefParams = (Omit<OpenParams, 'key'> & {
+    create?: true;
+}) | (Omit<OpenParams, 'key' | 'template'> & {
+    template?: string;
+    create: false;
+});
+type Files = CellClient['files'];
+type FileMethod = 'read' | 'readText' | 'readWithInfo' | 'write' | 'list' | 'stat' | 'remove' | 'mkdir' | 'move' | 'search' | 'patch';
+/** The workspace's files, as on `cell().files`; each call opens the key first if needed. */
+export type WorkspaceRefFiles = Pick<Files, FileMethod>;
+/**
+ * A workspace named by its key. Nothing is requested until the first call: `exec()`, `files`, a tool from `tools()`,
+ * `hint()` or `open()`. Concurrent first calls share one open; a failed open is not kept, so the next call opens again.
+ * A workspace deleted under the ref (409 `workspace_deleted`, `isWorkspaceGone`) fails the call that meets it and is
+ * forgotten: the next call opens the key again (a new workspace, as `open()` would). `open()` returns the full
+ * `Workspace` (suspend, fork, ports, computer, tool-call capture).
+ */
+export declare class WorkspaceRef implements ToolTarget {
+    #private;
+    readonly key: string;
+    /** Internal: use `cloud.workspace(key, params)` or the module-level `workspace(key, params)`. */
+    constructor(api: WorkspacesApi, key: string, params: WorkspaceRefParams, grants: () => Promise<ToolName[] | null>);
+    /**
+     * Whether the open that produced the current workspace created it (contracts §46.2): undefined until the ref has
+     * opened (or when the API does not report it), false for `create: false`.
+     */
+    get created(): boolean | undefined;
+    /** The opened workspace's mode, else the params' (`processful` when neither says). */
+    get mode(): WorkspaceMode;
+    /** Tools granted by the opened workspace's last token; null before the open. */
+    get grantedTools(): ToolName[] | null;
+    /** The workspace: opened (or, with `create: false`, found) on the first call and kept. */
+    open(): Promise<Workspace>;
+    /**
+     * Runs a command and collects its output (`cell().exec.run()`). A string runs through `bash -lc`, so shell syntax
+     * works; an argv array runs without a shell. A file-first workspace runs commands with `executions.run()`.
+     */
+    exec(command: string | readonly string[], opts?: RunOptions): Promise<RunResult>;
+    /** The workspace's files, as on `cell().files`. */
+    readonly files: WorkspaceRefFiles;
+    /** A file-first workspace's executions (`run`, `get`), as on `Workspace.executions`. */
+    readonly executions: {
+        run: (argv: string[], opts?: ExecutionRunOptions) => Promise<ExecutionResult>;
+        get: (executionId: string, opts?: ExecutionGetOptions) => Promise<ExecutionResult>;
+    };
+    /** The workspace's cell client (`Workspace.cell()`), opening the key first if needed. */
+    cell(opts?: {
+        agentLabel?: string;
+        tools?: ToolName[];
+    } & CellClientOptions): Promise<CellClient>;
+    /** Hints without waiting, runs the turn, and requests idle suspension even if the body throws. */
+    turn<T>(fn: (workspace: this) => T | Promise<T>, { afterSeconds }?: {
+        afterSeconds?: number;
+    }): Promise<T>;
+    /**
+     * Says a tool call is coming. Before the first open it starts the open in the background (`wake` resolves when the
+     * workspace runs; nothing has to await it), unless `wake: null`; afterwards it is `Workspace.hint()`.
+     */
+    hint(opts?: HintOptions): Promise<HintResult>;
+    /**
+     * Workspace tools for this key (`workspaceTools`), built before any VM exists: the definitions come from the API
+     * key's tool permissions (`GET /v1/me`, read once per client), and `computer` only with `computerUse: true` in the
+     * params or on an opened workspace whose computer use is on. The first tool call opens the key.
+     */
+    tools(opts?: WorkspaceToolsOptions): Promise<WorkspaceTool[]>;
+    /** Internal: tool-call capture's read-your-writes barrier, once the workspace is open. */
+    [CAPTURE_BARRIER](): Promise<void> | undefined;
+}
+export {};