@solarisdk/runloop-compat 0.0.0-stage → 0.1.1

package/dist/client.js

@@ -0,0 +1,924 @@
+// REST-layer client: `new Runloop({ bearerToken })` with `client.devboxes.*`, built on
+// @solarisdk/sandbox. Runloop's per-devbox calls (execute, file ops, snapshot) need a
+// live control channel in Solari, so the client keeps one cached handle per devbox.
+import { ConnectionError, GatewayError, HttpTransport, SolariError } from "@solarisdk/core";
+import { SandboxClient } from "@solarisdk/sandbox";
+import * as Errors from "./errors.js";
+import { Blueprints } from "./blueprints.js";
+import { Secrets } from "./secrets.js";
+import { APIConnectionError, APIConnectionTimeoutError, APIError, NotFoundError, RunloopError, SolariCompatUnsupported, translateError, translating, unsupportedNamespace } from "./errors.js";
+import { absPath, DEFAULT_HOME, mapStatus, statusToState, toDevboxView, toSnapshotView, translateCreate, } from "./mapping.js";
+export const DEFAULT_BASE_URL = "https://api.getsolari.com";
+/** @internal Whether an inherited base URL may receive a Solari key: https on getsolari.com or a subdomain, or loopback over http(s). */
+export function isSolariBaseUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    const host = u.hostname.toLowerCase().replace(/\.$/, "");
+    if (u.protocol === "https:" && (host === "getsolari.com" || host.endsWith(".getsolari.com")))
+        return true;
+    const loopback = host === "localhost" || host === "[::1]" || /^127(\.\d{1,3}){3}$/.test(host);
+    return loopback && (u.protocol === "http:" || u.protocol === "https:");
+}
+function describeHost(raw) {
+    try {
+        return new URL(raw).hostname || "unparsable URL";
+    }
+    catch {
+        return "unparsable URL";
+    }
+}
+const DEFAULT_KEEP_ALIVE_MS = 30 * 60 * 1000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Runloop {
+    // Error classes hang off the class, as in Runloop's client (`Runloop.APIError`).
+    static RunloopError = Errors.RunloopError;
+    static APIError = Errors.APIError;
+    static APIConnectionError = Errors.APIConnectionError;
+    static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+    static APIUserAbortError = Errors.APIUserAbortError;
+    static NotFoundError = Errors.NotFoundError;
+    static ConflictError = Errors.ConflictError;
+    static RateLimitError = Errors.RateLimitError;
+    static BadRequestError = Errors.BadRequestError;
+    static AuthenticationError = Errors.AuthenticationError;
+    static PermissionDeniedError = Errors.PermissionDeniedError;
+    static UnprocessableEntityError = Errors.UnprocessableEntityError;
+    static InternalServerError = Errors.InternalServerError;
+    static SolariCompatUnsupported = Errors.SolariCompatUnsupported;
+    // REST resources Solari has no equivalent for: every call throws SolariCompatUnsupported.
+    blueprints;
+    /** @internal Build contexts for COPY / ADD, by storage-object id. */
+    contexts = new Map();
+    objects = unsupportedNamespace("objects");
+    secrets;
+    agents = unsupportedNamespace("agents");
+    axons = unsupportedNamespace("axons");
+    networkPolicies = unsupportedNamespace("networkPolicies");
+    gatewayConfigs = unsupportedNamespace("gatewayConfigs");
+    mcpConfigs = unsupportedNamespace("mcpConfigs");
+    bearerToken;
+    baseURL;
+    devboxes;
+    /** @internal */
+    solari;
+    /** @internal Raw gateway requests for routes SandboxClient has no method for (PATCH, logs, templates, ...). */
+    http;
+    /** @internal Does GET /sandboxes honour `startingAfter`? Learned from the first list reply (`hasMore` present). */
+    startingAfterSupported;
+    /** @internal Output of commands run through this client, per devbox, for `devbox.logs()` on gateways without a logs route. */
+    localLogs = new Map();
+    handles = new Map();
+    /** @internal */
+    executions = new Map();
+    /** @internal */
+    keepAliveMs = new Map();
+    /** @internal */
+    createdAtMs = new Map();
+    /** @internal Devboxes this client opened an (open, per-port preview) tunnel for. */
+    tunnels = new Set();
+    constructor(opts = {}) {
+        const env = (k) => (typeof process !== "undefined" ? process.env[k] : undefined) || undefined;
+        // Only Solari keys (`slr_…`) are ever used or sent. A Runloop key (for example the RUNLOOP_API_KEY
+        // a Runloop-targeting program already has in its environment) must never be sent to Solari, so a
+        // non-slr_ candidate is skipped with a warning and the next source is tried.
+        const candidates = [
+            ["the bearerToken option", opts.bearerToken],
+            ["the apiKey option", opts.apiKey],
+            ["SOLARI_API_KEY", env("SOLARI_API_KEY")],
+            ["RUNLOOP_API_KEY", env("RUNLOOP_API_KEY")],
+        ];
+        let key;
+        for (const [source, value] of candidates) {
+            if (!value)
+                continue;
+            if (value.startsWith("slr_")) {
+                key = value;
+                break;
+            }
+            console.warn(`@solarisdk/runloop-compat: ignoring ${source}: it is not a Solari API key (slr_…). It is not sent anywhere.`);
+        }
+        if (!key) {
+            throw new RunloopError("No Solari API key. Set SOLARI_API_KEY, or pass new Runloop({ bearerToken: 'slr_live_…' }). A Runloop key (RUNLOOP_API_KEY) is never sent to Solari and cannot be used here.");
+        }
+        if (opts.defaultHeaders && Object.keys(opts.defaultHeaders).length > 0) {
+            throw new SolariCompatUnsupported("defaultHeaders");
+        }
+        if (opts.defaultQuery && Object.keys(opts.defaultQuery).length > 0) {
+            throw new SolariCompatUnsupported("defaultQuery");
+        }
+        this.bearerToken = key;
+        // RUNLOOP_BASE_URL is what a Runloop-targeting program already has set, usually https://api.runloop.ai.
+        // Using it blindly would send the user's slr_ key to Runloop, so it is only honoured when it points at
+        // Solari (or loopback, for local gateways). An explicit baseURL option and SOLARI_BASE_URL stay as given.
+        const runloopBase = env("RUNLOOP_BASE_URL");
+        let inheritedBase;
+        if (runloopBase) {
+            if (isSolariBaseUrl(runloopBase))
+                inheritedBase = runloopBase;
+            else if (!opts.baseURL && !env("SOLARI_BASE_URL")) {
+                console.warn(`@solarisdk/runloop-compat: ignoring RUNLOOP_BASE_URL (${describeHost(runloopBase)}): it does not point at Solari, and your Solari API key is never sent anywhere else. Using ${DEFAULT_BASE_URL}.`);
+            }
+        }
+        this.baseURL = (opts.baseURL ?? env("SOLARI_BASE_URL") ?? inheritedBase ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.solari = new SandboxClient({
+            apiKey: key,
+            baseUrl: this.baseURL,
+            ...(opts.fetch ? { fetch: opts.fetch } : {}),
+            ...(opts.timeout ? { callTimeoutMs: opts.timeout } : {}),
+        });
+        this.http = new HttpTransport({ apiKey: key, baseUrl: this.baseURL, ...(opts.fetch ? { fetch: opts.fetch } : {}) });
+        this.devboxes = new Devboxes(this);
+        this.blueprints = new Blueprints(this);
+        this.secrets = new Secrets(this);
+    }
+    /** @internal Live control handle for a devbox, cached per id. */
+    handle(id) {
+        let h = this.handles.get(id);
+        if (!h) {
+            h = this.solari.connect(id).then(async (sb) => {
+                await sb.connect();
+                return sb;
+            });
+            h.catch(() => this.handles.delete(id));
+            this.handles.set(id, h);
+        }
+        return h;
+    }
+    /**
+     * @internal Run `fn` on the devbox's live handle. If the control channel was closed under us
+     * (typically the first call after a resume), drop the handle, reconnect and retry once.
+     */
+    async on(id, fn) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await fn(await this.handle(id));
+            }
+            catch (e) {
+                const closed = e instanceof SolariError && !(e instanceof GatewayError) && (e instanceof ConnectionError || /closed|not connected|disconnect|websocket/i.test(e.message));
+                if (!closed || attempt >= 2)
+                    throw translateError(e);
+                this.dropHandle(id);
+                await sleep(500 * (attempt + 1));
+            }
+        }
+    }
+    homes = new Map();
+    /** @internal The guest's $HOME, created if missing (Runloop runs commands from the user's home). */
+    home(id) {
+        let h = this.homes.get(id);
+        if (!h) {
+            h = (async () => {
+                const r = await this.on(id, (sb) => sb.commands.run("/bin/bash", { args: ["-lc", 'printf %s "$HOME"'] }));
+                const home = r.stdout.trim() || DEFAULT_HOME;
+                await this.on(id, (sb) => sb.commands.run("/bin/mkdir", { args: ["-p", home] }));
+                return home;
+            })();
+            h.catch(() => this.homes.delete(id));
+            this.homes.set(id, h);
+        }
+        return h;
+    }
+    /** @internal */
+    dropHandle(id) {
+        const h = this.handles.get(id);
+        this.handles.delete(id);
+        h?.then((s) => s.close()).catch(() => undefined);
+    }
+    /** @internal */
+    adopt(id, sb) {
+        this.handles.set(id, sb.connect().then(() => sb));
+        this.handles.get(id)?.catch(() => this.handles.delete(id));
+    }
+}
+export class DevboxesCursorIDPage {
+    nextCursor;
+    fetchNext;
+    devboxes;
+    has_more;
+    total_count;
+    /** @internal */
+    constructor(items, nextCursor, fetchNext) {
+        this.nextCursor = nextCursor;
+        this.fetchNext = fetchNext;
+        this.devboxes = items;
+        this.has_more = !!nextCursor;
+        // Solari does not report a total; this is the count known so far.
+        this.total_count = items.length;
+    }
+    getPaginatedItems() {
+        return this.devboxes;
+    }
+    hasNextPage() {
+        return this.has_more;
+    }
+    async getNextPage() {
+        if (!this.nextCursor)
+            throw new RunloopError("No next page expected; please check `.hasNextPage()` before calling `.getNextPage()`.");
+        return this.fetchNext(this.nextCursor);
+    }
+    async *iterPages() {
+        let page = this;
+        yield page;
+        while (page.hasNextPage()) {
+            page = await page.getNextPage();
+            yield page;
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        for await (const p of this.iterPages())
+            for (const i of p.getPaginatedItems())
+                yield i;
+    }
+}
+function lines(buf, chunk, cb) {
+    if (!cb)
+        return;
+    buf.s += chunk;
+    let i;
+    while ((i = buf.s.indexOf("\n")) >= 0) {
+        cb(buf.s.slice(0, i + 1));
+        buf.s = buf.s.slice(i + 1);
+    }
+}
+let execSeq = 0;
+export class Devboxes {
+    client;
+    /** Disk snapshots (`client.devboxes.diskSnapshots`). */
+    diskSnapshots;
+    constructor(client) {
+        this.client = client;
+        this.diskSnapshots = new DiskSnapshots(client);
+    }
+    /** `POST /v1/devboxes` equivalent: create a sandbox. Returns once it is running. */
+    async create(params = {}, _options) {
+        // blueprint_id / blueprint_name are Solari templates: custom names resolve to the newest matching `tpl_` id.
+        const bp = params.blueprint_id ?? params.blueprint_name ?? null;
+        const resolved = bp ? await this.client.blueprints.resolveTemplate(bp) : null;
+        const tunnel = params.tunnel;
+        if (tunnel)
+            assertTunnelOptions(tunnel);
+        const t = translateCreate({ ...params, blueprint_id: null, tunnel: null, ...(resolved ? { blueprint_name: resolved } : {}) });
+        return this.createFrom(t, params);
+    }
+    async createAndAwaitRunning(params = {}, options) {
+        const v = await this.create(params, options);
+        return this.awaitRunning(v.id, options);
+    }
+    async createFrom(t, params) {
+        const c = this.client;
+        // A template that just finished building can read as still "building" on another gateway replica for up to the
+        // registry's 15 s cache TTL: retry `TemplateNotReady` for up to ~40 s instead of failing a create that is about to work.
+        let sb;
+        for (let attempt = 0; sb === undefined; attempt++) {
+            try {
+                sb = await c.solari.create(t.opts);
+            }
+            catch (e) {
+                if (e instanceof GatewayError && e.code === "TemplateNotReady" && attempt < 20)
+                    await sleep(2000);
+                else
+                    throw translateError(e);
+            }
+        }
+        const id = sb.sandboxId;
+        c.adopt(id, sb);
+        c.createdAtMs.set(id, Date.now());
+        c.keepAliveMs.set(id, t.opts.idleTimeoutMs ?? DEFAULT_KEEP_ALIVE_MS);
+        try {
+            if (Object.keys(t.fileMounts).length || t.launchCommands.length || t.entrypoint) {
+                const home = await c.home(id);
+                for (const [path, contents] of Object.entries(t.fileMounts))
+                    await this.writeAbs(id, absPath(home, path), contents);
+                for (const cmd of t.launchCommands) {
+                    const r = await c.on(id, (h) => h.commands.run("/bin/bash", { args: ["-lc", cmd], cwd: home }));
+                    if (r.exitCode !== 0) {
+                        throw new APIError(500, { message: `launch command failed (exit ${r.exitCode}): ${cmd}\n${r.stderr}` }, undefined, {});
+                    }
+                }
+                if (t.entrypoint)
+                    await c.on(id, (h) => h.commands.start("/bin/bash", { args: ["-lc", t.entrypoint], cwd: home }));
+            }
+            if (params.tunnel)
+                await this.enableTunnel(id, params.tunnel);
+        }
+        catch (e) {
+            await c.solari.kill(id).catch(() => undefined);
+            c.dropHandle(id);
+            throw e;
+        }
+        return this.retrieveFresh(id);
+    }
+    /** GET right after create can 404 on another gateway replica; retry briefly (0.3 s * n). */
+    async retrieveFresh(id) {
+        for (let n = 1;; n++) {
+            try {
+                return await this.retrieve(id);
+            }
+            catch (e) {
+                if (!(e instanceof NotFoundError) || n > 6)
+                    throw e;
+                await sleep(300 * n);
+            }
+        }
+    }
+    async retrieve(id, _options) {
+        const v = await translating(() => this.client.solari.get(id));
+        const created = this.client.createdAtMs.get(id);
+        if (created === undefined && v.createdAt === undefined) {
+            this.client.createdAtMs.set(id, Date.now());
+        }
+        const ka = this.client.keepAliveMs.get(id);
+        return toDevboxView(v, { createdAtMs: this.client.createdAtMs.get(id) ?? Date.now(), ...(ka ? { keepAliveSeconds: Math.floor(ka / 1000) } : {}) });
+    }
+    /** Does the gateway take `startingAfter=<sandboxId>` on GET /sandboxes? Probed once (it also adds `hasMore`). */
+    async supportsStartingAfter() {
+        if (this.client.startingAfterSupported === undefined) {
+            const probe = await translating(() => this.client.http.request("GET", "/sandboxes?kind=sandbox&limit=1"));
+            this.client.startingAfterSupported = "hasMore" in probe;
+        }
+        return this.client.startingAfterSupported;
+    }
+    /**
+     * List devboxes (sandboxes only). `starting_after` is an item id: a gateway with `startingAfter` support takes
+     * it directly; on an older one the client scans from the start and skips past it.
+     */
+    async list(params = {}, _options) {
+        const state = params.status ? statusToState(params.status) : undefined;
+        if (params.status && !state)
+            throw new SolariCompatUnsupported(`list status=${params.status}`);
+        const limit = params.limit ?? 20;
+        const native = params.starting_after ? await this.supportsStartingAfter() : false;
+        const fetchPage = async (cursor, startingAfter, skipUntil) => {
+            let cur = cursor;
+            let skipping = skipUntil;
+            for (;;) {
+                const q = new URLSearchParams({ kind: "sandbox", limit: String(limit) });
+                if (state)
+                    q.set("state", state);
+                if (cur)
+                    q.set("cursor", cur);
+                if (startingAfter && !cur)
+                    q.set("startingAfter", startingAfter);
+                if (params.include_total_count)
+                    q.set("includeTotalCount", "true");
+                const r = await translating(() => this.client.http.request("GET", `/sandboxes?${q}`));
+                if ("hasMore" in r)
+                    this.client.startingAfterSupported = true;
+                let items = r.sandboxes;
+                if (skipping) {
+                    const i = items.findIndex((s) => s.sandboxId === skipping);
+                    if (i >= 0) {
+                        items = items.slice(i + 1);
+                        skipping = undefined;
+                    }
+                    else if (r.nextCursor) {
+                        cur = r.nextCursor;
+                        continue;
+                    }
+                    else {
+                        items = [];
+                        skipping = undefined;
+                    }
+                }
+                const views = items
+                    .filter((s) => !params.status || mapStatus(s.state) === params.status || (params.status === "running" && s.state === "running"))
+                    .map((s) => toDevboxView(s, { createdAtMs: this.client.createdAtMs.get(s.sandboxId) ?? Date.now() }));
+                const page = new DevboxesCursorIDPage(views, r.nextCursor, (next) => fetchPage(next, undefined, undefined));
+                if (typeof r.totalCount === "number")
+                    page.total_count = r.totalCount;
+                if (typeof r.hasMore === "boolean")
+                    page.has_more = r.hasMore;
+                return page;
+            }
+        };
+        return fetchPage(undefined, native ? params.starting_after : undefined, native ? undefined : params.starting_after);
+    }
+    /**
+     * Update name / metadata (`PATCH /sandboxes/{id}`, pinetree-desktop#566). A gateway without the route
+     * answers 404; since a real missing devbox is also a 404, the devbox is re-read to tell them apart.
+     */
+    async update(id, params, _options) {
+        const body = {};
+        if (params.name !== undefined)
+            body.name = params.name;
+        if (params.metadata !== undefined)
+            body.metadata = params.metadata;
+        try {
+            await this.client.http.request("PATCH", `/sandboxes/${encodeURIComponent(id)}`, body);
+        }
+        catch (e) {
+            if (e instanceof GatewayError && (e.status === 404 || e.status === 405)) {
+                await this.retrieve(id); // a real missing devbox raises NotFoundError here
+                throw new SolariCompatUnsupported("devboxes.update", "This gateway has no PATCH /sandboxes/{id} yet");
+            }
+            throw translateError(e);
+        }
+        return this.retrieve(id);
+    }
+    /**
+     * Devbox logs. Uses the gateway's `GET /sandboxes/{id}/logs` when it has one; otherwise returns the output of the
+     * commands run through THIS client instance (they are not durable across processes).
+     */
+    async logs(id, params = {}, _options) {
+        const q = new URLSearchParams();
+        if (params.execution_id)
+            q.set("executionId", params.execution_id);
+        try {
+            const d = await this.client.http.request("GET", `/sandboxes/${encodeURIComponent(id)}/logs${q.toString() ? `?${q}` : ""}`);
+            const logs = (d.logs ?? []).map((e) => ({
+                level: e.source === "stderr" ? "ERROR" : "INFO",
+                source: (e.source === "entrypoint" ? "entrypoint" : "exec"),
+                timestamp_ms: typeof e.ts === "number" ? e.ts : Date.parse(String(e.ts ?? "")) || Date.now(),
+                message: e.message ?? "",
+                ...(e.executionId ? { cmd_id: e.executionId } : {}),
+            }));
+            return { logs: params.text ? logs.filter((l) => (l.message ?? "").includes(params.text)) : logs };
+        }
+        catch (e) {
+            if (!(e instanceof GatewayError && (e.status === 404 || e.status === 405)))
+                throw translateError(e);
+            await this.retrieve(id); // a real missing devbox raises NotFoundError here
+            if (params.shell_name)
+                return { logs: [] };
+            const rows = (this.client.localLogs.get(id) ?? []).filter((r) => !params.execution_id || r.execId === params.execution_id);
+            const logs = rows
+                .filter((r) => !params.text || r.message.includes(params.text))
+                .map((r) => ({
+                level: r.stream === "stderr" ? "ERROR" : "INFO",
+                source: "exec",
+                timestamp_ms: r.ts,
+                cmd: r.cmd,
+                cmd_id: r.execId,
+                ...(r.stream === "exit" ? { exit_code: r.exitCode ?? null } : { message: r.message }),
+            }));
+            return { logs };
+        }
+    }
+    async shutdown(id, _params, _options) {
+        let before;
+        try {
+            before = await this.retrieve(id);
+        }
+        catch {
+            /* already gone: kill is idempotent */
+        }
+        await translating(() => this.client.solari.kill(id));
+        this.client.dropHandle(id);
+        this.client.keepAliveMs.delete(id);
+        const now = Date.now();
+        const base = before ?? { id, create_time_ms: now, metadata: {}, launch_parameters: {}, capabilities: [], state_transitions: [] };
+        return {
+            ...base,
+            status: "shutdown",
+            end_time_ms: now,
+            state_transitions: [...base.state_transitions, { status: "shutdown", transition_time_ms: now }],
+        };
+    }
+    async suspend(id, _options) {
+        await this.client.on(id, (sb) => sb.pause());
+        return this.retrieve(id);
+    }
+    /** Resume a suspended devbox and wait until it is running. */
+    async resume(id, options) {
+        await this.resumeAsync(id, options);
+        let v = await this.awaitRunning(id, options);
+        // The gateway's view can flap running/paused for a second or two right after a resume
+        // (observed on staging), so require a short run of consecutive "running" reads.
+        for (let ok = 1, tries = 0; ok < 3 && tries < 40; tries++) {
+            await sleep(300);
+            v = await this.retrieve(id);
+            ok = v.status === "running" ? ok + 1 : 1;
+        }
+        return v;
+    }
+    async resumeAsync(id, _options) {
+        const sb = await this.client.handle(id);
+        try {
+            await translating(() => sb.resume());
+        }
+        catch (e) {
+            // The resume itself succeeded server-side if only the channel reconnect failed: reconnect fresh.
+            if (!(e instanceof APIConnectionError))
+                throw e;
+            this.client.dropHandle(id);
+            await this.client.on(id, async () => undefined);
+        }
+        return this.retrieve(id);
+    }
+    /** Extend the idle window by re-arming the timeout. */
+    async keepAlive(id, _options) {
+        const ms = this.client.keepAliveMs.get(id) ?? DEFAULT_KEEP_ALIVE_MS;
+        await this.client.on(id, (sb) => sb.setTimeout(ms));
+        return {};
+    }
+    awaitRunning(id, options) {
+        return this.poll(id, "running", options);
+    }
+    awaitSuspended(id, options) {
+        return this.poll(id, "suspended", options);
+    }
+    async poll(id, want, options) {
+        const interval = options?.polling?.pollingIntervalMs ?? 1000;
+        const maxAttempts = options?.polling?.maxAttempts ?? 120;
+        const deadline = options?.polling?.timeoutMs ? Date.now() + options.polling.timeoutMs : Infinity;
+        for (let i = 0; i < maxAttempts; i++) {
+            const v = await this.retrieve(id);
+            if (v.status === want)
+                return v;
+            if (v.status === "failure" || v.status === "shutdown") {
+                throw new APIError(409, { message: `Devbox ${id} is ${v.status}, expected ${want}` }, undefined, {});
+            }
+            if (Date.now() > deadline)
+                break;
+            await sleep(interval);
+        }
+        throw new APIConnectionTimeoutError({ message: `Timed out waiting for devbox ${id} to be ${want}` });
+    }
+    // --- execution ----------------------------------------------------------
+    /** Start a shell command and track it. `callbacks` receive complete lines. */
+    async startExecution(id, command, callbacks = {}) {
+        if (command.trim() === "")
+            throw new APIError(400, { message: "command must not be empty" }, undefined, {});
+        const home = await this.client.home(id);
+        const handle = await this.client.on(id, (sb) => sb.commands.start("/bin/bash", { args: ["-lc", command], cwd: home }));
+        const exec = {
+            executionId: `exec_${handle.cmdId}_${++execSeq}`,
+            devboxId: id,
+            status: "running",
+            exitStatus: null,
+            stdout: "",
+            stderr: "",
+            handle,
+            done: Promise.resolve(),
+        };
+        const ob = { s: "" };
+        const eb = { s: "" };
+        const record = (stream, message, exitCode) => {
+            const arr = this.client.localLogs.get(id) ?? [];
+            arr.push({ ts: Date.now(), cmd: command, execId: exec.executionId, stream, message, ...(exitCode !== undefined ? { exitCode } : {}) });
+            if (arr.length > 2000)
+                arr.splice(0, arr.length - 2000);
+            this.client.localLogs.set(id, arr);
+        };
+        handle.onData((c) => {
+            record(c.stream === "stderr" ? "stderr" : "stdout", c.data);
+            if (c.stream === "stdout") {
+                exec.stdout += c.data;
+                lines(ob, c.data, callbacks.stdout);
+                lines({ s: "" }, c.data, callbacks.output);
+            }
+            else {
+                exec.stderr += c.data;
+                lines(eb, c.data, callbacks.stderr);
+                lines({ s: "" }, c.data, callbacks.output);
+            }
+        });
+        exec.done = handle.wait().then((code) => {
+            exec.exitStatus = code;
+            exec.status = "completed";
+            record("exit", "", code);
+            if (ob.s)
+                callbacks.stdout?.(ob.s);
+            if (eb.s)
+                callbacks.stderr?.(eb.s);
+        }, (e) => {
+            exec.status = "completed";
+            exec.exitStatus = exec.exitStatus ?? -1;
+            throw translatingError(e);
+        });
+        exec.done.catch(() => undefined);
+        this.client.executions.set(exec.executionId, exec);
+        return exec;
+    }
+    view(rec) {
+        return {
+            devbox_id: rec.devboxId,
+            execution_id: rec.executionId,
+            status: rec.status,
+            exit_status: rec.exitStatus,
+            stdout: rec.stdout,
+            stderr: rec.stderr,
+            stdout_truncated: false,
+            stderr_truncated: false,
+        };
+    }
+    /** Run to completion and return the final detail view (`execute_and_await_completion`). */
+    async executeAndAwaitCompletion(id, params, _options) {
+        if (params.shell_name)
+            throw new SolariCompatUnsupported("named shells (shell_name)");
+        const rec = await this.startExecution(id, params.command);
+        await rec.done;
+        return this.view(rec);
+    }
+    async executeSync(id, params, options) {
+        if (params.attach_stdin)
+            throw new SolariCompatUnsupported("attach_stdin on a synchronous execute");
+        const v = await this.executeAndAwaitCompletion(id, { command: params.command, shell_name: params.shell_name ?? null }, options);
+        return { devbox_id: id, exit_status: v.exit_status ?? 0, stdout: v.stdout ?? "", stderr: v.stderr ?? "" };
+    }
+    async execute(id, params, options) {
+        return this.executeAndAwaitCompletion(id, params, options);
+    }
+    async executeAsync(id, params, _options) {
+        if (params.shell_name)
+            throw new SolariCompatUnsupported("named shells (shell_name)");
+        const rec = await this.startExecution(id, params.command);
+        return this.view(rec);
+    }
+    /** REST executions resource (`client.devboxes.executions.*`), in-process registry only. */
+    get executions() {
+        return new Executions(this);
+    }
+    async waitForCommand(id, executionId, params = {}, _options) {
+        const rec = this.findExecution(id, executionId);
+        const want = params.statuses ?? ["completed"];
+        const timeoutMs = (params.timeout_seconds ?? 30) * 1000;
+        if (want.includes("completed")) {
+            await Promise.race([rec.done.catch(() => undefined), sleep(timeoutMs)]);
+        }
+        return this.view(rec);
+    }
+    async listDiskSnapshots(params = {}) {
+        return this.diskSnapshots.list(params);
+    }
+    async deleteDiskSnapshot(snapshotId) {
+        return this.diskSnapshots.delete(snapshotId);
+    }
+    /** Executions are tracked per client instance only (Solari has no durable execution records yet). */
+    findExecution(id, executionId) {
+        const rec = this.client.executions.get(executionId);
+        if (!rec || rec.devboxId !== id) {
+            throw new NotFoundError(404, { message: `Execution ${executionId} is not known to this client; durable executions are not supported` }, undefined, {});
+        }
+        return rec;
+    }
+    // --- files ----------------------------------------------------------------
+    async readFileContents(id, params, _options) {
+        const path = absPath(await this.client.home(id), params.file_path);
+        return this.client.on(id, (sb) => sb.files.readText(path));
+    }
+    /** Write a file, creating its parent directories. */
+    async writeAbs(id, path, data, upload = false) {
+        const parent = path.slice(0, path.lastIndexOf("/")) || "/";
+        await this.client.on(id, (sb) => sb.commands.run("/bin/mkdir", { args: ["-p", parent] }));
+        await this.client.on(id, (sb) => (upload ? sb.files.upload(path, data) : sb.files.write(path, data)));
+    }
+    async writeFileContents(id, params, _options) {
+        await this.writeAbs(id, absPath(await this.client.home(id), params.file_path), params.contents);
+        return { devbox_id: id, exit_status: 0, stdout: "", stderr: "" };
+    }
+    async downloadFile(id, params, _options) {
+        const path = absPath(await this.client.home(id), params.path);
+        const bytes = await this.client.on(id, (sb) => sb.files.download(path));
+        return new Response(bytes, { status: 200, headers: { "content-type": "application/octet-stream" } });
+    }
+    async uploadFile(id, params, _options) {
+        const f = params.file;
+        let data;
+        if (f === undefined)
+            throw new APIError(400, { message: "uploadFile requires `file`" }, undefined, {});
+        else if (typeof f === "string" || f instanceof Uint8Array)
+            data = f;
+        else if (f instanceof ArrayBuffer)
+            data = new Uint8Array(f);
+        else
+            data = new Uint8Array(await f.arrayBuffer());
+        await this.writeAbs(id, absPath(await this.client.home(id), params.path), data, true);
+        return {};
+    }
+    // --- snapshots / misc ------------------------------------------------------
+    async snapshotDisk(id, params = {}, _options) {
+        let snapId;
+        for (let attempt = 0; snapId === undefined; attempt++) {
+            try {
+                snapId = await this.client.on(id, (sb) => sb.snapshot(params.name ?? undefined));
+            }
+            catch (e) {
+                // NotRunning / "Not snapshottable" right after a resume is a stale read on another gateway replica
+                // (observed on staging: up to ~20 s). Retry for up to a minute before giving up.
+                const err = e;
+                const transient = err.error?.code === "NotRunning" || /not snapshottable/i.test(err.message ?? "") || /not snapshottable/i.test(err.error?.error ?? "");
+                if (transient && attempt < 60)
+                    await sleep(1000);
+                else
+                    throw e;
+            }
+        }
+        // The snapshot record can briefly 404 on another gateway replica.
+        let s;
+        for (let n = 1; s === undefined; n++) {
+            try {
+                s = await this.client.solari.getSnapshot(snapId);
+            }
+            catch (e) {
+                if (!(e instanceof GatewayError && e.status === 404) || n > 6)
+                    throw translateError(e);
+                await sleep(300 * n);
+            }
+        }
+        // commit_message / metadata are echoed on this response but not stored until the gateway supports them.
+        return toSnapshotView(s, id, { metadata: params.metadata ?? null, commitMessage: params.commit_message ?? null });
+    }
+    /** Solari snapshots are synchronous, so the "async" call returns an already-complete snapshot. */
+    snapshotDiskAsync(id, params = {}, options) {
+        return this.snapshotDisk(id, params, options);
+    }
+    /**
+     * The devbox's tunnel (`GET /sandboxes/:id/tunnel`, re-mints `auth_token`). Rejects with `NotFoundError` when
+     * none is enabled. On a gateway without tunnel routes only an open tunnel enabled through this client can be shown.
+     */
+    async tunnelView(id, port = 8080) {
+        try {
+            return toTunnelView(await this.client.http.request("GET", `/sandboxes/${encodeURIComponent(id)}/tunnel`));
+        }
+        catch (e) {
+            if (!(e instanceof GatewayError) || e.status !== 404)
+                throw translateError(e);
+            if (e.body?.code === "TunnelNotEnabled")
+                throw translateError(e);
+            if (!this.client.tunnels.has(id))
+                throw translateError(e);
+        }
+        // Gateway without tunnel routes: the open per-port preview URL has `<key>-<port>` as its first label.
+        const url = new URL(await this.previewUrl(id, port));
+        const first = url.hostname.split(".")[0] ?? "";
+        const key = first.endsWith(`-${port}`) ? first.slice(0, -`-${port}`.length) : first;
+        return { auth_mode: "open", create_time_ms: Date.now(), http_keep_alive: false, tunnel_key: key, wake_on_http: false };
+    }
+    /** `getTunnel()`: the tunnel, or `null` when none is enabled. */
+    async tunnelOrNull(id) {
+        try {
+            return await this.tunnelView(id);
+        }
+        catch (e) {
+            if (e instanceof NotFoundError)
+                return null;
+            throw e;
+        }
+    }
+    /**
+     * `POST /sandboxes/:id/tunnel`: authenticated (default) or open, `wake_on_http`, `http_keep_alive`. Idempotent;
+     * the returned `auth_token` (authenticated only) is valid on every port for an hour and dies with `removeTunnel`.
+     */
+    async enableTunnel(id, params = {}, _options) {
+        assertTunnelOptions(params);
+        const body = {
+            authMode: params.auth_mode ?? "authenticated",
+            ...(params.wake_on_http != null ? { wakeOnHttp: params.wake_on_http } : {}),
+            ...(params.http_keep_alive != null ? { keepAlive: params.http_keep_alive } : {}),
+        };
+        try {
+            return toTunnelView(await this.client.http.request("POST", `/sandboxes/${encodeURIComponent(id)}/tunnel`, body));
+        }
+        catch (e) {
+            // A gateway without tunnel routes (404/405): only the open per-port preview URL exists.
+            const absent = e instanceof GatewayError && (e.status === 404 || e.status === 405);
+            if (!absent || body.authMode !== "open" || body.wakeOnHttp || body.keepAlive)
+                throw translateError(e);
+        }
+        this.client.tunnels.add(id);
+        return this.tunnelView(id);
+    }
+    async previewUrl(id, port) {
+        return (await this.client.on(id, (sb) => sb.previewUrl(port))).url;
+    }
+    /** `DELETE /sandboxes/:id/tunnel`: idempotent; revokes every `auth_token`. */
+    async removeTunnel(id, _options) {
+        this.client.tunnels.delete(id);
+        await translating(() => this.client.http.request("DELETE", `/sandboxes/${encodeURIComponent(id)}/tunnel`));
+    }
+    createSSHKey() {
+        throw new SolariCompatUnsupported("devboxes.createSSHKey");
+    }
+    watchEvictions() {
+        throw new SolariCompatUnsupported("devboxes.watchEvictions");
+    }
+}
+function translatingError(e) {
+    return e instanceof Error ? e : new RunloopError(String(e));
+}
+function assertTunnelOptions(t) {
+    if (t.auth_mode && t.auth_mode !== "open" && t.auth_mode !== "authenticated")
+        throw new SolariCompatUnsupported(`tunnel auth_mode=${t.auth_mode}`, "use 'open' or 'authenticated'");
+    if (t.auth_mode === "open" && t.wake_on_http)
+        throw new SolariCompatUnsupported("tunnel wake_on_http with auth_mode=open", "wake only on authenticated tunnels");
+}
+/** `https://<label>-{port}.<domain>` -> the `<label>` (Runloop's `tunnel_key`). */
+function toTunnelView(w) {
+    const first = (w.urlTemplate.replace(/^https?:\/\//, "").split(".")[0] ?? "");
+    const key = first.endsWith("-{port}") ? first.slice(0, -"-{port}".length) : first;
+    return {
+        auth_mode: w.authMode,
+        create_time_ms: Date.now(),
+        http_keep_alive: !!w.keepAlive,
+        tunnel_key: key,
+        wake_on_http: !!w.wakeOnHttp,
+        ...(w.authToken ? { auth_token: w.authToken } : {}),
+    };
+}
+export class Executions {
+    dev;
+    constructor(dev) {
+        this.dev = dev;
+    }
+    retrieve(devboxId, executionId, _params, _options) {
+        return Promise.resolve(this.dev.view(this.dev.findExecution(devboxId, executionId)));
+    }
+    awaitCompleted(devboxId, executionId, _options) {
+        return this.dev.waitForCommand(devboxId, executionId, { statuses: ["completed"], timeout_seconds: 3600 });
+    }
+    executeAsync(devboxId, params, options) {
+        return this.dev.executeAsync(devboxId, params, options);
+    }
+    executeSync(devboxId, params, options) {
+        return this.dev.executeSync(devboxId, params, options);
+    }
+    async kill(devboxId, executionId, _params, _options) {
+        const rec = this.dev.findExecution(devboxId, executionId);
+        await rec.handle?.kill();
+        return this.dev.view(rec);
+    }
+    async sendStdIn(devboxId, executionId, params, _options) {
+        const rec = this.dev.findExecution(devboxId, executionId);
+        if (params.text != null)
+            await rec.handle?.stdin(params.text);
+        return this.dev.view(rec);
+    }
+}
+export class DiskSnapshots {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async list(params = {}) {
+        const r = await translating(() => this.client.solari.listSnapshots({ kind: "sandbox", ...(params.limit ? { limit: params.limit } : {}) }));
+        let snaps = r.snapshots;
+        if (params.starting_after) {
+            const i = snaps.findIndex((s) => s.id === params.starting_after);
+            snaps = i >= 0 ? snaps.slice(i + 1) : [];
+        }
+        const views = snaps.map((s) => toSnapshotView(s));
+        return { snapshots: views, has_more: false, total_count: views.length };
+    }
+    async retrieve(id) {
+        return toSnapshotView(await translating(() => this.client.solari.getSnapshot(id)));
+    }
+    /**
+     * `DELETE /snapshots/{id}`. Large snapshots are erased incrementally: the gateway answers `202 {ok:false,
+     * status:"deleting"}`, keeps the row and expects the same DELETE again. Runloop's delete is "done when it returns",
+     * so this repeats the call (backoff 1 s doubling to 5 s) until the gateway says ok, or a 404 after a 202 says the
+     * previous pass finished, for at most `maxWaitMs` (default 5 min). It then raises rather than claim success.
+     */
+    async delete(id, opts = {}) {
+        const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        const now = opts.now ?? Date.now;
+        const maxWaitMs = opts.maxWaitMs ?? 5 * 60_000;
+        const started = now();
+        let delay = 1000;
+        for (let attempt = 0;; attempt++) {
+            let r;
+            try {
+                r = await this.client.http.request("DELETE", `/snapshots/${encodeURIComponent(id)}`);
+            }
+            catch (e) {
+                if (attempt > 0 && e instanceof GatewayError && e.status === 404)
+                    return {};
+                throw translateError(e);
+            }
+            if (!(r && r.ok === false && r.status === "deleting"))
+                return {};
+            if (now() - started + delay > maxWaitMs) {
+                throw new APIError(504, { message: `Snapshot ${id} is still being deleted after ${Math.round((now() - started) / 1000)} s; call delete again to continue` }, undefined, {});
+            }
+            await sleep(delay);
+            delay = Math.min(delay * 2, 5000);
+        }
+    }
+    /** `PATCH /snapshots/{id}` (pinetree-desktop#566); unsupported on a gateway without it. */
+    async update(id, params = {}) {
+        const body = {};
+        if (params.name !== undefined)
+            body.name = params.name;
+        if (params.commit_message !== undefined)
+            body.commitMessage = params.commit_message;
+        if (params.metadata !== undefined)
+            body.metadata = params.metadata;
+        try {
+            await this.client.http.request("PATCH", `/snapshots/${encodeURIComponent(id)}`, body);
+        }
+        catch (e) {
+            if (e instanceof GatewayError && (e.status === 404 || e.status === 405)) {
+                await this.retrieve(id); // a real missing snapshot raises NotFoundError here
+                throw new SolariCompatUnsupported("snapshot.update", "This gateway has no PATCH /snapshots/{id} yet");
+            }
+            throw translateError(e);
+        }
+        return this.retrieve(id);
+    }
+}
+//# sourceMappingURL=client.js.map