withruntime 0.14.0 → 0.16.0

package/dist/vercel/command.js

@@ -1,4 +1,4 @@
-import { guard, StreamError, translate } from "./errors.js";
+import { APIError, guard, StreamError, translate } from "./errors.js";
 const SIGNAL_NUMBERS = {
     1: "SIGHUP",
     2: "SIGINT",
@@ -22,6 +22,11 @@ function join(lines, stream) {
         .map((line) => line.data)
         .join("");
 }
+/** One stdin request carries at most this much of a write (Runtime's input
+ * request size); a client error on it means none of it was applied. */
+const STDIN_REQUEST_BYTES = 1_048_576;
+/** Reading a piped stream pauses once this much waits behind a write. */
+const STDIN_BUFFERED_BYTES = 512 * 1024;
 /** A command in a sandbox, as Vercel's `Command`. A detached one runs on:
  * `wait()` for its end, `logs()` for its output as it happens. `cmdId` is
  * Runtime's process id. */
@@ -30,6 +35,13 @@ export class Command {
     durationMs;
     init;
     #finished;
+    /** Pending stdin writes, so concurrent calls reach the process in call order. */
+    #stdinQueue = Promise.resolve();
+    /** Set when a write failed after possibly writing part of it; later writes
+     * are refused so nothing is appended to a partial message. */
+    #stdinError = null;
+    /** Set when the command was started with a `Readable` for stdin. */
+    stdinPipe = null;
     constructor(init) {
         this.init = init;
     }
@@ -93,10 +105,20 @@ export class Command {
             [Symbol.dispose]: () => abort.abort(),
         });
     }
-    /** Waits for the command to end. */
+    /** Waits for the command to end. With a `Readable` piped to its stdin,
+     * rejects if piping fails, and stops piping once the command exits. */
     wait(params = {}) {
         this.#finished ??= this.#follow(params);
-        return this.#finished;
+        const pipe = this.stdinPipe;
+        if (!pipe)
+            return this.#finished;
+        return waitWithStdinPipe(this.#finished, pipe, {
+            ...(params.signal ? { signal: params.signal } : {}),
+            onPipeError: () => {
+                if (this.stdinPipe === pipe)
+                    this.stdinPipe = null;
+            },
+        });
     }
     async #follow(params) {
         const lines = [];
