withruntime 0.11.2 → 0.14.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

@@ -8,9 +8,14 @@ import type { StreamUploadSource } from "./file-source.js";
 import { Machine, type MachineProduct } from "./machine.js";
 /** Sandboxes, as a product of the machine engine (machine.ts). */
 export declare const SANDBOXES: MachineProduct;
+/** How long past its timeoutMs a streamed exec waits for an exit that never came. */
+export declare const EXEC_EXIT_GRACE: {
+    ms: number;
+};
 /** 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 extends Machine<SandboxInfo, SandboxSettings, DeletedSandbox> {

package/dist/sandbox.js

@@ -1,7 +1,7 @@
 import { STREAMED_EXEC_TIMEOUT_MS } from "./api-defaults.js";
 import { CommandError, ConnectionError, DELIBERATE, errorFor, NotFoundError, RateLimitError, RuntimeError, ServiceUnavailableError, } from "./errors.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
-import { Transport } from "./transport.js";
+import { Transport, timeoutSignal } from "./transport.js";
 import { sandboxFactories } from "./products/index.js";
 import { Tunnel } from "./tunnel.js";
 import { pause } from "./wait.js";
@@ -20,7 +20,7 @@ const enc = (id) => encodeURIComponent(id);
 function requestScope(options) {
     const deadline = options.timeoutMs === undefined || options.timeoutMs === 0
         ? undefined
-        : AbortSignal.timeout(options.timeoutMs);
+        : timeoutSignal(options.timeoutMs);
     const signal = deadline && options.signal
         ? AbortSignal.any([deadline, options.signal])
         : (deadline ?? options.signal);
@@ -87,6 +87,8 @@ function commandBody(command, options) {
         ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     };
 }
+/** How long past its timeoutMs a streamed exec waits for an exit that never came. */
+export const EXEC_EXIT_GRACE = { ms: 120_000 };
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Sandbox extends Machine {
     #t;
@@ -147,8 +149,22 @@ export class Sandbox extends Machine {
             let exit;
             let processId;
             let dropped = false;
+            // A command with a time limit ends by it, the server killing it if need
+            // be; an exit that never comes after (a follow that resumes forever)
+            // ends the wait past the limit and EXEC_EXIT_GRACE.ms, as a timeout,
+            // its process named and sent SIGTERM. The hub's release train waited
+            // 29 min on a 10 min command (15 October 2026).
+            // A timer cleared when the call ends, so none outlives the exec.
+            const deadline = options.timeoutMs === undefined ? undefined : new AbortController();
+            const timer = deadline
+                ? setTimeout(() => deadline.abort(), options.timeoutMs + EXEC_EXIT_GRACE.ms)
+                : undefined;
+            timer?.unref?.();
+            const signal = deadline && options.signal
+                ? AbortSignal.any([options.signal, deadline.signal])
+                : (deadline?.signal ?? options.signal);
             try {
-                for await (const event of this.execStream(command, options)) {
+                for await (const event of this.execStream(command, { ...options, signal })) {
                     if (event.type === "start")
                         processId = event.processId;
                     else if (event.type === "stdout" || event.type === "stderr") {
@@ -162,7 +178,16 @@ export class Sandbox extends Machine {
                 }
             }
             catch (error) {
-                throw await this.#unfinished(error, processId, options.signal);
+                if (!deadline?.signal.aborted || options.signal?.aborted)
+                    throw await this.#unfinished(error, processId, signal);
+                if (processId)
+                    await new Process(this.#t, this.id, { id: processId })
+                        .kill("SIGTERM")
+                        .catch(() => { });
+                exit = { type: "exit", exitCode: null, timedOut: true };
+            }
+            finally {
+                clearTimeout(timer);
             }
             result = {
                 exitCode: exit?.exitCode ?? null,
@@ -171,6 +196,7 @@ export class Sandbox extends Machine {
                 ...truncation(dropped),
                 ...(exit?.durationMs === undefined ? {} : { durationMs: exit.durationMs }),
                 ...(processId ? { processId } : {}),
+                ...(exit?.outOfMemory ? { outOfMemory: exit.outOfMemory } : {}),
             };
         }
         if (options.check && (result.exitCode !== 0 || result.timedOut))
@@ -196,8 +222,8 @@ export class Sandbox extends Machine {
                 code: "cancelled",
                 status: 0,
                 hint: stopped
-                    ? `See what it printed: runtime sandbox logs ${id}`
-                    : `Stop it: runtime sandbox kill ${id}, or sandbox.processes.get("${processId}") and kill().`,
+                    ? `See what it printed: runtime sandboxes logs ${id}`
+                    : `Stop it: runtime sandboxes kill ${id}, or sandbox.processes.get("${processId}") and kill().`,
                 details: { sandboxId: this.id, processId, stopped },
                 cause: error,
             });
@@ -208,7 +234,7 @@ export class Sandbox extends Machine {
             message: `Lost the output of process ${processId}; the command may still be running.`,
             code: "connection_error",
             status: 0,
-            hint: `Follow it: runtime sandbox logs ${id} -f (sandbox.processes.get("${processId}")), or stop it: runtime sandbox kill ${id}.`,
+            hint: `Follow it: runtime sandboxes logs ${id} -f (sandbox.processes.get("${processId}")), or stop it: runtime sandboxes kill ${id}.`,
             details: { sandboxId: this.id, processId },
             cause: error,
         });
@@ -544,7 +570,7 @@ export class Processes {
                         message: `Lost the output stream of process ${processId} for ${FOLLOW_OUTAGE_MS / 60_000} minutes; the command may still be running.`,
                         code: "connection_error",
                         status: 0,
-                        hint: `Follow it again: runtime sandbox logs ${this.sandboxId} ${processId} -f`,
+                        hint: `Follow it again: runtime sandboxes logs ${this.sandboxId} ${processId} -f`,
                         details: { sandboxId: this.sandboxId, processId },
                         cause: failure,
                     });
@@ -555,7 +581,7 @@ export class Processes {
                     message: `The output stream of process ${processId} keeps closing before it ends.`,
                     code: "connection_error",
                     status: 0,
-                    hint: `Read what it printed so far: runtime sandbox logs ${this.sandboxId} ${processId}`,
+                    hint: `Read what it printed so far: runtime sandboxes logs ${this.sandboxId} ${processId}`,
                     details: { sandboxId: this.sandboxId, processId },
                 });
         }
@@ -647,6 +673,7 @@ export class Process {
                 ...this.info,
                 state: exit.state,
                 exitCode: exit.exitCode,
+                ...(exit.outOfMemory ? { outOfMemory: exit.outOfMemory } : {}),
             };
         return {
             exitCode: exit?.exitCode ?? null,
@@ -654,6 +681,7 @@ export class Process {
             timedOut: exit?.timedOut ?? false,
             ...truncation(dropped),
             processId: this.id,
+            ...(exit?.outOfMemory ? { outOfMemory: exit.outOfMemory } : {}),
         };
     }
     /** Sends input. Offsets protect transport retries; signal and timeoutMs cover
@@ -1268,9 +1296,11 @@ export class Files {
             const data = await readFile(localPath);
             const mode = info.mode & 0o777;
             await this.write(remotePath, data, { mode }).catch(async (error) => {
-                // A missing parent is made, as a directory upload makes its own.
+                // Make a missing parent, but keep errors about the sandbox or upload.
                 const parent = remotePath.slice(0, remotePath.lastIndexOf("/"));
-                if (!(error instanceof NotFoundError) || !parent)
+                if (!(error instanceof NotFoundError) ||
+                    (error.code !== "file_not_found" && error.code !== "path_not_found") ||
+                    !parent)
                     throw error;
                 await this.mkdir(parent, { parents: true });
                 await this.write(remotePath, data, { mode });

package/dist/sandboxes/index.d.ts

@@ -0,0 +1,11 @@
+/** `withruntime/sandboxes`: Sandboxes alone. Linux microVMs: create, find and list sandboxes.
+ *
+ *   import { sandboxes } from "withruntime/sandboxes";
+ *   const client = sandboxes(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export { Sandbox } from "../index.js";
+export { Sandboxes } from "../client.js";
+export type * from "../types.js";
+/** `runtime.sandboxes` of a client made with `options`. */
+export declare function sandboxes(options?: RuntimeOptions): Runtime["sandboxes"];

package/dist/sandboxes/index.js

@@ -0,0 +1,12 @@
+/** `withruntime/sandboxes`: Sandboxes alone. Linux microVMs: create, find and list sandboxes.
+ *
+ *   import { sandboxes } from "withruntime/sandboxes";
+ *   const client = sandboxes(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+export { Sandbox } from "../index.js";
+export { Sandboxes } from "../client.js";
+/** `runtime.sandboxes` of a client made with `options`. */
+export function sandboxes(options) {
+    return new Runtime(options).sandboxes;
+}

package/dist/snapshots/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/snapshots`: Snapshots alone. Saved sandboxes, disk and memory, to start or fork from.
+ *
+ *   import { snapshots } from "withruntime/snapshots";
+ *   const client = snapshots(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export { Snapshots, type Snapshot, type SnapshotOptions } from "../snapshots.js";
+/** `runtime.snapshots` of a client made with `options`. */
+export declare function snapshots(options?: RuntimeOptions): Runtime["snapshots"];

package/dist/snapshots/index.js

@@ -0,0 +1,11 @@
+/** `withruntime/snapshots`: Snapshots alone. Saved sandboxes, disk and memory, to start or fork from.
+ *
+ *   import { snapshots } from "withruntime/snapshots";
+ *   const client = snapshots(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+export { Snapshots } from "../snapshots.js";
+/** `runtime.snapshots` of a client made with `options`. */
+export function snapshots(options) {
+    return new Runtime(options).snapshots;
+}

package/dist/snapshots.d.ts

@@ -17,7 +17,8 @@ export type Snapshot = {
         diskMiB: number;
         memoryGuarantee: string;
     };
-    retentionDays: number;
+    /** Null: kept while your account has credit, up to a year from when it was taken. */
+    retentionDays: number | null;
     /** True while raw fork memory awaits verified compression. The snapshot
      * remains ready for starts on its current host, with no storage charge or
      * off-host copy until final publication. Absent on older servers. */
@@ -39,7 +40,8 @@ export type Snapshot = {
     error: string | null;
     createdAt: string;
     readyAt: string | null;
-    expiresAt: string;
+    /** Null while it is kept as long as your account has credit. */
+    expiresAt: string | null;
     [key: string]: unknown;
 };
 export type SnapshotOptions = {
@@ -47,7 +49,8 @@ export type SnapshotOptions = {
     mode?: "memory" | "disk";
     name?: string;
     labels?: Record<string, string>;
-    retentionDays?: number;
+    /** Days, or null to keep it while your account has credit. */
+    retentionDays?: number | null;
 };
 /** `runtime.snapshots`. Take one with `sbx.snapshot()`, start from one with
  * `runtime.sandboxes.create({ snapshot: id })`, or do both with `sbx.fork()`. */
@@ -71,5 +74,5 @@ export declare class Snapshots {
         ifLabels?: Record<string, string>;
     }, options?: RequestOptions): Promise<Snapshot>;
     delete(id: string, options?: RequestOptions): Promise<void>;
-    extend(id: string, retentionDays: number, options?: RequestOptions): Promise<Snapshot>;
+    extend(id: string, retentionDays: number | null, options?: RequestOptions): Promise<Snapshot>;
 }