withruntime 0.11.1 → 0.12.0

package/dist/runloop/sdk.js

@@ -0,0 +1,167 @@
+import { Runloop, } from "./index.js";
+import { only } from "../compat/core.js";
+export class RunloopError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RunloopError";
+    }
+}
+/** The high-level command handles share the low-level adapter's validation,
+ * cancellation and process input path; they never send a provider request. */
+export class RunloopSDK {
+    api;
+    devbox;
+    constructor(options = {}) {
+        this.api = new Runloop(options);
+        this.devbox = {
+            fromId: (id) => new Devbox(this.api, id),
+            create: async (params = {}, request) => {
+                const info = await this.api.devboxes.createAndAwaitRunning(params, request);
+                return new Devbox(this.api, info.id);
+            },
+        };
+    }
+    get secret() {
+        return this.api.secrets;
+    }
+    get storageObject() {
+        return this.api.objects;
+    }
+    get axon() {
+        return this.api.axons;
+    }
+    get gatewayConfig() {
+        return this.api.gatewayConfigs;
+    }
+    get mcpConfig() {
+        return this.api.mcpConfigs;
+    }
+    get networkPolicy() {
+        return this.api.networkPolicies;
+    }
+}
+export class Devbox {
+    client;
+    id;
+    cmd;
+    constructor(client, id) {
+        this.client = client;
+        this.id = id;
+        const start = async (command, params = {}, options) => {
+            only("Runloop command; use devboxes.executions streams for output callbacks", params, [
+                "shell_name",
+                "attach_stdin",
+            ]);
+            const initial = await client.devboxes.executeAsync(id, { command, ...params }, options);
+            return new Execution(client, id, initial.execution_id, initial);
+        };
+        this.cmd = {
+            execAsync: start,
+            exec: async (command, params = {}, options) => {
+                if (params.attach_stdin)
+                    throw new TypeError("attach_stdin requires cmd.execAsync");
+                return (await start(command, params, options)).result(options);
+            },
+        };
+    }
+    getInfo(options) {
+        return this.client.devboxes.retrieve(this.id, options);
+    }
+    shutdown(options) {
+        return this.client.devboxes.shutdown(this.id, {}, options);
+    }
+    suspend(options) {
+        return this.client.devboxes.suspend(this.id, options);
+    }
+    resume(options) {
+        return this.client.devboxes.resume(this.id, options);
+    }
+}
+export class Execution {
+    client;
+    devboxId;
+    executionId;
+    streamingPromise;
+    constructor(client, devboxId, executionId, _initialResult, streamingPromise) {
+        this.client = client;
+        this.devboxId = devboxId;
+        this.executionId = executionId;
+        this.streamingPromise = streamingPromise;
+    }
+    async sendStdIn(input, options) {
+        await this.input({ text: input }, options);
+    }
+    async closeStdIn(options) {
+        await this.input({ signal: "EOF" }, options);
+    }
+    async input(body, options) {
+        const response = await this.client.devboxes.executions.sendStdIn(this.devboxId, this.executionId, body, options);
+        if (!response.success)
+            throw new RunloopError(`Failed to send stdin to execution ${this.executionId}`);
+    }
+    getState(options) {
+        return this.client.devboxes.executions.retrieve(this.devboxId, this.executionId, {}, options);
+    }
+    async kill(options) {
+        await this.client.devboxes.executions.kill(this.devboxId, this.executionId, {}, options);
+    }
+    async result(options = {}) {
+        only("Runloop execution result; use Runtime process waits for other wait options", options, [
+            "signal",
+            "timeout",
+            "idempotencyKey",
+        ]);
+        const [command] = await Promise.allSettled([
+            this.client.devboxes.executions.awaitCompleted(this.devboxId, this.executionId, options),
+            this.streamingPromise,
+        ]);
+        if (command.status === "rejected")
+            throw command.reason;
+        return new ExecutionResult(this.client, this.devboxId, this.executionId, command.value);
+    }
+}
+export class ExecutionResult {
+    client;
+    devboxId;
+    executionId;
+    result;
+    constructor(client, devboxId, executionId, result) {
+        this.client = client;
+        this.devboxId = devboxId;
+        this.executionId = executionId;
+        this.result = result;
+    }
+    get exitCode() {
+        return this.result.exit_status ?? null;
+    }
+    get success() {
+        return this.exitCode === 0;
+    }
+    get failed() {
+        return this.exitCode !== null && this.exitCode !== 0;
+    }
+    stdout(numLines) {
+        return this.output("stdout", numLines);
+    }
+    stderr(numLines) {
+        return this.output("stderr", numLines);
+    }
+    async output(channel, numLines) {
+        let output = this.result[channel] ?? "";
+        if (this.result[`${channel}_truncated`] &&
+            (numLines === undefined || output.split("\n").filter(Boolean).length < numLines)) {
+            output = "";
+            const executions = this.client.devboxes.executions;
+            const stream = channel === "stdout"
+                ? executions.streamStdoutUpdates(this.devboxId, this.executionId)
+                : executions.streamStderrUpdates(this.devboxId, this.executionId);
+            for await (const chunk of stream)
+                output += chunk.output;
+        }
+        if (numLines === undefined)
+            return output;
+        if (numLines <= 0)
+            return "";
+        return output.replace(/\n+$/, "").split("\n").slice(-numLines).join("\n");
+    }
+}

