sbox-sdk 0.0.2

package/dist/internal/sandbox.js

@@ -0,0 +1,438 @@
+/**
+ * Wires a provider's `DriverHandle` into the public namespaced `Sandbox`:
+ * builds the sub-API facades, enforces capability gating (fail-fast
+ * NotSupportedError + type-level `undefined`), and silently polyfills universal
+ * filesystem ops via `exec` where the adapter doesn't implement them natively.
+ */
+import { assertCapability, freezeCapabilities, isCapable, } from "./capabilities.js";
+import { NotSupportedError, SandboxError } from "./errors.js";
+import { createExecHandle } from "./exec.js";
+import { buildExecCommand, joinCmd, parseLsOutput, parseStatOutput, shellQuote, } from "./shell.js";
+export function buildSandbox(provider, handle, base, setup = {}) {
+    const caps = freezeCapabilities(provider.capabilities, provider.flags);
+    const { name } = provider;
+    const mkCtx = (signal) => ({
+        attempt: 1,
+        fetch: base.fetch,
+        metadata: base.defaultMetadata,
+        signal,
+    });
+    const wrapErr = (e) => provider.mapError?.(e) ?? SandboxError.wrap(e, name);
+    const guard = async (fn) => {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            throw wrapErr(error);
+        }
+    };
+    const runExec = (command, opts = {}) => {
+        const built = buildExecCommand(command, opts, provider.flags);
+        const source = handle.exec(built.command, built.execOptions, mkCtx(opts.signal));
+        return createExecHandle(source, {
+            mapError: wrapErr,
+            parseExitMarker: built.parseExitMarker,
+        });
+    };
+    const commands = {
+        async connect(processId) {
+            if (!handle.connectProcess) {
+                throw new NotSupportedError(name, "commands.connect");
+            }
+            const proc = await guard(() => handle.connectProcess(processId, mkCtx()));
+            return makeProcess(proc, wrapErr);
+        },
+        async kill(processId, signal) {
+            if (!handle.killProcess) {
+                throw new NotSupportedError(name, "commands.kill");
+            }
+            await guard(() => handle.killProcess(processId, signal, mkCtx()));
+        },
+        async list() {
+            if (!handle.listProcesses) {
+                throw new NotSupportedError(name, "commands.list");
+            }
+            return guard(() => handle.listProcesses(mkCtx()));
+        },
+        run(cmd, opts = {}) {
+            const built = buildExecCommand(joinCmd(cmd), opts, provider.flags);
+            const source = handle.exec(built.command, built.execOptions, mkCtx(opts.signal));
+            return createExecHandle(source, {
+                mapError: wrapErr,
+                onStderr: opts.onStderr,
+                onStdout: opts.onStdout,
+                parseExitMarker: built.parseExitMarker,
+            });
+        },
+        async spawn(cmd, opts = {}) {
+            if (handle.spawn) {
+                const proc = await guard(() => handle.spawn(joinCmd(cmd), opts, mkCtx(opts.signal)));
+                return makeProcess(proc, wrapErr);
+            }
+            assertCapability(name, caps, "background", "commands.spawn");
+            throw new NotSupportedError(name, "commands.spawn");
+        },
+    };
+    const files = {
+        async download(path) {
+            if (handle.download) {
+                const stream = await guard(() => handle.download(path, mkCtx()));
+                return storedFileFromBytes(path, await drain(stream));
+            }
+            return files.read(path);
+        },
+        async exists(path) {
+            try {
+                await files.stat(path);
+                return true;
+            }
+            catch (error) {
+                if (error instanceof SandboxError && error.code === "NotFound") {
+                    return false;
+                }
+                throw error;
+            }
+        },
+        async list(path) {
+            if (handle.listDir) {
+                return guard(() => handle.listDir(path, mkCtx()));
+            }
+            const res = await runExec(`ls -1Ap ${shellQuote(path)}`);
+            if (res.exitCode !== 0) {
+                throw new SandboxError("NotFound", `cannot list '${path}'`, {
+                    provider: name,
+                });
+            }
+            return parseLsOutput(res.stdout, path);
+        },
+        async mkdir(path, opts) {
+            if (handle.mkdir) {
+                await guard(() => handle.mkdir(path, opts?.recursive ?? false, mkCtx()));
+                return;
+            }
+            const res = await runExec(`mkdir ${opts?.recursive ? "-p " : ""}${shellQuote(path)}`);
+            if (res.exitCode !== 0) {
+                throw new SandboxError("Provider", `mkdir failed: ${res.stderr}`, {
+                    provider: name,
+                });
+            }
+        },
+        async read(path) {
+            const bytes = await guard(() => handle.readFile(path, mkCtx()));
+            return storedFileFromBytes(path, bytes);
+        },
+        async remove(path, opts) {
+            if (handle.remove) {
+                await guard(() => handle.remove(path, opts?.recursive ?? false, mkCtx()));
+                return;
+            }
+            const res = await runExec(`rm ${opts?.recursive ? "-rf " : "-f "}${shellQuote(path)}`);
+            if (res.exitCode !== 0) {
+                throw new SandboxError("Provider", `rm failed: ${res.stderr}`, {
+                    provider: name,
+                });
+            }
+        },
+        async rename(from, to) {
+            if (handle.rename) {
+                await guard(() => handle.rename(from, to, mkCtx()));
+                return;
+            }
+            const res = await runExec(`mv ${shellQuote(from)} ${shellQuote(to)}`);
+            if (res.exitCode !== 0) {
+                throw new SandboxError("Provider", `mv failed: ${res.stderr}`, {
+                    provider: name,
+                });
+            }
+        },
+        async stat(path) {
+            if (handle.stat) {
+                return guard(() => handle.stat(path, mkCtx()));
+            }
+            const res = await runExec(`stat -c '%F|%s|%Y' ${shellQuote(path)}`);
+            if (res.exitCode !== 0) {
+                throw new SandboxError("NotFound", `not found: '${path}'`, {
+                    provider: name,
+                });
+            }
+            const parsed = parseStatOutput(res.stdout);
+            if (!parsed) {
+                throw new SandboxError("Provider", `cannot stat '${path}'`, {
+                    provider: name,
+                });
+            }
+            return {
+                mtime: parsed.mtime,
+                path,
+                size: parsed.size,
+                type: parsed.type,
+            };
+        },
+        async upload(path, body) {
+            if (handle.upload) {
+                await guard(() => handle.upload(path, body, mkCtx()));
+                return;
+            }
+            await files.write(path, body);
+        },
+        async watch(path, cb, opts) {
+            assertCapability(name, caps, "filesWatch", "files.watch");
+            if (!handle.watch) {
+                throw new NotSupportedError(name, "files.watch");
+            }
+            const stop = await guard(() => handle.watch(path, cb, opts?.recursive ?? false, mkCtx()));
+            return {
+                close: async () => {
+                    await stop();
+                },
+            };
+        },
+        async write(path, data) {
+            const bytes = await toBytes(data);
+            await guard(() => handle.writeFile(path, bytes, mkCtx()));
+        },
+    };
+    const code = {
+        async createContext(opts) {
+            assertCapability(name, caps, "codeInterpreter", "code.createContext");
+            if (!handle.createContext) {
+                throw new NotSupportedError(name, "code.createContext");
+            }
+            return guard(() => handle.createContext(opts ?? {}, mkCtx()));
+        },
+        async runCode(codeStr, opts) {
+            assertCapability(name, caps, "codeInterpreter", "code.runCode");
+            if (!handle.runCode) {
+                throw new NotSupportedError(name, "code.runCode");
+            }
+            return guard(() => handle.runCode(codeStr, opts ?? {}, mkCtx()));
+        },
+    };
+    const ports = {
+        async expose(port, opts) {
+            assertCapability(name, caps, "exposePort", "ports.expose");
+            if (!handle.exposePort) {
+                throw new NotSupportedError(name, "ports.expose");
+            }
+            return guard(() => handle.exposePort(port, { private: opts?.private }, mkCtx()));
+        },
+        async fetch(port, path, init) {
+            if (handle.proxyFetch) {
+                return guard(() => handle.proxyFetch(port, path, init, mkCtx()));
+            }
+            const preview = await ports.expose(port);
+            return base.fetch(new URL(path ?? "/", preview.url).toString(), init);
+        },
+        async list() {
+            if (!handle.listPorts) {
+                throw new NotSupportedError(name, "ports.list");
+            }
+            return guard(() => handle.listPorts(mkCtx()));
+        },
+        async unexpose(port) {
+            if (!handle.unexposePort) {
+                throw new NotSupportedError(name, "ports.unexpose");
+            }
+            await guard(() => handle.unexposePort(port, mkCtx()));
+        },
+    };
+    const snapshots = {
+        async create(opts) {
+            assertCapability(name, caps, "snapshot", "snapshots.create");
+            if (!handle.snapshot) {
+                throw new NotSupportedError(name, "snapshots.create");
+            }
+            return guard(() => handle.snapshot({ name: opts?.name }, mkCtx()));
+        },
+        async delete(ref) {
+            if (!handle.deleteSnapshot) {
+                throw new NotSupportedError(name, "snapshots.delete");
+            }
+            await guard(() => handle.deleteSnapshot(refId(ref), mkCtx()));
+        },
+        async fork(count) {
+            if (!handle.fork) {
+                throw new NotSupportedError(name, "snapshots.fork");
+            }
+            const handles = await guard(() => handle.fork(count ?? 1, mkCtx()));
+            return handles.map((h) => buildSandbox(provider, h, base));
+        },
+        async list() {
+            if (!handle.listSnapshots) {
+                throw new NotSupportedError(name, "snapshots.list");
+            }
+            return guard(() => handle.listSnapshots(mkCtx()));
+        },
+        async restore(ref) {
+            if (!handle.restoreSnapshot) {
+                throw new NotSupportedError(name, "snapshots.restore");
+            }
+            await guard(() => handle.restoreSnapshot(refId(ref), mkCtx()));
+        },
+    };
+    const network = {
+        async createSsh() {
+            assertCapability(name, caps, "ssh", "network.createSsh");
+            if (!handle.createSsh) {
+                throw new NotSupportedError(name, "network.createSsh");
+            }
+            return guard(() => handle.createSsh(mkCtx()));
+        },
+        async setEgressPolicy(policy) {
+            assertCapability(name, caps, "egressControl", "network.setEgressPolicy");
+            if (!handle.setEgressPolicy) {
+                throw new NotSupportedError(name, "network.setEgressPolicy");
+            }
+            await guard(() => handle.setEgressPolicy(policy, mkCtx()));
+        },
+    };
+    const sandbox = {
+        can: ((cap) => isCapable(caps, cap)),
+        capabilities: caps,
+        code: (isCapable(caps, "codeInterpreter") ? code : undefined),
+        commands,
+        destroy: () => guard(() => handle.destroy(mkCtx())),
+        files,
+        getInfo: () => guard(() => handle.getInfo(mkCtx())),
+        id: handle.id,
+        name: handle.name,
+        network: (isCapable(caps, "egressControl")
+            ? network
+            : undefined),
+        async pause() {
+            assertCapability(name, caps, "pause", "pause");
+            if (!handle.pause) {
+                throw new NotSupportedError(name, "pause");
+            }
+            await guard(() => handle.pause(mkCtx()));
+        },
+        ports: (isCapable(caps, "exposePort") ? ports : undefined),
+        provider: name,
+        raw: () => handle.raw,
+        async resume() {
+            if (!handle.resume) {
+                throw new NotSupportedError(name, "resume");
+            }
+            await guard(() => handle.resume(mkCtx()));
+        },
+        async setTimeout(ttlMs) {
+            assertCapability(name, caps, "setTimeout", "setTimeout");
+            if (!handle.setTimeout) {
+                throw new NotSupportedError(name, "setTimeout");
+            }
+            await guard(() => handle.setTimeout(ttlMs, mkCtx()));
+        },
+        snapshots: (isCapable(caps, "snapshot")
+            ? snapshots
+            : undefined),
+        async stop() {
+            assertCapability(name, caps, "stop", "stop");
+            if (!handle.stop) {
+                throw new NotSupportedError(name, "stop");
+            }
+            await guard(() => handle.stop(mkCtx()));
+        },
+    };
+    // Plugins: graft contributions onto the sandbox (e.g. `sandbox.tools`), and
+    // wrap destroy() to run onDestroy hooks first.
+    const { plugins } = base;
+    if (plugins && plugins.length > 0) {
+        const asBase = sandbox;
+        for (const p of plugins) {
+            if (p.extend) {
+                Object.assign(sandbox, p.extend(asBase, setup));
+            }
+        }
+        const teardown = plugins.filter((p) => p.onDestroy);
+        if (teardown.length > 0) {
+            const inner = sandbox.destroy.bind(sandbox);
+            sandbox.destroy = async () => {
+                for (const p of teardown) {
+                    await p.onDestroy?.(asBase);
+                }
+                await inner();
+            };
+        }
+    }
+    return sandbox;
+}
+// --------------------------------------------------------------------------
+// helpers
+// --------------------------------------------------------------------------
+function refId(ref) {
+    return typeof ref === "string" ? ref : ref.id;
+}
+async function toBytes(body) {
+    if (typeof body === "string") {
+        return new TextEncoder().encode(body);
+    }
+    if (body instanceof Uint8Array) {
+        return body;
+    }
+    return drain(body);
+}
+async function drain(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        if (value) {
+            chunks.push(value);
+            total += value.length;
+        }
+    }
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}
+function storedFileFromBytes(path, bytes) {
+    return {
+        async bytes() {
+            return bytes;
+        },
+        path,
+        stream() {
+            return new ReadableStream({
+                start(controller) {
+                    controller.enqueue(bytes);
+                    controller.close();
+                },
+            });
+        },
+        async text() {
+            return new TextDecoder().decode(bytes);
+        },
+    };
+}
+function makeProcess(proc, mapError) {
+    const handle = createExecHandle(proc, { mapError });
+    return {
+        id: proc.id,
+        kill: (signal) => proc.kill(signal),
+        stderr: filterText(handle, "stderr"),
+        stdout: filterText(handle, "stdout"),
+        wait: () => handle,
+        async writeStdin(data) {
+            await handle.writeStdin(data);
+        },
+    };
+}
+function filterText(handle, kind) {
+    return {
+        async *[Symbol.asyncIterator]() {
+            for await (const ev of handle) {
+                if (ev.type === kind) {
+                    yield ev.data;
+                }
+            }
+        },
+    };
+}