@@ -105,8 +127,11 @@ export class Command {
             for await (const event of this.init.process.output(params.signal ? { signal: params.signal } : {})) {
                 if (event.type === "truncated")
                     throw new StreamError("output_truncated", "Some command output is no longer available.", this.init.process.id);
-                if (event.type === "stdout" || event.type === "stderr")
-                    lines.push({ stream: event.type, data: event.data });
+                if (event.type === "stdout" || event.type === "stderr") {
+                    const line = { stream: event.type, data: event.data };
+                    lines.push(line);
+                    this.init.onLine?.(line);
+                }
                 else if (event.type === "exit")
                     exit = {
                         exitCode: event.exitCode,
@@ -120,7 +145,8 @@ export class Command {
         this.exitCode = exitCodeOf(exit.exitCode, exit.timedOut);
         if (exit.durationMs !== undefined)
             this.durationMs = exit.durationMs;
-        return new CommandFinished({ ...this.init, lines }, this.exitCode, exit.durationMs ?? undefined);
+        const { onLine: _onLine, ...init } = this.init;
+        return new CommandFinished({ ...init, lines }, this.exitCode, exit.durationMs ?? undefined);
     }
     /** stdout, stderr, or both in the order they were written. For a detached
      * command this waits for it to end. */
@@ -145,6 +171,203 @@ export class Command {
             throw new RangeError(`Signal ${signal} has no name Runtime knows; use SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT, SIGUSR1 or SIGUSR2.`);
         await guard(() => this.init.process.kill(name, opts.abortSignal ? { signal: opts.abortSignal } : {}), this.init.sandboxName);
     }
+    /** Writes to the stdin of a command started with `stdin: true` and
+     * `detached: true`. Writes reach the process in call order and resolve once
+     * it has accepted the data; Runtime's input offsets make every resend exact,
+     * so no byte is written twice. If a write fails, part of it may have been
+     * written, and later writes are refused; closeStdin still works. */
+    async writeStdin(data, opts = {}) {
+        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        if (bytes.length === 0)
+            return;
+        await this.#enqueueStdin(async (process) => {
+            if (this.#stdinError)
+                throw new Error("Stdin is in an unknown state after an earlier write failed. Close stdin or kill the command.", { cause: this.#stdinError });
+            opts.abortSignal?.throwIfAborted();
+            try {
+                await guard(() => process.write(bytes, opts.abortSignal ? { signal: opts.abortSignal } : {}), this.init.sandboxName);
+            }
+            catch (error) {
+                const rejectedWhole = error instanceof APIError &&
+                    error.response.status >= 400 &&
+                    error.response.status < 500 &&
+                    bytes.length <= STDIN_REQUEST_BYTES;
+                if (!rejectedWhole)
+                    this.#stdinError = error;
+                throw error;
+            }
+        }, opts.abortSignal);
+    }
+    /** Closes the command's stdin, so it reads EOF once it has consumed what
+     * was written. */
+    async closeStdin(opts = {}) {
+        await this.#enqueueStdin((process) => guard(() => process.write(new Uint8Array(0), {
+            eof: true,
+            ...(opts.abortSignal ? { signal: opts.abortSignal } : {}),
+        }), this.init.sandboxName), opts.abortSignal);
+    }
+    #enqueueStdin(work, signal) {
+        const previous = this.#stdinQueue;
+        const run = (async () => {
+            await waitForTurn(previous, signal);
+            return work(this.init.process);
+        })();
+        this.#stdinQueue = Promise.allSettled([previous, run]).then(() => { });
+        return run;
+    }
+}
+function waitForTurn(previous, signal) {
+    if (!signal)
+        return previous;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        void previous.then(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        });
+    });
+}
+/** The command exited or closed its input: piping ends quietly, as a closed
+ * pipe does in a shell. */
+function inputNoLongerAccepted(error) {
+    return (error instanceof APIError &&
+        (error.response.status === 404 ||
+            (error.response.status === 409 && error.code === "stdin_closed")));
+}
+/** Writes a stream to a command's stdin in order, closing stdin when it
+ * ends. What is read while a write is in flight goes in the next write, and
+ * reading pauses while too much waits. The stream is never ended or
+ * destroyed, and every listener is removed once piping stops. */
+export function pipeStdin(command, stream, signal) {
+    let stopped = false;
+    let writing = false;
+    let ended = false;
+    let waiting = [];
+    let waitingBytes = 0;
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((resolve, reject) => {
+        resolveDone = resolve;
+        rejectDone = reject;
+    });
+    done.catch(() => { });
+    const stop = () => {
+        if (stopped)
+            return false;
+        stopped = true;
+        stream.off("data", onData);
+        stream.off("end", onEnd);
+        stream.off("error", onError);
+        stream.off("close", onClose);
+        signal?.removeEventListener("abort", onAbort);
+        stream.pause();
+        return true;
+    };
+    const settle = (error) => {
+        if (!stop())
+            return;
+        if (error === undefined)
+            resolveDone();
+        else
+            rejectDone(error);
+    };
+    const failed = (error) => settle(inputNoLongerAccepted(error) ? undefined : error);
+    const flush = () => {
+        if (stopped || writing)
+            return;
+        if (waiting.length) {
+            writing = true;
+            const data = concat(waiting);
+            waiting = [];
+            waitingBytes = 0;
+            command.writeStdin(data).then(() => {
+                writing = false;
+                if (stopped)
+                    return;
+                if (!ended)
+                    stream.resume();
+                flush();
+            }, failed);
+        }
+        else if (ended) {
+            writing = true;
+            command.closeStdin().then(() => settle(), failed);
+        }
+    };
+    function onData(chunk) {
+        const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+        waiting.push(bytes);
+        waitingBytes += bytes.length;
+        if (waitingBytes >= STDIN_BUFFERED_BYTES)
+            stream.pause();
+        flush();
+    }
+    function onEnd() {
+        ended = true;
+        flush();
+    }
+    function onError(error) {
+        if (!stop())
+            return;
+        void command
+            .closeStdin()
+            .catch(() => { })
+            .finally(() => rejectDone(error));
+    }
+    function onClose() {
+        if (!stream.readableEnded)
+            onError(new Error("The stdin stream closed before it ended"));
+    }
+    function onAbort() {
+        settle();
+    }
+    if (signal?.aborted)
+        settle();
+    else {
+        signal?.addEventListener("abort", onAbort, { once: true });
+        stream.on("error", onError);
+        stream.on("close", onClose);
+        if (stream.destroyed && !stream.readableEnded)
+            onClose();
+        else {
+            stream.on("end", onEnd);
+            stream.on("data", onData);
+            if (stream.readableEnded)
+                onEnd();
+        }
+    }
+    return { done, stop: () => settle() };
+}
+function concat(chunks) {
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(chunks.reduce((n, chunk) => n + chunk.length, 0));
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.length;
+    }
+    return out;
+}
+/** Waits for a command to finish, rejecting early if piping its stdin fails,
+ * and stops piping once it has exited. Aborting `signal` stops waiting but
+ * leaves the pipe running. */
+export async function waitWithStdinPipe(finished, pipe, opts = {}) {
+    if (!pipe)
+        return finished;
+    finished.then(() => pipe.stop(), () => {
+        if (!opts.signal?.aborted)
+            pipe.stop();
+    });
+    return Promise.race([
+        finished,
+        pipe.done.then(() => finished, (error) => {
+            opts.onPipeError?.();
+            throw error;
+        }),
+    ]);
 }
 /** A command that has ended; `exitCode` is set. */
 export class CommandFinished extends Command {
@@ -157,4 +380,12 @@ export class CommandFinished extends Command {
     wait() {
         return Promise.resolve(this);
     }
+    /** Always throws: the command has already exited. */
+    async writeStdin(_data, _opts) {
+        throw new Error("Cannot write to stdin: the command has already finished.");
+    }
+    /** Always throws: the command has already exited. */
+    async closeStdin(_opts) {
+        throw new Error("Cannot close stdin: the command has already finished.");
+    }
 }

package/dist/vercel/sandbox-user.js

@@ -76,7 +76,8 @@ export class SandboxUser {
         return this.#sandbox.runCommand({
             cmd: wrapped.cmd,
             args: wrapped.args,
-            ...(params.detached ? { detached: true } : {}),
+            ...(params.detached ? { detached: true } : { onStart: params.onStart }),
+            ...(params.stdin ? { stdin: params.stdin } : {}),
             ...(params.stdout ? { stdout: params.stdout } : {}),
             ...(params.stderr ? { stderr: params.stderr } : {}),
             ...(params.signal ? { signal: params.signal } : {}),

package/dist/vercel/sandbox.d.ts

@@ -1,4 +1,4 @@
-import type { Writable } from "node:stream";
+import type { Readable, Writable } from "node:stream";
 import type { Runtime } from "../client.js";
 import { type Credentials, type RuntimeCreate, type RuntimeSandbox, type WithRuntime } from "./client.js";
 import { Command, CommandFinished } from "./command.js";
@@ -82,7 +82,7 @@ export interface CreateSandboxParams extends Credentials {
     /** Runtime-only: an explicit client, or fields for the create. */
     withruntime?: WithRuntime;
 }
-export interface RunCommandParams {
+interface RunCommandParamsBase {
     cmd: string;
     args?: string[];
     cwd?: string;
@@ -90,11 +90,25 @@ export interface RunCommandParams {
     /** Runs the command under `sudo`, which needs no password. */
     sudo?: boolean;
     detached?: boolean;
+    /** `true` keeps stdin open for `writeStdin` and `closeStdin` (needs
+     * `detached: true`). A `Readable` is written to stdin, which closes when it
+     * ends; the stream is never ended or destroyed. If piping fails, an
+     * attached command is killed and `runCommand` rejects; a detached one's
+     * `wait()` rejects. Unset or false: stdin is empty. */
+    stdin?: boolean | Readable;
     stdout?: Writable;
     stderr?: Writable;
     signal?: AbortSignal;
     timeoutMs?: number;
 }
+export type RunCommandParams = RunCommandParamsBase & ({
+    onStart?: never;
+} | {
+    detached?: false;
+    /** Called with the Command as soon as it starts, before it exits;
+     * awaited before `runCommand` resolves. */
+    onStart?: (command: Command) => void | Promise<void>;
+});
 export interface SandboxRoute {
     port: number;
     subdomain: string;

package/dist/vercel/sandbox.js

@@ -1,7 +1,7 @@
 import { extensionSeconds, LeaseKeeper, LEASE_MAX_SECONDS } from "../compat/lease.js";
 import { RuntimeError } from "../errors.js";
 import { clientFor, signalOf, } from "./client.js";
-import { Command, CommandFinished, exitCodeOf } from "./command.js";
+import { Command, CommandFinished, exitCodeOf, pipeStdin, waitWithStdinPipe, } from "./command.js";
 import { APIError, guard, NotSupportedError, StreamError, translate } from "./errors.js";
 import { FileSystem } from "./filesystem.js";
 import { rootOrThrow, SandboxUser, SandboxUserAlreadyExistsError, validateName, } from "./sandbox-user.js";
@@ -479,6 +479,9 @@ export class Sandbox {
         const params = typeof commandOrParams === "string"
             ? { cmd: commandOrParams, ...(args ? { args } : {}), ...opts }
             : commandOrParams;
+        if (params.stdin === true && !params.detached)
+            throw new TypeError("`stdin: true` requires `detached: true`, otherwise the command would wait for input that can never be written");
+        const stdinStream = typeof params.stdin === "object" && params.stdin !== null ? params.stdin : null;
         const argv = [
             ...(params.sudo ? ["sudo", "--preserve-env"] : []),
             params.cmd,
@@ -497,8 +500,9 @@ export class Sandbox {
         };
         const startedAt = Date.now();
         const vercelCwd = params.cwd === undefined ? HOME : toVercelPath(params.cwd);
+        const spawn = () => this.#withResume((runtime) => runtime.spawn(argv, { ...common, ...(params.stdin ? { stdin: "pipe" } : {}) }), params);
         if (params.detached) {
-            const process = await this.#withResume((runtime) => runtime.spawn(argv, common), params);
+            const process = await spawn();
             const command = new Command({
                 id: process.id,
                 cwd: vercelCwd,
@@ -506,10 +510,38 @@ export class Sandbox {
                 sandboxName: this.name,
                 process,
             });
+            if (stdinStream)
+                command.stdinPipe = pipeStdin(command, stdinStream, params.signal);
             if (params.stdout || params.stderr)
                 void pipe(command, params);
             return command;
         }
+        if (stdinStream || params.onStart) {
+            // Started as a process so its Command exists before it exits: for
+            // onStart, and as the target of the piped stdin.
+            const process = await spawn();
+            const command = new Command({
+                id: process.id,
+                cwd: vercelCwd,
+                startedAt,
+                sandboxName: this.name,
+                process,
+                onLine: (line) => (line.stream === "stdout" ? params.stdout : params.stderr)?.write(line.data),
+            });
+            const stdinPipe = stdinStream && pipeStdinOrKill(command, stdinStream, params.signal);
+            const finished = waitWithStdinPipe(command.wait(params.signal ? { signal: params.signal } : {}), stdinPipe);
+            // The command can fail while onStart is pending or after it throws.
+            finished.catch(() => { });
+            try {
+                await params.onStart?.(command);
+                return await finished;
+            }
+            catch (error) {
+                if (params.signal?.aborted)
+                    await command.kill("SIGTERM").catch(() => { });
+                throw error;
+            }
+        }
         const lines = [];
         const record = (stream, writer) => (data) => {
             lines.push({ stream, data });
@@ -855,6 +887,17 @@ export function retentionDays(ms) {
         return 365;
     return Math.min(365, Math.max(1, Math.ceil(ms / 86_400_000)));
 }
+/** Pipes stdin for a command the caller waits on, killing the command if
+ * piping fails, since the caller has no handle to stop it otherwise. */
+function pipeStdinOrKill(command, stream, signal) {
+    const stdinPipe = pipeStdin(command, stream, signal);
+    const done = stdinPipe.done.catch((error) => {
+        command.kill().catch(() => { });
+        throw error;
+    });
+    done.catch(() => { });
+    return { done, stop: () => stdinPipe.stop() };
+}
 async function pipe(command, params) {
     try {
         for await (const line of command.logs())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",
@@ -125,6 +125,11 @@
       "import": "./dist/freestyle/index.js",
       "default": "./dist/freestyle/index.js"
     },
+    "./morph": {
+      "types": "./dist/morph/index.d.ts",
+      "import": "./dist/morph/index.js",
+      "default": "./dist/morph/index.js"
+    },
     "./modal": {
       "types": "./dist/modal/index.d.ts",
       "import": "./dist/modal/index.js",