package/dist/sandbox.d.ts

@@ -1,27 +1,26 @@
-import { Page } from "./page.js";
+import type { Page } from "./page.js";
 import { type FileEvent, type WatchHandle, type WatchOptions } from "./products/watch.js";
 import { Transport, type RequestOptions } from "./transport.js";
-import type { CommandResult, DeletedSandbox, ExecOptions, FileEntry, OutputEvent, BinaryOutputEvent, KeepAliveOptions, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
+import type { CommandResult, DeletedSandbox, ExecOptions, FileEntry, OutputEvent, BinaryOutputEvent, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
 import { type SandboxExtensions } from "./products/index.js";
-import type { Snapshot, SnapshotOptions } from "./snapshots.js";
 import { Tunnel, type PortForward } from "./tunnel.js";
 import type { StreamUploadSource } from "./file-source.js";
-/** DELETE /v1/sandboxes/{id}, for `sandbox.delete()` and
- * `runtime.sandboxes.delete(id)`. */
-export declare function deleteSandbox(t: Transport, id: string, options?: RequestOptions): Promise<DeletedSandbox>;
+import { Machine, type MachineProduct } from "./machine.js";
+/** Sandboxes, as a product of the machine engine (machine.ts). */
+export declare const SANDBOXES: MachineProduct;
 /** A running (or stopped) sandbox. Every method is one API call or a short
- * sequence of them; `await using sbx = await Sandbox.create()` stops it for
- * you at the end of the block. */
+ * sequence of them; `await using sbx = await Sandbox.create()` deletes it at
+ * the end of the block, or stops it, keeping its disk, if created with
+ * `keep: true`. */
 export interface Sandbox extends SandboxExtensions {
 }
-export declare class Sandbox implements AsyncDisposable {
+export declare class Sandbox extends Machine<SandboxInfo, SandboxSettings, DeletedSandbox> {
     #private;
     readonly files: Files;
     readonly processes: Processes;
     /** Short-lived tokens that let a browser reach this sandbox directly. */
     readonly sessions: SandboxSessions;
     constructor(transport: Transport, info: SandboxInfo);
-    get id(): string;
     /** A sandbox reached with a session token instead of an API key, for code in
      * a browser: commands and their streams, processes, files and previews of
      * this one sandbox. Makes no call; `info` holds only the id until
@@ -39,14 +38,6 @@ export declare class Sandbox implements AsyncDisposable {
         apiUrl?: string;
         fetch?: typeof fetch;
     }): Sandbox;
-    /** What the API last said about this sandbox. `refresh()` asks again. */
-    get info(): SandboxInfo;
-    get state(): SandboxInfo["state"];
-    refresh(options?: RequestOptions): Promise<this>;
-    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
-    waitFor(state: "running" | "paused" | "stopped", options?: {
-        timeoutSeconds?: number;
-    } & RequestOptions): Promise<this>;
     /** Runs a command and returns its exit code and output. A string runs under
      * `bash -c`; an array runs without a shell. With onStdout/onStderr the output
      * streams as it happens. A timeout is a result (timedOut: true, the output so
@@ -94,76 +85,6 @@ export declare class Sandbox implements AsyncDisposable {
         localPort?: number;
         host?: string;
     }): Promise<PortForward>;
-    stop(options?: RequestOptions & {
-        wait?: boolean;
-    }): Promise<this>;
-    pause(options?: RequestOptions & {
-        wait?: boolean;
-    }): Promise<this>;
-    /** Deletes it for good: stops it if it runs or is paused, deletes its disk
-     * and paused memory, revokes its previews and ports, and removes it from
-     * lists. Its snapshots, usage and audit entries stay. Deleting it again
-     * answers the same. */
-    delete(options?: RequestOptions): Promise<DeletedSandbox>;
-    /** Carries on a paused sandbox; for one with a time limit,
-     * `timeoutSeconds` is its new one. */
-    wake(options?: RequestOptions & {
-        wait?: boolean;
-        timeoutSeconds?: number;
-    }): Promise<this>;
-    /** More time before its time limit ends (at most an hour ahead of now). A
-     * sandbox with no time limit needs none: the call answers at once and
-     * changes nothing. */
-    extend(seconds: number, options?: RequestOptions): Promise<this>;
-    /** Changes its name, labels, automatic wake, idle pause or persistence;
-     * fields left out stay as they are. `persistent: true` keeps it running
-     * while credit lasts (paid only). */
-    update(settings: SandboxSettings, options?: RequestOptions): Promise<this>;
-    /** Moves it to another image (id, name, name:tag or name@version), keeping
-     * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
-     * volumes, environment, name and previews. Its processes restart, and
-     * everything else on its old disk (sudo installs, apt packages, /etc) is
-     * lost; snapshot it first to keep everything. A running sandbox is paused
-     * first. A switch that fails is undone (`switch_undone`), the sandbox on
-     * its old image with nothing lost. Charged as a wake. `keep` is optional:
-     * "workspace" is the only value, and it is sent either way, so an API from
-     * before it was optional accepts the call too. */
-    switchImage(image: string, options?: RequestOptions & {
-        keep?: "workspace";
-    }): Promise<this>;
-    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
-     * whole disk, volumes, environment, name and previews stay, and its
-     * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
-     * persistent, and comes back running at the new size on the same server; a
-     * paused or stopped one is started. Memory bills on the new size from then.
-     * Refused, with nothing changed, when the server has no room
-     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
-     * while a snapshot or fork of it is being taken. `restart` is optional:
-     * true is the only value, and it is sent either way, so an API from before
-     * it was optional accepts the call too. */
-    resize(size: {
-        vcpu?: number;
-        memoryMiB?: number;
-    }, options?: RequestOptions & {
-        restart?: true;
-    }): Promise<this>;
-    /** Keeps a sandbox with a time limit running past it, in the background,
-     * until stop() or the returned function ends it: every `everySeconds` (60)
-     * it extends the limit so that `marginSeconds` (600) remain, never more
-     * than the hour ahead the API allows. A sandbox with no time limit
-     * (`endsAt` null) needs none, and is only watched. Running time is billed
-     * as it is used. A paused sandbox is left paused (a request wakes it,
-     * unless autoWake is off); a stopped one ends the loop. It does not keep a
-     * Node or Bun process alive by itself. */
-    keepAlive(options?: KeepAliveOptions): () => void;
-    /** Days a paused sandbox is kept before deletion (1 to 365). */
-    setRetention(days: number, options?: RequestOptions): Promise<this>;
-    /** Keeps this sandbox's whole machine (files, memory, running processes) as
-     * a snapshot to start new sandboxes from. A running sandbox is paused for
-     * the moment it takes, then woken; a paused one stays paused. Past
-     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
-     * the error names the snapshot. */
-    snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
     /** Copies of this sandbox as it is now (files, memory, running processes),
      * each its own sandbox, answered once they run. A running sandbox is paused
      * for the moment its snapshot takes, then woken. One without `count`; an
@@ -182,12 +103,6 @@ export declare class Sandbox implements AsyncDisposable {
         keepSnapshot?: boolean;
         funding?: "trial" | "paid";
     } & RequestOptions): Promise<Sandbox[]>;
-    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
-    restart(options?: RequestOptions & {
-        wait?: boolean;
-    }): Promise<this>;
-    [Symbol.asyncDispose](): Promise<void>;
-    toJSON(): SandboxInfo;
 }
 /** A sandbox session, as the API answers it. `token` is set only in the
  * answer to `create`. */
@@ -411,6 +326,7 @@ export declare class Files {
      * the API's folder route. */
     download(remotePath: string, localPath: string, options?: RequestOptions): Promise<void>;
 }
+/** One page of `runtime.sandboxes.list()`, and the pages after it. */
 export declare function sandboxPage(t: Transport, body: {
     data: SandboxInfo[];
     nextCursor: string | null;