@hyperbrowser/sdk 0.93.0 → 1.0.1

package/dist/services/sandboxes.js

@@ -1,29 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxesService = exports.SandboxHandle = void 0;
-const client_1 = require("../client");
+const error_1 = require("../error");
 const files_1 = require("../sandbox/files");
 const base_1 = require("../sandbox/base");
 const runtime_path_1 = require("../sandbox/runtime-path");
 const process_1 = require("../sandbox/process");
 const terminal_1 = require("../sandbox/terminal");
+const image_build_1 = require("../sandbox/image-build");
+const retry_1 = require("../retry");
+const normalize_1 = require("./normalize");
 const base_2 = require("./base");
 const RUNTIME_SESSION_REFRESH_BUFFER_MS = 60000;
 const normalizeSandbox = (sandbox) => {
     const { vcpus, memMiB, diskSizeMiB, ...rest } = sandbox;
     return {
         ...rest,
-        cpu: vcpus,
-        memoryMiB: memMiB,
-        diskMiB: diskSizeMiB,
+        cpu: (0, normalize_1.optionalInteger)(vcpus),
+        memoryMiB: (0, normalize_1.optionalInteger)(memMiB),
+        diskMiB: (0, normalize_1.optionalInteger)(diskSizeMiB),
+        endTime: (0, normalize_1.optionalInteger)(rest.endTime),
+        startTime: (0, normalize_1.optionalInteger)(rest.startTime),
+        dataConsumed: (0, normalize_1.optionalInteger)(rest.dataConsumed),
+        proxyDataConsumed: (0, normalize_1.optionalInteger)(rest.proxyDataConsumed),
+        proxyBytesUsed: (0, normalize_1.optionalInteger)(rest.proxyBytesUsed),
+        timeoutMinutes: (0, normalize_1.optionalInteger)(rest.timeoutMinutes),
+        creditsUsed: (0, normalize_1.optionalNumber)(rest.creditsUsed) ?? null,
+        exposedPorts: rest.exposedPorts ?? [],
+        network: rest.network ? { ...rest.network, allowOut: rest.network.allowOut ?? [], denyOut: rest.network.denyOut ?? [] } : rest.network,
     };
 };
 const normalizeSandboxDetail = (detail) => {
     const { token, tokenExpiresAt, ...sandbox } = detail;
     return {
         ...normalizeSandbox(sandbox),
-        token,
-        tokenExpiresAt,
+        token: token || null,
+        tokenExpiresAt: tokenExpiresAt || null,
     };
 };
 const normalizeSandboxListResponse = (response) => ({
@@ -31,8 +43,31 @@ const normalizeSandboxListResponse = (response) => ({
     sandboxes: response.sandboxes.map(normalizeSandbox),
 });
 const serializeCreateSandboxParams = (params) => {
+    if (!params || typeof params !== "object")
+        throw new error_1.HyperbrowserError("Sandbox launch parameters are required");
+    for (const name of ["imageName", "snapshotName", "imageId", "snapshotId"]) {
+        const value = params[name];
+        if (value !== undefined && (typeof value !== "string" || !value.trim()))
+            throw new error_1.HyperbrowserError(`${name} must be a nonempty string`);
+    }
+    if (params.imageId !== undefined && !params.imageName)
+        throw new error_1.HyperbrowserError("imageId requires imageName");
+    if (params.snapshotId !== undefined && !params.snapshotName)
+        throw new error_1.HyperbrowserError("snapshotId requires snapshotName");
+    if (Boolean(params.imageName) === Boolean(params.snapshotName))
+        throw new error_1.HyperbrowserError("Provide exactly one start source: snapshotName or imageName");
+    for (const name of ["cpu", "memoryMiB", "diskMiB"]) {
+        const value = params[name];
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+            throw new error_1.HyperbrowserError(`${name} must be a positive integer`);
+    }
+    if (params.runtimeClass !== undefined &&
+        params.runtimeClass !== "firecracker" &&
+        params.runtimeClass !== "gvisor-cpu")
+        throw new error_1.HyperbrowserError("Unsupported sandbox runtimeClass");
     if (typeof params.imageName === "string") {
         return {
+            runtimeClass: params.runtimeClass,
             imageName: params.imageName,
             imageId: params.imageId,
             region: params.region,
@@ -52,9 +87,10 @@ const serializeCreateSandboxParams = (params) => {
     if (snapshotParams.cpu !== undefined ||
         snapshotParams.memoryMiB !== undefined ||
         snapshotParams.diskMiB !== undefined) {
-        throw new client_1.HyperbrowserError("cpu, memoryMiB, and diskMiB are only supported for image launches", undefined);
+        throw new error_1.HyperbrowserError("cpu, memoryMiB, and diskMiB are only supported for image launches", undefined);
     }
     return {
+        runtimeClass: snapshotParams.runtimeClass,
         snapshotName: snapshotParams.snapshotName,
         snapshotId: snapshotParams.snapshotId,
         region: snapshotParams.region,
@@ -67,6 +103,59 @@ const serializeCreateSandboxParams = (params) => {
         denyOut: snapshotParams.denyOut,
     };
 };
+const IMAGE_BUILD_DEFAULT_POLL_INTERVAL_SECONDS = 3;
+const IMAGE_BUILD_DEFAULT_WAIT_TIMEOUT_SECONDS = 35 * 60;
+const IMAGE_BUILD_COMPLETE_RETRY_DELAY_MS = 2000;
+const READY_IMAGE_PAGE_SIZE = 100;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const validatePagination = (params, maxLimit) => {
+    for (const key of ["page", "limit"]) {
+        const value = params[key];
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+            throw new error_1.HyperbrowserError(`${key} must be a positive integer`);
+    }
+    if (maxLimit !== undefined && params.limit !== undefined && params.limit > maxLimit)
+        throw new error_1.HyperbrowserError(`limit must be at most ${maxLimit}`);
+};
+const validateImageBuildFormat = (params) => {
+    if (params.sourcePlatform !== undefined && params.sourcePlatform !== "linux/amd64")
+        throw new error_1.HyperbrowserError("sourcePlatform must be linux/amd64");
+    if (params.inputFormat !== undefined && ![
+        "rootfs_export_tar_gz", "dockerfile_context_tar_gz",
+        "dockerfile_context_manifest_v1", "docker_image_manifest_v1",
+    ].includes(params.inputFormat))
+        throw new error_1.HyperbrowserError("Unsupported image build inputFormat");
+};
+const serializeCreateImageBuildParams = (params) => {
+    validateImageBuildFormat(params);
+    for (const key of ["builderCpus", "builderMemoryMiB", "builderScratchMiB"]) {
+        const value = params[key];
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+            throw new error_1.HyperbrowserError(`${key} must be a positive integer`);
+    }
+    return ({
+        imageName: params.imageName,
+        inputSha256: params.inputSha256,
+        inputSizeBytes: params.inputSizeBytes,
+        vcpus: params.builderCpus,
+        memMiB: params.builderMemoryMiB,
+        scratchMiB: params.builderScratchMiB,
+        inputFormat: params.inputFormat,
+        sourcePlatform: params.sourcePlatform,
+        imageConfigUser: params.imageConfigUser,
+        imageInit: params.imageInit,
+        dockerfilePath: params.dockerfilePath,
+        contextManifest: params.contextManifest,
+        dockerImageManifest: params.dockerImageManifest,
+    });
+};
+const normalizeImageBuildPlatform = (platform) => {
+    const normalized = (platform ?? image_build_1.IMAGE_BUILD_SOURCE_PLATFORM).trim().toLowerCase();
+    if (normalized !== image_build_1.IMAGE_BUILD_SOURCE_PLATFORM) {
+        throw new error_1.HyperbrowserError(`Image builds require platform '${image_build_1.IMAGE_BUILD_SOURCE_PLATFORM}'`);
+    }
+    return normalized;
+};
 const resolveSandboxRuntimeSessionHost = (runtime, baseUrl) => {
     const sessionIdFromBasePath = (0, runtime_path_1.runtimeSessionIdFromPath)(baseUrl.pathname);
     if (sessionIdFromBasePath && baseUrl.hostname) {
@@ -168,7 +257,7 @@ class SandboxHandle {
         return this.service.createMemorySnapshot(this.id, params);
     }
     async expose(params) {
-        const exposure = await this.service.expose(this.id, params);
+        const exposure = await this.service.expose(this.id, params, this.runtime);
         this.detail = {
             ...this.detail,
             exposedPorts: upsertExposedPort(this.detail.exposedPorts ?? [], exposure),
@@ -243,6 +332,10 @@ class SandboxHandle {
         }
         return expiresAt - Date.now() <= RUNTIME_SESSION_REFRESH_BUFFER_MS;
     }
+    async createRuntimeSession(options = {}) {
+        const session = await this.ensureRuntimeSession(options.forceRefresh);
+        return { ...session, runtime: { ...session.runtime } };
+    }
     async ensureRuntimeSession(forceRefresh = false) {
         this.assertRuntimeAvailable();
         if (!forceRefresh && this.runtimeSession && !this.isRuntimeSessionExpiring()) {
@@ -251,7 +344,7 @@ class SandboxHandle {
         const detail = await this.service.getDetail(this.id);
         this.hydrate(detail);
         if (!this.runtimeSession) {
-            throw new client_1.HyperbrowserError(`Sandbox ${this.id} is not running`, {
+            throw new error_1.HyperbrowserError(`Sandbox ${this.id} is not running`, {
                 statusCode: 409,
                 code: "sandbox_not_running",
                 retryable: false,
@@ -284,7 +377,7 @@ class SandboxHandle {
         if (this.detail.status === "closed" ||
             this.detail.status === "close-error" ||
             this.detail.status === "error") {
-            throw new client_1.HyperbrowserError(`Sandbox ${this.id} is not running`, {
+            throw new error_1.HyperbrowserError(`Sandbox ${this.id} is not running`, {
                 statusCode: 409,
                 code: "sandbox_not_running",
                 retryable: false,
@@ -317,6 +410,29 @@ class SandboxesService extends base_2.BaseService {
         const detail = await this.createDetail(params);
         return this.attach(detail);
     }
+    async startFromSnapshot(params) {
+        if (!params?.snapshotName)
+            throw new error_1.HyperbrowserError("snapshotName is required");
+        return this.create(params);
+    }
+    async getRuntimeSession(id) {
+        const detail = await this.getDetail(id);
+        if (!detail.token || ["closed", "close-error", "error"].includes(detail.status)) {
+            throw new error_1.HyperbrowserError(`Sandbox ${id} is not running`, {
+                statusCode: 409,
+                code: "sandbox_not_running",
+                service: "runtime",
+            });
+        }
+        return {
+            sandboxId: id,
+            status: detail.status,
+            region: detail.region,
+            token: detail.token,
+            tokenExpiresAt: detail.tokenExpiresAt,
+            runtime: { ...detail.runtime },
+        };
+    }
     async get(id) {
         const detail = await this.getDetail(id);
         return this.attach(detail);
@@ -327,22 +443,23 @@ class SandboxesService extends base_2.BaseService {
         return handle;
     }
     async list(params = {}) {
+        validatePagination(params);
         try {
             const response = await this.request("/sandboxes", undefined, {
                 status: params.status,
                 start: params.start,
                 end: params.end,
                 search: params.search,
-                page: params.page,
-                limit: params.limit,
+                page: params.page ?? 1,
+                limit: params.limit ?? 10,
             });
             return normalizeSandboxListResponse(response);
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError("Failed to list sandboxes", undefined);
+            throw new error_1.HyperbrowserError("Failed to list sandboxes", undefined);
         }
     }
     async deleteImage(image) {
@@ -352,13 +469,14 @@ class SandboxesService extends base_2.BaseService {
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to delete image ${image}`);
+            throw new error_1.HyperbrowserError(`Failed to delete image ${image}`);
         }
     }
     async listImages(params = {}) {
+        validatePagination(params, 100);
         try {
             return await this.request("/images", undefined, {
                 source: params.source,
@@ -368,13 +486,14 @@ class SandboxesService extends base_2.BaseService {
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError("Failed to list sandbox images", undefined);
+            throw new error_1.HyperbrowserError("Failed to list sandbox images", undefined);
         }
     }
     async listSnapshots(params = {}) {
+        validatePagination(params, 100);
         try {
             return await this.request("/snapshots", undefined, {
                 status: params.status,
@@ -385,10 +504,10 @@ class SandboxesService extends base_2.BaseService {
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError("Failed to list sandbox snapshots", undefined);
+            throw new error_1.HyperbrowserError("Failed to list sandbox snapshots", undefined);
         }
     }
     async stop(id) {
@@ -398,10 +517,10 @@ class SandboxesService extends base_2.BaseService {
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to stop sandbox ${id}`, undefined);
+            throw new error_1.HyperbrowserError(`Failed to stop sandbox ${id}`, undefined);
         }
     }
     async getDetail(id) {
@@ -410,10 +529,10 @@ class SandboxesService extends base_2.BaseService {
             return normalizeSandboxDetail(detail);
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to get sandbox ${id}`, undefined);
+            throw new error_1.HyperbrowserError(`Failed to get sandbox ${id}`, undefined);
         }
     }
     attach(detail) {
@@ -427,24 +546,27 @@ class SandboxesService extends base_2.BaseService {
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to create memory snapshot for sandbox ${id}`, undefined);
+            throw new error_1.HyperbrowserError(`Failed to create memory snapshot for sandbox ${id}`, undefined);
         }
     }
-    async expose(id, params) {
+    async expose(id, params, runtime) {
         try {
-            return await this.request(`/sandbox/${id}/expose`, {
+            const exposure = await this.request(`/sandbox/${id}/expose`, {
                 method: "POST",
                 body: JSON.stringify(params),
             });
+            if (!exposure.url)
+                exposure.url = buildSandboxExposedUrl(runtime ?? (await this.getDetail(id)).runtime, exposure.port);
+            return exposure;
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to expose port ${params.port} for sandbox ${id}`);
+            throw new error_1.HyperbrowserError(`Failed to expose port ${params.port} for sandbox ${id}`);
         }
     }
     async getSnapshot(snapshot) {
@@ -453,10 +575,10 @@ class SandboxesService extends base_2.BaseService {
             return response.snapshot;
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to get snapshot ${snapshot}`);
+            throw new error_1.HyperbrowserError(`Failed to get snapshot ${snapshot}`);
         }
     }
     async deleteSnapshot(snapshot) {
@@ -464,36 +586,36 @@ class SandboxesService extends base_2.BaseService {
             return await this.request(`/snapshots/${encodeURIComponent(snapshot)}`, { method: "DELETE" });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to delete snapshot ${snapshot}`);
+            throw new error_1.HyperbrowserError(`Failed to delete snapshot ${snapshot}`);
         }
     }
     async createImageBuild(params) {
         try {
             return await this.request("/images/builds", {
                 method: "POST",
-                body: JSON.stringify(params),
+                body: JSON.stringify(serializeCreateImageBuildParams(params)),
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError("Failed to create image build");
+            throw new error_1.HyperbrowserError("Failed to create image build");
         }
     }
-    async getImageBuild(buildId) {
+    async getImageBuild(buildId, options = {}) {
         try {
-            const response = await this.request(`/images/builds/${encodeURIComponent(buildId)}`);
+            const response = await this.request(`/images/builds/${encodeURIComponent(buildId)}`, { signal: options.signal });
             return response.build;
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to get image build ${buildId}`);
+            throw new error_1.HyperbrowserError(`Failed to get image build ${buildId}`);
         }
     }
     async listImageBuilds(params = {}) {
@@ -504,13 +626,14 @@ class SandboxesService extends base_2.BaseService {
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError("Failed to list image builds");
+            throw new error_1.HyperbrowserError("Failed to list image builds");
         }
     }
     async completeImageBuild(buildId, params) {
+        validateImageBuildFormat(params);
         try {
             const response = await this.request(`/images/builds/${encodeURIComponent(buildId)}/complete`, {
                 method: "POST",
@@ -519,10 +642,10 @@ class SandboxesService extends base_2.BaseService {
             return response.build;
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to complete image build ${buildId}`);
+            throw new error_1.HyperbrowserError(`Failed to complete image build ${buildId}`);
         }
     }
     async cancelImageBuild(buildId) {
@@ -531,10 +654,403 @@ class SandboxesService extends base_2.BaseService {
             return response.build;
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new error_1.HyperbrowserError(`Failed to cancel image build ${buildId}`);
+        }
+    }
+    async reuseDockerImage(params) {
+        validateImageBuildFormat(params);
+        try {
+            return await this.request("/images/builds/reuse", {
+                method: "POST",
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            if (error instanceof error_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new error_1.HyperbrowserError("Failed to reuse Docker image");
+        }
+    }
+    /** Find an exact ready team image, including revisions awaiting backup. */
+    async findReadyImage(imageName) {
+        let page = 1;
+        for (;;) {
+            const response = await this.listImages({
+                search: imageName,
+                source: ["team"],
+                page,
+                limit: READY_IMAGE_PAGE_SIZE,
+            });
+            for (const image of response.images) {
+                if (image.imageName === imageName && (image.uploaded || image.ready === true)) {
+                    return image;
+                }
+            }
+            if (response.images.length < READY_IMAGE_PAGE_SIZE) {
+                return null;
+            }
+            if (typeof response.totalCount === "number" &&
+                page * READY_IMAGE_PAGE_SIZE >= response.totalCount) {
+                return null;
+            }
+            page += 1;
+        }
+    }
+    /** Poll an image build until it completes, rejecting on failure or timeout. */
+    async waitForImageBuild(buildId, options = {}) {
+        const pollInterval = options.pollInterval ?? IMAGE_BUILD_DEFAULT_POLL_INTERVAL_SECONDS;
+        const timeout = options.timeout === undefined ? IMAGE_BUILD_DEFAULT_WAIT_TIMEOUT_SECONDS : options.timeout;
+        if (!Number.isFinite(pollInterval) ||
+            pollInterval < 0 ||
+            (timeout !== null && (!Number.isFinite(timeout) || timeout < 0))) {
+            throw new error_1.HyperbrowserError("Image build wait timeout and interval must be nonnegative finite seconds");
+        }
+        const controller = new AbortController();
+        let timedOut = false;
+        const deadlineTimer = timeout === null
+            ? undefined
+            : setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, timeout * 1000);
+        const cancel = () => controller.abort();
+        options.signal?.addEventListener("abort", cancel, { once: true });
+        if (options.signal?.aborted)
+            cancel();
+        const waitFailure = (error) => {
+            if (timedOut)
+                throw new error_1.HyperbrowserError(`Timed out waiting for image build ${buildId}`, {
+                    code: "wait_timeout",
+                    service: "control",
+                    cause: error,
+                });
+            throw error;
+        };
+        try {
+            for (;;) {
+                const build = await this.getImageBuild(buildId, { signal: controller.signal }).catch(waitFailure);
+                if (build.status === "completed")
+                    return build;
+                if (build.status === "failed" || build.status === "canceled") {
+                    throw new error_1.HyperbrowserError(build.errorMessage || `Image build ${buildId} ${build.status}`, { code: build.errorCode || "image_build_failed", service: "control", details: build });
+                }
+                await (0, retry_1.retryDelay)(pollInterval * 1000, controller.signal).catch(waitFailure);
+            }
+        }
+        finally {
+            clearTimeout(deadlineTimer);
+            options.signal?.removeEventListener("abort", cancel);
+        }
+    }
+    /** Import a local Docker image as reusable layers, reusing exact cached imports. */
+    async buildImageFromDockerImage(options) {
+        const platform = normalizeImageBuildPlatform(options.platform);
+        const source = await (0, image_build_1.prepareDockerImageManifestSource)(options.dockerImage, { platform });
+        try {
+            if (options.expectedImageDigest !== undefined &&
+                source.imageDigest !== options.expectedImageDigest.toLowerCase()) {
+                throw new error_1.HyperbrowserError("Docker image changed after its cache identity was computed. " +
+                    "Retry with a fresh image digest.");
+            }
+            const imageInit = (0, image_build_1.mergeImageInit)(source.imageInit, options.imageInit);
+            const imageConfigUser = options.imageConfigUser ?? source.imageConfigUser;
+            let reused = null;
+            try {
+                reused = await this.reuseDockerImage({
+                    imageName: options.imageName,
+                    sourceImageDigest: source.imageDigest,
+                    sourcePlatform: "linux/amd64",
+                    imageConfigUser,
+                    imageInit,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof error_1.HyperbrowserError) || error.statusCode !== 404) {
+                    throw error;
+                }
+            }
+            if (reused?.hit) {
+                if (!reused.build) {
+                    throw new error_1.HyperbrowserError("exact image cache response is missing its completed build");
+                }
+                return reused.build;
+            }
+            const packaged = await (0, image_build_1.packageDockerImageManifest)(options.dockerImage, source.imageDigest, source.config, { platform, tempDir: options.tempDir });
+            try {
+                return await this.submitImageBuild({
+                    imageName: options.imageName,
+                    inputSha256: packaged.artifact.sha256Hex,
+                    inputSizeBytes: packaged.artifact.sizeBytes,
+                    inputFormat: packaged.artifact.inputFormat,
+                    sourcePlatform: "linux/amd64",
+                    imageConfigUser,
+                    imageInit,
+                    dockerImageManifest: packaged.manifest,
+                    builderCpus: options.builderCpus,
+                    builderMemoryMiB: options.builderMemoryMiB,
+                    builderScratchMiB: options.builderScratchMiB,
+                }, packaged.artifact, packaged.layers, "Docker image layer", options);
+            }
+            finally {
+                packaged.cleanup();
+            }
+        }
+        finally {
+            await source.cleanup();
+        }
+    }
+    /**
+     * Build a Dockerfile into a sandbox image.
+     *
+     * Remote builds (default) upload only the effective build context and build
+     * on Hyperbrowser. `remote: false` builds with local Docker and imports the
+     * resulting image instead.
+     */
+    async buildImageFromDockerfile(options) {
+        options = { ...options, platform: normalizeImageBuildPlatform(options.platform) };
+        const remote = options.remote ?? true;
+        if (remote) {
+            if (options.dockerTag !== undefined ||
+                (options.buildArgs && Object.keys(options.buildArgs).length > 0)) {
+                throw new error_1.HyperbrowserError("dockerTag and buildArgs require remote: false; remote Dockerfile builds " +
+                    "send the build context to Hyperbrowser");
+            }
+            return this.buildImageFromRemoteDockerfile(options);
+        }
+        if (options.expectedContextFingerprint !== undefined) {
+            throw new error_1.HyperbrowserError("expectedContextFingerprint requires remote: true");
+        }
+        const tag = options.dockerTag ?? (0, image_build_1.makeTempDockerTag)();
+        try {
+            await (0, image_build_1.buildDockerImageFromDockerfile)({
+                contextPath: options.contextPath,
+                dockerfile: options.dockerfile,
+                tag,
+                platform: options.platform,
+                buildArgs: options.buildArgs,
+            });
+            return await this.buildImageFromDockerImage({
+                dockerImage: tag,
+                imageName: options.imageName,
+                platform: options.platform,
+                imageInit: options.imageInit,
+                imageConfigUser: options.imageConfigUser,
+                builderCpus: options.builderCpus,
+                builderMemoryMiB: options.builderMemoryMiB,
+                builderScratchMiB: options.builderScratchMiB,
+                wait: options.wait,
+                pollInterval: options.pollInterval,
+                waitTimeout: options.waitTimeout,
+                signal: options.signal,
+                tempDir: options.tempDir,
+                uploadTimeout: options.uploadTimeout,
+            });
+        }
+        finally {
+            if (options.dockerTag === undefined) {
+                await (0, image_build_1.removeDockerImage)(tag);
+            }
+        }
+    }
+    /**
+     * Reuse, join, or build content-derived remote Dockerfile/image inputs.
+     *
+     * Supply exactly one of `contextPath` or `dockerImage`. Names include source
+     * contents, platform and image initialization overrides. `forceBuild` skips
+     * ready-image lookup, but joins matching active builds and retains builder
+     * layer/artifact caches. Canceling polling never cancels the backend build.
+     * `waitTimeout` applies to this caller's polling, independently of uploads.
+     * This composes existing APIs; lookup plus creation is not server-atomic.
+     */
+    async getOrBuildImage(options) {
+        const platform = normalizeImageBuildPlatform(options.platform);
+        const dockerfile = options.dockerfile ?? "Dockerfile";
+        const remoteFullContext = options.remoteFullContext ?? false;
+        const { contextPath, dockerImage } = options;
+        if ((contextPath === undefined) === (dockerImage === undefined)) {
+            throw new error_1.HyperbrowserError("Supply exactly one of contextPath or dockerImage");
+        }
+        let fingerprint;
+        let source;
+        let inputFormat;
+        if (contextPath !== undefined) {
+            if (options.expectedImageDigest !== undefined) {
+                throw new error_1.HyperbrowserError("expectedImageDigest requires dockerImage");
+            }
+            fingerprint =
+                options.expectedContextFingerprint ??
+                    (await (0, image_build_1.dockerBuildContextFingerprint)(contextPath, {
+                        dockerfile,
+                        forceFullContext: remoteFullContext,
+                    }));
+            source = "dockerfile";
+            inputFormat = "dockerfile_context_manifest_v1";
+        }
+        else {
+            if (options.expectedContextFingerprint !== undefined ||
+                remoteFullContext ||
+                dockerfile !== "Dockerfile") {
+                throw new error_1.HyperbrowserError("Dockerfile context options require contextPath");
+            }
+            fingerprint =
+                options.expectedImageDigest ??
+                    (await (0, image_build_1.dockerImageDigest)(dockerImage, { platform }));
+            source = "prebuilt";
+            inputFormat = "docker_image_manifest_v1";
+        }
+        const imageName = (0, image_build_1.imageBuildName)({
+            source,
+            fingerprint,
+            namePrefix: options.imageNamePrefix,
+            platform,
+            imageInit: options.imageInit,
+            imageConfigUser: options.imageConfigUser,
+        });
+        if (!options.forceBuild) {
+            const image = await this.findReadyImage(imageName);
+            if (image !== null) {
+                return { outcome: "reused", imageName, imageId: image.id };
+            }
+        }
+        const common = {
+            imageName,
+            platform,
+            imageInit: options.imageInit,
+            imageConfigUser: options.imageConfigUser,
+            builderCpus: options.builderCpus,
+            builderMemoryMiB: options.builderMemoryMiB,
+            builderScratchMiB: options.builderScratchMiB,
+            wait: false,
+            uploadTimeout: options.uploadTimeout === undefined ? 600 : options.uploadTimeout,
+            tempDir: options.tempDir,
+        };
+        let outcome = "created";
+        let build;
+        try {
+            build =
+                contextPath !== undefined
+                    ? await this.buildImageFromDockerfile({
+                        ...common,
+                        contextPath,
+                        dockerfile,
+                        remote: true,
+                        remoteFullContext,
+                        expectedContextFingerprint: fingerprint,
+                    })
+                    : await this.buildImageFromDockerImage({
+                        ...common,
+                        dockerImage: dockerImage,
+                        expectedImageDigest: fingerprint,
+                    });
+        }
+        catch (error) {
+            if (!(error instanceof error_1.HyperbrowserError)) {
+                throw error;
+            }
+            const existing = (0, image_build_1.matchingImageBuild)(error, imageName, inputFormat);
+            if (existing === null) {
+                throw error;
+            }
+            build = existing;
+            outcome = "joined";
+        }
+        const wait = options.wait ?? true;
+        if (wait && build.status !== "completed") {
+            build = await this.waitForImageBuild(build.id, {
+                pollInterval: options.pollInterval,
+                timeout: options.waitTimeout,
+                signal: options.signal,
+            });
+        }
+        return { outcome, imageName, imageId: (0, image_build_1.completedImageId)(build), build };
+    }
+    async buildImageFromRemoteDockerfile(options) {
+        const packaged = await (0, image_build_1.packageDockerBuildContextManifest)(options.contextPath, {
+            dockerfile: options.dockerfile,
+            forceFullContext: options.remoteFullContext,
+            expectedContextFingerprint: options.expectedContextFingerprint,
+            tempDir: options.tempDir,
+        });
+        try {
+            return await this.submitImageBuild({
+                imageName: options.imageName,
+                inputSha256: packaged.artifact.sha256Hex,
+                inputSizeBytes: packaged.artifact.sizeBytes,
+                inputFormat: packaged.artifact.inputFormat,
+                sourcePlatform: "linux/amd64",
+                dockerfilePath: packaged.manifest.dockerfilePath,
+                imageConfigUser: options.imageConfigUser,
+                imageInit: options.imageInit,
+                contextManifest: packaged.manifest,
+                builderCpus: options.builderCpus,
+                builderMemoryMiB: options.builderMemoryMiB,
+                builderScratchMiB: options.builderScratchMiB,
+            }, packaged.artifact, packaged.bundles, "build context bundle", options);
+        }
+        finally {
+            packaged.cleanup();
+        }
+    }
+    /** Create a build, upload requested artifacts, complete it, and optionally wait. */
+    async submitImageBuild(params, artifact, artifacts, label, options) {
+        let buildId = null;
+        let buildStarted = false;
+        try {
+            const createResult = await this.createImageBuild(params);
+            buildId = createResult.build.id;
+            await (0, image_build_1.uploadMissingImageBuildArtifacts)(createResult.uploads, artifacts, {
+                label,
+                timeout: options.uploadTimeout,
+            });
+            const build = await this.completeImageBuildResilient(buildId, artifact);
+            buildStarted = true;
+            if (options.wait ?? true) {
+                return await this.waitForImageBuild(build.id, {
+                    pollInterval: options.pollInterval,
+                    timeout: options.waitTimeout,
+                    signal: options.signal,
+                });
+            }
+            return build;
+        }
+        catch (error) {
+            if (buildId !== null && !buildStarted) {
+                try {
+                    await this.cancelImageBuild(buildId);
+                }
+                catch {
+                    // Best-effort cancellation; surface the original error.
+                }
+            }
+            throw error;
+        }
+    }
+    async completeImageBuildResilient(buildId, artifact) {
+        const params = {
+            inputSha256: artifact.sha256Hex,
+            inputSizeBytes: artifact.sizeBytes,
+            inputFormat: artifact.inputFormat,
+        };
+        try {
+            return await this.completeImageBuild(buildId, params);
+        }
+        catch (error) {
+            if (!(error instanceof error_1.HyperbrowserError) || error.statusCode !== 409) {
+                throw error;
+            }
+            if (error.message.toLowerCase().includes("already in progress")) {
+                return this.getImageBuild(buildId);
+            }
+            const current = await this.getImageBuild(buildId);
+            if (current.status !== "awaiting_upload" && current.status !== "upload_verified") {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to cancel image build ${buildId}`);
+            await sleep(IMAGE_BUILD_COMPLETE_RETRY_DELAY_MS);
+            return this.completeImageBuild(buildId, params);
         }
     }
     async updateNetwork(id, policy) {
@@ -545,10 +1061,10 @@ class SandboxesService extends base_2.BaseService {
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to update network policy for sandbox ${id}`);
+            throw new error_1.HyperbrowserError(`Failed to update network policy for sandbox ${id}`);
         }
     }
     async unexpose(id, port) {
@@ -559,10 +1075,10 @@ class SandboxesService extends base_2.BaseService {
             });
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(`Failed to unexpose port ${port} for sandbox ${id}`);
+            throw new error_1.HyperbrowserError(`Failed to unexpose port ${port} for sandbox ${id}`);
         }
     }
     async createDetail(params) {
@@ -574,10 +1090,10 @@ class SandboxesService extends base_2.BaseService {
             return normalizeSandboxDetail(detail);
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError("Failed to create sandbox", undefined);
+            throw new error_1.HyperbrowserError("Failed to create sandbox", undefined);
         }
     }
 }