withruntime 0.4.0 → 0.5.0

package/dist/sandbox.js

@@ -1,6 +1,7 @@
 import { CommandError, RuntimeError } from "./errors.js";
 import { Page } from "./page.js";
 import { sandboxFactories } from "./products/index.js";
+import { Tunnel } from "./tunnel.js";
 const CHUNK = 1_048_576;
 const PARALLEL = 4;
 const enc = (id) => encodeURIComponent(id);
@@ -21,6 +22,7 @@ function commandBody(command, options) {
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Sandbox {
     #info;
+    #keepAlive;
     #t;
     files;
     processes;
@@ -79,6 +81,7 @@ export class Sandbox {
             const out = { stdout: "", stderr: "" };
             let exit;
             let processId;
+            let dropped = false;
             for await (const event of this.execStream(command, options)) {
                 if (event.type === "start")
                     processId = event.processId;
@@ -86,6 +89,8 @@ export class Sandbox {
                     out[event.type] += event.data;
                     (event.type === "stdout" ? options.onStdout : options.onStderr)?.(event.data);
                 }
+                else if (event.type === "truncated")
+                    dropped = true;
                 else if (event.type === "exit")
                     exit = event;
             }
@@ -93,6 +98,7 @@ export class Sandbox {
                 exitCode: exit?.exitCode ?? null,
                 ...out,
                 timedOut: exit?.timedOut ?? false,
+                ...truncation(dropped),
                 ...(exit?.durationMs === undefined ? {} : { durationMs: exit.durationMs }),
                 ...(processId ? { processId } : {}),
             };
@@ -163,7 +169,35 @@ export class Sandbox {
         });
         return Terminal.open(socket, options.onData);
     }
+    /** A tunnel into the sandbox: TCP connections to any port on its loopback,
+     * and SSH logins, over one authenticated WebSocket. No port is opened to the
+     * internet. `tunnel.connect(5432)` gives one connection;
+     * `tunnel.forward(5432)` listens locally (Node and Bun). */
+    async tunnel() {
+        return Tunnel.open(await this.#t.websocket(`/v1/sandboxes/${enc(this.id)}/tunnel`));
+    }
+    /** Listens on a local port (the same number unless `localPort` says, 0 for
+     * any) and forwards each connection to `port` inside the sandbox, until
+     * `close()`. Node and Bun. */
+    async forwardPort(port, options = {}) {
+        const tunnel = await this.tunnel();
+        try {
+            const forward = await tunnel.forward(port, options);
+            return {
+                ...forward,
+                close: async () => {
+                    await forward.close();
+                    tunnel.close();
+                },
+            };
+        }
+        catch (error) {
+            tunnel.close();
+            throw error;
+        }
+    }
     async stop(options = {}) {
+        this.#keepAlive?.();
         return this.#lifecycle("stop", options);
     }
     async pause(options = {}) {
@@ -178,6 +212,58 @@ export class Sandbox {
     async extend(seconds, options = {}) {
         return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
     }
+    /** 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). */
+    async update(settings, options = {}) {
+        return this.#lifecycle("update", { ...options, wait: false }, { ...settings });
+    }
+    /** Keeps a running sandbox's lease ahead of now, in the background, until
+     * stop() or the returned function ends it: every `everySeconds` (60) it
+     * extends the lease so that `marginSeconds` (600) remain, never more than
+     * the hour ahead the API allows. Running time is billed as it is used, as
+     * for any extension. 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 = {}) {
+        this.#keepAlive?.();
+        const every = Math.max(10, options.everySeconds ?? 60) * 1000;
+        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? 600));
+        let ended = false;
+        let timer;
+        const end = () => {
+            ended = true;
+            if (timer)
+                clearTimeout(timer);
+            if (this.#keepAlive === end)
+                this.#keepAlive = undefined;
+        };
+        const tick = async () => {
+            if (ended)
+                return;
+            try {
+                await this.refresh();
+                if (this.state === "stopped" || this.state === "stopping")
+                    return end();
+                if (this.state === "running") {
+                    const left = (Date.parse(this.info.expiresAt) - Date.now()) / 1000;
+                    const need = Math.ceil(margin - left);
+                    if (need >= 1)
+                        await this.extend(Math.min(3600, need));
+                }
+            }
+            catch (error) {
+                options.onError?.(error);
+            }
+            if (ended)
+                return;
+            timer = setTimeout(() => void tick(), every);
+            timer.unref?.();
+        };
+        this.#keepAlive = end;
+        void tick();
+        return end;
+    }
     /** Days a paused sandbox is kept before deletion (1 to 365). */
     async setRetention(days, options = {}) {
         return this.#lifecycle("retention", { ...options, wait: false }, { days });
@@ -240,6 +326,7 @@ export class Sandbox {
         return this;
     }
     async [Symbol.asyncDispose]() {
+        this.#keepAlive?.();
         if (this.#info.state === "stopped")
             return;
         await this.stop({ wait: false }).catch(() => undefined);
@@ -248,6 +335,13 @@ export class Sandbox {
         return this.#info;
     }
 }
+/** A streamed command keeps all its output unless the reader fell more than the
+ * process's output buffer behind, which the server marks with a "truncated"
+ * event. That event does not say which stream lost bytes, so both flags carry
+ * it; without one, both are false, as a synchronous result's are. */
+function truncation(dropped) {
+    return { stdoutTruncated: dropped, stderrTruncated: dropped };
+}
 function pick(options) {
     return {
         ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
@@ -332,9 +426,12 @@ export class Process {
     async wait(options = {}) {
         const out = { stdout: "", stderr: "" };
         let exit;
+        let dropped = false;
         for await (const event of this.output(options)) {
             if (event.type === "stdout" || event.type === "stderr")
                 out[event.type] += event.data;
+            if (event.type === "truncated")
+                dropped = true;
             if (event.type === "exit")
                 exit = event;
         }
@@ -342,6 +439,7 @@ export class Process {
             exitCode: exit?.exitCode ?? null,
             ...out,
             timedOut: exit?.timedOut ?? false,
+            ...truncation(dropped),
             processId: this.id,
         };
     }
@@ -576,7 +674,9 @@ export class Files {
         }
         const { packDirectory } = await import("./tar.js");
         const archive = await packDirectory(localPath);
-        const staging = `/tmp/.runtime-upload-${crypto.randomUUID()}.tar.gz`;
+        // Large writes go only to /workspace (the server refuses others), so the
+        // archive is staged there and removed after unpacking.
+        const staging = `/workspace/.runtime-upload-${crypto.randomUUID()}.tar.gz`;
         await this.write(staging, archive);
         const result = await new Sandbox(this.t, { id: this.sandboxId }).exec([
             "sh",

package/dist/ssh.d.ts

@@ -0,0 +1,21 @@
+import type { Runtime } from "./client.js";
+import type { Sandbox } from "./sandbox.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+export declare const SSH_HELP: (me: string) => string;
+/** This machine's key for Runtime SSH logins, made on first use. Only its
+ * public half ever leaves the machine, and only into the one login it opens. */
+export declare function sshKey(env: NodeJS.ProcessEnv): Promise<{
+    path: string;
+    publicKey: string;
+}>;
+/** A sandbox by id or by its name, as `ssh` hands it over (`<id>.runtime`). */
+export declare function resolveSandbox(runtime: Runtime, target: string): Promise<Sandbox>;
+export declare function sshConfig(env: NodeJS.ProcessEnv): Promise<string>;
+export declare function sshCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
+/** `runtime sandbox port-forward <id> 5432 8080:3000 ...` */
+export declare function portForwardCommand(argv: string[], out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
+export {};

package/dist/ssh.js

@@ -0,0 +1,312 @@
+import { spawn, spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { RuntimeError } from "./errors.js";
+import { VERSION } from "./transport.js";
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+export const SSH_HELP = (me) => `${me} sandbox ssh <id|name> [-- <command...>]   Log in over SSH (an interactive shell, or run the command)
+${me} sandbox ssh config [--install]          The ssh config for \`ssh <id|name>.runtime\`, also from
+                                      VS Code Remote-SSH and JetBrains Gateway; --install adds
+                                      it to ~/.ssh/config
+${me} sandbox ssh proxy <id|name>[.runtime]   ProxyCommand mode: SSH on stdin and stdout
+${me} sandbox port-forward <id|name> <port|local:remote>... [--address 127.0.0.1]
+                                      Forward local ports to ports in the sandbox, until Ctrl-C
+
+SSH and port forwarding go through Runtime's API with your key: the sandbox opens
+no port to the internet. The login is the sandbox's user, runtime, with sudo.
+A paused sandbox wakes when you connect, like any command.
+`;
+function configDirectory(env) {
+    const root = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    if (!isAbsolute(root))
+        throw new Error("XDG_CONFIG_HOME must be an absolute path.");
+    return join(root, "runtime-cloud");
+}
+/** This machine's key for Runtime SSH logins, made on first use. Only its
+ * public half ever leaves the machine, and only into the one login it opens. */
+export async function sshKey(env) {
+    const dir = join(configDirectory(env), "ssh");
+    const path = join(dir, "id_ed25519");
+    try {
+        return { path, publicKey: (await readFile(`${path}.pub`, "utf8")).trim() };
+    }
+    catch {
+        // Made below.
+    }
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+    const made = spawnSync("ssh-keygen", ["-q", "-t", "ed25519", "-N", "", "-C", "runtime-cloud", "-f", path], {
+        stdio: ["ignore", "ignore", "pipe"],
+    });
+    if (made.error || made.status !== 0)
+        throw new RuntimeError({
+            message: `Could not make an SSH key with ssh-keygen${made.error ? `: ${made.error.message}` : `: ${made.stderr.toString().trim()}`}.`,
+            code: "ssh_keygen_failed",
+            status: 0,
+            hint: "Install OpenSSH (it has ssh and ssh-keygen), or pass --key with a public key file.",
+        });
+    return { path, publicKey: (await readFile(`${path}.pub`, "utf8")).trim() };
+}
+/** A sandbox by id or by its name, as `ssh` hands it over (`<id>.runtime`). */
+export async function resolveSandbox(runtime, target) {
+    const name = target.replace(/\.runtime$/, "");
+    if (UUID.test(name))
+        return runtime.sandboxes.get(name);
+    const page = await runtime.sandboxes.list({ name, limit: 2 });
+    if (page.data.length === 1)
+        return page.data[0];
+    throw new RuntimeError({
+        message: page.data.length
+            ? `More than one live sandbox is named ${name}.`
+            : `No live sandbox is named ${name}.`,
+        code: page.data.length ? "ambiguous_name" : "sandbox_not_found",
+        status: 0,
+        hint: "Use its id: runtime sandbox ls",
+    });
+}
+const quote = (text) => /^[A-Za-z0-9_./:@=-]+$/.test(text) ? text : `'${text.replace(/'/g, "'\\''")}'`;
+/** How ssh should start this CLI again: the same program and script, or npx
+ * at this version when it ran from npx's temporary cache. */
+function selfCommand(env) {
+    const script = process.argv[1];
+    const program = script && !/[\\/]_npx[\\/]/.test(script)
+        ? [process.execPath, realpathSync(script)]
+        : ["npx", "--yes", `withruntime@${VERSION}`];
+    const origin = env.RUNTIME_API_URL ? [`RUNTIME_API_URL=${env.RUNTIME_API_URL}`] : [];
+    return [...(origin.length ? ["env", ...origin] : []), ...program].map(quote).join(" ");
+}
+export async function sshConfig(env) {
+    const { path } = await sshKey(env);
+    return `# Runtime Cloud: \`ssh <sandbox id or name>.runtime\`, and the same host in
+# VS Code Remote-SSH or JetBrains Gateway. The connection is Runtime's
+# authenticated tunnel, which already proves which sandbox answers; each login
+# gets a fresh host key, so there is nothing to pin in known_hosts.
+Host *.runtime
+  User runtime
+  ProxyCommand ${selfCommand(env)} sandbox ssh proxy %h
+  IdentityFile "${path}"
+  IdentitiesOnly yes
+  StrictHostKeyChecking no
+  UserKnownHostsFile /dev/null
+  LogLevel ERROR
+  ServerAliveInterval 30
+`;
+}
+/** Writes the block to its own file and includes it from ~/.ssh/config once. */
+async function installConfig(env) {
+    const file = join(configDirectory(env), "ssh", "config");
+    await writeFile(file, await sshConfig(env), { mode: 0o600 });
+    const sshDir = join(homedir(), ".ssh");
+    await mkdir(sshDir, { recursive: true, mode: 0o700 });
+    const main = join(sshDir, "config");
+    const current = await readFile(main, "utf8").catch(() => "");
+    const include = `Include "${file}"`;
+    if (!current.split("\n").some((line) => line.trim() === include))
+        // First, because ssh reads an Include inside a Host block as part of it.
+        await writeFile(main, `${include}\n${current ? `\n${current}` : ""}`, { mode: 0o600 });
+    return file;
+}
+/** ProxyCommand mode: ssh speaks on this process's stdin and stdout. */
+async function proxy(runtime, target, publicKey) {
+    const sbx = await resolveSandbox(runtime, target);
+    const tunnel = await sbx.tunnel();
+    const stream = await tunnel.ssh(publicKey).catch((error) => {
+        tunnel.close();
+        throw error;
+    });
+    return new Promise(() => {
+        // When the sandbox side ends, the session is over: flush what ssh has not
+        // read yet, then exit, which is what closes the pipe ssh is reading (an
+        // ended process.stdout does not close it on every runtime).
+        let leaving = false;
+        const leave = (code) => {
+            if (leaving)
+                return;
+            leaving = true;
+            tunnel.close();
+            process.stdout.write("", () => process.exit(code));
+        };
+        stream.onData = (data) => void process.stdout.write(data);
+        stream.onEnd = () => leave(0);
+        stream.onLog = (text) => process.stderr.write(`sandbox sshd: ${text}`);
+        stream.onClose = (reason) => {
+            if (reason !== "done")
+                process.stderr.write(`Runtime: the SSH connection ended (${reason}).\n`);
+            leave(reason === "done" ? 0 : 1);
+        };
+        // Async iteration reads the next chunk only after this one is inside the
+        // window: backpressure that behaves the same on Node and Bun.
+        void (async () => {
+            for await (const data of process.stdin)
+                await stream.write(new Uint8Array(data));
+            stream.end();
+        })().catch(() => stream.close());
+    });
+}
+/** Installs the OpenSSH server in a sandbox that lacks it (an image made
+ * before it was in the base image, or a custom one), saying so first. */
+async function ensureSshd(sbx, out) {
+    const probe = await sbx.exec(["sh", "-c", "command -v sshd || test -x /usr/sbin/sshd"], {
+        timeoutMs: 30_000,
+    });
+    if (probe.exitCode === 0)
+        return;
+    out.error("This sandbox has no OpenSSH server yet; installing it once...");
+    const installed = await sbx.exec([
+        "sh",
+        "-c",
+        "sudo -n apt-get update -qq && sudo -n env DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends openssh-server",
+    ], { timeoutMs: 300_000 });
+    if (installed.exitCode !== 0)
+        throw new RuntimeError({
+            message: `Installing openssh-server in the sandbox failed: ${(installed.stderr || installed.stdout).trim().slice(-400)}`,
+            code: "sshd_missing",
+            status: 0,
+            hint: "Install an SSH server in the sandbox yourself, or build an image that has one.",
+        });
+}
+export async function sshCommand(argv, env, out, connect, me) {
+    const dash = argv.indexOf("--");
+    const words = dash === -1 ? argv : argv.slice(0, dash);
+    const remote = dash === -1 ? [] : argv.slice(dash + 1);
+    const keyAt = words.indexOf("--key");
+    const keyFile = keyAt === -1 ? undefined : words[keyAt + 1];
+    const positional = words.filter((word, i) => !word.startsWith("--") && (keyAt === -1 || i !== keyAt + 1));
+    const [first, second] = positional;
+    if (!first || first === "help") {
+        out.write(SSH_HELP(me));
+        return first ? 0 : 64;
+    }
+    const publicKey = async () => keyFile ? (await readFile(keyFile, "utf8")).trim() : (await sshKey(env)).publicKey;
+    if (first === "config") {
+        if (words.includes("--install")) {
+            const file = await installConfig(env);
+            out.write(out.json
+                ? JSON.stringify({ installed: file })
+                : `Added Include "${file}" to ~/.ssh/config. Connect with: ssh <sandbox id or name>.runtime`);
+        }
+        else
+            out.write(out.json ? JSON.stringify({ config: await sshConfig(env) }) : await sshConfig(env));
+        return 0;
+    }
+    if (first === "proxy") {
+        if (!second)
+            throw usageError(`Give the host: ${me} sandbox ssh proxy <id>.runtime`, me);
+        return proxy(await connect(), second, await publicKey());
+    }
+    const runtime = await connect();
+    const sbx = await resolveSandbox(runtime, first);
+    await ensureSshd(sbx, out);
+    const key = keyFile ? undefined : await sshKey(env);
+    const args = [
+        "-o",
+        `ProxyCommand=${selfCommand(env)} sandbox ssh proxy${keyFile ? ` --key ${quote(keyFile)}` : ""} %h`,
+        ...(key ? ["-i", key.path, "-o", "IdentitiesOnly=yes"] : []),
+        "-o",
+        "StrictHostKeyChecking=no",
+        "-o",
+        "UserKnownHostsFile=/dev/null",
+        "-o",
+        "LogLevel=ERROR",
+        "-o",
+        "ServerAliveInterval=30",
+        ...(remote.length ? [] : ["-t"]),
+        `runtime@${sbx.id}.runtime`,
+        // ssh joins what follows the host into one remote command line.
+        ...remote,
+    ];
+    return new Promise((resolve, reject) => {
+        const child = spawn("ssh", args, { stdio: "inherit" });
+        child.on("error", (error) => reject(new RuntimeError({
+            message: `Could not run ssh: ${error.message}`,
+            code: "ssh_missing",
+            status: 0,
+            hint: "Install OpenSSH, or use `runtime sandbox shell <id>`, which needs nothing.",
+        })));
+        child.on("exit", (code) => resolve(code ?? 255));
+    });
+}
+function usageError(message, me) {
+    return new RuntimeError({
+        message,
+        code: "usage",
+        status: 0,
+        hint: `Run \`${me} sandbox ssh help\`.`,
+    });
+}
+/** `runtime sandbox port-forward <id> 5432 8080:3000 ...` */
+export async function portForwardCommand(argv, out, connect, me) {
+    const at = argv.indexOf("--address");
+    const address = at === -1 ? "127.0.0.1" : argv[at + 1];
+    const positional = argv.filter((word, i) => !word.startsWith("--") && (at === -1 || i !== at + 1));
+    const [target, ...specs] = positional;
+    if (!target || !specs.length || !address)
+        throw new RuntimeError({
+            message: `Give a sandbox and at least one port: ${me} sandbox port-forward <id> 5432 8080:3000`,
+            code: "usage",
+            status: 0,
+            hint: `Run \`${me} sandbox ssh help\`.`,
+        });
+    const ports = specs.map((spec) => {
+        const match = /^(?:(\d{1,5}):)?(\d{1,5})$/.exec(spec);
+        const remote = Number(match?.[2]);
+        const local = match?.[1] === undefined ? remote : Number(match[1]);
+        if (!match || remote < 1 || remote > 65_535 || local > 65_535)
+            throw new RuntimeError({
+                message: `${spec} is not a port or local:remote pair.`,
+                code: "usage",
+                status: 0,
+                hint: "For example 5432, or 15432:5432 to listen on 15432 here.",
+            });
+        return { local, remote };
+    });
+    const sbx = await resolveSandbox(await connect(), target);
+    const tunnel = await sbx.tunnel();
+    const forwards = [];
+    try {
+        for (const { local, remote } of ports)
+            forwards.push(await tunnel.forward(remote, { localPort: local, host: address }));
+    }
+    catch (error) {
+        tunnel.close();
+        throw new RuntimeError({
+            message: `Could not listen here: ${error instanceof Error ? error.message : String(error)}`,
+            code: "listen_failed",
+            status: 0,
+            hint: "Pick another local port with local:remote, for example 15432:5432.",
+        });
+    }
+    out.write(out.json
+        ? JSON.stringify({
+            sandboxId: sbx.id,
+            forwarding: forwards.map((f) => ({
+                address: f.host,
+                localPort: f.localPort,
+                port: f.port,
+            })),
+        })
+        : forwards
+            .map((f) => `Forwarding ${f.host}:${f.localPort} -> sandbox ${sbx.id} port ${f.port}`)
+            .join("\n") + "\nPress Ctrl-C to stop.");
+    return new Promise((resolve) => {
+        let stopping = false;
+        const stop = () => {
+            stopping = true;
+            process.off("SIGINT", stop);
+            void Promise.all(forwards.map((f) => f.close())).then(() => {
+                tunnel.close();
+                resolve(0);
+            });
+        };
+        process.once("SIGINT", stop);
+        void tunnel.closed.then((reason) => {
+            if (stopping)
+                return;
+            process.off("SIGINT", stop);
+            out.error(`The tunnel closed: ${reason}`);
+            void Promise.all(forwards.map((f) => f.close())).then(() => resolve(1));
+        });
+    });
+}

package/dist/tar.d.ts

@@ -1,3 +1,4 @@
+export declare function tarHeader(name: string, size: number, mode: number, type: "0" | "5" | "2", link?: string, mtime?: number): Uint8Array;
 export declare function packDirectory(root: string): Promise<Uint8Array>;
 /** Unpacks into `target`, refusing any entry that would land outside it. */
 export declare function unpackArchive(archive: Uint8Array, target: string): Promise<void>;

package/dist/tar.js

@@ -4,7 +4,7 @@ import { gunzipSync, gzipSync } from "node:zlib";
 /* A small ustar writer and reader for directory uploads and downloads, so the
    SDK needs no dependency. Regular files, directories and symbolic links;
    names up to 255 bytes through the ustar prefix field. */
-function header(name, size, mode, type, link = "", mtime = 0) {
+export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
     const block = new Uint8Array(512);
     const bytes = new TextEncoder().encode(name);
     let prefix = new Uint8Array();
@@ -48,16 +48,16 @@ export async function packDirectory(root) {
             const info = await lstat(full);
             const mtime = Math.floor(info.mtimeMs / 1000);
             if (info.isDirectory()) {
-                parts.push(header(`${path}/`, 0, info.mode, "5", "", mtime));
+                parts.push(tarHeader(`${path}/`, 0, info.mode, "5", "", mtime));
                 await walk(full);
             }
             else if (info.isSymbolicLink()) {
                 const { readlink } = await import("node:fs/promises");
-                parts.push(header(path, 0, info.mode, "2", await readlink(full), mtime));
+                parts.push(tarHeader(path, 0, info.mode, "2", await readlink(full), mtime));
             }
             else if (info.isFile()) {
                 const data = await readFile(full);
-                parts.push(header(path, data.length, info.mode, "0", "", mtime), data);
+                parts.push(tarHeader(path, data.length, info.mode, "0", "", mtime), data);
                 const pad = (512 - (data.length % 512)) % 512;
                 if (pad)
                     parts.push(new Uint8Array(pad));

package/dist/tools/index.d.ts

@@ -0,0 +1,62 @@
+import type { Sandbox } from "../sandbox.js";
+export type ToolInputSchema = {
+    type: "object";
+    properties: Record<string, {
+        type: "string" | "integer";
+        description: string;
+        minimum?: number;
+    }>;
+    required: string[];
+    additionalProperties: false;
+};
+export type SandboxTool<Input, Output> = {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+    execute(input: Input): Promise<Output>;
+};
+export type ExecInput = {
+    command: string;
+    cwd?: string;
+    timeoutSeconds?: number;
+};
+export type ExecOutput = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+};
+export type ListEntry = {
+    path: string;
+    type: "file" | "directory" | "symlink" | "other";
+    size: number;
+};
+export type SandboxToolOptions = {
+    /** Where relative paths resolve. Default /workspace. */
+    root?: string;
+    /** For a command that names no timeout. Default 300. */
+    timeoutSeconds?: number;
+    /** Characters kept from each of stdout, stderr and a file read; the rest is cut from the front. Default 20 000. */
+    maxOutputChars?: number;
+};
+export type SandboxTools = [
+    SandboxTool<ExecInput, ExecOutput>,
+    SandboxTool<{
+        path: string;
+    }, string>,
+    SandboxTool<{
+        path: string;
+        content: string;
+    }, string>,
+    SandboxTool<{
+        path?: string;
+        depth?: number;
+    }, ListEntry[] | {
+        error: string;
+    }>
+];
+/** A POSIX path joined and normalized: `..` cannot climb past `/`. */
+export declare function resolvePath(root: string, path: string | undefined): string;
+export declare function clip(text: string, limit: number): string;
+/** runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files, bound to `sandbox`. */
+export declare function sandboxTools(sandbox: Sandbox, options?: SandboxToolOptions): SandboxTools;