@schemavaults/sandbox-management-sdk 0.0.0-stage → 0.1.0

package/dist/docker/provider.d.ts

@@ -0,0 +1,101 @@
+import Docker from "dockerode";
+import type { MainLogChunk, ProviderCreateInput, ProviderCreateResult, ProviderSandbox, ProviderSandboxStatus, ResolvedSandboxFile, SandboxProvider } from "../provider.js";
+import type { ExecOptions, ExecResult, MainProcessInfo, NormalizedCommand } from "../types.js";
+export type DockerPullPolicy = "if-not-present" | "always" | "never";
+/** Per-sandbox options, set as `spec.providerOptions.docker`. */
+export interface DockerSandboxOptions {
+    /** Image to run. Must provide `/bin/sh`; `git` is needed for `spec.git`. */
+    image?: string;
+    /** User commands run as (container `User`). */
+    user?: string;
+    /**
+     * Docker network to attach the container to. With a `spec.network`
+     * allowlist, this is the network the egress proxy reaches the outside
+     * through instead (default `"bridge"`). Leave it unset for `"deny-all"`.
+     */
+    network?: string;
+    pullPolicy?: DockerPullPolicy;
+    /** Extra container labels. */
+    labels?: Record<string, string>;
+}
+declare module "../types.js" {
+    interface SandboxProviderOptions {
+        docker?: DockerSandboxOptions;
+    }
+}
+export interface DockerSandboxProviderOptions {
+    /** A configured dockerode client. Defaults to `new Docker()` (honors `DOCKER_HOST`). */
+    docker?: Docker;
+    /** Provider name used in sandbox records. Default `"docker"`. */
+    name?: string;
+    /** Image used when the spec does not set one. */
+    defaultImage?: string;
+    /** Default `"/workspace"`. */
+    defaultWorkdir?: string;
+    /** Default `"if-not-present"`. */
+    pullPolicy?: DockerPullPolicy;
+    /** Host interface published ports bind to. Default `"127.0.0.1"`. */
+    portBindingHost?: string;
+    /** Host name used in URLs from `getUrl`. Default `"localhost"`. */
+    urlHost?: string;
+    /** Container name prefix. Default `"sandbox-"`. */
+    containerNamePrefix?: string;
+    /**
+     * Image of the egress proxy that enforces `spec.network` allowlists. Default
+     * `DOCKER_EGRESS_PROXY_IMAGE`, published for each SDK release. Pulled
+     * according to `pullPolicy`.
+     */
+    egressProxyImage?: string;
+    /**
+     * How long to wait for an egress proxy to report healthy. Default 60 seconds.
+     * Docker Engine 25+ reports it within a second; older engines ignore the
+     * image's `--start-interval` and take up to its 30-second interval.
+     */
+    egressProxyStartTimeoutMs?: number;
+}
+export declare const DOCKER_SANDBOX_ID_LABEL = "dev.schemavaults.sandbox.id";
+/**
+ * Runs each sandbox as a long-lived container. `stop` / `wake` map to
+ * `docker stop` / `docker start`, which keep the container filesystem.
+ * Docker has no native timeout: run `SandboxManager.stopExpired()` periodically.
+ *
+ * A sandbox with a `spec.network` allowlist (or `"deny-all"` and `ports`) gets
+ * an internal network of its own, with no route out, and an egress proxy
+ * container (`<name>-egress`) that is its only way to the outside: it enforces
+ * the allowlist for HTTP(S) and forwards the published ports.
+ */
+export declare class DockerSandboxProvider implements SandboxProvider {
+    readonly name: string;
+    readonly defaultWorkdir: string;
+    /** `"deny-all"` without ports is `--network none`; the rest runs behind an egress proxy. */
+    readonly networkPolicies: readonly ["deny-all", "allowlist"];
+    private readonly docker;
+    private readonly defaultImage;
+    private readonly pullPolicy;
+    private readonly portBindingHost;
+    private readonly urlHost;
+    private readonly containerNamePrefix;
+    private readonly egressProxyImage;
+    private readonly egressProxyStartTimeoutMs;
+    constructor(options?: DockerSandboxProviderOptions);
+    create(input: ProviderCreateInput): Promise<ProviderCreateResult>;
+    wake(sandbox: ProviderSandbox): Promise<void>;
+    stop(sandbox: ProviderSandbox): Promise<void>;
+    destroy(sandbox: ProviderSandbox): Promise<void>;
+    status(sandbox: ProviderSandbox): Promise<ProviderSandboxStatus>;
+    exec(sandbox: ProviderSandbox, command: NormalizedCommand, options?: ExecOptions): Promise<ExecResult>;
+    startMainProcess(sandbox: ProviderSandbox, command: NormalizedCommand): Promise<void>;
+    getMainProcess(sandbox: ProviderSandbox): Promise<MainProcessInfo | null>;
+    readMainLog(sandbox: ProviderSandbox, offset: number): Promise<MainLogChunk>;
+    writeFiles(sandbox: ProviderSandbox, files: ResolvedSandboxFile[]): Promise<void>;
+    readFile(sandbox: ProviderSandbox, path: string): Promise<Uint8Array | null>;
+    getUrl(sandbox: ProviderSandbox, port: number): Promise<string>;
+    private container;
+    private inspect;
+    private assertRunning;
+    private findEgressProxy;
+    private requireEgressProxy;
+    /** Waits for the proxy's HEALTHCHECK to pass. An image without one counts as ready once running. */
+    private waitForEgressProxy;
+    private ensureImage;
+}