package/dist/internal/shell.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shell emulation primitives. These build command STRINGS that run INSIDE the
+ * remote sandbox via the adapter's `exec` — there is no local `child_process`
+ * here. All interpolated values are single-quoted with `shellQuote` so user
+ * input cannot break out of the intended command.
+ */
+import type { CapabilityFlags } from "./capabilities.js";
+import type { DirEntry, ExecOptions } from "./types.js";
+export declare const EXIT_MARKER = "__sbox_rc";
+/** POSIX-safe single-quote escaping: wrap in '...', and encode embedded quotes. */
+export declare function shellQuote(value: string): string;
+export declare function joinCmd(cmd: string | string[]): string;
+export interface BuiltExec {
+    /** The command string to hand to the adapter's exec. */
+    command: string;
+    /** The ExecOptions to pass to the adapter (cwd/env stripped if baked into the command). */
+    execOptions: ExecOptions;
+    /** Whether the core should parse an exit-code marker out of stdout. */
+    parseExitMarker: boolean;
+}
+/**
+ * Decide how a command is executed given a provider's behavioral flags:
+ * - native cwd/env  -> pass cwd/env straight through as ExecOptions
+ * - emulated cwd/env -> bake `cd ... && export ...; cmd` into a `sh -c` string
+ * - non-native exit code -> append `; echo __sbox_rc=$?` for the core to parse
+ */
+export declare function buildExecCommand(rawCmd: string, opts: ExecOptions, flags: CapabilityFlags): BuiltExec;
+/** Parse `ls -1Ap <dir>` output (names; dirs have a trailing slash) into DirEntry[]. */
+export declare function parseLsOutput(output: string, dir: string): DirEntry[];
+/** Parse `stat -c '%F|%s|%Y' <path>` (GNU coreutils, Linux sandboxes). */
+export declare function parseStatOutput(output: string): {
+    type: "file" | "dir" | "symlink";
+    size: number;
+    mtime?: Date;
+} | null;
+//# sourceMappingURL=shell.d.ts.map

