withruntime 0.9.0 → 0.11.0

package/dist/transport.js

@@ -1,6 +1,6 @@
 import { ConnectionError, DELIBERATE, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.9.0";
+export const VERSION = "0.11.0";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -80,18 +80,57 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
     else
         signal?.addEventListener("abort", abort, { once: true });
 });
+/** A credential lookup can finish independently, but must not keep its
+ * caller waiting after cancellation or hold that caller's queue slot. */
+function untilAborted(pending, signal) {
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(abortReason(signal));
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener("abort", abort, { once: true });
+        pending.then((value) => {
+            signal.removeEventListener("abort", abort);
+            resolve(value);
+        }, (cause) => {
+            signal.removeEventListener("abort", abort);
+            reject(cause instanceof Error ? cause : new Error("Credential lookup failed.", { cause }));
+        });
+    });
+}
+function abortReason(signal) {
+    return signal?.reason instanceof Error
+        ? signal.reason
+        : new Error("Aborted", { cause: signal?.reason });
+}
 /** At most `maximum` holders at once; the rest wait their turn, first come
  * first served. */
 function slots(maximum) {
     let active = 0;
     const waiting = [];
     return {
-        async take() {
+        async take(signal) {
+            signal?.throwIfAborted();
             if (active < maximum) {
                 active++;
                 return;
             }
-            await new Promise((resolve) => waiting.push(resolve));
+            await new Promise((resolve, reject) => {
+                const ready = () => {
+                    signal?.removeEventListener("abort", abort);
+                    resolve();
+                };
+                const abort = () => {
+                    const at = waiting.indexOf(ready);
+                    if (at >= 0)
+                        waiting.splice(at, 1);
+                    reject(abortReason(signal));
+                };
+                waiting.push(ready);
+                signal?.addEventListener("abort", abort, { once: true });
+            });
         },
         give() {
             const next = waiting.shift();
@@ -170,22 +209,71 @@ export class Transport {
      * the same key every time, and waits out a full house for a call that sets
      * waitForCapacityMs. */
     async send(call) {
-        const apiKey = await this.#key();
-        const write = call.method !== "GET";
-        const key = write ? (call.idempotencyKey ?? crypto.randomUUID()) : undefined;
-        // Time spent waiting for room is added to the call's deadline, not taken
-        // from it: once admitted, a create still has its whole timeoutMs.
+        return this.#send(this.#prepare(call), async (response) => response);
+    }
+    /** Start the deadline before waiting for a connection; keep one key and
+     * signal through every retry and the complete response body. */
+    #prepare(call) {
+        const timeoutMs = call.timeoutMs ?? this.#timeoutMs;
+        const roomMs = Math.max(0, call.waitForCapacityMs ?? 0);
+        const deadline = timeoutMs === 0 ? undefined : AbortSignal.timeout(timeoutMs + roomMs);
+        const signal = deadline
+            ? call.signal
+                ? AbortSignal.any([call.signal, deadline])
+                : deadline
+            : call.signal;
+        return {
+            ...call,
+            timeoutMs: 0,
+            ...(signal ? { signal } : {}),
+            ...(call.method !== "GET"
+                ? { idempotencyKey: call.idempotencyKey ?? crypto.randomUUID() }
+                : {}),
+        };
+    }
+    #connectionError(call, cause) {
+        const cancelled = call.signal?.aborted === true;
+        const route = this.#routed && !cancelled
+            ? describeRoute(`${this.baseUrl}${call.path}`, cause)
+            : { via: "" };
+        return new ConnectionError({
+            message: cancelled
+                ? "The call was cancelled or ran past its deadline."
+                : call.method !== "GET"
+                    ? `No answer from Runtime at ${this.baseUrl}${route.via}. The change may have happened; retrying with the same idempotencyKey is safe.`
+                    : `No answer from Runtime at ${this.baseUrl}${route.via}.`,
+            hint: cancelled
+                ? "Raise timeoutMs for a long call, or retry with the same idempotencyKey."
+                : (route.hint ?? "Check the network, and RUNTIME_API_URL if you set it."),
+            code: cancelled ? "timeout" : "connection_error",
+            status: 0,
+            ...(call.idempotencyKey ? { idempotencyKey: call.idempotencyKey } : {}),
+            cause,
+        });
+    }
+    async #send(call, consume) {
+        let apiKey;
+        try {
+            call.signal?.throwIfAborted();
+            apiKey = await untilAborted(this.#key(), call.signal);
+        }
+        catch (cause) {
+            if (call.signal?.aborted)
+                throw this.#connectionError(call, cause);
+            throw cause;
+        }
+        const key = call.method !== "GET" ? call.idempotencyKey : undefined;
         const roomMs = Math.max(0, call.waitForCapacityMs ?? 0);
         const roomUntil = performance.now() + roomMs;
         let roomAttempt = 0;
-        const timeoutMs = call.timeoutMs ?? this.#timeoutMs;
-        const deadline = timeoutMs === 0 ? new AbortController().signal : AbortSignal.timeout(timeoutMs + roomMs);
-        const signal = call.signal ? AbortSignal.any([call.signal, deadline]) : deadline;
+        const signal = call.signal;
         const url = `${this.baseUrl}${call.path}${encodeQuery(call.query)}`;
         const body = call.bytes ?? (call.body === undefined ? undefined : JSON.stringify(call.body));
         const retry = call.retry ?? true;
-        for (let attempt = 0;; attempt++) {
+        let attempt = 0;
+        for (;;) {
             let response;
+            let inCallback = false;
             // Called as a plain function: Cloudflare Workers' fetch throws "Illegal
             // invocation" when called as a method of another object (this.#fetch()).
             const send = this.#fetch;
@@ -193,6 +281,7 @@ export class Transport {
                 // "manual", not "error": Workers accept only "follow" and "manual".
                 // The API never redirects, so a redirect is refused here exactly as
                 // "error" refused it: thrown, retried, then a connection_error.
+                signal?.throwIfAborted();
                 response = await send(url, {
                     method: call.method,
                     headers: this.#headers(call, key, apiKey),
@@ -205,138 +294,132 @@ export class Transport {
                     await response.body?.cancel().catch(() => { });
                     throw new TypeError(`fetch failed: Runtime answered a redirect (${response.status}).`);
                 }
-            }
-            catch (cause) {
-                // A proxy variable the SDK cannot use: retrying cannot change it.
-                if (cause instanceof RuntimeError)
-                    throw cause;
-                if (signal.aborted || !retry || attempt >= this.#maxRetries) {
-                    const route = this.#routed && !signal.aborted ? describeRoute(url, cause) : { via: "" };
+                /* An answer that took longer than the API holds its headers (90 s)
+                 comes as a 200 sent early, and then its JSON: the answer, or
+                 {"error": ...} when the work failed after the status went
+                 (runtime-late-answer, api.md). Either way it is read here, so a
+                 failure is thrown as the error it is, never returned as a success. */
+                let late;
+                if (response.ok && response.headers.get("runtime-late-answer") === "true") {
+                    const text = await response.text();
+                    const failed = lateFailure(text);
+                    if (failed === undefined)
+                        return await consume(new Response(text, { headers: response.headers }));
+                    late = { status: failed, text };
+                }
+                else if (response.ok) {
+                    inCallback = true;
+                    call.onResponse?.(response);
+                    inCallback = false;
+                    return await consume(response);
+                }
+                const status = late?.status ?? response.status;
+                // Runtime never answers 407: it is a proxy refusing the tunnel, which
+                // Bun's fetch hands back as a response rather than an error.
+                if (response.status === 407 && this.#routed) {
+                    await response.body?.cancel();
+                    const route = describeRoute(url, 407);
                     throw new ConnectionError({
-                        message: signal.aborted
-                            ? "The call was cancelled or ran past its deadline."
-                            : write
-                                ? `No answer from Runtime at ${this.baseUrl}${route.via}. The change may have happened; retrying with the same idempotencyKey is safe.`
-                                : `No answer from Runtime at ${this.baseUrl}${route.via}.`,
-                        hint: signal.aborted
-                            ? "Raise timeoutMs for a long call, or retry with the same idempotencyKey."
-                            : (route.hint ?? "Check the network, and RUNTIME_API_URL if you set it."),
-                        code: signal.aborted ? "timeout" : "connection_error",
+                        message: `No answer from Runtime at ${this.baseUrl}${route.via}.`,
+                        code: "connection_error",
                         status: 0,
+                        ...(route.hint ? { hint: route.hint } : {}),
                         ...(key ? { idempotencyKey: key } : {}),
-                        cause,
                     });
                 }
-                await sleep(backoff(attempt), signal);
-                continue;
-            }
-            /* An answer that took longer than the API holds its headers (90 s)
-               comes as a 200 sent early, and then its JSON: the answer, or
-               {"error": ...} when the work failed after the status went
-               (runtime-late-answer, api.md). Either way it is read here, so a
-               failure is thrown as the error it is, never returned as a success. */
-            let late;
-            if (response.ok && response.headers.get("runtime-late-answer") === "true") {
-                const text = await response.text();
-                const failed = lateFailure(text);
-                if (failed === undefined)
-                    return new Response(text, { headers: response.headers });
-                late = { status: failed, text };
-            }
-            else if (response.ok) {
-                call.onResponse?.(response);
-                return response;
+                const text = late?.text ?? (await response.text());
+                let parsed = null;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    parsed = { error: { message: text.slice(0, 500) || `HTTP ${status}` } };
+                }
+                const error = errorFor(status, parsed, key);
+                // A full house: wait for a slot or for room, then send the same call
+                // again. A request that can never fit (a fork of more copies than the
+                // trial runs) is not waited for.
+                if (retry &&
+                    roomMs > 0 &&
+                    WAITS_FOR_ROOM.has(error.code) &&
+                    error.details?.field !== "count") {
+                    const left = roomUntil - performance.now();
+                    if (left <= 0)
+                        throw error;
+                    const pause = Math.min(left, error.retryAfterMs ?? roomBackoff(roomAttempt++));
+                    inCallback = true;
+                    call.onCapacityWait?.(error, pause);
+                    inCallback = false;
+                    await sleep(pause, signal);
+                    continue;
+                }
+                const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);
+                if (!retry || !retryable || attempt >= this.#maxRetries)
+                    throw error;
+                const header = Number(response.headers.get("retry-after"));
+                const wait = error.retryAfterMs ??
+                    (Number.isFinite(header) && header > 0 ? header * 1000 : backoff(attempt));
+                await sleep(Math.min(30_000, wait) * (0.9 + Math.random() * 0.2), signal);
             }
-            const status = late?.status ?? response.status;
-            // Runtime never answers 407: it is a proxy refusing the tunnel, which
-            // Bun's fetch hands back as a response rather than an error.
-            if (response.status === 407 && this.#routed) {
-                await response.body?.cancel();
-                const route = describeRoute(url, 407);
-                throw new ConnectionError({
-                    message: `No answer from Runtime at ${this.baseUrl}${route.via}.`,
-                    code: "connection_error",
-                    status: 0,
-                    ...(route.hint ? { hint: route.hint } : {}),
-                    ...(key ? { idempotencyKey: key } : {}),
+            catch (cause) {
+                // Deliberate API refusals and unusable proxy settings cannot be
+                // fixed by repeating the request. Body failures are transport
+                // failures too: a write replays under its original key.
+                if (inCallback) {
+                    await response?.body?.cancel().catch(() => undefined);
+                    throw cause;
+                }
+                if (cause instanceof RuntimeError)
+                    throw cause;
+                if (signal?.aborted || !retry || attempt >= this.#maxRetries)
+                    throw this.#connectionError(call, cause);
+                await sleep(backoff(attempt), signal).catch((cause) => {
+                    throw this.#connectionError(call, cause);
                 });
             }
-            const text = late?.text ?? (await response.text());
-            let parsed = null;
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch {
-                parsed = { error: { message: text.slice(0, 500) || `HTTP ${status}` } };
-            }
-            const error = errorFor(status, parsed, key);
-            // A full house: wait for a slot or for room, then send the same call
-            // again. A request that can never fit (a fork of more copies than the
-            // trial runs) is not waited for.
-            if (retry &&
-                roomMs > 0 &&
-                WAITS_FOR_ROOM.has(error.code) &&
-                error.details?.field !== "count") {
-                const left = roomUntil - performance.now();
-                if (left <= 0)
-                    throw error;
-                const pause = Math.min(left, error.retryAfterMs ?? roomBackoff(roomAttempt++));
-                call.onCapacityWait?.(error, pause);
-                await sleep(pause, signal);
-                continue;
-            }
-            const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);
-            if (!retry || !retryable || attempt >= this.#maxRetries)
-                throw error;
-            const header = Number(response.headers.get("retry-after"));
-            const wait = error.retryAfterMs ??
-                (Number.isFinite(header) && header > 0 ? header * 1000 : backoff(attempt));
-            await sleep(Math.min(30_000, wait) * (0.9 + Math.random() * 0.2), signal);
+            attempt++;
         }
     }
-    async json(call) {
-        await this.#slots.take();
+    async #queued(call, consume) {
         try {
-            const text = await (await this.send(call)).text();
-            return (text ? JSON.parse(text) : null);
+            await this.#slots.take(call.signal);
         }
-        finally {
-            this.#slots.give();
+        catch (cause) {
+            throw this.#connectionError(call, cause);
         }
-    }
-    async bytes(call) {
-        await this.#slots.take();
         try {
-            return new Uint8Array(await (await this.send(call)).arrayBuffer());
+            return await this.#send(call, consume);
         }
         finally {
             this.#slots.give();
         }
     }
-    /** A file's bytes, read whole and checked: the API says a body's length
-     * (x-content-length) and, when small, its SHA-256 (x-content-sha256) before
-     * sending it, and a body that falls short or differs is read again, twice,
-     * then refused. Nothing between the API and here reliably turns a stream
-     * cut part way into an error: on 25 September 2026 a 50 MB file came back
-     * 29 MB long, exit 0. */
+    async json(call) {
+        return this.#queued(this.#prepare(call), async (response) => {
+            const text = await response.text();
+            return (text ? JSON.parse(text) : null);
+        });
+    }
+    async bytes(call) {
+        return this.#queued(this.#prepare(call), async (response) => new Uint8Array(await response.arrayBuffer()));
+    }
+    /** A file's bytes, read whole and checked against its promised length and
+     * SHA-256. A short or different body is read again twice, within the same
+     * call deadline. */
     async fileBytes(call) {
+        call = this.#prepare(call);
         for (let attempt = 0;; attempt++) {
-            await this.#slots.take();
-            let failure;
-            try {
-                const response = await this.send(call);
+            const { body, problem } = await this.#queued(call, async (response) => {
                 const body = new Uint8Array(await response.arrayBuffer());
-                const problem = await checkBody(response.headers, body);
-                if (!problem)
-                    return body;
-                failure = problem;
-            }
-            finally {
-                this.#slots.give();
-            }
-            if (attempt >= 2 || call.signal?.aborted)
-                throw failure;
-            await sleep(backoff(attempt), call.signal);
+                return { body, problem: await checkBody(response.headers, body) };
+            });
+            if (!problem)
+                return body;
+            if (attempt >= 2)
+                throw problem;
+            await sleep(backoff(attempt), call.signal).catch((cause) => {
+                throw this.#connectionError(call, cause);
+            });
         }
     }
     /** A file's bytes as they arrive, for files too big to hold. The stream

package/dist/types.d.ts

@@ -42,8 +42,9 @@ export type SandboxInfo = {
     /** The names of its own environment variables (`env`), on a create, an
      * update and a read of one sandbox. Values are never shown. */
     envNames?: string[];
-    /** On a create from an image with a start command: whether it started,
-     * became ready (readyMs), timed out, or exited first. The create's answer
+    /** On a create from an image with a start command: whether it started
+     * (and was still running half a second later), became ready (readyMs),
+     * timed out, or exited first (exitCode, and stderr's last lines). The create's answer
      * alone carries it, and the Sandbox that create returned keeps it through
      * later reads; `sandboxes.get` and `list` have none, because the API keeps
      * no record of it. */
@@ -52,6 +53,8 @@ export type SandboxInfo = {
         processId?: string;
         exitCode?: number | null;
         readyMs?: number;
+        /** With exited: the last lines the start command wrote to stderr. */
+        stderr?: string;
     };
     /** Present and true when getOrCreate answered a sandbox that already held the name. */
     reused?: boolean;

package/dist/vercel/command.d.ts

@@ -57,7 +57,7 @@ export declare class Command {
         signal?: AbortSignal;
     }): Promise<string>;
     /** Sends a signal, SIGTERM by default. */
-    kill(signal?: Signal, _opts?: {
+    kill(signal?: Signal, opts?: {
         abortSignal?: AbortSignal;
     }): Promise<void>;
 }

package/dist/vercel/command.js

@@ -136,13 +136,14 @@ export class Command {
         return this.output("stderr", opts);
     }
     /** Sends a signal, SIGTERM by default. */
-    async kill(signal = "SIGTERM", _opts = {}) {
+    async kill(signal = "SIGTERM", opts = {}) {
+        opts.abortSignal?.throwIfAborted();
         if (!this.init.process)
             return;
         const name = typeof signal === "number" ? SIGNAL_NUMBERS[signal] : signal;
         if (!name)
             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), this.init.sandboxName);
+        await guard(() => this.init.process.kill(name, opts.abortSignal ? { signal: opts.abortSignal } : {}), this.init.sandboxName);
     }
 }
 /** A command that has ended; `exitCode` is set. */

package/dist/vercel/errors.d.ts

@@ -45,7 +45,7 @@ export declare function translate(error: unknown, sandboxName?: string): unknown
 export declare function guard<T>(work: () => Promise<T>, sandboxName?: string): Promise<T>;
 /** A node:fs-style error, as Vercel's `sandbox.fs` throws. */
 export declare function fsError(code: "ENOENT" | "EEXIST" | "EISDIR" | "ENOTDIR" | "EACCES" | "ENOTEMPTY" | "EINVAL", syscall: string, path: string): Error & {
-    code: "ENOENT" | "EEXIST" | "ENOTDIR" | "EISDIR" | "EACCES" | "ENOTEMPTY" | "EINVAL";
+    code: "ENOENT" | "ENOTDIR" | "EEXIST" | "EISDIR" | "EACCES" | "ENOTEMPTY" | "EINVAL";
     errno: number;
     syscall: string;
     path: string;

package/dist/vercel/errors.js

@@ -73,7 +73,13 @@ export function translate(error, sandboxName) {
         return new NotSupportedError(error.code.replace(/_unavailable$/, ""), error.hint ?? "", message);
     if (error.status < 200 || error.status > 599)
         return error;
-    const json = { error: { code: error.code, message: error.message } };
+    const json = {
+        error: {
+            code: error.code,
+            message: error.message,
+            ...(error.details ? { details: error.details } : {}),
+        },
+    };
     const out = new APIError(new Response(JSON.stringify(json), {
         status: error.status,
         headers: { "content-type": "application/json" },

package/dist/vercel/index.d.ts

@@ -1,6 +1,7 @@
 export { Sandbox, DEFAULT_TIMEOUT_MS, DEFAULT_VCPUS, MEMORY_MIB_PER_VCPU, networkRules, toRuntimePath, type CreateSandboxParams, type RunCommandParams, type NetworkPolicy, type SandboxRoute, } from "./sandbox.js";
 export { Command, CommandFinished, type CommandOutput, type LogOutputLine, type Signal, } from "./command.js";
 export { FileSystem, Stats, Dirent } from "./filesystem.js";
+export { SandboxUser, SandboxUserAlreadyExistsError } from "./sandbox-user.js";
 export { Snapshot } from "./snapshot.js";
 export { APIError, StreamError, AuthenticationError, NotSupportedError } from "./errors.js";
 export type { Credentials, WithRuntime } from "./client.js";
@@ -16,13 +17,6 @@ export declare const Session: {
     new (...args: unknown[]): never;
     readonly [key: string]: (...args: unknown[]) => never;
 };
-export declare const SandboxUser: {
-    (...args: unknown[]): never;
-    new (...args: unknown[]): never;
-    readonly [key: string]: (...args: unknown[]) => never;
-};
-export declare class SandboxUserAlreadyExistsError extends Error {
-}
 export declare const defineSandboxProxy: {
     (...args: unknown[]): never;
     new (...args: unknown[]): never;

package/dist/vercel/index.js

@@ -9,6 +9,7 @@ import { NotSupportedError } from "./errors.js";
 export { Sandbox, DEFAULT_TIMEOUT_MS, DEFAULT_VCPUS, MEMORY_MIB_PER_VCPU, networkRules, toRuntimePath, } from "./sandbox.js";
 export { Command, CommandFinished, } from "./command.js";
 export { FileSystem, Stats, Dirent } from "./filesystem.js";
+export { SandboxUser, SandboxUserAlreadyExistsError } from "./sandbox-user.js";
 export { Snapshot } from "./snapshot.js";
 export { APIError, StreamError, AuthenticationError, NotSupportedError } from "./errors.js";
 /** Vercel's default region; Runtime runs in one US region. */
@@ -32,7 +33,4 @@ function unsupportedExport(name, alternative) {
 }
 export const Drive = unsupportedExport("Drive", "Use a Runtime volume (runtime.volumes) and mount it with withruntime: { create: { volumes: [{ volumeId, path }] } }.");
 export const Session = unsupportedExport("Session", "A Runtime sandbox is its own session: call the methods on the sandbox.");
-export const SandboxUser = unsupportedExport("SandboxUser", "Commands run as the sandbox owner with passwordless sudo; create users with `sudo useradd` in runCommand.");
-export class SandboxUserAlreadyExistsError extends Error {
-}
 export const defineSandboxProxy = unsupportedExport("sandbox proxy (defineSandboxProxy)", "Share a port with sandbox.withruntime.previews.create(port) instead.");

package/dist/vercel/sandbox-user.d.ts

@@ -0,0 +1,70 @@
+import type { Command, CommandFinished } from "./command.js";
+import type { RunCommandParams, Sandbox } from "./sandbox.js";
+/** A Linux user or group name Vercel accepts, which is also safe to pass to
+ * useradd, groupadd and sudo. */
+export declare function validateName(name: string, kind: string): void;
+/** Thrown when `sandbox.createUser` is called for an existing username. */
+export declare class SandboxUserAlreadyExistsError extends Error {
+    readonly username: string;
+    constructor(username: string);
+}
+type Signal = {
+    signal?: AbortSignal;
+};
+/** A user in a sandbox, made with `sandbox.createUser` or found with
+ * `sandbox.asUser`. Commands and file calls run as this user. */
+export declare class SandboxUser {
+    #private;
+    readonly username: string;
+    /** `/root` for root, else `/home/<username>`. */
+    readonly homeDir: string;
+    /** Use sandbox.createUser or sandbox.asUser. */
+    constructor({ sandbox, username }: {
+        sandbox: Sandbox;
+        username: string;
+    });
+    /** Runs a command as this user. `sudo: true` runs it as root instead. */
+    runCommand(command: string, args?: string[], opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<CommandFinished>;
+    runCommand(params: RunCommandParams & {
+        detached: true;
+    }): Promise<Command>;
+    runCommand(params: RunCommandParams): Promise<CommandFinished>;
+    /** Writes files into this user's home (or absolute paths), then gives them
+     * and the directories made for them to this user. */
+    writeFiles(files: {
+        path: string;
+        content: string | Uint8Array;
+        mode?: number;
+    }[], opts?: Signal): Promise<void>;
+    /** The file as this user may read it, as a stream; null when missing. */
+    readFile(file: {
+        path: string;
+        cwd?: string;
+    }, opts?: Signal): Promise<NodeJS.ReadableStream | null>;
+    /** The file as this user may read it; null when missing. */
+    readFileToBuffer(file: {
+        path: string;
+        cwd?: string;
+    }, opts?: Signal): Promise<Buffer | null>;
+    /** Copies a file this user may read to the local disk; null when missing. */
+    downloadFile(src: {
+        path: string;
+        cwd?: string;
+    }, dst: {
+        path: string;
+        cwd?: string;
+    }, opts?: {
+        mkdirRecursive?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+    /** Makes a directory owned by this user. */
+    mkDir(path: string, opts?: Signal): Promise<void>;
+    addToGroup(groupname: string, opts?: Signal): Promise<void>;
+    removeFromGroup(groupname: string, opts?: Signal): Promise<void>;
+}
+/** Runs `cmd args` under sudo; a non-zero exit throws `what(): <stderr>`. */
+export declare function rootOrThrow(sandbox: Sandbox, cmd: string, args: string[], signal: AbortSignal | undefined, what: () => string): Promise<CommandFinished>;
+export {};