package/dist/docker/provider.js

@@ -0,0 +1,373 @@
+import Docker from "dockerode";
+import { ProviderSandboxMissingError, ProviderSandboxStoppedError, SandboxError } from "../errors.js";
+import { outputCollector } from "../internal/output.js";
+import { shellGetMainProcess, shellReadMainLog, shellStartMainProcess } from "../shell-main-process.js";
+import { DOCKER_EGRESS_PROXY_IMAGE, DOCKER_EGRESS_PROXY_LABEL, EGRESS_PROXY_ALIAS, SANDBOX_ALIAS, dockerNetworkPlan, egressProxyConfig, egressProxyEnv, usesEgressProxy, } from "./egress.js";
+import { EGRESS_PROXY_CONFIG_ENV } from "./egress-proxy/config.js";
+import { createTar, extractFirstFile } from "./tar.js";
+export const DOCKER_SANDBOX_ID_LABEL = "dev.schemavaults.sandbox.id";
+/** PID 1 of every sandbox container: idle until stopped, exiting promptly on SIGTERM. */
+const KEEPALIVE_SCRIPT = "trap 'exit 0' TERM INT; while :; do sleep 3600 & wait $!; done";
+/**
+ * Runs each sandbox as a long-lived container. `stop` / `wake` map to
+ * `docker stop` / `docker start`, which keep the container filesystem.
+ * Docker has no native timeout: run `SandboxManager.stopExpired()` periodically.
+ *
+ * A sandbox with a `spec.network` allowlist (or `"deny-all"` and `ports`) gets
+ * an internal network of its own, with no route out, and an egress proxy
+ * container (`<name>-egress`) that is its only way to the outside: it enforces
+ * the allowlist for HTTP(S) and forwards the published ports.
+ */
+export class DockerSandboxProvider {
+    name;
+    defaultWorkdir;
+    /** `"deny-all"` without ports is `--network none`; the rest runs behind an egress proxy. */
+    networkPolicies = ["deny-all", "allowlist"];
+    docker;
+    defaultImage;
+    pullPolicy;
+    portBindingHost;
+    urlHost;
+    containerNamePrefix;
+    egressProxyImage;
+    egressProxyStartTimeoutMs;
+    constructor(options = {}) {
+        this.docker = options.docker ?? new Docker();
+        this.name = options.name ?? "docker";
+        this.defaultImage = options.defaultImage;
+        this.defaultWorkdir = options.defaultWorkdir ?? "/workspace";
+        this.pullPolicy = options.pullPolicy ?? "if-not-present";
+        this.portBindingHost = options.portBindingHost ?? "127.0.0.1";
+        this.urlHost = options.urlHost ?? "localhost";
+        this.containerNamePrefix = options.containerNamePrefix ?? "sandbox-";
+        this.egressProxyImage = options.egressProxyImage ?? DOCKER_EGRESS_PROXY_IMAGE;
+        this.egressProxyStartTimeoutMs = options.egressProxyStartTimeoutMs ?? 60_000;
+    }
+    async create(input) {
+        const options = input.spec.providerOptions?.docker ?? {};
+        const image = options.image ?? this.defaultImage;
+        if (!image) {
+            throw new SandboxError("No Docker image: set spec.providerOptions.docker.image or defaultImage");
+        }
+        const plan = dockerNetworkPlan(this, input.spec, options.network);
+        await this.ensureImage(image, options.pullPolicy ?? this.pullPolicy);
+        if (plan.mode === "proxy")
+            await this.ensureImage(this.egressProxyImage, this.pullPolicy);
+        const name = `${this.containerNamePrefix}${input.id}`;
+        const ports = (input.spec.ports ?? []).map((port) => `${port}/tcp`);
+        const exposedPorts = Object.fromEntries(ports.map((port) => [port, {}]));
+        const portBindings = Object.fromEntries(ports.map((port) => [port, [{ HostIp: this.portBindingHost, HostPort: "" }]]));
+        const { vcpus, memoryMb } = input.spec.resources ?? {};
+        const undo = [];
+        try {
+            let env = input.spec.env ?? {};
+            let proxy;
+            let internalNetwork;
+            if (plan.mode === "proxy") {
+                internalNetwork = `${name}-net`;
+                const network = await this.docker.createNetwork({
+                    Name: internalNetwork,
+                    Driver: "bridge",
+                    Internal: true,
+                    Labels: { [DOCKER_EGRESS_PROXY_LABEL]: input.id },
+                });
+                undo.push(() => network.remove());
+                const subnets = (await network.inspect()).IPAM?.Config?.flatMap((config) => config.Subnet ? [config.Subnet] : []);
+                const config = egressProxyConfig(plan, input.spec, subnets ?? []);
+                const egressProxy = await this.docker.createContainer({
+                    name: `${name}-egress`,
+                    Image: this.egressProxyImage,
+                    Env: [`${EGRESS_PROXY_CONFIG_ENV}=${JSON.stringify(config)}`],
+                    Labels: { ...options.labels, [DOCKER_EGRESS_PROXY_LABEL]: input.id },
+                    ExposedPorts: exposedPorts,
+                    HostConfig: {
+                        Init: true,
+                        NetworkMode: plan.outsideNetwork,
+                        PortBindings: portBindings,
+                        ReadonlyRootfs: true,
+                        CapDrop: ["ALL"],
+                        SecurityOpt: ["no-new-privileges"],
+                        RestartPolicy: { Name: "on-failure" },
+                    },
+                });
+                proxy = egressProxy;
+                undo.push(() => egressProxy.remove({ force: true }));
+                await network.connect({ Container: egressProxy.id, EndpointConfig: { Aliases: [EGRESS_PROXY_ALIAS] } });
+                env = { ...egressProxyEnv(plan.proxyPort), ...env };
+            }
+            const container = await this.docker.createContainer({
+                name,
+                Image: image,
+                Entrypoint: ["/bin/sh", "-c", KEEPALIVE_SCRIPT],
+                Cmd: [],
+                WorkingDir: input.workdir,
+                Env: Object.entries(env).map(([key, value]) => `${key}=${value}`),
+                User: options.user,
+                Labels: { ...options.labels, [DOCKER_SANDBOX_ID_LABEL]: input.id },
+                ExposedPorts: exposedPorts,
+                HostConfig: {
+                    Init: true,
+                    // Behind a proxy, the proxy publishes the ports: Docker publishes none from internal networks.
+                    PortBindings: proxy ? {} : portBindings,
+                    Memory: memoryMb ? memoryMb * 1024 * 1024 : undefined,
+                    NanoCpus: vcpus ? Math.round(vcpus * 1e9) : undefined,
+                    NetworkMode: internalNetwork ?? (plan.mode === "direct" ? plan.networkMode : undefined),
+                },
+                NetworkingConfig: internalNetwork
+                    ? { EndpointsConfig: { [internalNetwork]: { Aliases: [SANDBOX_ALIAS] } } }
+                    : undefined,
+            });
+            undo.push(() => container.remove({ force: true }));
+            if (proxy) {
+                await proxy.start();
+                await this.waitForEgressProxy(proxy);
+            }
+            await container.start();
+            return { providerRef: container.id };
+        }
+        catch (error) {
+            for (const step of undo.reverse())
+                await step().catch(() => undefined);
+            throw error;
+        }
+    }
+    async wake(sandbox) {
+        const info = await this.inspect(sandbox);
+        if (usesEgressProxy(sandbox.spec)) {
+            const proxy = await this.requireEgressProxy(sandbox);
+            if (!(await proxy.inspect()).State.Running)
+                await proxy.start();
+            await this.waitForEgressProxy(proxy);
+        }
+        if (!info.State.Running) {
+            await this.container(sandbox).start();
+        }
+    }
+    async stop(sandbox) {
+        const info = await this.inspect(sandbox);
+        if (info.State.Running)
+            await stopContainer(this.container(sandbox));
+        if (usesEgressProxy(sandbox.spec)) {
+            const proxy = await this.findEgressProxy(sandbox);
+            if (proxy)
+                await stopContainer(proxy);
+        }
+    }
+    async destroy(sandbox) {
+        await ignoreNotFound(this.container(sandbox).remove({ force: true, v: true }));
+        // The egress proxy and internal network, if any. Looked up by label so they are removed even if the spec changed.
+        const filters = { label: [`${DOCKER_EGRESS_PROXY_LABEL}=${sandbox.id}`] };
+        for (const proxy of await this.docker.listContainers({ all: true, filters })) {
+            await ignoreNotFound(this.docker.getContainer(proxy.Id).remove({ force: true }));
+        }
+        for (const network of await this.docker.listNetworks({ filters })) {
+            await ignoreNotFound(this.docker.getNetwork(network.Id).remove());
+        }
+    }
+    async status(sandbox) {
+        try {
+            const info = await this.inspect(sandbox);
+            if (!usesEgressProxy(sandbox.spec))
+                return info.State.Running ? "running" : "stopped";
+            // Without its proxy the sandbox cannot reach anything: it only counts as running with it.
+            const proxy = await this.findEgressProxy(sandbox);
+            if (!proxy)
+                return "missing";
+            return info.State.Running && (await proxy.inspect()).State.Running ? "running" : "stopped";
+        }
+        catch (error) {
+            if (error instanceof ProviderSandboxMissingError)
+                return "missing";
+            throw error;
+        }
+    }
+    async exec(sandbox, command, options = {}) {
+        await this.assertRunning(sandbox);
+        const exec = await this.container(sandbox).exec({
+            Cmd: [command.cmd, ...command.args],
+            Env: Object.entries(command.env).map(([key, value]) => `${key}=${value}`),
+            WorkingDir: command.cwd,
+            AttachStdout: true,
+            AttachStderr: true,
+        });
+        const stream = (await exec.start({ hijack: true, stdin: false }));
+        const stdout = outputCollector(options.onStdout);
+        const stderr = outputCollector(options.onStderr);
+        this.docker.modem.demuxStream(stream, stdout.writable, stderr.writable);
+        await waitForStream(stream, options);
+        // The exit code can lag the end of the stream briefly.
+        let info = await exec.inspect();
+        for (let attempt = 0; info.Running && attempt < 50; attempt++) {
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            info = await exec.inspect();
+        }
+        return { exitCode: info.ExitCode ?? -1, stdout: stdout.finish(), stderr: stderr.finish() };
+    }
+    async startMainProcess(sandbox, command) {
+        await shellStartMainProcess((cmd) => this.exec(sandbox, cmd), async (launcher) => {
+            const exec = await this.container(sandbox).exec({
+                Cmd: [launcher.cmd, ...launcher.args],
+                WorkingDir: launcher.cwd,
+            });
+            await exec.start({ Detach: true });
+        }, command);
+    }
+    async getMainProcess(sandbox) {
+        return shellGetMainProcess((cmd) => this.exec(sandbox, cmd));
+    }
+    async readMainLog(sandbox, offset) {
+        return shellReadMainLog((cmd) => this.exec(sandbox, cmd), offset);
+    }
+    async writeFiles(sandbox, files) {
+        await this.assertRunning(sandbox);
+        const tar = createTar(files.map((file) => ({ path: file.path, content: file.content, mode: file.mode })));
+        await this.container(sandbox).putArchive(Buffer.from(tar), { path: "/", copyUIDGID: true });
+    }
+    async readFile(sandbox, path) {
+        await this.assertRunning(sandbox);
+        let stream;
+        try {
+            stream = await this.container(sandbox).getArchive({ path });
+        }
+        catch (error) {
+            if (statusCode(error) === 404)
+                return null;
+            throw error;
+        }
+        const chunks = [];
+        for await (const chunk of stream)
+            chunks.push(Buffer.from(chunk));
+        const file = extractFirstFile(new Uint8Array(Buffer.concat(chunks)));
+        return file?.content ?? null;
+    }
+    async getUrl(sandbox, port) {
+        let info = await this.assertRunning(sandbox);
+        if (usesEgressProxy(sandbox.spec))
+            info = await (await this.requireEgressProxy(sandbox)).inspect();
+        const hostPort = info.NetworkSettings.Ports?.[`${port}/tcp`]?.[0]?.HostPort;
+        if (!hostPort)
+            throw new SandboxError(`Port ${port} is not published on sandbox "${sandbox.id}"`);
+        return `http://${this.urlHost}:${hostPort}`;
+    }
+    container(sandbox) {
+        return this.docker.getContainer(sandbox.providerRef);
+    }
+    async inspect(sandbox) {
+        try {
+            return await this.container(sandbox).inspect();
+        }
+        catch (error) {
+            if (statusCode(error) === 404)
+                throw new ProviderSandboxMissingError(sandbox.providerRef);
+            throw error;
+        }
+    }
+    async assertRunning(sandbox) {
+        const info = await this.inspect(sandbox);
+        if (!info.State.Running)
+            throw new ProviderSandboxStoppedError(sandbox.providerRef);
+        return info;
+    }
+    async findEgressProxy(sandbox) {
+        const [proxy] = await this.docker.listContainers({
+            all: true,
+            filters: { label: [`${DOCKER_EGRESS_PROXY_LABEL}=${sandbox.id}`] },
+        });
+        return proxy ? this.docker.getContainer(proxy.Id) : null;
+    }
+    async requireEgressProxy(sandbox) {
+        const proxy = await this.findEgressProxy(sandbox);
+        if (!proxy) {
+            throw new SandboxError(`The egress proxy of sandbox "${sandbox.id}" no longer exists; destroy and recreate the sandbox`);
+        }
+        return proxy;
+    }
+    /** Waits for the proxy's HEALTHCHECK to pass. An image without one counts as ready once running. */
+    async waitForEgressProxy(proxy) {
+        const deadline = Date.now() + this.egressProxyStartTimeoutMs;
+        for (;;) {
+            const { Name, State } = await proxy.inspect();
+            const health = State.Health?.Status;
+            if (State.Running && (health === undefined || health === "healthy"))
+                return;
+            const name = Name.replace(/^\//, "");
+            if (!State.Running && !State.Restarting) {
+                throw new SandboxError(`Egress proxy ${name} exited with code ${State.ExitCode}; see \`docker logs ${name}\``);
+            }
+            if (health === "unhealthy" || Date.now() > deadline) {
+                throw new SandboxError(`Egress proxy ${name} did not become healthy; see \`docker logs ${name}\``);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    async ensureImage(image, policy) {
+        if (policy === "never")
+            return;
+        if (policy === "if-not-present") {
+            try {
+                await this.docker.getImage(image).inspect();
+                return;
+            }
+            catch (error) {
+                if (statusCode(error) !== 404)
+                    throw error;
+            }
+        }
+        const stream = await this.docker.pull(image);
+        await new Promise((resolve, reject) => {
+            this.docker.modem.followProgress(stream, (error) => (error ? reject(error) : resolve()));
+        });
+        await this.docker.getImage(image).inspect();
+    }
+}
+async function stopContainer(container) {
+    try {
+        await container.stop({ t: 10 });
+    }
+    catch (error) {
+        if (statusCode(error) !== 304)
+            throw error; // 304: already stopped
+    }
+}
+async function ignoreNotFound(operation) {
+    try {
+        await operation;
+    }
+    catch (error) {
+        if (statusCode(error) !== 404)
+            throw error;
+    }
+}
+function statusCode(error) {
+    return typeof error === "object" && error !== null && "statusCode" in error
+        ? error.statusCode
+        : undefined;
+}
+function waitForStream(stream, options) {
+    return new Promise((resolve, reject) => {
+        const timer = options.timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => fail(new SandboxError(`Command timed out after ${options.timeoutMs}ms`)), options.timeoutMs);
+        const onAbort = () => fail(new SandboxError("Command aborted"));
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        if (options.signal?.aborted)
+            return onAbort();
+        stream.once("end", done);
+        stream.once("close", done);
+        stream.once("error", fail);
+        function cleanup() {
+            if (timer)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+        }
+        function done() {
+            cleanup();
+            resolve();
+        }
+        function fail(error) {
+            cleanup();
+            stream.destroy();
+            reject(error);
+        }
+    });
+}

package/dist/docker/tar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal POSIX tar support for Docker's archive endpoints: write regular
+ * files (with PAX headers for long paths) and read back the first file.
+ */
+export interface TarFileEntry {
+    /** Path inside the archive, without a leading slash. */
+    path: string;
+    content: Uint8Array;
+    mode: number;
+}
+export declare function createTar(entries: TarFileEntry[]): Uint8Array;
+export interface TarExtractedFile {
+    path: string;
+    content: Uint8Array;
+}
+/**
+ * The first regular file in the archive. Throws if the archive's first entry
+ * is a directory; resolves `null` for an empty archive.
+ */
+export declare function extractFirstFile(tar: Uint8Array): TarExtractedFile | null;

package/dist/docker/tar.js

@@ -0,0 +1,124 @@
+/**
+ * Minimal POSIX tar support for Docker's archive endpoints: write regular
+ * files (with PAX headers for long paths) and read back the first file.
+ */
+const BLOCK = 512;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function createTar(entries) {
+    const parts = [];
+    const mtime = Math.floor(Date.now() / 1000);
+    for (const entry of entries) {
+        const path = entry.path.replace(/^\/+/, "");
+        if (encoder.encode(path).length > 100) {
+            const pax = paxRecord("path", path);
+            parts.push(header({ name: "././@PaxHeader", mode: 0o644, size: pax.length, mtime, type: "x" }), pad(pax));
+        }
+        parts.push(header({ name: truncateUtf8(path, 100), mode: entry.mode, size: entry.content.length, mtime, type: "0" }), pad(entry.content));
+    }
+    parts.push(new Uint8Array(BLOCK * 2));
+    return concat(parts);
+}
+/**
+ * The first regular file in the archive. Throws if the archive's first entry
+ * is a directory; resolves `null` for an empty archive.
+ */
+export function extractFirstFile(tar) {
+    let offset = 0;
+    let paxPath;
+    while (offset + BLOCK <= tar.length) {
+        const block = tar.subarray(offset, offset + BLOCK);
+        if (block.every((byte) => byte === 0))
+            return null;
+        const name = readString(block, 0, 100);
+        const prefix = readString(block, 345, 155);
+        const size = readOctal(block, 124, 12);
+        const type = String.fromCharCode(block[156] ?? 0);
+        const dataStart = offset + BLOCK;
+        const data = tar.subarray(dataStart, dataStart + size);
+        offset = dataStart + Math.ceil(size / BLOCK) * BLOCK;
+        if (type === "x") {
+            paxPath = parsePax(data).path ?? paxPath;
+            continue;
+        }
+        if (type === "L") {
+            paxPath = decoder.decode(data).replace(/\0+$/, "");
+            continue;
+        }
+        const path = paxPath ?? (prefix ? `${prefix}/${name}` : name);
+        paxPath = undefined;
+        if (type === "5")
+            throw new Error(`"${path}" is a directory`);
+        if (type === "0" || type === "\0")
+            return { path, content: data.slice() };
+    }
+    return null;
+}
+function header(fields) {
+    const block = new Uint8Array(BLOCK);
+    writeString(block, 0, 100, fields.name);
+    writeOctal(block, 100, 8, fields.mode & 0o7777);
+    writeOctal(block, 108, 8, 0);
+    writeOctal(block, 116, 8, 0);
+    writeOctal(block, 124, 12, fields.size);
+    writeOctal(block, 136, 12, fields.mtime);
+    block.fill(0x20, 148, 156); // checksum is computed with this field as spaces
+    block[156] = fields.type.charCodeAt(0);
+    writeString(block, 257, 6, "ustar");
+    writeString(block, 263, 2, "00");
+    const checksum = block.reduce((sum, byte) => sum + byte, 0);
+    writeString(block, 148, 8, `${checksum.toString(8).padStart(6, "0")}\0 `);
+    return block;
+}
+function paxRecord(key, value) {
+    // A record is "<length> <key>=<value>\n", where <length> counts its own digits.
+    const bodyLength = encoder.encode(` ${key}=${value}\n`).length;
+    let length = bodyLength;
+    while (bodyLength + String(length).length !== length)
+        length = bodyLength + String(length).length;
+    return encoder.encode(`${length} ${key}=${value}\n`);
+}
+function parsePax(data) {
+    const records = {};
+    for (const line of decoder.decode(data).split("\n")) {
+        const match = /^\d+ ([^=]+)=(.*)$/s.exec(line);
+        if (match?.[1])
+            records[match[1]] = match[2] ?? "";
+    }
+    return records;
+}
+function pad(data) {
+    const padded = new Uint8Array(Math.ceil(data.length / BLOCK) * BLOCK);
+    padded.set(data);
+    return padded;
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function writeString(block, offset, length, value) {
+    block.set(encoder.encode(value).subarray(0, length), offset);
+}
+function writeOctal(block, offset, length, value) {
+    writeString(block, offset, length, `${value.toString(8).padStart(length - 1, "0")}\0`);
+}
+function readString(block, offset, length) {
+    const slice = block.subarray(offset, offset + length);
+    const end = slice.indexOf(0);
+    return decoder.decode(end === -1 ? slice : slice.subarray(0, end));
+}
+function readOctal(block, offset, length) {
+    const text = readString(block, offset, length).trim();
+    return text ? Number.parseInt(text, 8) : 0;
+}
+function truncateUtf8(value, maxBytes) {
+    let result = value;
+    while (encoder.encode(result).length > maxBytes)
+        result = result.slice(1);
+    return result;
+}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+import type { ExecResult, SandboxStatus } from "./types.js";
+export declare class SandboxError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class SandboxNotFoundError extends SandboxError {
+    readonly sandboxId: string;
+    constructor(sandboxId: string);
+}
+export declare class ProviderNotFoundError extends SandboxError {
+    readonly providerName: string;
+    constructor(providerName: string);
+}
+/** The operation is not allowed while the sandbox is in its current status. */
+export declare class SandboxStateError extends SandboxError {
+    readonly sandboxId: string;
+    readonly status: SandboxStatus;
+    constructor(sandboxId: string, status: SandboxStatus, operation: string);
+}
+/** The sandbox stayed in a transitional status for longer than the manager waits. */
+export declare class SandboxBusyError extends SandboxError {
+    readonly sandboxId: string;
+    readonly status: SandboxStatus;
+    constructor(sandboxId: string, status: SandboxStatus);
+}
+/** A lifecycle command (git clone or a setup step) exited non-zero. */
+export declare class SandboxCommandError extends SandboxError {
+    readonly step: string;
+    readonly result: ExecResult;
+    constructor(step: string, result: ExecResult);
+}
+/** Thrown by providers when an operation needs a running sandbox but it is stopped. */
+export declare class ProviderSandboxStoppedError extends SandboxError {
+    readonly providerRef: string;
+    constructor(providerRef: string);
+}
+/** Thrown by providers when the sandbox no longer exists on the provider. */
+export declare class ProviderSandboxMissingError extends SandboxError {
+    readonly providerRef: string;
+    constructor(providerRef: string);
+}