package/dist/internal/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/internal/shell.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,eAAO,MAAM,WAAW,cAAc,CAAC;AAEvC,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,CAEtD;AAED,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,WAAW,EAAE,WAAW,CAAC;IACzB,uEAAuE;IACvE,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,eAAe,GACrB,SAAS,CAsCX;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,EAAE,CAiBrE;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAmBzE"}

package/dist/internal/shell.js

@@ -0,0 +1,88 @@
+export const EXIT_MARKER = "__sbox_rc";
+/** POSIX-safe single-quote escaping: wrap in '...', and encode embedded quotes. */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+export function joinCmd(cmd) {
+    return Array.isArray(cmd) ? cmd.map(shellQuote).join(" ") : cmd;
+}
+/**
+ * Decide how a command is executed given a provider's behavioral flags:
+ * - native cwd/env  -> pass cwd/env straight through as ExecOptions
+ * - emulated cwd/env -> bake `cd ... && export ...; cmd` into a `sh -c` string
+ * - non-native exit code -> append `; echo __sbox_rc=$?` for the core to parse
+ */
+export function buildExecCommand(rawCmd, opts, flags) {
+    const needsExitMarker = !flags.exitCodeNative;
+    const hasCwd = !!opts.cwd;
+    const hasEnv = !!opts.env && Object.keys(opts.env).length > 0;
+    const emulateCwdEnv = !flags.perCommandEnvCwd && (hasCwd || hasEnv);
+    if (!emulateCwdEnv && !needsExitMarker) {
+        return { command: rawCmd, execOptions: opts, parseExitMarker: false };
+    }
+    let inner = rawCmd;
+    if (needsExitMarker) {
+        inner = `${inner}; echo ${EXIT_MARKER}=$?`;
+    }
+    if (emulateCwdEnv) {
+        if (hasEnv) {
+            const exports = Object.entries(opts.env)
+                .map(([k, v]) => `export ${k}=${shellQuote(v)};`)
+                .join(" ");
+            inner = `${exports} ${inner}`;
+        }
+        if (hasCwd) {
+            inner = `cd ${shellQuote(opts.cwd)} && ${inner}`;
+        }
+    }
+    // Strip the now-baked cwd/env from the options handed to the adapter.
+    const execOptions = { ...opts };
+    if (emulateCwdEnv) {
+        delete execOptions.cwd;
+        delete execOptions.env;
+    }
+    return {
+        command: `sh -c ${shellQuote(inner)}`,
+        execOptions,
+        parseExitMarker: needsExitMarker,
+    };
+}
+/** Parse `ls -1Ap <dir>` output (names; dirs have a trailing slash) into DirEntry[]. */
+export function parseLsOutput(output, dir) {
+    const base = dir.endsWith("/") ? dir.slice(0, -1) : dir;
+    const entries = [];
+    for (const line of output.split("\n")) {
+        const name = line.trimEnd();
+        if (!name) {
+            continue;
+        }
+        const isDir = name.endsWith("/");
+        const clean = isDir ? name.slice(0, -1) : name;
+        entries.push({
+            name: clean,
+            path: `${base}/${clean}`,
+            type: isDir ? "dir" : "file",
+        });
+    }
+    return entries;
+}
+/** Parse `stat -c '%F|%s|%Y' <path>` (GNU coreutils, Linux sandboxes). */
+export function parseStatOutput(output) {
+    const parts = output.trim().split("|");
+    if (parts.length < 2) {
+        return null;
+    }
+    const kind = parts[0] ?? "";
+    const size = Number(parts[1] ?? "0");
+    const mtimeEpoch = parts[2] ? Number(parts[2]) : undefined;
+    const type = kind === "directory"
+        ? "dir"
+        : kind.includes("symbolic")
+            ? "symlink"
+            : "file";
+    return {
+        mtime: mtimeEpoch ? new Date(mtimeEpoch * 1000) : undefined,
+        size: Number.isFinite(size) ? size : 0,
+        type,
+    };
+}

