withruntime 0.5.1 → 0.6.1

package/dist/ai-harness/index.js

@@ -0,0 +1,504 @@
+/** Runtime Cloud sandboxes for the Vercel AI SDK's harnesses (`@ai-sdk/harness`).
+ *
+ * `createRuntimeSandbox()` is a `HarnessV1SandboxProvider`, like
+ * `@ai-sdk/sandbox-vercel`'s `createVercelSandbox()`: a `HarnessAgent` runs its
+ * harness (Claude Code, Codex, OpenCode, Pi, ...) in a Runtime microVM, and
+ * the agent definition does not change:
+ *
+ *   import { HarnessAgent } from "@ai-sdk/harness/agent";
+ *   import { claudeCode } from "@ai-sdk/harness-claude-code";
+ *   import { createRuntimeSandbox } from "withruntime/ai-harness";
+ *
+ *   const agent = new HarnessAgent({
+ *     harness: claudeCode,
+ *     sandbox: createRuntimeSandbox({ ports: [4000], create: { funding: "trial" } }),
+ *   });
+ *
+ * Commands run under `bash -c` as the sandbox user, streamed. Exposed ports
+ * are Runtime previews, private by default: the endpoint carries the preview
+ * token. The key comes from RUNTIME_API_KEY or this machine's `runtime login`.
+ * Needs `@ai-sdk/harness` 1.x beside this package. */
+import { HarnessCapabilityUnsupportedError, HarnessSandboxAuthenticationError, } from "@ai-sdk/harness";
+import { Runtime } from "../client.js";
+import { AuthenticationError, NotFoundError, PermissionDeniedError, RuntimeError, } from "../errors.js";
+export const PROVIDER_ID = "runtime-sandbox";
+/** The preview token's header. The edge also takes it as `runtime_preview_token` in the query. */
+export const PREVIEW_TOKEN_HEADER = "x-runtime-preview-token";
+const TOKEN_QUERY = "runtime_preview_token";
+const SESSION_NAME_PREFIX = "ai-harness-";
+const MAX_COMMAND_MS = 86_400_000;
+const DEFAULT_COMMAND_MS = 3_600_000;
+/** Exit codes for a command that ended without one, as coreutils `timeout` and SIGKILL give. */
+const TIMED_OUT_EXIT = 124;
+const KILLED_EXIT = 137;
+/** A harness sandbox provider backed by Runtime Cloud. Construct it once, at
+ * module scope; nothing is created until a session is. */
+export function createRuntimeSandbox(settings = {}) {
+    return new RuntimeSandboxProvider(settings);
+}
+/** The sandbox name a harness session id maps to: `ai-harness-<id>`, or a
+ * digest of the id when it would not make a valid name. */
+export async function sessionSandboxName(sessionId) {
+    const name = `${SESSION_NAME_PREFIX}${sessionId}`;
+    if (/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(name))
+        return name;
+    const { createHash } = await import("node:crypto");
+    return `${SESSION_NAME_PREFIX}${createHash("sha256").update(sessionId).digest("hex").slice(0, 40)}`;
+}
+export class RuntimeSandboxProvider {
+    settings;
+    specificationVersion = "harness-sandbox-v1";
+    providerId = PROVIDER_ID;
+    #runtime;
+    constructor(settings = {}) {
+        this.settings = settings;
+        this.#runtime = settings.runtime;
+    }
+    get runtime() {
+        this.#runtime ??= new Runtime();
+        return this.#runtime;
+    }
+    /** A new sandbox (named after `sessionId` when given), or the wrapped one.
+     * `onFirstCreate` runs on a new sandbox before this returns; Runtime keeps
+     * no template for `identity`, so it runs for every new sandbox. */
+    createSession = async (options = {}) => {
+        options.abortSignal?.throwIfAborted();
+        if (this.settings.sandbox)
+            return this.#session(this.settings.sandbox, false, options.abortSignal);
+        const name = options.sessionId ? await sessionSandboxName(options.sessionId) : undefined;
+        const sandbox = await authenticated(() => this.runtime.sandboxes.create({ ...this.settings.create, ...(name ? { name } : {}) }, options.abortSignal ? { signal: options.abortSignal } : {}));
+        try {
+            const session = await this.#session(sandbox, true, options.abortSignal);
+            await options.onFirstCreate?.(session.restricted(), {
+                ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+            });
+            return session;
+        }
+        catch (error) {
+            // A sandbox nobody holds would run until its lease ends.
+            await sandbox.stop({ wait: false }).catch(() => undefined);
+            throw error;
+        }
+    };
+    /** The sandbox `createSession` made for `sessionId`, woken if it is paused.
+     * A stopped one cannot be resumed: its memory and disk are gone. */
+    resumeSession = async (options) => {
+        options.abortSignal?.throwIfAborted();
+        if (this.settings.sandbox)
+            return this.#session(this.settings.sandbox, false, options.abortSignal);
+        const name = await sessionSandboxName(options.sessionId);
+        const found = await authenticated(async () => {
+            const page = await this.runtime.sandboxes.list({ name, limit: 1 });
+            return page.data[0];
+        });
+        if (!found)
+            throw new NotFoundError({
+                message: `No live Runtime sandbox is named ${name}, so harness session ${options.sessionId} cannot be resumed.`,
+                code: "not_found",
+                status: 404,
+                hint: "A stopped sandbox cannot be resumed. Set pauseOnStop: true so session.stop() pauses it instead.",
+            });
+        const request = options.abortSignal ? { signal: options.abortSignal } : {};
+        if (found.state === "paused" || found.state === "pausing")
+            await found.wake(request);
+        else if (found.state !== "running")
+            await found.waitFor("running", request);
+        return this.#session(found, true, options.abortSignal);
+    };
+    async #session(sandbox, ownsLifecycle, abortSignal) {
+        const session = new RuntimeNetworkSandboxSession(sandbox, this.settings, ownsLifecycle);
+        // The harness composes each session's directory under the sandbox's own
+        // working directory, read from the sandbox rather than assumed.
+        const pwd = await session.run({ command: "pwd", ...(abortSignal ? { abortSignal } : {}) });
+        const cwd = pwd.stdout.trim();
+        if (pwd.exitCode === 0 && cwd.startsWith("/"))
+            session.defaultWorkingDirectory = cwd;
+        if (this.settings.ports?.length)
+            await session.setPorts(this.settings.ports, abortSignal ? { abortSignal } : {});
+        return session;
+    }
+}
+/** Files and processes in one Runtime sandbox: what `restricted()` hands to
+ * tools, with nothing that stops the sandbox or changes its network. */
+export class RuntimeSandboxSession {
+    sandbox;
+    settings;
+    /** Where relative paths and commands without a `workingDirectory` start. */
+    defaultWorkingDirectory = "/workspace";
+    constructor(sandbox, settings = {}) {
+        this.sandbox = sandbox;
+        this.settings = settings;
+    }
+    get description() {
+        return [
+            `Runtime Cloud sandbox ${this.sandbox.id}: a Firecracker microVM with its own Linux kernel.`,
+            `Commands run under bash as the user "runtime", with passwordless sudo. HOME and the default working directory are ${this.defaultWorkingDirectory}.`,
+            "Files persist for the life of the sandbox.",
+        ].join("\n");
+    }
+    #path(path) {
+        return resolvePosix(this.defaultWorkingDirectory, path);
+    }
+    #commandOptions(options) {
+        const env = { ...this.settings.env, ...options.env };
+        return {
+            // Without one, the sandbox's own working directory, which is what
+            // defaultWorkingDirectory was read from.
+            ...(options.workingDirectory === undefined
+                ? {}
+                : { cwd: this.#path(options.workingDirectory) }),
+            ...(Object.keys(env).length ? { env } : {}),
+            timeoutMs: Math.min(MAX_COMMAND_MS, options.timeoutMs ?? this.settings.commandTimeoutMs ?? DEFAULT_COMMAND_MS),
+        };
+    }
+    /** Runs `command` under `bash -c` and returns once it exits, with all of
+     * its output. A timeout exits 124, with a note on standard error. */
+    run = async (options) => {
+        const { abortSignal } = options;
+        abortSignal?.throwIfAborted();
+        const out = { stdout: "", stderr: "" };
+        let exit;
+        let processId;
+        try {
+            // Streamed, so no output is cut at the size a single answer holds.
+            for await (const event of this.sandbox.execStream(options.command, {
+                ...this.#commandOptions(options),
+                ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+                ...(abortSignal ? { signal: abortSignal } : {}),
+            })) {
+                if (event.type === "start")
+                    processId = event.processId;
+                else if (event.type === "stdout" || event.type === "stderr")
+                    out[event.type] += event.data;
+                else if (event.type === "exit")
+                    exit = event;
+            }
+        }
+        catch (error) {
+            if (abortSignal?.aborted) {
+                // Aborting the request does not end the command; end it too.
+                if (processId)
+                    await this.#kill(processId);
+                throw abortSignal.reason ?? error;
+            }
+            throw error;
+        }
+        if (abortSignal?.aborted)
+            throw abortSignal.reason;
+        const timedOut = exit?.timedOut ?? false;
+        return {
+            exitCode: exit?.exitCode ?? (timedOut ? TIMED_OUT_EXIT : KILLED_EXIT),
+            stdout: out.stdout,
+            stderr: timedOut
+                ? `${out.stderr}${out.stderr && !out.stderr.endsWith("\n") ? "\n" : ""}Timed out: the command ran past its limit and was ended.\n`
+                : out.stderr,
+        };
+    };
+    /** Starts `command` and returns at once, with its output as streams. */
+    spawn = async (options) => {
+        const { abortSignal } = options;
+        abortSignal?.throwIfAborted();
+        if (options.stdin instanceof Uint8Array)
+            throw new RuntimeError({
+                message: "spawn takes standard input as text; use run for bytes.",
+                code: "invalid_request",
+                status: 0,
+            });
+        const { timeoutMs, ...command } = this.#commandOptions(options);
+        const process = await this.sandbox.spawn(options.command, {
+            ...command,
+            // A spawned process is often a server: it runs until killed unless a limit is asked for.
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs }),
+            ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+            ...(abortSignal ? { signal: abortSignal } : {}),
+        });
+        return this.#process(process, abortSignal);
+    };
+    #process(process, abortSignal) {
+        const encoder = new TextEncoder();
+        const streams = {};
+        const stdout = new ReadableStream({ start: (c) => void (streams.stdout = c) });
+        const stderr = new ReadableStream({ start: (c) => void (streams.stderr = c) });
+        const stopReading = new AbortController();
+        const onAbort = () => {
+            stopReading.abort();
+            void this.#kill(process.id);
+        };
+        abortSignal?.addEventListener("abort", onAbort, { once: true });
+        const drained = (async () => {
+            let exit;
+            try {
+                for await (const event of process.output({ signal: stopReading.signal })) {
+                    if (event.type === "stdout" || event.type === "stderr")
+                        streams[event.type].enqueue(encoder.encode(event.data));
+                    else if (event.type === "exit")
+                        exit = event;
+                }
+                streams.stdout.close();
+                streams.stderr.close();
+            }
+            catch (error) {
+                streams.stdout.error(error);
+                streams.stderr.error(error);
+                throw error;
+            }
+            finally {
+                abortSignal?.removeEventListener("abort", onAbort);
+            }
+            return exit;
+        })();
+        // Read or not, a failure is reported by wait(), never as an unhandled rejection.
+        drained.catch(() => undefined);
+        let killed = false;
+        return {
+            stdout,
+            stderr,
+            wait: async () => {
+                let exit;
+                try {
+                    exit = await drained;
+                }
+                catch (error) {
+                    if (abortSignal?.aborted)
+                        throw abortSignal.reason ?? error;
+                    throw error;
+                }
+                if (abortSignal?.aborted)
+                    throw abortSignal.reason;
+                return {
+                    exitCode: exit?.exitCode ?? (exit?.timedOut ? TIMED_OUT_EXIT : KILLED_EXIT),
+                };
+            },
+            kill: async () => {
+                if (killed)
+                    return;
+                killed = true;
+                await this.#kill(process.id);
+            },
+        };
+    }
+    /** Ends a process; one that has already exited is not an error. */
+    async #kill(processId) {
+        try {
+            const process = await this.sandbox.processes.get(processId);
+            if (process.info.state === "running")
+                await process.kill("SIGKILL");
+        }
+        catch {
+            // Gone already, or the sandbox is: nothing is left to end.
+        }
+    }
+    readBinaryFile = async (options) => {
+        options.abortSignal?.throwIfAborted();
+        try {
+            return await this.sandbox.files.read(this.#path(options.path), options.abortSignal ? { signal: options.abortSignal } : {});
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                return null;
+            throw error;
+        }
+    };
+    readFile = async (options) => {
+        const bytes = await this.readBinaryFile(options);
+        if (!bytes)
+            return null;
+        return new ReadableStream({
+            start(controller) {
+                controller.enqueue(bytes);
+                controller.close();
+            },
+        });
+    };
+    readTextFile = async (options) => {
+        const bytes = await this.readBinaryFile(options);
+        if (!bytes)
+            return null;
+        const text = new TextDecoder(options.encoding ?? "utf-8").decode(bytes);
+        return lines(text, options.startLine, options.endLine);
+    };
+    /** Writes atomically, making parent directories. Past 1 MiB a file must be under /workspace. */
+    writeBinaryFile = async (options) => {
+        options.abortSignal?.throwIfAborted();
+        await this.sandbox.files.write(this.#path(options.path), options.content, options.abortSignal ? { signal: options.abortSignal } : {});
+    };
+    writeFile = async (options) => {
+        const content = new Uint8Array(await new Response(options.content).arrayBuffer());
+        await this.writeBinaryFile({ ...options, content });
+    };
+    writeTextFile = async (options) => {
+        const encoding = (options.encoding ?? "utf-8");
+        await this.writeBinaryFile({
+            ...options,
+            content: new Uint8Array(Buffer.from(options.content, encoding)),
+        });
+    };
+}
+/** The session a harness keeps: files and processes, plus ports as previews,
+ * network rules, and stopping. */
+export class RuntimeNetworkSandboxSession extends RuntimeSandboxSession {
+    settings;
+    ownsLifecycle;
+    #ports = [];
+    constructor(sandbox, settings, ownsLifecycle) {
+        super(sandbox, settings);
+        this.settings = settings;
+        this.ownsLifecycle = ownsLifecycle;
+    }
+    /** The sandbox's id: `resumeSession` finds it again by the name it was given. */
+    get id() {
+        return this.sandbox.id;
+    }
+    get ports() {
+        return this.#ports;
+    }
+    get description() {
+        const ports = this.#ports.length
+            ? `\nPorts ${this.#ports.join(", ")} are shared at HTTPS preview addresses; listen on 0.0.0.0 or localhost.`
+            : "";
+        return `${super.description}${ports}`;
+    }
+    restricted = () => {
+        const session = new RuntimeSandboxSession(this.sandbox, this.settings);
+        session.defaultWorkingDirectory = this.defaultWorkingDirectory;
+        return session;
+    };
+    /** Where to reach `port`. A private preview's token is in the URL's query and
+     * in `headers`. For `ws` the URL has no token: the preview edge answers a GET
+     * whose query carries one with a redirect that sets a cookie, which a
+     * WebSocket client does not follow, so the header carries it. */
+    getPortEndpoint = async (options) => {
+        if (!this.#ports.includes(options.port))
+            throw new HarnessCapabilityUnsupportedError({
+                harnessId: PROVIDER_ID,
+                message: `Port ${options.port} is not exposed on this sandbox. Exposed ports: [${this.#ports.join(", ")}]. Pass it in createRuntimeSandbox({ ports }).`,
+            });
+        const preview = await this.#share(options.port);
+        const protocol = options.protocol ?? "https";
+        const url = new URL(preview.url);
+        url.protocol = protocol === "ws" ? "wss:" : "https:";
+        if (!preview.token)
+            return { url: url.toString() };
+        if (protocol !== "ws")
+            url.searchParams.set(TOKEN_QUERY, preview.token);
+        return { url: url.toString(), headers: { [PREVIEW_TOKEN_HEADER]: preview.token } };
+    };
+    /** @deprecated As the AI SDK's: use `getPortEndpoint`. The URL carries the token in its query. */
+    getPortUrl = async (options) => {
+        const endpoint = await this.getPortEndpoint({ ...options, protocol: "https" });
+        const url = new URL(endpoint.url);
+        if (options.protocol === "ws")
+            url.protocol = "wss:";
+        return url.toString();
+    };
+    /** Shares exactly `ports`: new ones become previews, dropped ones stop being shared. */
+    setPorts = async (ports, options = {}) => {
+        const wanted = [...new Set(ports)];
+        const request = options.abortSignal ? { signal: options.abortSignal } : {};
+        for (const port of this.#ports.filter((port) => !wanted.includes(port)))
+            await this.sandbox.previews.delete(port, request).catch((error) => {
+                if (!(error instanceof NotFoundError))
+                    throw error;
+            });
+        for (const port of wanted.filter((port) => !this.#ports.includes(port)))
+            await this.#share(port, request);
+        this.#ports = wanted;
+    };
+    /** Creates the preview, or answers the existing one with a fresh token. */
+    #share(port, request = {}) {
+        return this.sandbox.previews.create(port, {
+            visibility: this.settings.previewVisibility ?? "private",
+            ...(this.settings.previewTtlSeconds ? { ttlSeconds: this.settings.previewTtlSeconds } : {}),
+        }, request);
+    }
+    /** Outbound rules: `allow-all` is the public web, `deny-all` nothing, and
+     * `custom` only the listed hosts and ranges, with `deniedCIDRs` refused. */
+    setNetworkPolicy = async (policy) => {
+        await this.sandbox.network.set(networkRules(policy));
+    };
+    /** Stops the sandbox (or pauses it, with `pauseOnStop`). A wrapped sandbox is left alone. */
+    stop = async () => {
+        if (!this.ownsLifecycle)
+            return;
+        if (this.settings.pauseOnStop) {
+            try {
+                await this.sandbox.pause();
+                return;
+            }
+            catch {
+                // Stop it rather than leave it running.
+            }
+        }
+        await this.#stop();
+    };
+    /** Stops the sandbox, whatever `pauseOnStop` says: its files and memory are gone. */
+    destroy = async () => {
+        if (!this.ownsLifecycle)
+            return;
+        await this.#stop();
+    };
+    async #stop() {
+        try {
+            await this.sandbox.stop();
+        }
+        catch (error) {
+            if (!(error instanceof NotFoundError))
+                throw error;
+        }
+    }
+}
+/** The harness's network policy as a Runtime sandbox's network rules. */
+export function networkRules(policy) {
+    if (policy.mode === "allow-all")
+        return { internet: true };
+    if (policy.mode === "deny-all")
+        return { internet: false };
+    const allow = [...(policy.allowedHosts ?? []), ...(policy.allowedCIDRs ?? [])];
+    const deny = [...(policy.deniedCIDRs ?? [])];
+    return { internet: true, allow, ...(deny.length ? { deny } : {}) };
+}
+/** A missing or refused key as the harness's own error, so a framework can
+ * tell configuration from an outage. */
+async function authenticated(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof AuthenticationError ||
+            error instanceof PermissionDeniedError ||
+            (error instanceof RuntimeError && error.code === "missing_api_key"))
+            throw new HarnessSandboxAuthenticationError({
+                message: `Runtime authentication failed: ${error.message} Set RUNTIME_API_KEY, run \`npx -y withruntime login\`, or pass createRuntimeSandbox({ runtime: new Runtime({ apiKey }) }).`,
+                sandboxProviderId: PROVIDER_ID,
+                cause: error,
+            });
+        throw error;
+    }
+}
+/** Lines `start` to `end` (1-based, inclusive) of `text`; past the end is the
+ * end. The file's own line ending is kept, as the AI SDK's `extractLines`. */
+function lines(text, start, end) {
+    if (start === undefined && end === undefined)
+        return text;
+    const eol = text.includes("\r\n")
+        ? "\r\n"
+        : !text.includes("\n") && text.includes("\r")
+            ? "\r"
+            : "\n";
+    const all = text.split(eol);
+    const from = Math.max(1, start ?? 1) - 1;
+    const to = Math.min(all.length, end ?? all.length);
+    return all.slice(from, to).join(eol);
+}
+function resolvePosix(base, path) {
+    const parts = [];
+    for (const part of `${path.startsWith("/") ? "" : `${base}/`}${path}`.split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..")
+            parts.pop();
+        else
+            parts.push(part);
+    }
+    return `/${parts.join("/")}`;
+}

package/dist/cli-extras.d.ts

@@ -0,0 +1,24 @@
+import type { CliKit } from "./cli.js";
+import type { Sandbox } from "./sandbox.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+export declare function recordCommand(sbx: Sandbox, argv: string[], out: Out, kit: CliKit): Promise<number>;
+export declare function watchCommand(sbx: Sandbox, argv: string[], out: Out, kit: CliKit): Promise<number>;
+export declare function mcpCommand(sbx: Sandbox, argv: string[], out: Out, kit: CliKit): Promise<number>;
+/** Standard input when it is piped or redirected from a file, read whole, up
+ * to the API's 1 MiB; undefined for a terminal. A pipe that says nothing for
+ * `quietMs` is taken as no input, so a script that leaves standard input open
+ * and silent never hangs a command. */
+export declare function pipedStdin(options?: {
+    limit?: number;
+    quietMs?: number;
+}): Promise<Uint8Array | undefined>;
+/** What to say when a command's streamed output lost bytes, or nothing. */
+export declare function lostOutput(result: {
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+}, id: string): string | undefined;
+export {};