withruntime 0.8.4 → 0.10.0

package/dist/tar.js

@@ -1,6 +1,8 @@
-import { chmod, lstat, mkdir, readdir, readFile, realpath, symlink, unlink, writeFile, } from "node:fs/promises";
+import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { gunzipSync, gzipSync } from "node:zlib";
+import { Readable } from "node:stream";
+import { createGunzip, gzipSync } from "node:zlib";
+import { RuntimeError } from "./errors.js";
 /* 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. */
@@ -111,34 +113,224 @@ async function linkStaysInside(root, directory, link) {
     }
     return true;
 }
-/** Unpacks into `target`, refusing any entry that would land outside it. */
-export async function unpackArchive(archive, target) {
-    const data = gunzipSync(archive);
-    await mkdir(resolve(target), { recursive: true });
-    const root = await realpath(resolve(target));
-    const text = (start, length) => {
-        const slice = data.subarray(start, start + length);
+/** A folder that did not arrive whole: tar in the sandbox stopped part way
+ * (a file it may not read, one that changed as it was read), which ends the
+ * gzip stream short, or the connection was lost (ARCHITECTURE.md section 10,
+ * "Folders over HTTP"). */
+function cutShort(cause) {
+    return new RuntimeError({
+        message: "The folder's archive arrived cut short: tar in the sandbox stopped part way, or the connection was lost. Nothing was written.",
+        hint: "Try again. If it fails the same way, a file in the folder cannot be read by the sandbox user or changes as it is read.",
+        code: "download_incomplete",
+        status: 0,
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function checkSignal(signal) {
+    if (signal?.aborted)
+        throw new RuntimeError({
+            message: "The download was cancelled or ran past its deadline.",
+            code: "timeout",
+            status: 0,
+            cause: signal.reason,
+        });
+}
+/** Linux path names fit well below this generous metadata-only memory bound. */
+const MAX_LONG_NAME_BYTES = 65_536;
+function archiveSize(field) {
+    const text = field.trim();
+    if (text !== "" && !/^[0-7]+$/.test(text))
+        throw new Error("The archive contains an invalid file size.");
+    const size = text === "" ? 0 : parseInt(text, 8);
+    if (!Number.isSafeInteger(size) || size < 0 || size > Number.MAX_SAFE_INTEGER - 511)
+        throw new Error("The archive contains an invalid file size.");
+    return size;
+}
+/** The gzip check protects the compressed bytes; tar's own checksum also
+ * protects the header that determines each file's name, kind and length. */
+function checkHeader(header, field) {
+    const text = field.trim();
+    let unsigned = 0;
+    let signed = 0;
+    for (let index = 0; index < header.length; index++) {
+        const byte = index >= 148 && index < 156 ? 32 : header[index];
+        unsigned += byte;
+        signed += byte < 128 ? byte : byte - 256;
+    }
+    const expected = /^[0-7]+$/.test(text) ? parseInt(text, 8) : NaN;
+    // Older tar implementations used signed bytes for non-ASCII path names.
+    if (expected !== unsigned && expected !== signed)
+        throw new Error("The archive contains an invalid header checksum.");
+}
+/** Validate links against the tree a merge will produce. Staged entries
+ * take precedence; paths absent there retain the existing target's entry.
+ * A link safe in staging may otherwise lead through an old escaping link. */
+async function mergedLinkStaysInside(staging, root, destination, link) {
+    let path = dirname(join(root, relative(staging, destination)));
+    const pending = link.split("/");
+    const followed = new Set();
+    while (pending.length) {
+        const part = pending.shift();
+        if (!part || part === ".")
+            continue;
+        path = part === ".." ? dirname(path) : join(path, part);
+        if (path !== root && !path.startsWith(root + sep))
+            return false;
+        const staged = join(staging, relative(root, path));
+        const stagedKind = await lstat(staged).catch((error) => {
+            if (error.code === "ENOENT" || error.code === "ENOTDIR")
+                return undefined;
+            throw error;
+        });
+        const actual = stagedKind ? staged : path;
+        const kind = stagedKind ??
+            (await lstat(actual).catch((error) => {
+                if (error.code === "ENOENT" || error.code === "ENOTDIR")
+                    return undefined;
+                throw error;
+            }));
+        if (!kind?.isSymbolicLink())
+            continue;
+        if (followed.has(path))
+            return false;
+        followed.add(path);
+        const next = await readlink(actual);
+        if (isAbsolute(next)) {
+            // An existing absolute link is safe only when it stays in this root.
+            if (next !== root && !next.startsWith(root + sep))
+                return false;
+            path = root;
+            pending.unshift(...relative(root, next).split(sep));
+        }
+        else {
+            path = dirname(path);
+            pending.unshift(...next.split("/"));
+        }
+    }
+    return true;
+}
+/** The gzip stream's bytes, decompressed as they arrive. */
+function gunzipped(source, signal) {
+    const input = Readable.from(source, { objectMode: false });
+    const output = createGunzip();
+    // A filesystem await may precede async iteration; retain early stream
+    // errors for that iterator without an unhandled EventEmitter error.
+    output.on("error", () => undefined);
+    input.on("error", (error) => output.destroy(error));
+    input.pipe(output);
+    const abort = () => {
+        try {
+            checkSignal(signal);
+        }
+        catch (error) {
+            output.destroy(error);
+        }
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    output.on("close", () => {
+        signal?.removeEventListener("abort", abort);
+        input.destroy();
+    });
+    return output;
+}
+/** Exact byte counts from a stream of chunks, holding at most one chunk. */
+class Bytes {
+    #chunks;
+    #held = new Uint8Array(0);
+    constructor(source) {
+        this.#chunks = source[Symbol.asyncIterator]();
+    }
+    async #more() {
+        let next;
+        try {
+            next = await this.#chunks.next();
+        }
+        catch (error) {
+            throw error instanceof RuntimeError ? error : cutShort(error);
+        }
+        if (next.done)
+            return false;
+        this.#held = this.#held.length ? Buffer.concat([this.#held, next.value]) : next.value;
+        return true;
+    }
+    /** `n` bytes, or undefined at a clean end before any of them. */
+    async exactly(n) {
+        while (this.#held.length < n) {
+            if (await this.#more())
+                continue;
+            if (this.#held.length === 0)
+                return undefined;
+            throw cutShort();
+        }
+        const out = this.#held.subarray(0, n);
+        this.#held = this.#held.subarray(n);
+        return out;
+    }
+    /** The next `n` bytes as they arrive. */
+    async *take(n) {
+        while (n > 0) {
+            if (this.#held.length === 0 && !(await this.#more()))
+                throw cutShort();
+            const out = this.#held.subarray(0, n);
+            this.#held = this.#held.subarray(out.length);
+            n -= out.length;
+            yield out;
+        }
+    }
+    /** Reads to the end, so the gzip stream's own check has run. */
+    async drain() {
+        this.#held = new Uint8Array(0);
+        while (await this.#more())
+            this.#held = new Uint8Array(0);
+    }
+}
+/** Unpacks a tar stream into `root`, a fresh folder: files and folders as they
+ * arrive, links noted to make at the end. Throws unless the archive's end
+ * arrived. */
+async function unpackEntries(bytes, root, signal) {
+    const links = [];
+    const decode = (slice) => {
         const end = slice.indexOf(0);
         return new TextDecoder().decode(end < 0 ? slice : slice.subarray(0, end));
     };
-    const links = [];
     let longName;
     let longLink;
-    for (let offset = 0; offset + 512 <= data.length;) {
-        if (data.subarray(offset, offset + 512).every((byte) => byte === 0))
-            break;
-        const size = parseInt(text(offset + 124, 12).trim() || "0", 8);
-        const type = String.fromCharCode(data[offset + 156] ?? 48);
-        const prefix = text(offset + 345, 155);
-        let name = longName ?? (prefix ? `${prefix}/${text(offset, 100)}` : text(offset, 100));
-        const link = longLink ?? text(offset + 157, 100);
+    for (;;) {
+        checkSignal(signal);
+        const header = await bytes.exactly(512);
+        if (!header)
+            throw cutShort();
+        if (header.every((byte) => byte === 0)) {
+            const terminator = await bytes.exactly(512);
+            if (!terminator || !terminator.every((byte) => byte === 0))
+                throw cutShort();
+            await bytes.drain();
+            return links;
+        }
+        const text = (start, length) => decode(header.subarray(start, start + length));
+        const size = archiveSize(text(124, 12));
+        checkHeader(header, text(148, 8));
+        const type = String.fromCharCode(header[156] ?? 48);
+        const prefix = text(345, 155);
+        let name = longName ?? (prefix ? `${prefix}/${text(0, 100)}` : text(0, 100));
+        const link = longLink ?? text(157, 100);
         longName = undefined;
         longLink = undefined;
-        const mode = parseInt(text(offset + 100, 8).trim() || "644", 8);
-        const body = data.subarray(offset + 512, offset + 512 + size);
-        offset += 512 + Math.ceil(size / 512) * 512;
+        const mode = parseInt(text(100, 8).trim() || "644", 8);
+        const padding = Math.ceil(size / 512) * 512 - size;
+        const skip = async () => {
+            for await (const _ of bytes.take(size + padding))
+                ;
+        };
         if (type === "L" || type === "K") {
-            const value = new TextDecoder().decode(body).replace(/\0.*$/s, "");
+            if (size > MAX_LONG_NAME_BYTES)
+                throw new Error("The archive contains oversized path metadata.");
+            const parts = [];
+            for await (const part of bytes.take(size))
+                parts.push(Uint8Array.from(part));
+            for await (const _ of bytes.take(padding))
+                ;
+            const value = new TextDecoder().decode(Buffer.concat(parts)).replace(/\0.*$/s, "");
             if (type === "L")
                 longName = value;
             else
@@ -146,29 +338,113 @@ export async function unpackArchive(archive, target) {
             continue;
         }
         name = name.replace(/^\.\//, "");
-        if (!name || name === "." || name === "./")
+        if (!name || name === "." || name === "./") {
+            await skip();
             continue;
+        }
         const destination = resolve(root, name);
         await assertPlain(root, destination, name);
-        if (type === "5")
+        if (type === "5") {
             await mkdir(destination, { recursive: true });
-        else if (type === "2")
+            await skip();
+        }
+        else if (type === "2") {
             links.push({ destination, link, name });
+            await skip();
+        }
         else if (type === "0" || type === "\0" || type === "7") {
             await mkdir(dirname(destination), { recursive: true });
-            await writeFile(destination, body);
+            const file = await open(destination, "w");
+            try {
+                for await (const part of bytes.take(size)) {
+                    let written = 0;
+                    while (written < part.length) {
+                        checkSignal(signal);
+                        const result = await file.write(part.subarray(written));
+                        if (result.bytesWritten === 0)
+                            throw new Error("The local file accepted no bytes.");
+                        written += result.bytesWritten;
+                    }
+                }
+            }
+            finally {
+                await file.close();
+            }
             await chmod(destination, mode & 0o777);
+            for await (const _ of bytes.take(padding))
+                ;
         }
+        else
+            await skip();
     }
-    for (const { destination, link, name } of links) {
-        await assertPlain(root, destination, name);
-        await mkdir(dirname(destination), { recursive: true });
-        await symlink(link, destination).catch(() => undefined);
+}
+/** Moves what was unpacked in `from` into `to`, merging with what is there
+ * and replacing files of the same name, never through a link in `to`. */
+async function merge(from, to, root, signal) {
+    for (const name of await readdir(from)) {
+        checkSignal(signal);
+        const source = join(from, name);
+        const destination = join(to, name);
+        await assertPlain(root, destination, relative(root, destination));
+        const [kind, there] = await Promise.all([
+            lstat(source),
+            lstat(destination).catch(() => undefined),
+        ]);
+        checkSignal(signal);
+        if (kind.isDirectory() && there?.isDirectory())
+            await merge(source, destination, root, signal);
+        else
+            await rename(source, destination);
     }
-    for (const { destination, link, name } of links) {
-        if (await linkStaysInside(root, dirname(destination), link))
-            continue;
-        await unlink(destination).catch(() => undefined);
-        throw new Error(`Refusing an archive link that leads outside the target: ${name} -> ${link}`);
+}
+/** Unpacks a gzipped tar that arrives as a stream into `target`, refusing any
+ * entry that would land outside it, holding no more than a chunk at a time.
+ * It unpacks into a folder beside the target and moves it into place only
+ * once the whole archive arrived, so an archive cut short leaves nothing
+ * behind that could pass for the folder. A target that exists is merged
+ * into, files of the same name replaced. */
+export async function unpackStream(source, target, options = {}) {
+    checkSignal(options.signal);
+    const final = resolve(target);
+    await mkdir(dirname(final), { recursive: true });
+    const staging = await mkdtemp(`${final}.runtime-partial-`);
+    const stream = gunzipped(source, options.signal);
+    try {
+        const root = await realpath(staging);
+        const links = await unpackEntries(new Bytes(stream), root, options.signal);
+        for (const { destination, link, name } of links) {
+            checkSignal(options.signal);
+            await assertPlain(root, destination, name);
+            await mkdir(dirname(destination), { recursive: true });
+            await symlink(link, destination).catch(() => undefined);
+        }
+        for (const { destination, link, name } of links) {
+            checkSignal(options.signal);
+            if (await linkStaysInside(root, dirname(destination), link))
+                continue;
+            await unlink(destination).catch(() => undefined);
+            throw new Error(`Refusing an archive link that leads outside the target: ${name} -> ${link}`);
+        }
+        const there = await lstat(final).catch(() => undefined);
+        checkSignal(options.signal);
+        if (!there)
+            await rename(staging, final);
+        else {
+            const targetRoot = await realpath(final);
+            for (const { destination, link, name } of links) {
+                checkSignal(options.signal);
+                if (!(await mergedLinkStaysInside(root, targetRoot, destination, link)))
+                    throw new Error(`Refusing an archive link that leads outside the target: ${name} -> ${link}`);
+            }
+            await merge(root, targetRoot, targetRoot, options.signal);
+        }
+    }
+    finally {
+        stream.destroy();
+        await rm(staging, { recursive: true, force: true });
     }
 }
+/** Unpacks a whole gzipped tar held in memory, by the same rules. */
+export function unpackArchive(archive, target) {
+    return unpackStream([archive], target);
+}

package/dist/tools/index.js

@@ -10,6 +10,7 @@
  * chooses commands and paths, never the sandbox, the account or the key.
  * Relative paths are under /workspace, and output is capped so one noisy
  * command cannot flood the model's context. */
+import { TOOL_EXEC_TIMEOUT_SECONDS } from "../api-defaults.js";
 import { NotFoundError } from "../errors.js";
 const WORKSPACE = "/workspace";
 /** A POSIX path joined and normalized: `..` cannot climb past `/`. */
@@ -34,7 +35,7 @@ export function clip(text, limit) {
 /** runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files, bound to `sandbox`. */
 export function sandboxTools(sandbox, options = {}) {
     const root = resolvePath("/", options.root ?? WORKSPACE);
-    const timeoutSeconds = options.timeoutSeconds ?? 300;
+    const timeoutSeconds = options.timeoutSeconds ?? TOOL_EXEC_TIMEOUT_SECONDS;
     const limit = options.maxOutputChars ?? 20_000;
     const inFilesApi = (path) => path.startsWith(`${WORKSPACE}/`);
     return [

package/dist/transport.d.ts

@@ -1,17 +1,35 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.8.4";
+export declare const VERSION = "0.10.0";
 export declare 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
+ * on that host, whose addresses a sandbox cannot reach directly. Plain HTTP
+ * because the hop never leaves the machine: it goes from the program to the
+ * guest's own proxy and over the sandbox's private channel to its host. */
+export declare const SANDBOX_BASE_URL = "http://runtime.internal";
+/** True in a Runtime sandbox. Node and Bun only; a browser is never one. */
+export declare function inRuntimeSandbox(marker?: string): boolean;
+/** Where calls go when no base URL is given: RUNTIME_API_URL, then Runtime's
+ * public API, which `reachable` turns into runtime.internal in a sandbox. */
+export declare function defaultBaseUrl(env?: Record<string, string | undefined>, inSandbox?: typeof inRuntimeSandbox): string;
+/** The origin calls for `origin` are sent to from here. In a sandbox the
+ * public API is its own host, which it cannot reach directly, so calls for it
+ * go to runtime.internal; every other origin is left as it is. */
+export declare function reachable(origin: string, inSandbox?: typeof inRuntimeSandbox): string;
 export type RequestOptions = {
     /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps
      * it across its own retries, so a retried write never happens twice. Pass
      * your own only to retry a call yourself after the process restarted. */
     idempotencyKey?: string;
     signal?: AbortSignal;
-    /** Deadline for this call, retries included. */
+    /** Deadline for this call, retries included. 0 disables this deadline;
+     * an explicit signal can still cancel the call. */
     timeoutMs?: number;
 };
 export type Query = Record<string, string | number | boolean | readonly string[] | undefined>;
 export type Call = RequestOptions & {
+    /** Internal protocol hook: successful headers arrived, before reading the body. */
+    onResponse?: (response: Response) => void;
     method: "GET" | "POST" | "PUT" | "DELETE";
     path: string;
     query?: Query;
@@ -69,12 +87,9 @@ export declare class Transport {
     send(call: Call): Promise<Response>;
     json<T>(call: Call): Promise<T>;
     bytes(call: Call): Promise<Uint8Array>;
-    /** 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. */
+    /** 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. */
     fileBytes(call: Call): Promise<Uint8Array>;
     /** A file's bytes as they arrive, for files too big to hold. The stream
      * errors with `download_incomplete` if it ends short of the length the API