withruntime 0.10.0 → 0.11.1

package/dist/products/secrets.d.ts

@@ -4,7 +4,7 @@ import type { RequestOptions, Transport } from "../transport.js";
  * absent) and `paths`, each exact (`/v1/chat/completions`) or a prefix ending
  * in `/*` (`/repos/acme/*`), written canonically: starting with `/`, no `.` or
  * `..` segments, no `;` or `\`, no encoded slash. A request whose path could be
- * read two ways gets no secret that has rules. Paid accounts only. */
+ * read two ways gets no secret that has rules. Needs credit on the account. */
 export type SecretRule = {
     methods?: string[];
     paths: string[];
@@ -37,7 +37,7 @@ export type SetSecret = {
     header?: string;
     /** With `header`: its value, `{value}` where the secret goes. Default `{value}`. */
     format?: string;
-    /** Only requests a rule allows carry the value. Paid accounts only. 1 to 16.
+    /** Only requests a rule allows carry the value. Needs credit on the account. 1 to 16.
      * Absent: every request to the hosts; replacing a secret without rules
      * clears them. */
     rules?: SecretRule[];

package/dist/runloop/index.js

@@ -172,8 +172,12 @@ export class Devboxes {
             vcpu: p.custom_cpu_cores ?? size?.[0],
             memoryMiB: p.custom_gb_memory ? p.custom_gb_memory * 1024 : size?.[1],
             diskMiB: p.custom_disk_size ? p.custom_disk_size * 1024 : size?.[2],
-            timeoutSeconds: p.keep_alive_time_seconds ?? 3600,
-            idlePauseSeconds: 0,
+            // keep_alive_time_seconds is the customer's limit, with no idle pause
+            // before it. None is no time limit (0300): it runs while it works and
+            // pauses when idle.
+            ...(p.keep_alive_time_seconds === undefined || p.keep_alive_time_seconds === null
+                ? {}
+                : { timeoutSeconds: p.keep_alive_time_seconds, idlePauseSeconds: 0 }),
             onLeaseEnd: "stop",
         }, input.environment_variables ?? undefined, async (sandbox) => {
             for (const [path, content] of Object.entries(input.file_mounts ?? {})) {

package/dist/sandbox.d.ts

@@ -105,12 +105,15 @@ export declare class Sandbox implements AsyncDisposable {
      * lists. Its snapshots, usage and audit entries stay. Deleting it again
      * answers the same. */
     delete(options?: RequestOptions): Promise<DeletedSandbox>;
-    /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
+    /** Carries on a paused sandbox; for one with a time limit,
+     * `timeoutSeconds` is its new one. */
     wake(options?: RequestOptions & {
         wait?: boolean;
         timeoutSeconds?: number;
     }): Promise<this>;
-    /** More time before the lease ends (at most an hour ahead of now). */
+    /** More time before its time limit ends (at most an hour ahead of now). A
+     * sandbox with no time limit needs none: the call answers at once and
+     * changes nothing. */
     extend(seconds: number, options?: RequestOptions): Promise<this>;
     /** Changes its name, labels, automatic wake, idle pause or persistence;
      * fields left out stay as they are. `persistent: true` keeps it running
@@ -120,18 +123,36 @@ export declare class Sandbox implements AsyncDisposable {
      * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
      * volumes, environment, name and previews. Its processes restart, and
      * everything else on its old disk (sudo installs, apt packages, /etc) is
-     * lost, which `keep: "workspace"` says you know; snapshot it first to keep
-     * everything. A running sandbox is paused first. A switch that fails is
-     * undone (`switch_undone`), the sandbox on its old image with nothing lost.
-     * Charged as a wake. */
-    switchImage(image: string, options: RequestOptions & {
-        keep: "workspace";
+     * lost; snapshot it first to keep everything. A running sandbox is paused
+     * first. A switch that fails is undone (`switch_undone`), the sandbox on
+     * its old image with nothing lost. Charged as a wake. `keep` is optional:
+     * "workspace" is the only value, and it is sent either way, so an API from
+     * before it was optional accepts the call too. */
+    switchImage(image: string, options?: RequestOptions & {
+        keep?: "workspace";
     }): Promise<this>;
-    /** 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,
+    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
+     * whole disk, volumes, environment, name and previews stay, and its
+     * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
+     * persistent, and comes back running at the new size on the same server; a
+     * paused or stopped one is started. Memory bills on the new size from then.
+     * Refused, with nothing changed, when the server has no room
+     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
+     * while a snapshot or fork of it is being taken. `restart` is optional:
+     * true is the only value, and it is sent either way, so an API from before
+     * it was optional accepts the call too. */
+    resize(size: {
+        vcpu?: number;
+        memoryMiB?: number;
+    }, options?: RequestOptions & {
+        restart?: true;
+    }): Promise<this>;
+    /** Keeps a sandbox with a time limit running past it, in the background,
+     * until stop() or the returned function ends it: every `everySeconds` (60)
+     * it extends the limit so that `marginSeconds` (600) remain, never more
+     * than the hour ahead the API allows. A sandbox with no time limit
+     * (`endsAt` null) needs none, and is only watched. Running time is billed
+     * as it is used. 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?: KeepAliveOptions): () => void;
@@ -139,7 +160,9 @@ export declare class Sandbox implements AsyncDisposable {
     setRetention(days: number, options?: RequestOptions): Promise<this>;
     /** Keeps this sandbox's whole machine (files, memory, running processes) as
      * a snapshot to start new sandboxes from. A running sandbox is paused for
-     * the moment it takes, then woken; a paused one stays paused. */
+     * the moment it takes, then woken; a paused one stays paused. Past
+     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
+     * the error names the snapshot. */
     snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
     /** Copies of this sandbox as it is now (files, memory, running processes),
      * each its own sandbox, answered once they run. A running sandbox is paused
@@ -229,6 +252,13 @@ export declare class Process {
     info: ProcessInfo;
     constructor(t: Transport, sandboxId: string, info: ProcessInfo);
     get id(): string;
+    /** The command line as the sandbox reports it. */
+    get command(): string;
+    /** As of the last answer: spawn, `wait()` or `refresh()`. */
+    get state(): ProcessInfo["state"];
+    /** null while it runs, and when it was killed or timed out. */
+    get exitCode(): number | null;
+    toJSON(): ProcessInfo;
     /** Every output event from the start (or `cursor`) until exit. */
     output(options?: {
         cursor?: number;

package/dist/sandbox.js

@@ -1,10 +1,13 @@
 import { KEEP_ALIVE_MARGIN_SECONDS, STREAMED_EXEC_TIMEOUT_MS, WAIT_FOR_TIMEOUT_SECONDS, } from "./api-defaults.js";
-import { CommandError, ConnectionError, NotFoundError, RuntimeError } from "./errors.js";
+import { CommandError, ConnectionError, DELIBERATE, errorFor, NotFoundError, RateLimitError, RuntimeError, ServiceUnavailableError, } from "./errors.js";
 import { Page } from "./page.js";
 import { sandboxWatches, watchDirectory, } from "./products/watch.js";
 import { Transport } from "./transport.js";
 import { sandboxFactories } from "./products/index.js";
 import { Tunnel } from "./tunnel.js";
+import { pause } from "./wait.js";
+/** How long snapshot() waits, pause and capture together, unless told. */
+const SNAPSHOT_DEADLINE_MS = 10 * 60_000;
 const CHUNK = 1_048_576;
 /** Chunks of a large write in flight at once. Each chunk's reply waits on the
  * API and the guest, and the link idles while every chunk in flight waits:
@@ -380,7 +383,8 @@ export class Sandbox {
         this.#keepAlive?.();
         return deleteSandbox(this.#t, this.id, options);
     }
-    /** Carries on a paused sandbox; `timeoutSeconds` is its new lease. */
+    /** Carries on a paused sandbox; for one with a time limit,
+     * `timeoutSeconds` is its new one. */
     async wake(options = {}) {
         const { timeoutSeconds, ...rest } = options;
         try {
@@ -391,13 +395,15 @@ export class Sandbox {
             // lease asked for, the refusal stands: it was not given.
             if (!(error instanceof RuntimeError) || error.code !== "not_paused" || timeoutSeconds)
                 throw error;
-            await this.refresh(pick(rest));
+            await this.refresh(requestOnly(rest));
             if (this.state !== "running" && this.state !== "starting")
                 throw error;
             return this;
         }
     }
-    /** More time before the lease ends (at most an hour ahead of now). */
+    /** More time before its time limit ends (at most an hour ahead of now). A
+     * sandbox with no time limit needs none: the call answers at once and
+     * changes nothing. */
     async extend(seconds, options = {}) {
         return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
     }
@@ -411,27 +417,51 @@ export class Sandbox {
      * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
      * volumes, environment, name and previews. Its processes restart, and
      * everything else on its old disk (sudo installs, apt packages, /etc) is
-     * lost, which `keep: "workspace"` says you know; snapshot it first to keep
-     * everything. A running sandbox is paused first. A switch that fails is
-     * undone (`switch_undone`), the sandbox on its old image with nothing lost.
-     * Charged as a wake. */
-    async switchImage(image, options) {
-        const { keep, ...rest } = options;
+     * lost; snapshot it first to keep everything. A running sandbox is paused
+     * first. A switch that fails is undone (`switch_undone`), the sandbox on
+     * its old image with nothing lost. Charged as a wake. `keep` is optional:
+     * "workspace" is the only value, and it is sent either way, so an API from
+     * before it was optional accepts the call too. */
+    async switchImage(image, options = {}) {
+        const { keep = "workspace", ...rest } = options;
         this.#keep(await this.#t.json({
             method: "POST",
             path: `/v1/sandboxes/${enc(this.id)}:switch-image`,
             body: { image, keep },
             // A pause, two boots and the copy between them.
             wait: 120,
-            ...pick(rest),
+            ...requestOnly(rest),
         }));
         return this;
     }
-    /** 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,
+    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
+     * whole disk, volumes, environment, name and previews stay, and its
+     * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
+     * persistent, and comes back running at the new size on the same server; a
+     * paused or stopped one is started. Memory bills on the new size from then.
+     * Refused, with nothing changed, when the server has no room
+     * (`no_capacity`), above your quota or the trial's 2 vCPU and 4 GiB, or
+     * while a snapshot or fork of it is being taken. `restart` is optional:
+     * true is the only value, and it is sent either way, so an API from before
+     * it was optional accepts the call too. */
+    async resize(size, options = {}) {
+        const { restart = true, ...rest } = options;
+        this.#keep(await this.#t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(this.id)}:resize`,
+            body: { ...size, restart },
+            // A pause or stop and a cold boot.
+            wait: 120,
+            ...requestOnly(rest),
+        }));
+        return this;
+    }
+    /** Keeps a sandbox with a time limit running past it, in the background,
+     * until stop() or the returned function ends it: every `everySeconds` (60)
+     * it extends the limit so that `marginSeconds` (600) remain, never more
+     * than the hour ahead the API allows. A sandbox with no time limit
+     * (`endsAt` null) needs none, and is only watched. Running time is billed
+     * as it is used. 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 = {}) {
@@ -454,8 +484,9 @@ export class Sandbox {
                 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;
+                // No time limit: nothing to extend (an older server sends no endsAt).
+                if (this.state === "running" && this.info.endsAt !== null) {
+                    const left = (Date.parse(this.info.endsAt ?? this.info.expiresAt) - Date.now()) / 1000;
                     const need = Math.ceil(margin - left);
                     if (need >= 1)
                         await this.extend(Math.min(3600, need));
@@ -479,16 +510,34 @@ export class Sandbox {
     }
     /** Keeps this sandbox's whole machine (files, memory, running processes) as
      * a snapshot to start new sandboxes from. A running sandbox is paused for
-     * the moment it takes, then woken; a paused one stays paused. */
+     * the moment it takes, then woken; a paused one stays paused. Past
+     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
+     * the error names the snapshot. */
     async snapshot(options = {}) {
         const { idempotencyKey, signal, timeoutMs, ...body } = options;
         if (body.mode !== undefined && body.mode !== "memory" && body.mode !== "disk")
             throw new TypeError("Snapshot mode must be memory or disk.");
         signal?.throwIfAborted();
-        const until = performance.now() + Math.min(timeoutMs && timeoutMs > 0 ? timeoutMs : 60_000, 60_000);
+        // One minute, whatever `timeoutMs` said, was too short: pausing a busy
+        // 16 vCPU, 32 GiB sandbox writes its memory out first (4 October 2026).
+        const until = performance.now() + (timeoutMs && timeoutMs > 0 ? timeoutMs : SNAPSHOT_DEADLINE_MS);
+        let running = false;
+        /** The capture in progress, once the server has one. */
+        let capturing;
+        let late = false;
         const request = () => {
             signal?.throwIfAborted();
             const left = Math.ceil(until - performance.now());
+            if (left <= 0 && capturing) {
+                late = true;
+                throw new RuntimeError({
+                    code: "snapshot_timeout",
+                    status: 0,
+                    message: `Snapshot ${capturing} was still capturing at the deadline.${running ? " The sandbox stays paused until it ends: waking it now would fail the capture." : ""}`,
+                    hint: `Wait until runtime.snapshots.get("${capturing}") is ready${running ? ", then wake the sandbox" : ""}, or pass a longer timeoutMs.`,
+                    details: { snapshotId: capturing, sourceSandboxId: this.id },
+                });
+            }
             if (left <= 0)
                 throw new RuntimeError({
                     code: "snapshot_timeout",
@@ -505,7 +554,7 @@ export class Sandbox {
             await this.waitFor("running", request());
         else if (this.state === "pausing")
             await this.waitFor("paused", request());
-        const running = this.state === "running";
+        running = this.state === "running";
         // Check before entering cleanup: an abort during refresh must not pause or wake.
         const pauseOptions = running ? request() : undefined;
         let captured;
@@ -526,14 +575,8 @@ export class Sandbox {
             // Prefer: wait is bounded on the server. A capture still in progress
             // must keep its source paused, or the worker refuses it after we wake.
             while (snapshot.state === "capturing") {
-                signal?.throwIfAborted();
-                if (performance.now() >= until)
-                    throw new RuntimeError({
-                        code: "snapshot_timeout",
-                        status: 0,
-                        message: "Snapshot capture did not finish within one minute.",
-                        details: { snapshotId: snapshot.id },
-                    });
+                capturing = snapshot.id;
+                request();
                 await new Promise((resolve) => setTimeout(resolve, 200));
                 snapshot = await this.#t.json({
                     method: "GET",
@@ -560,8 +603,13 @@ export class Sandbox {
         catch (error) {
             failed = true;
             primary = error;
+            // A request cut off by the deadline mid-capture is late all the same.
+            if (capturing && performance.now() >= until)
+                late = true;
         }
-        if (running) {
+        // A capture still running needs its source paused: the worker fails one
+        // whose source woke. The timeout says so and leaves the wake to the caller.
+        if (running && !late) {
             try {
                 await this.wake();
             }
@@ -596,11 +644,7 @@ export class Sandbox {
             path: `/v1/sandboxes/${enc(this.id)}:fork`,
             body,
             wait: 60,
-            ...pick({
-                ...(idempotencyKey ? { idempotencyKey } : {}),
-                ...(signal ? { signal } : {}),
-                ...(timeoutMs ? { timeoutMs } : {}),
-            }),
+            ...requestOnly({ idempotencyKey, signal, timeoutMs }),
         });
         const sandboxes = reply.sandboxes.map((info) => new Sandbox(this.#t, info));
         return options.count === undefined ? sandboxes[0] : sandboxes;
@@ -615,7 +659,7 @@ export class Sandbox {
             path: `/v1/sandboxes/${enc(this.id)}:${verb}`,
             body,
             wait: options.wait === false ? 0 : 60,
-            ...pick(options),
+            ...requestOnly(options),
         }));
         return this;
     }
@@ -639,13 +683,10 @@ class OutputCursor {
         this.cursor = cursor;
     }
     *pass(event) {
+        // As the status the API would have answered it, so a passing failure (a
+        // host restarting) is followed again rather than ending the read.
         if (event.type === "error")
-            throw new RuntimeError({
-                message: event.error.message,
-                code: event.error.code,
-                status: 0,
-                ...(event.error.requestId ? { requestId: event.error.requestId } : {}),
-            });
+            throw errorFor(event.error.status ?? 0, event);
         if (event.type === "truncated")
             this.cursor = Math.max(this.cursor, event.resumeAt);
         if (event.type === "stdout" || event.type === "stderr") {
@@ -676,11 +717,20 @@ function processBytes(encoded) {
         });
     }
 }
-/** A stream cut off by the network rather than refused by Runtime: worth
- * reconnecting to from the cursor. */
+/** A stream cut off by the network, or refused by a failure that passes by
+ * itself (a busy API, a 429, a host restarting), rather than refused for good:
+ * worth reconnecting to from the cursor. */
 function cutOff(error) {
-    return !(error instanceof RuntimeError) || error instanceof ConnectionError;
+    return (!(error instanceof RuntimeError) ||
+        error instanceof ConnectionError ||
+        ((error instanceof RateLimitError || error instanceof ServiceUnavailableError) &&
+            [429, 502, 503, 504].includes(error.status) &&
+            !DELIBERATE.has(error.code)));
 }
+/** How long a follow keeps reconnecting while every attempt fails. A command
+ * runs for hours whether or not anyone reads it; a few minutes of a deploy, a
+ * network blip or a busy API must not end the read of it. */
+const FOLLOW_OUTAGE_MS = 300_000;
 /** 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
@@ -688,6 +738,8 @@ function cutOff(error) {
 function truncation(dropped) {
     return { stdoutTruncated: dropped, stderrTruncated: dropped };
 }
+/** A command's request options: its `timeoutMs` is the command's own limit
+ * in the guest, so the call is given a minute more for the answer. */
 function pick(options) {
     return {
         ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
@@ -695,6 +747,15 @@ function pick(options) {
         ...(options.timeoutMs ? { timeoutMs: options.timeoutMs + 60_000 } : {}),
     };
 }
+/** Any other call's request options, as the caller gave them: `timeoutMs` is
+ * the call's whole deadline, and 0 turns it off. */
+function requestOnly(options) {
+    return {
+        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    };
+}
 /** Sessions: a token your backend makes and hands to your own frontend, which
  * then runs commands, reads and writes files and reaches previews in this one
  * sandbox directly, without proxying through your servers. A session cannot
@@ -783,12 +844,19 @@ export class Processes {
     /** Output events from `cursor` until the process exits, across stream slices. */
     async *follow(processId, options = {}) {
         const read = new OutputCursor(options.cursor ?? 0);
-        // Reconnections in a row that brought nothing: a stream that keeps
-        // closing without output or an exit is given up, not followed forever.
+        // Reconnections in a row that closed cleanly with nothing: a stream that
+        // keeps closing without output or an exit is given up, not followed
+        // forever.
         let idle = 0;
+        // Since when every reconnection has failed (a cut, a busy API, a host
+        // restarting). The command runs on regardless, so these are waited out
+        // for FOLLOW_OUTAGE_MS, with backoff, before the follow gives up.
+        let failingSince;
+        let failures = 0;
         for (;;) {
             const before = read.cursor;
             let resumed = false;
+            let failure;
             try {
                 for await (const event of this.t.events({
                     method: "GET",
@@ -810,8 +878,28 @@ export class Processes {
             catch (error) {
                 if (options.signal?.aborted || !cutOff(error))
                     throw error;
+                failure = error;
+            }
+            if (resumed || read.cursor > before) {
+                idle = failures = 0;
+                failingSince = undefined;
+                continue;
+            }
+            if (failure === undefined)
+                idle++;
+            else {
+                failingSince ??= performance.now();
+                if (performance.now() - failingSince >= FOLLOW_OUTAGE_MS)
+                    throw new ConnectionError({
+                        message: `Lost the output stream of process ${processId} for ${FOLLOW_OUTAGE_MS / 60_000} minutes; the command may still be running.`,
+                        code: "connection_error",
+                        status: 0,
+                        hint: `Follow it again: runtime sandbox logs ${this.sandboxId} ${processId} -f`,
+                        details: { sandboxId: this.sandboxId, processId },
+                        cause: failure,
+                    });
+                await pause(Math.min(5000, 50 * 2 ** failures++), options.signal);
             }
-            idle = resumed || read.cursor > before ? 0 : idle + 1;
             if (idle > 3)
                 throw new ConnectionError({
                     message: `The output stream of process ${processId} keeps closing before it ends.`,
@@ -839,6 +927,26 @@ export class Process {
     get id() {
         return this.info.id;
     }
+    /** The command line as the sandbox reports it. */
+    get command() {
+        return this.info.command;
+    }
+    /** As of the last answer: spawn, `wait()` or `refresh()`. */
+    get state() {
+        return this.info.state;
+    }
+    /** null while it runs, and when it was killed or timed out. */
+    get exitCode() {
+        return this.info.exitCode;
+    }
+    toJSON() {
+        return this.info;
+    }
+    /** console.log shows what the process is, not the client inside it. */
+    [Symbol.for("nodejs.util.inspect.custom")](_depth, options, show) {
+        const { id, sandboxId, command, state, exitCode } = this;
+        return `Process ${show({ id, sandboxId, command, state, exitCode }, options)}`;
+    }
     /** Every output event from the start (or `cursor`) until exit. */
     output(options = {}) {
         return new Processes(this.t, this.sandboxId).follow(this.id, options);
@@ -884,6 +992,12 @@ export class Process {
             if (event.type === "exit")
                 exit = event;
         }
+        if (exit)
+            this.info = {
+                ...this.info,
+                state: exit.state,
+                exitCode: exit.exitCode,
+            };
         return {
             exitCode: exit?.exitCode ?? null,
             ...out,

package/dist/tar.d.ts

@@ -1,3 +1,5 @@
+/** One entry's header: the ustar block, after the long-name and long-link
+ * entries it needs. A whole number of 512-byte blocks. */
 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 a gzipped tar that arrives as a stream into `target`, refusing any

package/dist/tar.js

@@ -1,25 +1,35 @@
-import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
+import { chmod, copyFile, link as hardLink, 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 { 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. */
-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();
-    let short = bytes;
-    if (bytes.length > 100) {
-        const split = name.lastIndexOf("/", 155);
-        if (split <= 0 || new TextEncoder().encode(name.slice(split + 1)).length > 100)
-            throw new Error(`Path too long for a tar archive: ${name}`);
-        prefix = new TextEncoder().encode(name.slice(0, split));
-        short = new TextEncoder().encode(name.slice(split + 1));
+/* A small tar writer and reader for directory uploads and downloads, so the
+   SDK needs no dependency. Regular files, directories, symbolic links and,
+   reading, hard links. A name that does not fit the ustar name and prefix
+   fields, or a link target longer than 100 bytes, travels in a GNU long-name
+   or long-link entry, which GNU tar, BusyBox tar and every SDK's reader
+   take; nothing is cut short. */
+const encode = (value) => new TextEncoder().encode(value);
+/** The ustar prefix and name of `name`, split at a slash so that each fits
+ * its field in bytes, or null when no split fits. */
+function ustarName(name) {
+    const bytes = encode(name);
+    if (bytes.length <= 100)
+        return { prefix: new Uint8Array(), short: bytes };
+    for (let split = name.lastIndexOf("/"); split > 0; split = name.lastIndexOf("/", split - 1)) {
+        const prefix = encode(name.slice(0, split));
+        const short = encode(name.slice(split + 1));
+        if (short.length > 100)
+            return null;
+        if (prefix.length <= 155)
+            return { prefix, short };
     }
+    return null;
+}
+function headerBlock(short, prefix, size, mode, type, link, mtime) {
+    const block = new Uint8Array(512);
     const put = (offset, value, length) => {
-        const data = typeof value === "string" ? new TextEncoder().encode(value) : value;
+        const data = typeof value === "string" ? encode(value) : value;
         block.set(data.subarray(0, length), offset);
     };
     const octal = (value, length) => value.toString(8).padStart(length - 1, "0") + "\0";
@@ -40,6 +50,29 @@ export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
     put(148, sum.toString(8).padStart(6, "0") + "\0 ", 8);
     return block;
 }
+/** A GNU long-name ("L") or long-link ("K") entry carrying `value`. */
+function longEntry(type, value) {
+    const size = value.length + 1;
+    const out = new Uint8Array(512 + Math.ceil(size / 512) * 512);
+    out.set(headerBlock(encode("././@LongLink"), new Uint8Array(), size, 0o644, type, new Uint8Array(), 0));
+    out.set(value, 512);
+    return out;
+}
+/** One entry's header: the ustar block, after the long-name and long-link
+ * entries it needs. A whole number of 512-byte blocks. */
+export function tarHeader(name, size, mode, type, link = "", mtime = 0) {
+    const parts = [];
+    let fitted = ustarName(name);
+    if (!fitted) {
+        parts.push(longEntry("L", encode(name)));
+        fitted = { prefix: new Uint8Array(), short: encode(name).subarray(0, 100) };
+    }
+    const target = encode(link);
+    if (target.length > 100)
+        parts.push(longEntry("K", target));
+    parts.push(headerBlock(fitted.short, fitted.prefix, size, mode, type, target, mtime));
+    return parts.length === 1 ? parts[0] : new Uint8Array(Buffer.concat(parts));
+}
 export async function packDirectory(root) {
     const parts = [];
     const base = resolve(root);
@@ -352,8 +385,15 @@ async function unpackEntries(bytes, root, signal) {
             links.push({ destination, link, name });
             await skip();
         }
+        else if (type === "1") {
+            await hardLinkEntry(root, destination, link, name);
+            await skip();
+        }
         else if (type === "0" || type === "\0" || type === "7") {
             await mkdir(dirname(destination), { recursive: true });
+            // A name already unpacked may share its file with a hard link; writing
+            // through it would change the link's copy too.
+            await unlink(destination).catch(() => undefined);
             const file = await open(destination, "w");
             try {
                 for await (const part of bytes.take(size)) {
@@ -378,6 +418,24 @@ async function unpackEntries(bytes, root, signal) {
             await skip();
     }
 }
+/** A second name for a file the archive already carried: tar writes the
+ * first name as a file and every other as a hard link to it. The link names
+ * a plain file unpacked earlier in this archive, or the unpack fails; it
+ * never reaches outside, through a link or ahead. */
+async function hardLinkEntry(root, destination, link, name) {
+    const named = link.replace(/^(\.\/)+/, "");
+    const source = resolve(root, named);
+    if (!named || isAbsolute(named) || source === root || !source.startsWith(root + sep))
+        throw new Error(`Refusing an archive hard link that leads outside the target: ${name} -> ${link}`);
+    await assertPlain(root, source, named);
+    if (!(await lstat(source).catch(() => undefined))?.isFile())
+        throw new Error(`Refusing an archive hard link to a file it does not carry: ${name} -> ${link}`);
+    if (source === destination)
+        return;
+    await mkdir(dirname(destination), { recursive: true });
+    await unlink(destination).catch(() => undefined);
+    await hardLink(source, destination).catch(() => copyFile(source, destination));
+}
 /** 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) {