@volter/browser-sandboxes 0.1.3

package/dist/contract.js

@@ -0,0 +1,79 @@
+// Walks the hosted wire contract against a live server: negotiates the
+// descriptor, checks the catalogue is covered, calls every safe route, and
+// confirms refusals for an unknown route, a route outside the base path, a
+// missing token, and a client stating another version. Returns failures; the
+// caller decides what to do with them. The same walk proves a self-hosted
+// tier and a managed service are one API.
+import { SUBSTRATE_AGENT_PROTOCOL, SUBSTRATE_AGENT_ROUTES, SUBSTRATE_CONTROL_PLANE_ROUTES, SUBSTRATE_PROTOCOL_HEADER, hostedProtocolHeader, missingHostedRoutes, negotiateHostedProtocol, parseHostedProtocolHeader, } from "@volter/browser-runtime/browser-hosted-protocol.js";
+export async function runHostedContract({ baseUrl, token, protocol, fetch: network = globalThis.fetch }) {
+    const failures = [];
+    const check = (label, ok, detail) => { if (!ok)
+        failures.push({ label, ...(detail !== undefined ? { detail } : {}) }); };
+    const base = baseUrl.replace(/\/$/, "");
+    const auth = token ? { authorization: `Bearer ${token}` } : {};
+    const call = (path, init = {}) => {
+        const headers = new Headers(init.headers);
+        for (const [name, value] of Object.entries(auth))
+            headers.set(name, value);
+        return network(`${base}${path}`, { ...init, headers });
+    };
+    const catalogue = protocol === SUBSTRATE_AGENT_PROTOCOL ? SUBSTRATE_AGENT_ROUTES : SUBSTRATE_CONTROL_PLANE_ROUTES;
+    // 1. The descriptor, negotiated before anything else is trusted.
+    const root = await call("/");
+    check(`${protocol}: GET / answers`, root.ok, root.status);
+    const descriptor = root.ok ? await root.json().catch(() => undefined) : undefined;
+    const negotiated = negotiateHostedProtocol(descriptor, { protocol });
+    check(`${protocol}: descriptor negotiates`, negotiated.ok, negotiated);
+    const sent = parseHostedProtocolHeader(root.headers.get(SUBSTRATE_PROTOCOL_HEADER));
+    check(`${protocol}: every response carries ${SUBSTRATE_PROTOCOL_HEADER}`, sent?.protocol === protocol && sent.version === 1, root.headers.get(SUBSTRATE_PROTOCOL_HEADER));
+    if (!negotiated.ok)
+        return failures;
+    const basePath = negotiated.descriptor.basePath.replace(/\/$/, "");
+    const versioned = (path, init) => call(`${basePath}${path}`, init);
+    // 2. The catalogue the server claims covers the one the client speaks.
+    const missing = missingHostedRoutes(negotiated.descriptor.routes, catalogue);
+    check(`${protocol}: the server's catalogue covers the client's`, missing.length === 0, missing.map((r) => `${r.method} ${r.path}`));
+    // 3. Every safe route answers something other than "no such route".
+    for (const route of catalogue.filter((r) => r.safe && !r.path.includes("{"))) {
+        if (route.path === "/events") {
+            const controller = new AbortController();
+            try {
+                const response = await versioned(route.path, { signal: controller.signal });
+                check(`${protocol}: ${route.method} ${route.path} streams events`, response.ok && /text\/event-stream/.test(response.headers.get("content-type") ?? ""), response.status);
+            }
+            catch (error) {
+                check(`${protocol}: ${route.method} ${route.path} streams events`, false, String(error));
+            }
+            finally {
+                controller.abort();
+            }
+            continue;
+        }
+        const query = route.path.startsWith("/fs/") ? "?path=/workspace&root=/workspace" : "";
+        const response = await versioned(`${route.path}${query}`, { method: route.method });
+        // A route may answer 404 for a missing resource; only "no such route" means it is not served.
+        const body = response.status === 404 ? (await response.json().catch(() => ({}))) : undefined;
+        const routed = response.status !== 404 || !/no such route/.test(String(body?.error ?? ""));
+        check(`${protocol}: ${route.method} ${route.path} is routed`, routed, { status: response.status, ...(body ? { body } : {}) });
+        check(`${protocol}: ${route.method} ${route.path} carries the protocol header`, response.headers.get(SUBSTRATE_PROTOCOL_HEADER) === hostedProtocolHeader(protocol), response.headers.get(SUBSTRATE_PROTOCOL_HEADER));
+        if (!body)
+            await response.arrayBuffer().catch(() => undefined);
+    }
+    // 4. Refusals are refusals.
+    const unknown = await versioned("/definitely-not-a-route");
+    const unknownBody = (await unknown.json().catch(() => ({})));
+    check(`${protocol}: an unknown route is 404 with a JSON error`, unknown.status === 404 && typeof unknownBody.error === "string", unknown.status);
+    const unversioned = await call("/health");
+    check(`${protocol}: a route outside the base path is 404`, unversioned.status === 404, unversioned.status);
+    await unversioned.arrayBuffer().catch(() => undefined);
+    if (token) {
+        const anonymous = await network(`${base}${basePath}/health`);
+        check(`${protocol}: a missing token is 401`, anonymous.status === 401, anonymous.status);
+        await anonymous.arrayBuffer().catch(() => undefined);
+    }
+    const wrongVersion = await versioned("/health", { headers: { [SUBSTRATE_PROTOCOL_HEADER]: `${protocol}/999` } });
+    check(`${protocol}: a client stating another version is refused with 426`, wrongVersion.status === 426, wrongVersion.status);
+    await wrongVersion.arrayBuffer().catch(() => undefined);
+    return failures;
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/control-plane.d.ts

@@ -0,0 +1,14 @@
+import * as http from "node:http";
+import type { SandboxManager } from "./manager.js";
+export interface ControlPlaneOptions {
+    manager: SandboxManager;
+    port?: number;
+    bind?: string;
+}
+export interface ControlPlaneServer {
+    server: http.Server;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function serveControlPlane({ manager, port, bind }: ControlPlaneOptions): Promise<ControlPlaneServer>;
+//# sourceMappingURL=control-plane.d.ts.map

package/dist/control-plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane.d.ts","sourceRoot":"","sources":["../src/control-plane.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAKlC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAWD,wBAAsB,iBAAiB,CAAC,EAAE,OAAO,EAAE,IAAW,EAAE,IAAkB,EAAE,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiGtI"}

package/dist/control-plane.js

@@ -0,0 +1,133 @@
+// A control plane a page can call: creates sandboxes through the manager and
+// proxies each sandbox's agent under /sandboxes/<id>/agent/, adding the agent
+// token server-side so the page never holds it, plus the CORS and
+// embedder-policy headers a cross-origin-isolated page needs to frame a guest.
+import * as http from "node:http";
+import { SUBSTRATE_CONTROL_PLANE_PROTOCOL, SUBSTRATE_PROTOCOL_BASE_PATH, SUBSTRATE_PROTOCOL_HEADER, SUBSTRATE_PROTOCOL_VERSION, describeControlPlaneProtocol, hostedProtocolHeader, parseHostedProtocolHeader, } from "@volter/browser-runtime/browser-hosted-protocol.js";
+const HOP_HEADERS = new Set(["content-length", "transfer-encoding", "connection", "keep-alive"]);
+const REQUEST_HEADERS_DROPPED = new Set(["host", "authorization", "connection", "content-length", "origin"]);
+const PROTOCOL = hostedProtocolHeader(SUBSTRATE_CONTROL_PLANE_PROTOCOL);
+function versionedPath(pathname) {
+    if (pathname === SUBSTRATE_PROTOCOL_BASE_PATH)
+        return "/";
+    return pathname.startsWith(`${SUBSTRATE_PROTOCOL_BASE_PATH}/`) ? pathname.slice(SUBSTRATE_PROTOCOL_BASE_PATH.length) : undefined;
+}
+export async function serveControlPlane({ manager, port = 4291, bind = "127.0.0.1" }) {
+    const cors = (request) => ({
+        "access-control-allow-origin": request.headers.origin ?? "*",
+        "access-control-allow-methods": "GET,POST,PUT,DELETE,OPTIONS",
+        "access-control-allow-headers": "authorization,content-type",
+        "cross-origin-embedder-policy": "credentialless",
+        "cross-origin-resource-policy": "cross-origin",
+    });
+    const json = (request, response, status, value) => {
+        response.writeHead(status, { ...cors(request), "content-type": "application/json" });
+        response.end(JSON.stringify(value));
+    };
+    const readBody = (request) => new Promise((done, fail) => {
+        const chunks = [];
+        request.on("data", (chunk) => chunks.push(chunk));
+        request.on("end", () => done(Buffer.concat(chunks)));
+        request.on("error", fail);
+    });
+    const server = http.createServer(async (request, response) => {
+        response.setHeader(SUBSTRATE_PROTOCOL_HEADER, PROTOCOL);
+        const url = new URL(request.url ?? "/", "http://control-plane.invalid");
+        const method = request.method ?? "GET";
+        try {
+            if (method === "OPTIONS") {
+                response.writeHead(204, cors(request));
+                response.end();
+                return;
+            }
+            if (method === "GET" && url.pathname === "/")
+                return json(request, response, 200, describeControlPlaneProtocol());
+            const pathname = versionedPath(url.pathname);
+            if (pathname === undefined)
+                return json(request, response, 404, { error: `no such route; the catalogue is under ${SUBSTRATE_PROTOCOL_BASE_PATH}` });
+            const segments = pathname.split("/").filter(Boolean);
+            // A stated protocol is judged by the server it is addressed to: this one
+            // for its own routes, the agent for everything under its proxy prefix.
+            const proxying = segments[0] === "sandboxes" && segments[2] === "agent";
+            const stated = request.headers[SUBSTRATE_PROTOCOL_HEADER];
+            if (!proxying && typeof stated === "string") {
+                const parsed = parseHostedProtocolHeader(stated);
+                if (!parsed || parsed.protocol !== SUBSTRATE_CONTROL_PLANE_PROTOCOL || parsed.version !== SUBSTRATE_PROTOCOL_VERSION) {
+                    return json(request, response, 426, { error: `this server speaks ${PROTOCOL}, the client stated ${stated}`, protocol: PROTOCOL });
+                }
+            }
+            if (pathname === "/health")
+                return json(request, response, 200, { ok: true, sandboxes: manager.list().length });
+            if (segments[0] !== "sandboxes")
+                return json(request, response, 404, { error: "no such route" });
+            if (segments.length === 1 && method === "GET")
+                return json(request, response, 200, manager.list());
+            if (segments.length === 1 && method === "POST") {
+                const text = (await readBody(request)).toString("utf8");
+                const options = (text ? JSON.parse(text) : {});
+                const created = await manager.create({ ...(options.volume ? { volume: options.volume } : {}) });
+                return json(request, response, 201, { id: created.id, agent: `${SUBSTRATE_PROTOCOL_BASE_PATH}/sandboxes/${created.id}/agent`, state: created.state });
+            }
+            const id = segments[1] ?? "";
+            const sandbox = manager.get(id);
+            if (!sandbox)
+                return json(request, response, 404, { error: "unknown sandbox" });
+            if (segments.length === 2 && method === "DELETE") {
+                await sandbox.kill();
+                return json(request, response, 200, { killed: sandbox.id });
+            }
+            if (segments[2] === "agent") {
+                const target = `${sandbox.url}/${segments.slice(3).join("/")}${url.search}`;
+                const headers = { authorization: `Bearer ${sandbox.token}` };
+                for (const [name, value] of Object.entries(request.headers)) {
+                    if (typeof value === "string" && !REQUEST_HEADERS_DROPPED.has(name))
+                        headers[name] = value;
+                }
+                const body = method === "GET" || method === "HEAD" ? undefined : await readBody(request);
+                // A page that navigates away closes its event stream; abort upstream instead of erroring here.
+                const abort = new AbortController();
+                request.on("close", () => abort.abort());
+                const proxied = await fetch(target, {
+                    method, headers, redirect: "manual", signal: abort.signal,
+                    ...(body ? { body: body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength) } : {}),
+                });
+                const responseHeaders = { ...cors(request) };
+                proxied.headers.forEach((value, name) => { if (!HOP_HEADERS.has(name))
+                    responseHeaders[name] = value; });
+                // A proxied response is the agent's; it carries the agent's protocol, not this server's.
+                response.removeHeader(SUBSTRATE_PROTOCOL_HEADER);
+                response.writeHead(proxied.status, responseHeaders);
+                try {
+                    if (proxied.body) {
+                        const reader = proxied.body.getReader();
+                        for (;;) {
+                            const { value, done } = await reader.read();
+                            if (done)
+                                break;
+                            response.write(Buffer.from(value));
+                        }
+                    }
+                }
+                catch { /* client or upstream went away */ }
+                response.end();
+                return;
+            }
+            return json(request, response, 404, { error: "no such route" });
+        }
+        catch (cause) {
+            if (response.headersSent) {
+                response.destroy();
+                return;
+            }
+            return json(request, response, 500, { error: cause instanceof Error ? cause.message : String(cause) });
+        }
+    });
+    await new Promise((resolve) => server.listen(port, bind, () => resolve()));
+    const address = server.address();
+    return {
+        server,
+        port: typeof address === "object" && address ? address.port : port,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+//# sourceMappingURL=control-plane.js.map

package/dist/control-plane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane.js","sourceRoot":"","sources":["../src/control-plane.ts"],"names":[],"mappings":"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"}

package/dist/docker-provider.d.ts

@@ -0,0 +1,23 @@
+import type { ProviderStartSpec, ProviderStarted, SandboxProvider } from "./manager.js";
+export interface DockerProviderOptions {
+    /** The guest image carrying the agent; the default is the image `build-image` produces. */
+    image?: string;
+    /** Bind this repository at /repo and run the agent from its built package instead of the image's. */
+    repo?: string;
+    label?: string;
+}
+/** Runs the agent image as a local container with the guest root at "/". */
+export declare class DockerProvider implements SandboxProvider {
+    readonly image: string;
+    readonly repo: string | undefined;
+    readonly label: string;
+    constructor({ image, repo, label }?: DockerProviderOptions);
+    private docker;
+    start({ id, token, image, limits, volume }: ProviderStartSpec): ProviderStarted;
+    pause({ name }: ProviderStarted): void;
+    resume({ name }: ProviderStarted): void;
+    stop({ name }: ProviderStarted): void;
+    running(): Set<string>;
+    removeVolume(volume: string): void;
+}
+//# sourceMappingURL=docker-provider.d.ts.map

package/dist/docker-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-provider.d.ts","sourceRoot":"","sources":["../src/docker-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAExF,MAAM,WAAW,qBAAqB;IACpC,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qGAAqG;IACrG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4EAA4E;AAC5E,qBAAa,cAAe,YAAW,eAAe;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,EAAE,KAAmC,EAAE,IAAI,EAAE,KAAkC,EAAE,GAAE,qBAA0B;IAOzH,OAAO,CAAC,MAAM;IAId,KAAK,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAkB,EAAE,MAAW,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAAG,eAAe;IAmBjG,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe,GAAG,IAAI;IACtC,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe,GAAG,IAAI;IACvC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe,GAAG,IAAI;IACrC,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC;IAItB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CACnC"}

package/dist/docker-provider.js

@@ -0,0 +1,50 @@
+import { execFileSync } from "node:child_process";
+/** Runs the agent image as a local container with the guest root at "/". */
+export class DockerProvider {
+    image;
+    repo;
+    label;
+    constructor({ image = "substrate-node-host:local", repo, label = "volter.substrate.sandbox" } = {}) {
+        // With the repository bound in, the base Node image suffices; the agent runs from the built package.
+        this.image = image === "substrate-node-host:local" && repo ? "node:22-bookworm-slim" : image;
+        this.repo = repo;
+        this.label = label;
+    }
+    docker(args) {
+        return execFileSync("docker", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    }
+    start({ id, token, image = this.image, limits = {}, volume }) {
+        const name = `substrate-sandbox-${id.slice(0, 12)}`;
+        this.docker([
+            "run", "-d", "--rm", "--name", name, "--label", `${this.label}=${id}`,
+            "-p", "127.0.0.1::8787",
+            // Resource limits are the provider's job; the manager only passes them through.
+            ...(limits.cpus ? ["--cpus", String(limits.cpus)] : []),
+            ...(limits.memoryBytes ? ["--memory", String(limits.memoryBytes)] : []),
+            ...(limits.pids ? ["--pids-limit", String(limits.pids)] : []),
+            // A named volume is the workspace that outlives the sandbox.
+            ...(volume ? ["-v", `${volume}:/workspace`] : []),
+            ...(this.repo ? ["-v", `${this.repo}:/repo:ro`, "-w", "/repo"] : []),
+            "-e", "SUBSTRATE_ROOT=/", "-e", `SUBSTRATE_TOKEN=${token}`, "-e", "PORT=8787", "-e", "HOST=::",
+            image,
+            ...(this.repo ? ["node", "/repo/packages/host-node/dist/bin/agent.js"] : []),
+        ]);
+        const published = this.docker(["port", name, "8787/tcp"]).split("\n")[0] ?? "";
+        return { name, url: `http://127.0.0.1:${published.slice(published.lastIndexOf(":") + 1)}` };
+    }
+    pause({ name }) { this.docker(["pause", name]); }
+    resume({ name }) { this.docker(["unpause", name]); }
+    stop({ name }) { try {
+        this.docker(["rm", "-f", name]);
+    }
+    catch { /* already gone */ } }
+    running() {
+        const out = this.docker(["ps", "--filter", `label=${this.label}`, "--format", `{{.Label "${this.label}"}}`]);
+        return new Set(out ? out.split("\n") : []);
+    }
+    removeVolume(volume) { try {
+        this.docker(["volume", "rm", volume]);
+    }
+    catch { /* absent */ } }
+}
+//# sourceMappingURL=docker-provider.js.map

package/dist/docker-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-provider.js","sourceRoot":"","sources":["../src/docker-provider.ts"],"names":[],"mappings":"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"}

package/dist/fly-provider.d.ts

@@ -0,0 +1,51 @@
+import type { ProviderStartSpec, ProviderStarted, SandboxProvider } from "./manager.js";
+export interface FlyProviderOptions {
+    apiUrl?: string;
+    token?: string;
+    app?: string;
+    org?: string;
+    region?: string;
+    image?: string;
+    label?: string;
+    /**
+     * How machines are reached. The twin publishes loopback ports; Fly itself
+     * exposes machines on their private IPv6 network, reached through flyctl's
+     * WireGuard proxy using the existing login ("proxy"), or directly when the
+     * caller is already on that network ("direct").
+     */
+    access?: "proxy" | "direct";
+}
+/**
+ * Fly Machines provider: the same four calls against api.machines.dev. Vendor
+ * truth carried through: a stopped machine restarts from a clean rootfs, so
+ * only a volume-mounted workspace survives pause and resume; guest memory is
+ * sized in 256 MiB steps; a deleted volume lingers as pending_destroy.
+ */
+export declare class FlyProvider implements SandboxProvider {
+    readonly apiUrl: string;
+    readonly app: string;
+    readonly org: string;
+    readonly region: string;
+    readonly image: string;
+    readonly label: string;
+    readonly access: "proxy" | "direct";
+    private readonly token;
+    /** Local port forwards to machines' private addresses, by machine id, when access is "proxy". */
+    private readonly proxies;
+    constructor({ apiUrl, token, app, org, region, image, label, access, }?: FlyProviderOptions);
+    private api;
+    ensureApp(): Promise<void>;
+    private ensureVolume;
+    private url;
+    private closeProxy;
+    start({ id, token, image, limits, volume }: ProviderStartSpec): Promise<ProviderStarted>;
+    pause({ name }: ProviderStarted): Promise<void>;
+    resume({ name }: ProviderStarted): Promise<{
+        url: string;
+    }>;
+    stop({ name }: ProviderStarted): Promise<void>;
+    close(): void;
+    running(): Promise<Set<string>>;
+    removeVolume(name: string): Promise<void>;
+}
+//# sourceMappingURL=fly-provider.d.ts.map

package/dist/fly-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fly-provider.d.ts","sourceRoot":"","sources":["../src/fly-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAExF,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC7B;AAYD;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,eAAe;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,iGAAiG;IACjG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2D;gBAEvE,EACV,MAAmE,EACnE,KAAiC,EACjC,GAAkD,EAClD,GAAuC,EACvC,MAAwC,EACxC,KAA4D,EAC5D,KAAkC,EAClC,MAAM,GACP,GAAE,kBAAuB;YAaZ,GAAG;IAWX,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;YAKlB,YAAY;YAOZ,GAAG;IAejB,OAAO,CAAC,UAAU;IAOZ,KAAK,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAkB,EAAE,MAAW,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAqB1G,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAQ3D,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD,KAAK,IAAI,IAAI;IAEP,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAK/B,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMhD"}

package/dist/fly-provider.js

@@ -0,0 +1,135 @@
+import { spawn } from "node:child_process";
+/**
+ * Fly Machines provider: the same four calls against api.machines.dev. Vendor
+ * truth carried through: a stopped machine restarts from a clean rootfs, so
+ * only a volume-mounted workspace survives pause and resume; guest memory is
+ * sized in 256 MiB steps; a deleted volume lingers as pending_destroy.
+ */
+export class FlyProvider {
+    apiUrl;
+    app;
+    org;
+    region;
+    image;
+    label;
+    access;
+    token;
+    /** Local port forwards to machines' private addresses, by machine id, when access is "proxy". */
+    proxies = new Map();
+    constructor({ apiUrl = process.env.FLY_API_HOSTNAME ?? "https://api.machines.dev", token = process.env.FLY_API_TOKEN, app = process.env.FLY_APP ?? "substrate-sandboxes", org = process.env.FLY_ORG ?? "personal", region = process.env.FLY_REGION ?? "iad", image = process.env.FLY_IMAGE ?? "substrate-node-host:local", label = "volter.substrate.sandbox", access, } = {}) {
+        if (!token)
+            throw new Error("FLY_API_TOKEN is required.");
+        this.apiUrl = apiUrl.replace(/\/$/, "");
+        this.token = token;
+        this.app = app;
+        this.org = org;
+        this.region = region;
+        this.image = image;
+        this.label = label;
+        const configured = process.env.FLY_ACCESS === "direct" ? "direct" : process.env.FLY_ACCESS === "proxy" ? "proxy" : undefined;
+        this.access = access ?? configured ?? (/api\.machines\.dev/.test(this.apiUrl) ? "proxy" : "direct");
+    }
+    async api(method, path, body) {
+        const response = await fetch(`${this.apiUrl}/v1${path}`, {
+            method,
+            headers: { authorization: `Bearer ${this.token}`, ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw new Error(`Fly ${method} ${path} -> ${response.status} ${text}`);
+        return (text ? JSON.parse(text) : undefined);
+    }
+    async ensureApp() {
+        try {
+            await this.api("GET", `/apps/${this.app}`);
+        }
+        catch {
+            await this.api("POST", "/apps", { app_name: this.app, org_slug: this.org });
+        }
+    }
+    async ensureVolume(name) {
+        const volumes = await this.api("GET", `/apps/${this.app}/volumes`);
+        // A deleted volume lingers as pending_destroy; only a created one is mountable.
+        return volumes.find((volume) => volume.name === name && volume.state === "created")
+            ?? this.api("POST", `/apps/${this.app}/volumes`, { name, region: this.region, size_gb: 1 });
+    }
+    async url(machine) {
+        const local = (machine.twin_local_ports ?? []).find((entry) => entry.internal === 8787);
+        if (local)
+            return `http://127.0.0.1:${local.host}`;
+        if (this.access !== "proxy")
+            return `http://[${machine.private_ip ?? ""}]:8787`;
+        const existing = this.proxies.get(machine.id);
+        if (existing)
+            return existing.url;
+        const port = 20_000 + Math.floor(Math.random() * 20_000);
+        const child = spawn("fly", ["proxy", `${port}:8787`, machine.private_ip ?? "", "-a", this.app], { stdio: ["ignore", "ignore", "pipe"] });
+        child.stderr?.on("data", () => undefined);
+        child.on("error", () => this.proxies.delete(machine.id));
+        const proxy = { child, url: `http://127.0.0.1:${port}` };
+        this.proxies.set(machine.id, proxy);
+        return proxy.url;
+    }
+    closeProxy(machineId) {
+        const proxy = this.proxies.get(machineId);
+        if (!proxy)
+            return;
+        proxy.child.kill("SIGTERM");
+        this.proxies.delete(machineId);
+    }
+    async start({ id, token, image = this.image, limits = {}, volume }) {
+        await this.ensureApp();
+        const mounts = volume ? [{ volume: (await this.ensureVolume(volume)).id, path: "/workspace" }] : [];
+        const created = await this.api("POST", `/apps/${this.app}/machines`, {
+            name: `sandbox-${id.slice(0, 12)}`,
+            region: this.region,
+            config: {
+                image,
+                env: { SUBSTRATE_ROOT: "/", SUBSTRATE_TOKEN: token, PORT: "8787", HOST: "::" },
+                services: [{ protocol: "tcp", internal_port: 8787, ports: [{ port: 8787 }] }],
+                // Fly sizes guest memory in 256 MiB steps.
+                guest: { cpu_kind: "shared", cpus: Math.max(1, Math.ceil(limits.cpus ?? 1)), memory_mb: Math.max(256, Math.ceil((limits.memoryBytes ?? 256 * 1024 * 1024) / (256 * 1_048_576)) * 256) },
+                metadata: { [this.label]: id },
+                mounts,
+            },
+        });
+        await this.api("GET", `/apps/${this.app}/machines/${created.id}/wait?state=started&timeout=60`);
+        const machine = await this.api("GET", `/apps/${this.app}/machines/${created.id}`);
+        return { name: created.id, url: await this.url(machine) };
+    }
+    async pause({ name }) {
+        await this.api("POST", `/apps/${this.app}/machines/${name}/stop`);
+        await this.api("GET", `/apps/${this.app}/machines/${name}/wait?state=stopped&timeout=60`);
+    }
+    async resume({ name }) {
+        // A restarted machine is a new guest; the old forward is stale, so rebuild it.
+        this.closeProxy(name);
+        await this.api("POST", `/apps/${this.app}/machines/${name}/start`);
+        await this.api("GET", `/apps/${this.app}/machines/${name}/wait?state=started&timeout=60`);
+        return { url: await this.url(await this.api("GET", `/apps/${this.app}/machines/${name}`)) };
+    }
+    async stop({ name }) {
+        this.closeProxy(name);
+        try {
+            await this.api("DELETE", `/apps/${this.app}/machines/${name}?force=true`);
+        }
+        catch { /* already gone */ }
+    }
+    close() { for (const id of [...this.proxies.keys()])
+        this.closeProxy(id); }
+    async running() {
+        const machines = await this.api("GET", `/apps/${this.app}/machines`);
+        return new Set(machines.filter((machine) => machine.state === "started").map((machine) => machine.config?.metadata?.[this.label]).filter((value) => Boolean(value)));
+    }
+    async removeVolume(name) {
+        const volumes = await this.api("GET", `/apps/${this.app}/volumes`);
+        for (const volume of volumes.filter((candidate) => candidate.name === name)) {
+            try {
+                await this.api("DELETE", `/apps/${this.app}/volumes/${volume.id}`);
+            }
+            catch { /* gone */ }
+        }
+    }
+}
+//# sourceMappingURL=fly-provider.js.map

package/dist/fly-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fly-provider.js","sourceRoot":"","sources":["../src/fly-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AA8B9D;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACb,MAAM,CAAS;IACf,GAAG,CAAS;IACZ,GAAG,CAAS;IACZ,MAAM,CAAS;IACf,KAAK,CAAS;IACd,KAAK,CAAS;IACd,MAAM,CAAqB;IACnB,KAAK,CAAS;IAC/B,iGAAiG;IAChF,OAAO,GAAG,IAAI,GAAG,EAAgD,CAAC;IAEnF,YAAY,EACV,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,0BAA0B,EACnE,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,EACjC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,qBAAqB,EAClD,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,UAAU,EACvC,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,KAAK,EACxC,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,2BAA2B,EAC5D,KAAK,GAAG,0BAA0B,EAClC,MAAM,MACgB,EAAE;QACxB,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7H,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,UAAU,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACtG,CAAC;IAEO,KAAK,CAAC,GAAG,CAAc,MAAc,EAAE,IAAY,EAAE,IAAc;QACzE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,MAAM,IAAI,EAAE,EAAE;YACvD,MAAM;YACN,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;YACzH,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,OAAO,MAAM,IAAI,IAAI,OAAO,QAAQ,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;QACzF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAM,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,SAAS;QACb,IAAI,CAAC;YAAC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAAC,CAAC;QACnD,MAAM,CAAC;YAAC,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAAC,CAAC;IACxF,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAY;QACrC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAc,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC;QAChF,gFAAgF;QAChF,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC;eAC9E,IAAI,CAAC,GAAG,CAAY,MAAM,EAAE,SAAS,IAAI,CAAC,GAAG,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3G,CAAC;IAEO,KAAK,CAAC,GAAG,CAAC,OAAmB;QACnC,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QACxF,IAAI,KAAK;YAAE,OAAO,oBAAoB,KAAK,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO;YAAE,OAAO,WAAW,OAAO,CAAC,UAAU,IAAI,EAAE,QAAQ,CAAC;QAChF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC,GAAG,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACzI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1C,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,oBAAoB,IAAI,EAAE,EAAE,CAAC;QACzD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QACpC,OAAO,KAAK,CAAC,GAAG,CAAC;IACnB,CAAC;IAEO,UAAU,CAAC,SAAiB;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,EAAE,MAAM,EAAqB;QACnF,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpG,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAa,MAAM,EAAE,SAAS,IAAI,CAAC,GAAG,WAAW,EAAE;YAC/E,IAAI,EAAE,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;YAClC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE;gBACN,KAAK;gBACL,GAAG,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE;gBAC9E,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;gBAC7E,2CAA2C;gBAC3C,KAAK,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC,GAAG,GAAG,CAAC,EAAE;gBACvL,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE;gBAC9B,MAAM;aACP;SACF,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,aAAa,OAAO,CAAC,EAAE,gCAAgC,CAAC,CAAC;QAChG,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAa,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,aAAa,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9F,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAmB;QACnC,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,IAAI,CAAC,GAAG,aAAa,IAAI,OAAO,CAAC,CAAC;QAClE,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,aAAa,IAAI,gCAAgC,CAAC,CAAC;IAC5F,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAmB;QACpC,+EAA+E;QAC/E,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,IAAI,CAAC,GAAG,aAAa,IAAI,QAAQ,CAAC,CAAC;QACnE,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,aAAa,IAAI,gCAAgC,CAAC,CAAC;QAC1F,OAAO,EAAE,GAAG,EAAE,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,CAAa,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,aAAa,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IAC1G,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAmB;QAClC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC;YAAC,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,IAAI,CAAC,GAAG,aAAa,IAAI,aAAa,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IACjH,CAAC;IAED,KAAK,KAAW,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAAE,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEjF,KAAK,CAAC,OAAO;QACX,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAe,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;QACnF,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxL,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,IAAY;QAC7B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAc,KAAK,EAAE,SAAS,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC;QAChF,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YAC5E,IAAI,CAAC;gBAAC,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,IAAI,CAAC,GAAG,YAAY,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./client.js";
+export * from "./manager.js";
+export * from "./docker-provider.js";
+export * from "./fly-provider.js";
+export * from "./providers.js";
+export * from "./control-plane.js";
+export * from "./mcp.js";
+export * from "./contract.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./client.js";
+export * from "./manager.js";
+export * from "./docker-provider.js";
+export * from "./fly-provider.js";
+export * from "./providers.js";
+export * from "./control-plane.js";
+export * from "./mcp.js";
+export * from "./contract.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}