withruntime 0.4.0 → 0.5.1

package/dist/tools/index.js

@@ -0,0 +1,180 @@
+/** Four tools bound to one Runtime sandbox, in no framework's format: a name,
+ * a description, a JSON Schema and a function. The adapters for the Vercel AI
+ * SDK (and Mastra), the Claude Agent SDK and the OpenAI Agents SDK wrap these,
+ * and any other framework can too:
+ *
+ *   import { sandboxTools } from "withruntime/tools";
+ *   for (const t of sandboxTools(sbx)) register(t.name, t.description, t.inputSchema, t.execute);
+ *
+ * The application creates the sandbox and binds the tools to it: the model
+ * chooses commands and paths, never the sandbox, the account or the key.
+ * Relative paths are under /workspace, and output is capped so one noisy
+ * command cannot flood the model's context. */
+import { NotFoundError } from "../errors.js";
+const WORKSPACE = "/workspace";
+/** A POSIX path joined and normalized: `..` cannot climb past `/`. */
+export function resolvePath(root, path) {
+    const joined = (path ?? ".").startsWith("/") ? path : `${root}/${path ?? "."}`;
+    const parts = [];
+    for (const part of joined.split("/")) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..")
+            parts.pop();
+        else
+            parts.push(part);
+    }
+    return `/${parts.join("/")}`;
+}
+export function clip(text, limit) {
+    return text.length <= limit
+        ? text
+        : `[${text.length - limit} earlier characters omitted]\n${text.slice(-limit)}`;
+}
+/** runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files, bound to `sandbox`. */
+export function sandboxTools(sandbox, options = {}) {
+    const root = resolvePath("/", options.root ?? WORKSPACE);
+    const timeoutSeconds = options.timeoutSeconds ?? 300;
+    const limit = options.maxOutputChars ?? 20_000;
+    const inFilesApi = (path) => path.startsWith(`${WORKSPACE}/`);
+    return [
+        {
+            name: "runtime_exec",
+            description: "Run a shell command (bash) in the sandbox and return its exit code, stdout and stderr.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    command: {
+                        type: "string",
+                        description: "The command line, run under `bash -c`, for example `pytest -q`.",
+                    },
+                    cwd: {
+                        type: "string",
+                        description: "Directory to run in. Relative paths are under /workspace, the default.",
+                    },
+                    timeoutSeconds: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "Seconds before the command is stopped and reported as timed out.",
+                    },
+                },
+                required: ["command"],
+                additionalProperties: false,
+            },
+            async execute({ command, cwd, timeoutSeconds: seconds }) {
+                const result = await sandbox.exec(command, {
+                    cwd: resolvePath(root, cwd),
+                    timeoutMs: (seconds ?? timeoutSeconds) * 1000,
+                });
+                return {
+                    exitCode: result.exitCode,
+                    stdout: clip(result.stdout, limit),
+                    stderr: clip(result.stderr, limit),
+                    timedOut: result.timedOut,
+                };
+            },
+        },
+        {
+            name: "runtime_read_file",
+            description: "Read a text file from the sandbox.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "The file's path. Relative paths are under /workspace.",
+                    },
+                },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            async execute({ path }) {
+                const target = resolvePath(root, path);
+                if (inFilesApi(target)) {
+                    try {
+                        return clip(await sandbox.files.readText(target), limit);
+                    }
+                    catch (error) {
+                        if (error instanceof NotFoundError)
+                            return `No such file: ${target}`;
+                        throw error;
+                    }
+                }
+                const result = await sandbox.exec(["cat", "--", target]);
+                return clip(result.exitCode === 0 ? result.stdout : result.stderr, limit);
+            },
+        },
+        {
+            name: "runtime_write_file",
+            description: "Create or replace a text file in the sandbox, making parent directories.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "The file's path. Relative paths are under /workspace.",
+                    },
+                    content: { type: "string", description: "The file's full new content." },
+                },
+                required: ["path", "content"],
+                additionalProperties: false,
+            },
+            async execute({ path, content }) {
+                const target = resolvePath(root, path);
+                if (inFilesApi(target))
+                    await sandbox.files.write(target, content);
+                else {
+                    const result = await sandbox.exec(["sh", "-c", 'mkdir -p -- "$(dirname -- "$1")" && cat > "$1"', "sh", target], { stdin: content });
+                    if (result.exitCode !== 0)
+                        return `Could not write ${target}: ${result.stderr.trim()}`;
+                }
+                return `Wrote ${new TextEncoder().encode(content).length} bytes to ${target}`;
+            },
+        },
+        {
+            name: "runtime_list_files",
+            description: "List a directory in the sandbox: each entry's path, type and size.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "The directory. Relative paths are under /workspace, the default.",
+                    },
+                    depth: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "How many levels below it to include; 1 lists only its children.",
+                    },
+                },
+                required: [],
+                additionalProperties: false,
+            },
+            async execute({ path, depth }) {
+                const levels = String(Math.max(1, Math.min(depth ?? 1, 10)));
+                const result = await sandbox.exec([
+                    "sh",
+                    "-c",
+                    'find "$1" -mindepth 1 -maxdepth "$2" -printf "%y\\t%s\\t%p\\n" | sort -k3 | head -n 1000',
+                    "sh",
+                    resolvePath(root, path),
+                    levels,
+                ]);
+                if (result.exitCode !== 0 && !result.stdout)
+                    return { error: result.stderr.trim() || `find exited with ${result.exitCode}` };
+                const kinds = {
+                    f: "file",
+                    d: "directory",
+                    l: "symlink",
+                };
+                return result.stdout
+                    .split("\n")
+                    .filter(Boolean)
+                    .map((line) => {
+                    const [kind = "", size = "0", ...rest] = line.split("\t");
+                    return { path: rest.join("\t"), type: kinds[kind] ?? "other", size: Number(size) || 0 };
+                });
+            },
+        },
+    ];
+}

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.1";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export type RequestOptions = {
     /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps
