@hyperbrowser/sdk 0.93.0 → 1.0.0

package/dist/sandbox/files.js

@@ -3,12 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxFilesApi = exports.SandboxWatchDirHandle = void 0;
+exports.SandboxFilesApi = exports.SandboxWatchDirHandle = exports.SandboxFileWatchHandle = void 0;
 const buffer_1 = require("buffer");
 const path_1 = __importDefault(require("path"));
 const web_1 = require("node:stream/web");
 const ws_1 = __importDefault(require("ws"));
-const client_1 = require("../client");
+const stream_1 = require("stream");
+const error_1 = require("../error");
 const ws_2 = require("./ws");
 const normalizeFileType = (value) => {
     if (!value) {
@@ -123,12 +124,13 @@ const encodeWriteData = async (data, encoding) => {
     }
     throw new Error("Unsupported write data type");
 };
-class RuntimeFileWatchHandle {
+class SandboxFileWatchHandle {
     constructor(transport, getConnectionInfo, status, runtimeProxyOverride) {
         this.transport = transport;
         this.getConnectionInfo = getConnectionInfo;
         this.status = status;
         this.runtimeProxyOverride = runtimeProxyOverride;
+        this.connections = new Set();
     }
     get id() {
         return this.status.id;
@@ -136,27 +138,66 @@ class RuntimeFileWatchHandle {
     get path() {
         return this.status.path;
     }
-    async stop() {
-        await this.transport.requestJSON(`/sandbox/files/watch/${this.status.id}`, {
-            method: "DELETE",
-        });
+    get current() {
+        return this.toJSON();
+    }
+    toJSON() {
+        return {
+            ...this.status,
+            ...(this.status.events ? { events: this.status.events.map((event) => ({ ...event })) } : {}),
+        };
+    }
+    async refresh(includeEvents = false) {
+        const response = await this.transport.requestJSON(`/sandbox/files/watch/${encodeURIComponent(this.id)}`, undefined, includeEvents ? { includeEvents: true } : undefined);
+        this.status = response.watch;
+        return this;
     }
-    async *events(cursor) {
+    async stop() {
+        try {
+            await this.transport.requestJSON(`/sandbox/files/watch/${encodeURIComponent(this.id)}`, {
+                method: "DELETE",
+            });
+        }
+        catch (error) {
+            if (!(error instanceof error_1.HyperbrowserError) || ![404, 409].includes(error.statusCode ?? 0))
+                throw error;
+        }
+        this.status = { ...this.status, active: false, stoppedAt: this.status.stoppedAt || Date.now() };
+        for (const socket of this.connections)
+            socket.terminate();
+    }
+    async *events(options = {}) {
+        const { cursor, route = "ws", signal } = options;
+        if (route !== "ws" && route !== "stream")
+            throw new error_1.HyperbrowserError("Watch route must be ws or stream");
+        if (signal?.aborted)
+            throw new error_1.HyperbrowserError("Watch canceled", {
+                code: "request_aborted",
+                service: "runtime",
+            });
         const connectionInfo = await this.getConnectionInfo();
-        const target = (0, ws_2.toWebSocketUrl)(connectionInfo.baseUrl, `/sandbox/files/watch/${this.status.id}/ws?sessionId=${encodeURIComponent(connectionInfo.sandboxId)}${cursor !== undefined ? `&cursor=${encodeURIComponent(String(cursor))}` : ""}`, this.runtimeProxyOverride);
+        const target = (0, ws_2.toWebSocketUrl)(connectionInfo.baseUrl, `/sandbox/files/watch/${encodeURIComponent(this.status.id)}/${route}?sessionId=${encodeURIComponent(connectionInfo.sandboxId)}${cursor !== undefined ? `&cursor=${encodeURIComponent(String(cursor))}` : ""}`, this.runtimeProxyOverride);
         const headers = {
             Authorization: `Bearer ${connectionInfo.token}`,
         };
         if (target.hostHeader) {
             headers.Host = target.hostHeader;
         }
-        const ws = await (0, ws_2.openRuntimeWebSocket)(target, headers);
+        const ws = await (0, ws_2.openRuntimeWebSocket)(target, headers, { signal });
+        this.connections.add(ws);
         const queue = new ws_2.AsyncEventQueue();
+        const abort = () => {
+            queue.fail(new error_1.HyperbrowserError("Watch canceled", { code: "request_aborted", service: "runtime" }));
+            ws.terminate();
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
         ws.on("message", (data) => {
             try {
                 const parsed = JSON.parse(data.toString());
                 if ("error" in parsed) {
-                    queue.fail(new client_1.HyperbrowserError(parsed.error, {
+                    queue.fail(new error_1.HyperbrowserError(parsed.error, {
                         statusCode: 410,
                         code: parsed.code,
                         retryable: false,
@@ -165,9 +206,17 @@ class RuntimeFileWatchHandle {
                     return;
                 }
                 if (parsed.type === "event") {
-                    queue.push(parsed.event);
+                    this.status = {
+                        ...this.status,
+                        // Receiver sequences start at 1; zero denotes an empty buffer.
+                        oldestSeq: this.status.oldestSeq || parsed.event.seq,
+                        lastSeq: Math.max(this.status.lastSeq ?? 0, parsed.event.seq),
+                    };
+                    queue.push(parsed);
                     return;
                 }
+                this.status = parsed.status;
+                queue.push({ type: "done", status: this.current });
                 queue.close();
             }
             catch (error) {
@@ -176,34 +225,38 @@ class RuntimeFileWatchHandle {
         });
         ws.on("close", () => queue.close());
         ws.on("error", (error) => queue.fail(error));
+        ws.resume?.();
         try {
             for await (const event of queue) {
                 yield event;
             }
         }
         finally {
-            if (ws.readyState !== ws_1.default.CLOSING && ws.readyState !== ws_1.default.CLOSED) {
-                await new Promise((resolve) => {
-                    ws.once("close", () => resolve());
-                    ws.close();
-                });
-            }
+            signal?.removeEventListener("abort", abort);
+            this.connections.delete(ws);
+            // terminate also releases peers which never acknowledge a close frame.
+            if (ws.readyState !== ws_1.default.CLOSED)
+                ws.terminate();
         }
     }
 }
+exports.SandboxFileWatchHandle = SandboxFileWatchHandle;
 class SandboxWatchDirHandle {
     constructor(watch, onEvent, onExit, timeoutMs) {
         this.watch = watch;
         this.onExit = onExit;
         this.stopRequested = false;
         this.exitNotified = false;
+        this.invokingCallback = false;
         if (timeoutMs !== undefined && timeoutMs > 0) {
             this.timeout = setTimeout(() => {
-                void this.stop();
+                void this.stop().catch(() => undefined);
             }, timeoutMs);
             this.timeout.unref?.();
         }
         this.runPromise = this.run(onEvent);
+        // Callback failures must not become unhandled background rejections.
+        this.runPromise.catch(() => undefined);
     }
     async stop() {
         if (this.stopRequested) {
@@ -215,20 +268,27 @@ class SandboxWatchDirHandle {
             this.timeout = undefined;
         }
         await this.watch.stop();
-        await this.runPromise.catch(() => undefined);
+        if (!this.invokingCallback)
+            await this.runPromise.catch(() => undefined);
     }
     async run(onEvent) {
         let exitError;
         try {
-            for await (const event of this.watch.events()) {
+            for await (const message of this.watch.events()) {
+                if (message.type === "done")
+                    break;
+                const event = message.event;
                 const type = normalizeEventType(event.op);
                 if (!type) {
                     continue;
                 }
-                await onEvent({
-                    type,
-                    name: relativeWatchName(this.watch.path, event.path),
-                });
+                this.invokingCallback = true;
+                try {
+                    await onEvent({ type, name: relativeWatchName(this.watch.path, event.path) });
+                }
+                finally {
+                    this.invokingCallback = false;
+                }
             }
         }
         catch (error) {
@@ -241,7 +301,13 @@ class SandboxWatchDirHandle {
             }
             if (!this.exitNotified) {
                 this.exitNotified = true;
-                await this.onExit?.(exitError);
+                this.invokingCallback = true;
+                try {
+                    await this.onExit?.(exitError);
+                }
+                finally {
+                    this.invokingCallback = false;
+                }
             }
         }
     }
@@ -264,7 +330,7 @@ class SandboxFilesApi {
             return true;
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError && error.statusCode === 404) {
+            if (error instanceof error_1.HyperbrowserError && error.statusCode === 404) {
                 return false;
             }
             if (error instanceof Error && /not found|no such file|does not exist/i.test(error.message)) {
@@ -381,12 +447,13 @@ class SandboxFilesApi {
         });
         return Boolean(response.created);
     }
-    async rename(oldPath, newPath) {
+    async rename(oldPath, newPath, options = {}) {
         const response = await this.transport.requestJSON("/sandbox/files/move", {
             method: "POST",
             body: this.withRunAsBody({
                 from: oldPath,
                 to: newPath,
+                overwrite: options.overwrite,
             }),
             headers: {
                 "content-type": "application/json",
@@ -440,18 +507,60 @@ class SandboxFilesApi {
         });
     }
     async watchDir(path, onEvent, options = {}) {
+        const watch = await this.watch(path, options);
+        return new SandboxWatchDirHandle(watch, onEvent, options.onExit, options.timeoutMs);
+    }
+    async watch(path, options = {}) {
         const response = await this.transport.requestJSON("/sandbox/files/watch", {
             method: "POST",
-            body: this.withRunAsBody({
-                path,
-                recursive: options.recursive,
-            }),
-            headers: {
-                "content-type": "application/json",
-            },
+            body: this.withRunAsBody({ path, recursive: options.recursive }),
+            headers: { "content-type": "application/json" },
         });
-        const watch = new RuntimeFileWatchHandle(this.transport, this.getConnectionInfo, response.watch, this.runtimeProxyOverride);
-        return new SandboxWatchDirHandle(watch, onEvent, options.onExit, options.timeoutMs);
+        return new SandboxFileWatchHandle(this.transport, this.getConnectionInfo, response.watch, this.runtimeProxyOverride);
+    }
+    async getWatch(id, includeEvents = false) {
+        const response = await this.transport.requestJSON(`/sandbox/files/watch/${encodeURIComponent(id)}`, undefined, includeEvents ? { includeEvents: true } : undefined);
+        return new SandboxFileWatchHandle(this.transport, this.getConnectionInfo, response.watch, this.runtimeProxyOverride);
+    }
+    stat(path) {
+        return this.getInfo(path);
+    }
+    mkdir(path, options = {}) {
+        return this.makeDir(path, options);
+    }
+    move(params) {
+        return this.rename(params.source, params.destination, params);
+    }
+    delete(path, options = {}) {
+        return this.remove(path, options);
+    }
+    /** Upload without buffering; the source is closed on completion, rejection or cancellation. */
+    async uploadStream(path, source, options = {}) {
+        if (options.contentLength !== undefined &&
+            (!Number.isSafeInteger(options.contentLength) || options.contentLength < 0)) {
+            throw new error_1.HyperbrowserError("contentLength must be a nonnegative safe integer");
+        }
+        const body = stream_1.Readable.from(source, { objectMode: false, highWaterMark: 64 * 1024 });
+        try {
+            return await this.transport.requestJSON("/sandbox/files/upload", {
+                method: "PUT",
+                body,
+                signal: options.signal,
+                headers: {
+                    "content-type": "application/octet-stream",
+                    ...(options.contentLength !== undefined
+                        ? { "content-length": String(options.contentLength) }
+                        : {}),
+                },
+            }, this.withRunAsQuery({ path }));
+        }
+        finally {
+            body.destroy();
+        }
+    }
+    /** Pull-based download; consume with for-await or Readable.from(). */
+    downloadStream(path, options = {}) {
+        return this.transport.streamBytes("/sandbox/files/download", { signal: options.signal }, this.withRunAsQuery({ path }));
     }
     async uploadUrl(path, options = {}) {
         return this.transport.requestJSON("/sandbox/files/presign-upload", {

package/dist/sandbox/image-build/artifacts.d.ts

@@ -0,0 +1,16 @@
+import { SandboxImageBuildInputFormat, SandboxImageInit } from "../../types/sandbox";
+export declare const IMAGE_BUILD_INPUT_FORMAT: SandboxImageBuildInputFormat;
+export declare const CONTEXT_MANIFEST_INPUT_FORMAT: SandboxImageBuildInputFormat;
+export declare const DOCKER_IMAGE_MANIFEST_INPUT_FORMAT: SandboxImageBuildInputFormat;
+export declare const IMAGE_BUILD_SOURCE_PLATFORM = "linux/amd64";
+export interface DockerImageBuildArtifact {
+    path: string;
+    sha256Hex: string;
+    sizeBytes: number;
+    inputFormat: SandboxImageBuildInputFormat;
+    sourcePlatform: string;
+    imageConfigUser: string;
+    imageInit?: SandboxImageInit;
+}
+export declare const removeArtifact: (artifact: DockerImageBuildArtifact) => void;
+export declare const removeWorkspace: (workspace: string) => void;

package/dist/sandbox/image-build/artifacts.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeWorkspace = exports.removeArtifact = exports.IMAGE_BUILD_SOURCE_PLATFORM = exports.DOCKER_IMAGE_MANIFEST_INPUT_FORMAT = exports.CONTEXT_MANIFEST_INPUT_FORMAT = exports.IMAGE_BUILD_INPUT_FORMAT = void 0;
+const fs_1 = require("fs");
+exports.IMAGE_BUILD_INPUT_FORMAT = "rootfs_export_tar_gz";
+exports.CONTEXT_MANIFEST_INPUT_FORMAT = "dockerfile_context_manifest_v1";
+exports.DOCKER_IMAGE_MANIFEST_INPUT_FORMAT = "docker_image_manifest_v1";
+exports.IMAGE_BUILD_SOURCE_PLATFORM = "linux/amd64";
+const removeArtifact = (artifact) => {
+    (0, fs_1.rmSync)(artifact.path, { force: true });
+};
+exports.removeArtifact = removeArtifact;
+const removeWorkspace = (workspace) => {
+    (0, fs_1.rmSync)(workspace, { recursive: true, force: true });
+};
+exports.removeWorkspace = removeWorkspace;

package/dist/sandbox/image-build/blake2b.d.ts

@@ -0,0 +1,2 @@
+/** Minimal BLAKE2b (RFC 7693) supporting arbitrary digest lengths. */
+export declare const blake2b: (data: Buffer, digestSize: number) => Buffer;

package/dist/sandbox/image-build/blake2b.js

@@ -0,0 +1,89 @@
+"use strict";
+/** Minimal BLAKE2b (RFC 7693) supporting arbitrary digest lengths. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blake2b = void 0;
+const IV = [
+    0x6a09e667f3bcc908n,
+    0xbb67ae8584caa73bn,
+    0x3c6ef372fe94f82bn,
+    0xa54ff53a5f1d36f1n,
+    0x510e527fade682d1n,
+    0x9b05688c2b3e6c1fn,
+    0x1f83d9abfb41bd6bn,
+    0x5be0cd19137e2179n,
+];
+const SIGMA = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+    [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+    [11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4],
+    [7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8],
+    [9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13],
+    [2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9],
+    [12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11],
+    [13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10],
+    [6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5],
+    [10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0],
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+    [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+];
+const MASK = (1n << 64n) - 1n;
+const rotr = (value, bits) => ((value >> bits) | (value << (64n - bits))) & MASK;
+const compress = (h, block, counter, last) => {
+    const m = [];
+    for (let index = 0; index < 16; index += 1) {
+        m.push(block.readBigUInt64LE(index * 8));
+    }
+    const v = [...h, ...IV];
+    v[12] ^= counter & MASK;
+    v[13] ^= (counter >> 64n) & MASK;
+    if (last) {
+        v[14] ^= MASK;
+    }
+    const mix = (a, b, c, d, x, y) => {
+        v[a] = (v[a] + v[b] + x) & MASK;
+        v[d] = rotr(v[d] ^ v[a], 32n);
+        v[c] = (v[c] + v[d]) & MASK;
+        v[b] = rotr(v[b] ^ v[c], 24n);
+        v[a] = (v[a] + v[b] + y) & MASK;
+        v[d] = rotr(v[d] ^ v[a], 16n);
+        v[c] = (v[c] + v[d]) & MASK;
+        v[b] = rotr(v[b] ^ v[c], 63n);
+    };
+    for (let round = 0; round < 12; round += 1) {
+        const s = SIGMA[round];
+        mix(0, 4, 8, 12, m[s[0]], m[s[1]]);
+        mix(1, 5, 9, 13, m[s[2]], m[s[3]]);
+        mix(2, 6, 10, 14, m[s[4]], m[s[5]]);
+        mix(3, 7, 11, 15, m[s[6]], m[s[7]]);
+        mix(0, 5, 10, 15, m[s[8]], m[s[9]]);
+        mix(1, 6, 11, 12, m[s[10]], m[s[11]]);
+        mix(2, 7, 8, 13, m[s[12]], m[s[13]]);
+        mix(3, 4, 9, 14, m[s[14]], m[s[15]]);
+    }
+    for (let index = 0; index < 8; index += 1) {
+        h[index] = h[index] ^ v[index] ^ v[index + 8];
+    }
+};
+const blake2b = (data, digestSize) => {
+    if (!Number.isInteger(digestSize) || digestSize < 1 || digestSize > 64) {
+        throw new RangeError("digestSize must be between 1 and 64");
+    }
+    const h = [...IV];
+    h[0] ^= BigInt(0x01010000 ^ digestSize);
+    let offset = 0;
+    let counter = 0n;
+    while (data.length - offset > 128) {
+        counter += 128n;
+        compress(h, data.subarray(offset, offset + 128), counter, false);
+        offset += 128;
+    }
+    const remaining = data.subarray(offset);
+    const block = Buffer.alloc(128);
+    remaining.copy(block);
+    counter += BigInt(remaining.length);
+    compress(h, block, counter, true);
+    const out = Buffer.alloc(64);
+    h.forEach((word, index) => out.writeBigUInt64LE(word, index * 8));
+    return out.subarray(0, digestSize);
+};
+exports.blake2b = blake2b;

package/dist/sandbox/image-build/common.d.ts

@@ -0,0 +1,19 @@
+/** Python `posixpath.normpath` semantics (keeps exactly two leading slashes). */
+export declare const posixNormpath: (value: string) => string;
+export declare const posixDirname: (value: string) => string;
+export declare const posixJoin: (...parts: string[]) => string;
+/** Compare strings by Unicode code point, like Python's default `str` ordering. */
+export declare const compareCodePoints: (a: string, b: string) => number;
+/**
+ * Compact JSON matching Python `json.dumps(value, separators=(",", ":"))`.
+ * `sortKeys` mirrors `sort_keys=True`; `ensureAscii` mirrors the default
+ * `ensure_ascii=True` escaping of non-ASCII characters.
+ */
+export declare const compactJson: (value: unknown, options?: {
+    sortKeys?: boolean;
+    ensureAscii?: boolean;
+}) => string;
+export declare const SHA256_HEX_PATTERN: RegExp;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const requireRecord: (value: unknown, label: string) => Record<string, unknown>;
+export declare const sleep: (seconds: number) => Promise<void>;

package/dist/sandbox/image-build/common.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = exports.requireRecord = exports.isRecord = exports.SHA256_HEX_PATTERN = exports.compactJson = exports.compareCodePoints = exports.posixJoin = exports.posixDirname = exports.posixNormpath = void 0;
+/** Python `posixpath.normpath` semantics (keeps exactly two leading slashes). */
+const posixNormpath = (value) => {
+    if (value === "") {
+        return ".";
+    }
+    let initialSlashes = value.startsWith("/") ? 1 : 0;
+    if (initialSlashes && value.startsWith("//") && !value.startsWith("///")) {
+        initialSlashes = 2;
+    }
+    const components = [];
+    for (const component of value.split("/")) {
+        if (component === "" || component === ".") {
+            continue;
+        }
+        if (component !== ".." ||
+            (!initialSlashes && components.length === 0) ||
+            (components.length > 0 && components[components.length - 1] === "..")) {
+            components.push(component);
+        }
+        else if (components.length > 0) {
+            components.pop();
+        }
+    }
+    const joined = "/".repeat(initialSlashes) + components.join("/");
+    return joined || ".";
+};
+exports.posixNormpath = posixNormpath;
+const posixDirname = (value) => {
+    const index = value.lastIndexOf("/") + 1;
+    let head = value.slice(0, index);
+    if (head && head !== "/".repeat(head.length)) {
+        head = head.replace(/\/+$/, "");
+    }
+    return head;
+};
+exports.posixDirname = posixDirname;
+const posixJoin = (...parts) => {
+    let joined = "";
+    for (const part of parts) {
+        if (part.startsWith("/")) {
+            joined = part;
+        }
+        else if (!joined || joined.endsWith("/")) {
+            joined += part;
+        }
+        else {
+            joined += "/" + part;
+        }
+    }
+    return joined;
+};
+exports.posixJoin = posixJoin;
+/** Compare strings by Unicode code point, like Python's default `str` ordering. */
+const compareCodePoints = (a, b) => {
+    const left = Array.from(a);
+    const right = Array.from(b);
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = (left[index].codePointAt(0) ?? 0) - (right[index].codePointAt(0) ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return left.length - right.length;
+};
+exports.compareCodePoints = compareCodePoints;
+const escapeNonAscii = (json) => json.replace(/[\u007f-\uffff]/g, (character) => {
+    return "\\u" + character.charCodeAt(0).toString(16).padStart(4, "0");
+});
+// Serialize keys directly: assigning sorted keys to an object lets JavaScript
+// reorder integer-like keys and treats __proto__ as a setter.
+const sortedJson = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map((item) => sortedJson(item) ?? "null").join(",")}]`;
+    if (value && typeof value === "object") {
+        const record = value;
+        const entries = Object.keys(record).sort(exports.compareCodePoints).flatMap((key) => {
+            const item = sortedJson(record[key]);
+            return item === undefined ? [] : [`${JSON.stringify(key)}:${item}`];
+        });
+        return `{${entries.join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+/**
+ * Compact JSON matching Python `json.dumps(value, separators=(",", ":"))`.
+ * `sortKeys` mirrors `sort_keys=True`; `ensureAscii` mirrors the default
+ * `ensure_ascii=True` escaping of non-ASCII characters.
+ */
+const compactJson = (value, options = {}) => {
+    const json = options.sortKeys ? sortedJson(value) : JSON.stringify(value);
+    return options.ensureAscii === false ? json : escapeNonAscii(json);
+};
+exports.compactJson = compactJson;
+exports.SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+exports.isRecord = isRecord;
+const requireRecord = (value, label) => {
+    if (!(0, exports.isRecord)(value)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    return value;
+};
+exports.requireRecord = requireRecord;
+const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, Math.max(0, seconds) * 1000));
+exports.sleep = sleep;

package/dist/sandbox/image-build/context.d.ts

@@ -0,0 +1,43 @@
+/** Remote Dockerfile build context selection, fingerprinting, and packaging. */
+import { SandboxBuildContextManifest } from "../../types/sandbox";
+import { DockerImageBuildArtifact } from "./artifacts";
+import { DockerIgnoreMatcher } from "./dockerignore";
+/** The packaged context no longer matches the caller's cache fingerprint. */
+export declare class DockerBuildContextChangedError extends Error {
+    constructor(message: string);
+}
+export interface PackagedDockerBuildContext {
+    artifact: DockerImageBuildArtifact;
+    manifest: SandboxBuildContextManifest;
+    bundles: Record<string, DockerImageBuildArtifact>;
+    workspace: string;
+    fingerprint: string;
+    cleanup(): void;
+}
+export interface DockerBuildContextOptions {
+    dockerfile?: string;
+    forceFullContext?: boolean;
+}
+export declare const loadDockerignore: (ignorePath: string) => DockerIgnoreMatcher | null;
+export declare const collectContextEntries: (contextRoot: string, sources: string[], options: {
+    ignoreMatcher: DockerIgnoreMatcher | null;
+    required: boolean;
+}) => Set<string>;
+/**
+ * Fingerprint the effective remote context without compressing or staging it.
+ *
+ * Uses the same Dockerfile source selection, ignore rules, and normalized tar
+ * entries as remote packaging. Pass the result as `expectedContextFingerprint`
+ * when building to detect context changes. Build options outside the context
+ * (e.g. platform or imageInit) must also be included in the caller's cache
+ * key. Mutable base tags and network resources are not resolved.
+ */
+export declare const dockerBuildContextFingerprint: (contextPath: string, options?: DockerBuildContextOptions) => Promise<string>;
+/** Serialize a manifest exactly as the Python SDK does (field order, no nulls). */
+export declare const canonicalManifestJson: (value: unknown) => Buffer;
+export declare const writeManifestArtifact: (workspace: string, filename: string, data: Buffer, inputFormat: DockerImageBuildArtifact["inputFormat"], extras?: Pick<DockerImageBuildArtifact, "imageConfigUser" | "imageInit">) => DockerImageBuildArtifact;
+export interface PackageDockerBuildContextOptions extends DockerBuildContextOptions {
+    tempDir?: string;
+    expectedContextFingerprint?: string;
+}
+export declare const packageDockerBuildContextManifest: (contextPath: string, options?: PackageDockerBuildContextOptions) => Promise<PackagedDockerBuildContext>;