package/dist/internal/stream.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared push-to-pull bridge for adapters: provider SDKs deliver output via
+ * push callbacks or their own async iterables, while the core consumes a single
+ * `AsyncIterable<OutputEvent>`. `AsyncQueue` adapts the former to the latter.
+ */
+export declare class AsyncQueue<T> {
+    #private;
+    push(item: T): void;
+    close(): void;
+    fail(err: unknown): void;
+    iterator(): AsyncGenerator<T>;
+}
+/** Best-effort exit code from a thrown provider error that carries one. */
+export declare function numExit(e: unknown): number;
+//# sourceMappingURL=stream.d.ts.map

package/dist/internal/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/internal/stream.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,UAAU,CAAC,CAAC;;IAMvB,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAInB,KAAK,IAAI,IAAI;IAIb,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAYjB,QAAQ,IAAI,cAAc,CAAC,CAAC,CAAC;CAiBrC;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAQ1C"}

package/dist/internal/stream.js

@@ -0,0 +1,58 @@
+/**
+ * Shared push-to-pull bridge for adapters: provider SDKs deliver output via
+ * push callbacks or their own async iterables, while the core consumes a single
+ * `AsyncIterable<OutputEvent>`. `AsyncQueue` adapts the former to the latter.
+ */
+export class AsyncQueue {
+    #items = [];
+    #wakers = [];
+    #closed = false;
+    #err = null;
+    push(item) {
+        this.#items.push(item);
+        this.#wake();
+    }
+    close() {
+        this.#closed = true;
+        this.#wake();
+    }
+    fail(err) {
+        this.#err = err;
+        this.#closed = true;
+        this.#wake();
+    }
+    #wake() {
+        const w = this.#wakers;
+        this.#wakers = [];
+        for (const f of w) {
+            f();
+        }
+    }
+    async *iterator() {
+        let i = 0;
+        for (;;) {
+            while (i < this.#items.length) {
+                const item = this.#items[i];
+                i++;
+                yield item;
+            }
+            if (this.#closed) {
+                if (this.#err) {
+                    throw this.#err;
+                }
+                return;
+            }
+            await new Promise((r) => this.#wakers.push(r));
+        }
+    }
+}
+/** Best-effort exit code from a thrown provider error that carries one. */
+export function numExit(e) {
+    if (e && typeof e === "object" && "exitCode" in e) {
+        const code = e.exitCode;
+        if (typeof code === "number" && Number.isFinite(code)) {
+            return code;
+        }
+    }
+    return 1;
+}