@@ -25,6 +25,11 @@ export type Call = RequestOptions & {
      * reads and for writes (the key makes them safe); false only for calls
      * the server cannot deduplicate. */
     retry?: boolean;
+    /** How long to keep retrying, with the same key and input, a refusal that
+     * clears when a sandbox stops or a host frees room (WAITS_FOR_ROOM): a
+     * full trial, a full quota, a full region. Then the refusal is thrown as
+     * it came. Only a create sets it; 0 or absent fails at once. */
+    waitForCapacityMs?: number;
 };
 export declare function apiOrigin(value: string): string;
 export declare function encodeQuery(query: Query | undefined): string;
@@ -39,6 +44,8 @@ export declare function encodeQuery(query: Query | undefined): string;
 export declare class Transport {
     #private;
     readonly baseUrl: string;
+    /** What `sandboxes.create` waits for room by default. */
+    readonly waitForCapacityMs: number;
     constructor(options: {
         /** A key, or where to find one when the first call is made. */
         apiKey: string | (() => Promise<string>);
@@ -49,10 +56,13 @@ export declare class Transport {
         client?: string;
         /** Calls read whole that may be in flight at once. Default 32. */
         maxConnections?: number;
+        /** How long a create waits for room. Default 120 000; 0 fails at once. */
+        waitForCapacityMs?: number;
     });
     /** Sends a call and returns the raw Response once it succeeded. Retries
      * transport failures, 429, 502, 503 and 504 with backoff and jitter, with
-     * the same key every time. */
+     * the same key every time, and waits out a full house for a call that sets
+     * waitForCapacityMs. */
     send(call: Call): Promise<Response>;
     json<T>(call: Call): Promise<T>;
     bytes(call: Call): Promise<Uint8Array>;

package/dist/transport.js

@@ -1,6 +1,6 @@
-import { ConnectionError, errorFor, RuntimeError } from "./errors.js";
+import { ConnectionError, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.1";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export function apiOrigin(value) {
     const url = new URL(value);
@@ -90,6 +90,8 @@ export class Transport {
     #maxRetries;
     #client;
     #slots;
+    /** What `sandboxes.create` waits for room by default. */
+    waitForCapacityMs;
     constructor(options) {
         if (typeof options.apiKey === "function")
             this.#findKey = options.apiKey;
@@ -106,6 +108,7 @@ export class Transport {
         this.#maxRetries = options.maxRetries ?? 4;
         this.#client = options.client ?? `sdk-js/${VERSION}`;
         this.#slots = slots(Math.max(1, options.maxConnections ?? 32));
+        this.waitForCapacityMs = Math.max(0, options.waitForCapacityMs ?? 120_000);
     }
     /** The key, found once on first use when it was not given. */
     async #key() {
@@ -133,12 +136,18 @@ export class Transport {
     }
     /** Sends a call and returns the raw Response once it succeeded. Retries
      * transport failures, 429, 502, 503 and 504 with backoff and jitter, with
-     * the same key every time. */
+     * the same key every time, and waits out a full house for a call that sets
+     * waitForCapacityMs. */
     async send(call) {
         const apiKey = await this.#key();
         const write = call.method !== "GET";
         const key = write ? (call.idempotencyKey ?? crypto.randomUUID()) : undefined;
-        const deadline = AbortSignal.timeout(call.timeoutMs ?? this.#timeoutMs);
+        // Time spent waiting for room is added to the call's deadline, not taken
+        // from it: once admitted, a create still has its whole timeoutMs.
+        const roomMs = Math.max(0, call.waitForCapacityMs ?? 0);
+        const roomUntil = performance.now() + roomMs;
+        let roomAttempt = 0;
+        const deadline = AbortSignal.timeout((call.timeoutMs ?? this.#timeoutMs) + roomMs);
         const signal = call.signal ? AbortSignal.any([call.signal, deadline]) : deadline;
         const url = `${this.baseUrl}${call.path}${encodeQuery(call.query)}`;
         const body = call.bytes ?? (call.body === undefined ? undefined : JSON.stringify(call.body));
@@ -213,6 +222,19 @@ export class Transport {
                 parsed = { error: { message: text.slice(0, 500) || `HTTP ${response.status}` } };
             }
             const error = errorFor(response.status, parsed, key);
+            // A full house: wait for a slot or for room, then send the same call
+            // again. A request that can never fit (a fork of more copies than the
+            // trial runs) is not waited for.
+            if (retry &&
+                roomMs > 0 &&
+                WAITS_FOR_ROOM.has(error.code) &&
+                error.details?.field !== "count") {
+                const left = roomUntil - performance.now();
+                if (left <= 0)
+                    throw error;
+                await sleep(Math.min(left, error.retryAfterMs ?? roomBackoff(roomAttempt++)), signal);
+                continue;
+            }
             const retryable = [429, 502, 503, 504].includes(response.status) && !DELIBERATE.has(error.code);
             if (!retry || !retryable || attempt >= this.#maxRetries)
                 throw error;
@@ -292,3 +314,8 @@ export function missingKey() {
 function backoff(attempt) {
     return Math.min(8000, 250 * 2 ** attempt) * (0.5 + Math.random());
 }
+/** Between tries for room: 0.5 s, 1 s, 2 s, 4 s, then every 8 s, jittered, so
+ * a queue of CI jobs spreads out instead of knocking at once. */
+function roomBackoff(attempt) {
+    return Math.min(8000, 500 * 2 ** attempt) * (0.75 + Math.random() * 0.5);
+}

package/dist/tunnel.d.ts

@@ -0,0 +1,70 @@
+import { RuntimeError } from "./errors.js";
+/** One TCP connection (or SSH login) inside a tunnel. Set the handlers before
+ * data can arrive, which is as soon as the promise that gave you this resolves. */
+export declare class TunnelStream {
+    #private;
+    private readonly tunnel;
+    readonly id: number;
+    /** Bytes from the sandbox side. */
+    onData?: (data: Uint8Array) => void;
+    /** The sandbox side will send nothing more; you may still write. */
+    onEnd?: () => void;
+    /** The connection is gone. `reason` is "done" after a clean finish. */
+    onClose?: (reason: string) => void;
+    /** sshd's own error output, for an SSH login that fails. */
+    onLog?: (text: string) => void;
+    constructor(tunnel: Tunnel, id: number);
+    /** Sends bytes. Resolves once they are within the tunnel's window, so
+     * awaiting each write is enough backpressure. */
+    write(data: Uint8Array): Promise<void>;
+    /** No more bytes from this side; the sandbox side reads end of input. */
+    end(): void;
+    /** Drops the connection at once. After both sides have ended, the sandbox
+     * finishes it by itself, so a close then would only race the last bytes. */
+    close(): void;
+    /** @internal */
+    receive(kind: number, payload: Uint8Array): void;
+    /** @internal */
+    gone(reason: string): void;
+}
+/** A local port forwarded into the sandbox. */
+export type PortForward = {
+    /** The local address and port that forward (the port the system chose, if you passed 0). */
+    readonly host: string;
+    readonly localPort: number;
+    /** The port inside the sandbox. */
+    readonly port: number;
+    /** Stops listening and closes every forwarded connection. */
+    close(): Promise<void>;
+};
+export declare class Tunnel {
+    #private;
+    private readonly socket;
+    readonly closed: Promise<string>;
+    private constructor();
+    /** Waits for the server's ready message. */
+    static open(socket: WebSocket): Promise<Tunnel>;
+    /** A TCP connection to `port` on the sandbox's loopback (127.0.0.1, then ::1). */
+    connect(port: number): Promise<TunnelStream>;
+    /** An SSH login as the sandbox's user, authorized by this one public key
+     * (the text of an OpenSSH `.pub` file). Speak SSH over the stream. */
+    ssh(publicKey: string): Promise<TunnelStream>;
+    /** Listens on a local port and carries each connection to `port` in the
+     * sandbox. Node and Bun only. A connection the sandbox cannot open, such as
+     * one to a port nothing listens on, is closed at once; `onError` says why. */
+    forward(port: number, options?: {
+        localPort?: number;
+        host?: string;
+        onError?: (error: RuntimeError) => void;
+    }): Promise<PortForward>;
+    /** Closes the tunnel and every connection in it. */
+    close(): void;
+    /** @internal Data for one stream, within the window. */
+    send(id: number, data: Uint8Array): Promise<void>;
+    /** @internal End or close, in order behind any data still waiting. */
+    control(kind: number, id: number): Promise<void>;
+    /** @internal */
+    forget(id: number): void;
+    private receive;
+    private end;
+}

package/dist/tunnel.js

@@ -0,0 +1,316 @@
+import { RuntimeError } from "./errors.js";
+/* A tunnel into a sandbox: one WebSocket carrying many TCP connections to
+   ports on the sandbox's loopback, and SSH logins. The server end and the
+   protocol are documented in packages/cloud/src/api/tunnels.ts. */
+const OPEN = 0x6f;
+const DATA = 0x64;
+const END = 0x65;
+const CLOSE = 0x63;
+const ACK = 0x61;
+const LOG = 0x6c;
+/** Data this side may send past the sandbox's last report of what it took. */
+const WINDOW = 1_048_576;
+const CHUNK = 65_536;
+function frame(kind, stream, payload = new Uint8Array()) {
+    const out = new Uint8Array(5 + payload.length);
+    out[0] = kind;
+    new DataView(out.buffer).setUint32(1, stream);
+    out.set(payload, 5);
+    return out;
+}
+/** One TCP connection (or SSH login) inside a tunnel. Set the handlers before
+ * data can arrive, which is as soon as the promise that gave you this resolves. */
+export class TunnelStream {
+    tunnel;
+    id;
+    /** Bytes from the sandbox side. */
+    onData;
+    /** The sandbox side will send nothing more; you may still write. */
+    onEnd;
+    /** The connection is gone. `reason` is "done" after a clean finish. */
+    onClose;
+    /** sshd's own error output, for an SSH login that fails. */
+    onLog;
+    #ended = false;
+    #remoteEnded = false;
+    #closed = false;
+    constructor(tunnel, id) {
+        this.tunnel = tunnel;
+        this.id = id;
+    }
+    /** Sends bytes. Resolves once they are within the tunnel's window, so
+     * awaiting each write is enough backpressure. */
+    write(data) {
+        if (this.#ended || this.#closed)
+            return Promise.resolve();
+        return this.tunnel.send(this.id, data);
+    }
+    /** No more bytes from this side; the sandbox side reads end of input. */
+    end() {
+        if (this.#ended || this.#closed)
+            return;
+        this.#ended = true;
+        void this.tunnel.control(END, this.id);
+    }
+    /** Drops the connection at once. After both sides have ended, the sandbox
+     * finishes it by itself, so a close then would only race the last bytes. */
+    close() {
+        if (this.#closed)
+            return;
+        const finishing = this.#ended && this.#remoteEnded;
+        this.#closed = true;
+        if (!finishing)
+            void this.tunnel.control(CLOSE, this.id);
+        this.tunnel.forget(this.id);
+    }
+    /** @internal */
+    receive(kind, payload) {
+        if (kind === DATA)
+            this.onData?.(payload);
+        else if (kind === LOG)
+            this.onLog?.(new TextDecoder().decode(payload));
+        else if (kind === END) {
+            this.#remoteEnded = true;
+            this.onEnd?.();
+        }
+        else if (kind === CLOSE)
+            this.gone(new TextDecoder().decode(payload) || "closed");
+    }
+    /** @internal */
+    gone(reason) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.tunnel.forget(this.id);
+        this.onClose?.(reason);
+    }
+}
+export class Tunnel {
+    socket;
+    closed;
+    #streams = new Map();
+    #opening = new Map();
+    #next = 1;
+    #sent = 0;
+    #credited = 0;
+    #waiting = [];
+    #sending = Promise.resolve();
+    #over;
+    constructor(socket, closed) {
+        this.socket = socket;
+        this.closed = closed;
+    }
+    /** Waits for the server's ready message. */
+    static open(socket) {
+        socket.binaryType = "arraybuffer";
+        let settle;
+        const closed = new Promise((resolve) => (settle = resolve));
+        return new Promise((resolve, reject) => {
+            let tunnel;
+            let failure;
+            socket.onmessage = (event) => {
+                if (typeof event.data === "string") {
+                    const message = JSON.parse(event.data);
+                    if (message.type === "ready" && !tunnel) {
+                        tunnel = new Tunnel(socket, closed);
+                        resolve(tunnel);
+                    }
+                    else if (message.type === "error") {
+                        failure = new RuntimeError({
+                            message: message.error?.message ?? "The tunnel failed.",
+                            code: message.error?.code ?? "tunnel_failed",
+                            status: 0,
+                            ...(message.error?.hint ? { hint: message.error.hint } : {}),
+                            ...(message.error?.requestId ? { requestId: message.error.requestId } : {}),
+                        });
+                        if (!tunnel)
+                            reject(failure);
+                    }
+                }
+                else
+                    tunnel?.receive(new Uint8Array(event.data));
+            };
+            socket.onclose = () => {
+                const reason = failure?.message ?? "The tunnel closed.";
+                tunnel?.end(reason);
+                settle(reason);
+                if (!tunnel)
+                    reject(new RuntimeError({
+                        message: "The tunnel could not be opened: check the key, that the sandbox is running, and that your organization has fewer than 16 tunnels open.",
+                        code: "tunnel_refused",
+                        status: 0,
+                    }));
+            };
+            socket.onerror = () => undefined;
+        });
+    }
+    /** A TCP connection to `port` on the sandbox's loopback (127.0.0.1, then ::1). */
+    connect(port) {
+        if (!Number.isSafeInteger(port) || port < 1 || port > 65_535)
+            return Promise.reject(new RuntimeError({
+                message: "port must be 1 to 65535.",
+                code: "invalid_request",
+                status: 0,
+            }));
+        return this.#open(`tcp ${port}`, port);
+    }
+    /** An SSH login as the sandbox's user, authorized by this one public key
+     * (the text of an OpenSSH `.pub` file). Speak SSH over the stream. */
+    ssh(publicKey) {
+        return this.#open(`ssh ${publicKey.trim()}`);
+    }
+    /** Listens on a local port and carries each connection to `port` in the
+     * sandbox. Node and Bun only. A connection the sandbox cannot open, such as
+     * one to a port nothing listens on, is closed at once; `onError` says why. */
+    async forward(port, options = {}) {
+        const net = await import("node:net");
+        const host = options.host ?? "127.0.0.1";
+        const sockets = new Set();
+        // Half-open: a client that ends its input still gets the answer.
+        const server = net.createServer({ allowHalfOpen: true }, (socket) => {
+            sockets.add(socket);
+            socket.pause();
+            socket.on("error", () => undefined);
+            socket.on("close", () => sockets.delete(socket));
+            this.connect(port).then((stream) => {
+                stream.onData = (data) => void socket.write(data);
+                stream.onEnd = () => void socket.end();
+                // "done" follows the last data; ending lets the socket flush it.
+                stream.onClose = (reason) => void (reason === "done" ? socket.end() : socket.destroy());
+                socket.on("data", (data) => {
+                    socket.pause();
+                    void stream.write(new Uint8Array(data)).then(() => socket.resume());
+                });
+                socket.on("end", () => stream.end());
+                socket.on("close", () => stream.close());
+                socket.resume();
+            }, (error) => {
+                socket.destroy();
+                if (error instanceof RuntimeError)
+                    options.onError?.(error);
+            });
+        });
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.localPort ?? port, host, () => resolve());
+        });
+        const address = server.address();
+        return {
+            host,
+            localPort: typeof address === "object" && address ? address.port : (options.localPort ?? port),
+            port,
+            close: () => new Promise((resolve) => {
+                for (const socket of sockets)
+                    socket.destroy();
+                server.close(() => resolve());
+            }),
+        };
+    }
+    /** Closes the tunnel and every connection in it. */
+    close() {
+        this.socket.close(1000);
+    }
+    #open(target, port) {
+        if (this.#over)
+            return Promise.reject(new RuntimeError({ message: this.#over, code: "tunnel_closed", status: 0 }));
+        const id = this.#next++;
+        return new Promise((resolve, reject) => {
+            this.#opening.set(id, {
+                resolve,
+                reject: (error) => reject(port !== undefined && error.message === "closed"
+                    ? new RuntimeError({
+                        message: `Nothing is listening on port ${port} in the sandbox.`,
+                        code: "port_closed",
+                        status: 0,
+                        hint: "Start the server with spawn (`runtime sandbox spawn <id> -- <command>`, sbx.spawn()), which keeps it running: a process started by exec ends with its command. Let it listen on 127.0.0.1, ::1 or every address.",
+                    })
+                    : error.message === "reserved"
+                        ? new RuntimeError({
+                            message: `Port ${port} is the sandbox's own outbound proxy, which a tunnel does not reach.`,
+                            code: "port_reserved",
+                            status: 0,
+                        })
+                        : error.message === "no-sshd"
+                            ? new RuntimeError({
+                                message: "The sandbox has no OpenSSH server (sshd).",
+                                code: "sshd_missing",
+                                status: 0,
+                                hint: "Install it once: sudo apt-get install -y openssh-server",
+                            })
+                            : new RuntimeError({
+                                message: `The sandbox refused the connection (${error.message}).`,
+                                code: "tunnel_refused",
+                                status: 0,
+                            })),
+            });
+            this.#write(frame(OPEN, id, new TextEncoder().encode(target)));
+        });
+    }
+    /** @internal Data for one stream, within the window. */
+    send(id, data) {
+        const sending = this.#sending.then(async () => {
+            for (let at = 0; at < data.length && !this.#over; at += CHUNK) {
+                const piece = data.subarray(at, at + CHUNK);
+                while (this.#sent + piece.length - this.#credited > WINDOW && !this.#over)
+                    await new Promise((resolve) => this.#waiting.push(resolve));
+                if (this.#over)
+                    return;
+                this.#sent += piece.length;
+                this.#write(frame(DATA, id, piece));
+            }
+        });
+        this.#sending = sending.catch(() => undefined);
+        return sending;
+    }
+    /** @internal End or close, in order behind any data still waiting. */
+    control(kind, id) {
+        const sending = this.#sending.then(() => this.#write(frame(kind, id)));
+        this.#sending = sending.catch(() => undefined);
+        return sending;
+    }
+    /** @internal */
+    forget(id) {
+        this.#streams.delete(id);
+    }
+    #write(bytes) {
+        if (!this.#over && this.socket.readyState === 1)
+            this.socket.send(bytes);
+    }
+    receive(message) {
+        if (message.length < 5)
+            return;
+        const kind = message[0];
+        const view = new DataView(message.buffer, message.byteOffset, message.length);
+        const id = view.getUint32(1);
+        const payload = message.subarray(5);
+        if (kind === ACK) {
+            this.#credited = Math.max(this.#credited, Number(view.getBigUint64(5)));
+            for (const wake of this.#waiting.splice(0))
+                wake();
+            return;
+        }
+        const opening = this.#opening.get(id);
+        if (opening) {
+            this.#opening.delete(id);
+            if (kind === OPEN) {
+                const stream = new TunnelStream(this, id);
+                this.#streams.set(id, stream);
+                opening.resolve(stream);
+            }
+            else
+                opening.reject(new Error(new TextDecoder().decode(payload) || "closed"));
+            return;
+        }
+        this.#streams.get(id)?.receive(kind, payload);
+    }
+    end(reason) {
+        this.#over = reason;
+        for (const wake of this.#waiting.splice(0))
+            wake();
+        for (const { reject } of this.#opening.values())
+            reject(new Error(reason));
+        this.#opening.clear();
+        for (const stream of [...this.#streams.values()])
+            stream.gone(reason);
+    }
+}