@workbench-ai/workbench-core 0.0.46

package/dist/sandbox-backends/docker.js

@@ -0,0 +1,568 @@
+import { createHash, } from "node:crypto";
+import { createWriteStream, existsSync, } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, } from "node:url";
+import { createSandboxAdapterRequest, executionResultFromCompletedSandboxJob, } from "../sandbox-inputs.js";
+import { asRuntimeRecord, importNodeModule, nodeBuiltin, } from "../runtime-utils.js";
+import { createWorkbenchProgressStdoutParser, publishWorkbenchProgressStdoutEnvelope, } from "../execution-events.js";
+import { resolveSandboxTemplateImage, } from "./template-images.js";
+import { DOCKER_SANDBOX_BACKEND, } from "./names.js";
+const BUILT_IN_ENVIRONMENT_IMAGES = {
+    "workbench/workbench-node-22:envv_node_22": "products/workbench/environments/node-22/Dockerfile",
+    "workbench/workbench-python-3.12:envv_python_3_12": "products/workbench/environments/python-3.12/Dockerfile",
+    "workbench/workbench-libreoffice-python:envv_libreoffice_python": "products/workbench/environments/libreoffice-python/Dockerfile",
+    "workbench/workbench-libreoffice-agent:envv_libreoffice_agent": "products/workbench/environments/libreoffice-agent/Dockerfile",
+};
+const DOCKER_RUNTIME_MOUNT = "/workbench-runtime";
+const DOCKER_DEFAULT_WORKSPACE = "/workspace";
+export function createDockerSandboxBackendDescriptor() {
+    return {
+        name: DOCKER_SANDBOX_BACKEND,
+        version: "1",
+        capabilities: {
+            snapshots: true,
+            interactiveExec: false,
+            filesystemDiff: false,
+            networkPolicy: ["none", "open"],
+            fileCapabilities: true,
+        },
+    };
+}
+export function createDockerSandboxPlane(args, startedAt, fileStore) {
+    return {
+        backend: createDockerSandboxBackendDescriptor(),
+        async prepareEnvironment(execution) {
+            const [{ execFile }, { promisify }] = await Promise.all([
+                importNodeModule(nodeBuiltin("child_process")),
+                importNodeModule(nodeBuiltin("util")),
+            ]);
+            const execFileAsync = promisify(execFile);
+            const templateImage = await prepareDockerTemplateImage(execution, args, execFileAsync);
+            await ensureDockerExecutionImage(templateImage, execFileAsync);
+            return {
+                backend: DOCKER_SANDBOX_BACKEND,
+                kind: execution.sandbox.kind,
+                ref: execution.sandbox.ref,
+                metadata: {
+                    templateImage,
+                },
+            };
+        },
+        async createSandbox(request) {
+            const metadata = await prepareDockerSandboxWorkspace(args, request, startedAt);
+            return {
+                sandboxId: request.allocation.sandboxId,
+                lifecycleId: request.allocation.lifecycleId,
+                backend: request.allocation.backend,
+                executionId: request.execution.id,
+                template: request.allocation.template,
+                metadata: {
+                    allocation: request.allocation,
+                    ...metadata,
+                },
+            };
+        },
+        async exec(request) {
+            const completedJob = await runDockerSandboxExecution(request.sandbox, request.execution);
+            return await executionResultFromCompletedSandboxJob({
+                completedJob,
+                execution: request.execution,
+                startedAt,
+                backend: DOCKER_SANDBOX_BACKEND,
+                allocation: request.allocation,
+                capability: request.capability,
+                handle: request.sandbox,
+                fileStore,
+            });
+        },
+        async destroySandbox(sandbox) {
+            await destroyDockerSandbox(sandbox);
+        },
+    };
+}
+async function prepareDockerTemplateImage(execution, args, execFileAsync) {
+    const ref = execution.sandbox.ref;
+    if (execution.sandbox.kind !== "oci" || !ref.startsWith("dockerfile://")) {
+        return resolveSandboxTemplateImage(execution, args);
+    }
+    const dockerfile = args.environmentDockerfile?.trim();
+    if (!dockerfile) {
+        throw new Error(`Execution ${execution.id} uses ${ref}, but the claimed job input omitted environmentDockerfile.`);
+    }
+    const [fs, os, path] = await Promise.all([
+        importNodeModule(nodeBuiltin("fs/promises")),
+        importNodeModule(nodeBuiltin("os")),
+        importNodeModule(nodeBuiltin("path")),
+    ]);
+    const sourceHash = args.environmentVersion?.sourceHash?.trim() || createHash("sha256").update(dockerfile).digest("hex");
+    const image = `workbench/sandbox-${safeDockerImageSegment(args.environmentVersion?.id ?? "env")}:${sourceHash.slice(0, 16)}`;
+    const imageExists = await execFileAsync("docker", ["image", "inspect", image], { maxBuffer: 1024 * 1024 })
+        .then(() => true, () => false);
+    if (imageExists) {
+        return image;
+    }
+    const contextRoot = path.join(args.workdir ?? os.tmpdir(), "workbench-docker-environments", sourceHash.slice(0, 32));
+    const dockerfilePath = path.join(contextRoot, "Dockerfile");
+    await fs.rm(contextRoot, { recursive: true, force: true }).catch(() => undefined);
+    await fs.mkdir(contextRoot, { recursive: true });
+    await fs.writeFile(dockerfilePath, `${dockerfile}\n`, { mode: 0o600 });
+    await execFileAsync("docker", ["build", "-t", image, "-f", dockerfilePath, contextRoot], { maxBuffer: 20 * 1024 * 1024 });
+    return image;
+}
+async function prepareDockerSandboxWorkspace(args, request, startedAt) {
+    const [{ execFile }, fs, os, path, { promisify }] = await Promise.all([
+        importNodeModule(nodeBuiltin("child_process")),
+        importNodeModule(nodeBuiltin("fs/promises")),
+        importNodeModule(nodeBuiltin("os")),
+        importNodeModule(nodeBuiltin("path")),
+        importNodeModule(nodeBuiltin("util")),
+    ]);
+    const execFileAsync = promisify(execFile);
+    const sandboxUser = dockerSandboxUser();
+    const workdir = args.workdir ?? os.tmpdir();
+    const sandboxRoot = path.join(workdir, "workbench-docker", request.allocation.sandboxId);
+    const requestPath = path.join(sandboxRoot, "request.json");
+    const responsePath = path.join(sandboxRoot, "response.json");
+    const stdoutPath = path.join(sandboxRoot, "stdout.log");
+    const stderrPath = path.join(sandboxRoot, "stderr.log");
+    await fs.rm(sandboxRoot, { recursive: true, force: true }).catch(() => undefined);
+    await fs.mkdir(sandboxRoot, { recursive: true });
+    await alignDockerSandboxPath(fs, sandboxRoot, sandboxUser, 0o700, 0o777);
+    await fs.writeFile(requestPath, `${JSON.stringify(createSandboxAdapterRequest(args, request, startedAt), null, 2)}\n`, { mode: 0o600 });
+    await alignDockerSandboxPath(fs, requestPath, sandboxUser, 0o600, 0o644);
+    const environmentMetadata = asRuntimeRecord(request.environment.metadata);
+    const image = typeof environmentMetadata.templateImage === "string"
+        ? environmentMetadata.templateImage
+        : await prepareDockerTemplateImage(request.execution, args, execFileAsync);
+    const network = dockerNetworkConfigForExecution(request.execution);
+    const runtimePayload = await prepareDockerRuntimePayload(workdir, execFileAsync, fs, path);
+    return {
+        root: sandboxRoot,
+        request: requestPath,
+        response: responsePath,
+        stdout: stdoutPath,
+        stderr: stderrPath,
+        templateImage: image,
+        containerName: dockerContainerName(request.allocation.sandboxId),
+        runtimeRoot: runtimePayload.mountRoot,
+        runnerPath: runtimePayload.runnerPath,
+        runtimeImport: runtimePayload.runtimeImport,
+        sandboxUid: sandboxUser.uid,
+        sandboxGid: sandboxUser.gid,
+        network: network,
+    };
+}
+async function runDockerSandboxExecution(sandbox, execution) {
+    const metadata = asRuntimeRecord(sandbox.metadata);
+    const root = readRequiredMetadataString(metadata, "root", DOCKER_SANDBOX_BACKEND);
+    const responsePath = readRequiredMetadataString(metadata, "response", DOCKER_SANDBOX_BACKEND);
+    const stdoutPath = readRequiredMetadataString(metadata, "stdout", DOCKER_SANDBOX_BACKEND);
+    const stderrPath = readRequiredMetadataString(metadata, "stderr", DOCKER_SANDBOX_BACKEND);
+    const image = readRequiredMetadataString(metadata, "templateImage", DOCKER_SANDBOX_BACKEND);
+    const containerName = readRequiredMetadataString(metadata, "containerName", DOCKER_SANDBOX_BACKEND);
+    const runtimeRoot = readRequiredMetadataString(metadata, "runtimeRoot", DOCKER_SANDBOX_BACKEND);
+    const runnerPath = readRequiredMetadataString(metadata, "runnerPath", DOCKER_SANDBOX_BACKEND);
+    const runtimeImport = readRequiredMetadataString(metadata, "runtimeImport", DOCKER_SANDBOX_BACKEND);
+    const sandboxUid = readRequiredMetadataNumber(metadata, "sandboxUid", DOCKER_SANDBOX_BACKEND);
+    const sandboxGid = readRequiredMetadataNumber(metadata, "sandboxGid", DOCKER_SANDBOX_BACKEND);
+    const network = asRuntimeRecord(metadata.network);
+    const resources = execution.policy.resources;
+    const tmpfsSize = dockerSize(resources.diskGb);
+    const memorySize = dockerSize(resources.memoryGb);
+    const workspaceRoot = dockerExecutionWorkspaceRoot(execution);
+    const [{ execFile, spawn }, fs, { promisify }] = await Promise.all([
+        importNodeModule(nodeBuiltin("child_process")),
+        importNodeModule(nodeBuiltin("fs/promises")),
+        importNodeModule(nodeBuiltin("util")),
+    ]);
+    const execFileAsync = promisify(execFile);
+    await execFileAsync("docker", ["rm", "-f", containerName], { maxBuffer: 1024 * 1024 }).catch(() => undefined);
+    const tmpfsArgs = [
+        tmpfsDockerArg(DOCKER_DEFAULT_WORKSPACE, sandboxUid, sandboxGid, tmpfsSize),
+        ...(workspaceRoot !== DOCKER_DEFAULT_WORKSPACE
+            ? [tmpfsDockerArg(workspaceRoot, sandboxUid, sandboxGid, tmpfsSize)]
+            : []),
+    ].flatMap((entry) => ["--tmpfs", entry]);
+    const dockerArgs = [
+        "run",
+        "--rm",
+        "--name",
+        containerName,
+        "--network",
+        typeof network.mode === "string" ? network.mode : "none",
+        "--cpus",
+        dockerCpu(resources.cpu),
+        "--memory",
+        memorySize,
+        "--memory-swap",
+        memorySize,
+        "--user",
+        `${sandboxUid}:${sandboxGid}`,
+        ...tmpfsArgs,
+        "--workdir",
+        DOCKER_RUNTIME_MOUNT,
+        "-v",
+        `${root}:/workbench-execution`,
+        "-v",
+        `${runtimeRoot}:${DOCKER_RUNTIME_MOUNT}:ro`,
+        "--env",
+        "HOME=/tmp",
+        "--env",
+        "USER=workbench",
+        "--env",
+        `WORKBENCH_WORKSPACE_ROOT=${workspaceRoot}`,
+        "--env",
+        `WORKBENCH_RUNTIME_IMPORT=${runtimeImport}`,
+        image,
+        "node",
+        runnerPath,
+        "/workbench-execution/request.json",
+        "/workbench-execution/response.json",
+    ];
+    const timeoutMs = Math.max(60_000, execution.policy.resources.timeoutMinutes * 60_000 + 30_000);
+    let dockerError = null;
+    try {
+        await runDockerSandboxProcess(spawn, dockerArgs, {
+            stdoutPath,
+            stderrPath,
+            timeoutMs,
+        });
+    }
+    catch (error) {
+        dockerError = error instanceof Error ? error.stack ?? error.message : String(error);
+    }
+    const responseText = await fs.readFile(responsePath, "utf8").catch(async (error) => {
+        const [stdout, stderr] = await Promise.all([
+            fs.readFile(stdoutPath, "utf8").catch(() => ""),
+            fs.readFile(stderrPath, "utf8").catch(() => ""),
+        ]);
+        const details = [
+            dockerError ? `Docker error: ${dockerError}` : null,
+            stdout.trim() ? `stdout: ${stdout.trim().slice(0, 4000)}` : null,
+            stderr.trim() ? `stderr: ${stderr.trim().slice(0, 4000)}` : null,
+        ].filter((entry) => Boolean(entry)).join(" ");
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Docker sandbox exited without a response: ${message}${details ? `. ${details}` : ""}`);
+    });
+    const response = JSON.parse(responseText);
+    if (!response.ok) {
+        throw new Error(typeof response.error === "string" ? response.error : "Sandbox adapter runner failed.");
+    }
+    if (!response.job || typeof response.job !== "object") {
+        throw new Error("Sandbox adapter runner response omitted job.");
+    }
+    return response.job;
+}
+function tmpfsDockerArg(pathname, uid, gid, size) {
+    return `${pathname}:rw,exec,uid=${uid},gid=${gid},mode=1777,size=${size}`;
+}
+function dockerExecutionWorkspaceRoot(execution) {
+    const metadata = asRuntimeRecord(execution.metadata);
+    const workdir = typeof metadata.workdir === "string" ? metadata.workdir.trim() : "";
+    if (!workdir || workdir === DOCKER_DEFAULT_WORKSPACE) {
+        return DOCKER_DEFAULT_WORKSPACE;
+    }
+    if (!isSafeDockerWorkspaceRoot(workdir)) {
+        return DOCKER_DEFAULT_WORKSPACE;
+    }
+    return workdir;
+}
+function isSafeDockerWorkspaceRoot(value) {
+    return value.startsWith("/") &&
+        value !== "/" &&
+        value !== DOCKER_RUNTIME_MOUNT &&
+        value !== "/workbench-execution" &&
+        !value.startsWith(`${DOCKER_RUNTIME_MOUNT}/`) &&
+        !value.startsWith("/workbench-execution/") &&
+        !/[\0\r\n:]/u.test(value);
+}
+async function destroyDockerSandbox(sandbox) {
+    const metadata = asRuntimeRecord(sandbox.metadata);
+    const root = typeof metadata.root === "string" ? metadata.root : null;
+    const containerName = typeof metadata.containerName === "string" ? metadata.containerName : null;
+    const [{ execFile }, fs, { promisify }] = await Promise.all([
+        importNodeModule(nodeBuiltin("child_process")),
+        importNodeModule(nodeBuiltin("fs/promises")),
+        importNodeModule(nodeBuiltin("util")),
+    ]);
+    const execFileAsync = promisify(execFile);
+    if (containerName) {
+        await execFileAsync("docker", ["rm", "-f", containerName], { maxBuffer: 1024 * 1024 }).catch(() => undefined);
+    }
+    if (root) {
+        await fs.rm(root, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+function runDockerSandboxProcess(spawn, args, options) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timedOut = false;
+        const progressPublishes = [];
+        const progressParser = createWorkbenchProgressStdoutParser((envelope) => {
+            progressPublishes.push(publishWorkbenchProgressStdoutEnvelope(envelope).catch(() => undefined));
+        });
+        const stdout = createWriteStream(options.stdoutPath);
+        const stderr = createWriteStream(options.stderrPath);
+        const child = spawn("docker", args, {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, options.timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout.write(chunk);
+            progressParser.write(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr.write(chunk);
+        });
+        const finish = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            progressParser.flush();
+            const stdoutClosed = new Promise((closeResolve) => stdout.end(closeResolve));
+            const stderrClosed = new Promise((closeResolve) => stderr.end(closeResolve));
+            Promise.allSettled([...progressPublishes, stdoutClosed, stderrClosed]).then(() => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        };
+        child.on("error", (error) => finish(error));
+        child.on("exit", (code, signal) => {
+            if (timedOut) {
+                finish(new Error(`Docker sandbox timed out after ${options.timeoutMs}ms.`));
+                return;
+            }
+            if (code === 0) {
+                finish();
+                return;
+            }
+            finish(new Error(code === null
+                ? `Docker sandbox exited from signal ${signal ?? "unknown"}.`
+                : `Docker sandbox exited with code ${code}.`));
+        });
+    });
+}
+function dockerNetworkConfigForExecution(execution) {
+    if (execution.policy.network.egress === "none") {
+        return { mode: "none", egress: "none", allowlistEnforced: true };
+    }
+    if (execution.policy.network.egress === "open") {
+        return { mode: "bridge", egress: "open", allowlistEnforced: true };
+    }
+    return {
+        mode: "bridge",
+        egress: "allowlist",
+        allow: [...(execution.policy.network.allow ?? [])],
+        allowlistEnforced: false,
+    };
+}
+function dockerContainerName(sandboxId) {
+    return `workbench-sandbox-${sandboxId}`.replace(/[^a-z0-9_.-]+/giu, "-").slice(0, 120);
+}
+function dockerCpu(value) {
+    return String(value);
+}
+function dockerSize(gib) {
+    return `${Math.ceil(gib * 1024)}m`;
+}
+function safeDockerImageSegment(value) {
+    return value.toLowerCase().replace(/[^a-z0-9_.-]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, 80) || "env";
+}
+async function prepareDockerRuntimePayload(workdir, execFileAsync, fs, path) {
+    const configured = process.env.WORKBENCH_DOCKER_RUNTIME_ROOT?.trim();
+    if (configured) {
+        return monorepoDockerPayload(configured);
+    }
+    const runtimeImage = process.env.WORKBENCH_DOCKER_RUNTIME_IMAGE?.trim();
+    if (!runtimeImage) {
+        return resolveLocalDockerRuntimePayload();
+    }
+    const runtimeImageId = await dockerImageId(runtimeImage, execFileAsync);
+    const cacheRoot = path.join(workdir, "workbench-docker-runtime", `${safeCacheSegment(runtimeImage)}-${safeCacheSegment(runtimeImageId).slice(0, 24)}`);
+    const marker = path.join(cacheRoot, ".workbench-core-ready");
+    try {
+        await fs.access(marker);
+        return monorepoDockerPayload(cacheRoot);
+    }
+    catch {
+        // Rebuild the cache below.
+    }
+    const tmpRoot = `${cacheRoot}.tmp-${Date.now().toString(36)}`;
+    const containerName = `workbench-core-${Date.now().toString(36)}`.replace(/[^a-z0-9_.-]+/giu, "-");
+    await fs.rm(tmpRoot, { recursive: true, force: true }).catch(() => undefined);
+    await fs.mkdir(tmpRoot, { recursive: true });
+    try {
+        await execFileAsync("docker", ["rm", "-f", containerName], { maxBuffer: 1024 * 1024 }).catch(() => undefined);
+        await execFileAsync("docker", ["create", "--name", containerName, runtimeImage, "true"], { maxBuffer: 5 * 1024 * 1024 });
+        await execFileAsync("docker", ["cp", `${containerName}:/app/.`, tmpRoot], { maxBuffer: 20 * 1024 * 1024 });
+        await fs.writeFile(path.join(tmpRoot, ".workbench-core-ready"), `${runtimeImage}\n${runtimeImageId}\n`);
+        await fs.rm(cacheRoot, { recursive: true, force: true }).catch(() => undefined);
+        await fs.rename(tmpRoot, cacheRoot);
+        return monorepoDockerPayload(cacheRoot);
+    }
+    finally {
+        await execFileAsync("docker", ["rm", "-f", containerName], { maxBuffer: 1024 * 1024 }).catch(() => undefined);
+        await fs.rm(tmpRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function dockerImageId(image, execFileAsync) {
+    const result = await execFileAsync("docker", ["image", "inspect", image, "--format", "{{.Id}}"], { maxBuffer: 1024 * 1024 });
+    const id = typeof result.stdout === "string" ? result.stdout.trim() : result.stdout?.toString("utf8").trim();
+    if (!id) {
+        throw new Error(`Docker image ${image} did not report an image id.`);
+    }
+    return id;
+}
+function safeCacheSegment(value) {
+    return value.replace(/[^a-z0-9_.-]+/giu, "-");
+}
+async function ensureDockerExecutionImage(image, execFileAsync) {
+    const imageExists = await execFileAsync("docker", ["image", "inspect", image], { maxBuffer: 1024 * 1024 })
+        .then(() => true, () => false);
+    if (imageExists) {
+        return;
+    }
+    const builtInDockerfile = localBuiltInDockerfileForImage(image);
+    if (builtInDockerfile) {
+        await execFileAsync("docker", [
+            "build",
+            "-t",
+            image,
+            "-f",
+            builtInDockerfile,
+            path.dirname(builtInDockerfile),
+        ], { maxBuffer: 20 * 1024 * 1024 });
+        return;
+    }
+    await execFileAsync("docker", ["pull", image], { maxBuffer: 20 * 1024 * 1024 });
+}
+function localBuiltInDockerfileForImage(image) {
+    if (hasRegistryHost(image)) {
+        return null;
+    }
+    const dockerfile = BUILT_IN_ENVIRONMENT_IMAGES[image];
+    if (!dockerfile) {
+        return null;
+    }
+    return path.join(resolveLocalDockerRuntimePayload().builtInDockerfileRoot, dockerfile.replace(/^products\/workbench\/environments\//u, ""));
+}
+function hasRegistryHost(image) {
+    const first = image.split("/")[0] ?? "";
+    return first === "localhost" || first.includes(".") || first.includes(":");
+}
+function resolveLocalDockerRuntimePayload() {
+    const sourceRoot = findDockerSourceRoot();
+    if (sourceRoot) {
+        return monorepoDockerPayload(sourceRoot);
+    }
+    const packagePayload = findInstalledPackageDockerPayload();
+    if (packagePayload) {
+        return packagePayload;
+    }
+    throw new Error(`Could not resolve Workbench runtime payload from ${process.cwd()}. Run from the monorepo checkout or install the published @workbench-ai/workbench package.`);
+}
+function monorepoDockerPayload(root) {
+    return {
+        mountRoot: root,
+        runnerPath: `${DOCKER_RUNTIME_MOUNT}/products/workbench/packages/core/worker/sandbox-adapter-runner.cjs`,
+        runtimeImport: `${DOCKER_RUNTIME_MOUNT}/products/workbench/packages/core/src/index.ts`,
+        builtInDockerfileRoot: path.join(root, "products/workbench/environments"),
+    };
+}
+function findInstalledPackageDockerPayload() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const packageRoot = path.resolve(moduleDir, "../..");
+    const nodeModulesRoot = findAncestorNamed(packageRoot, "node_modules");
+    if (!nodeModulesRoot) {
+        return null;
+    }
+    if (existsSync(path.join(packageRoot, "worker/sandbox-adapter-runner.cjs")) &&
+        existsSync(path.join(packageRoot, "dist/index.js")) &&
+        existsSync(path.join(packageRoot, "environments/node-22/Dockerfile"))) {
+        return {
+            mountRoot: path.dirname(nodeModulesRoot),
+            runnerPath: `${DOCKER_RUNTIME_MOUNT}/node_modules/@workbench-ai/workbench-core/worker/sandbox-adapter-runner.cjs`,
+            runtimeImport: `${DOCKER_RUNTIME_MOUNT}/node_modules/@workbench-ai/workbench-core/dist/index.js`,
+            builtInDockerfileRoot: path.join(packageRoot, "environments"),
+        };
+    }
+    return null;
+}
+function findAncestorNamed(start, name) {
+    let current = start;
+    for (;;) {
+        if (path.basename(current) === name) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function findDockerSourceRoot() {
+    const configured = process.env.WORKBENCH_DOCKER_SOURCE_ROOT?.trim();
+    if (configured) {
+        return configured;
+    }
+    const cwd = process.cwd();
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const subjects = [
+        cwd,
+        path.resolve(cwd, ".."),
+        path.resolve(cwd, "../.."),
+        path.resolve(cwd, "../../.."),
+        path.resolve(moduleDir, "../../../../../.."),
+    ];
+    for (const subject of subjects) {
+        if (existsSync(path.join(subject, "products/workbench/packages/core/worker/sandbox-adapter-runner.cjs")) &&
+            existsSync(path.join(subject, "products/workbench/packages/core/src/index.ts"))) {
+            return subject;
+        }
+    }
+    return null;
+}
+function readRequiredMetadataString(metadata, key, backend) {
+    const value = metadata[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${backend} sandbox metadata is missing ${key}.`);
+    }
+    return value;
+}
+function readRequiredMetadataNumber(metadata, key, backend) {
+    const value = metadata[key];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${backend} sandbox metadata is missing ${key}.`);
+    }
+    return value;
+}
+function dockerSandboxUser() {
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    const gid = typeof process.getgid === "function" ? process.getgid() : null;
+    if (typeof uid === "number" && Number.isInteger(uid) && uid > 0) {
+        return {
+            uid,
+            gid: typeof gid === "number" && Number.isInteger(gid) && gid >= 0 ? gid : uid,
+        };
+    }
+    return { uid: 1000, gid: 1000 };
+}
+async function alignDockerSandboxPath(fs, targetPath, user, privateMode, fallbackMode) {
+    await fs.chmod(targetPath, privateMode).catch(() => undefined);
+    const currentUid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (currentUid === user.uid) {
+        return;
+    }
+    await fs.chown(targetPath, user.uid, user.gid).catch(async () => {
+        await fs.chmod(targetPath, fallbackMode).catch(() => undefined);
+    });
+}

package/dist/sandbox-backends/index.d.ts

@@ -0,0 +1,37 @@
+import type { WorkbenchExecutionRuntimeInput } from "../execution-runtime-types.ts";
+import type { SandboxBackendCapabilities, SandboxExecutionFileStore, SandboxPlane } from "../sandbox-plane.ts";
+import { type WorkbenchSandboxProviderName } from "./names.ts";
+export { DOCKER_SANDBOX_BACKEND, resolveWorkbenchSandboxProviderName, type WorkbenchSandboxProviderName, } from "./names.ts";
+export { createDockerSandboxBackendDescriptor, createDockerSandboxPlane, } from "./docker.ts";
+export interface SandboxHostHealthExpectation {
+    provider: WorkbenchSandboxProviderName;
+    backend: string;
+    capabilities: SandboxBackendCapabilities;
+}
+export interface SandboxProviderRequestedResources {
+    cpu: number;
+    memoryGb: number;
+    diskGb?: number;
+    timeoutMinutes?: number;
+}
+export interface SandboxProviderHostCost {
+    cpu: number;
+    memoryGb: number;
+    diskGb: number;
+}
+export interface SandboxProviderLeaseRequest {
+    scope: string;
+    units: number;
+}
+export interface SandboxProviderAdmission {
+    provider: WorkbenchSandboxProviderName;
+    hostCost: SandboxProviderHostCost;
+    providerLeases: SandboxProviderLeaseRequest[];
+}
+export declare function createSandboxBackendPlaneForProvider(provider: string, args: WorkbenchExecutionRuntimeInput, startedAt: string, fileStore: SandboxExecutionFileStore): SandboxPlane;
+export declare function sandboxHostHealthExpectationForProvider(provider: WorkbenchSandboxProviderName): SandboxHostHealthExpectation;
+export declare function assertSandboxHostHealthForProvider(value: unknown, provider: WorkbenchSandboxProviderName): void;
+export declare function sandboxProviderDefaultMaxConcurrentJobs(_provider: WorkbenchSandboxProviderName): number | null;
+export declare function sandboxProviderAdmissionForResources(provider: WorkbenchSandboxProviderName, resources: SandboxProviderRequestedResources): SandboxProviderAdmission;
+export declare function sandboxProviderLeaseScope(provider: WorkbenchSandboxProviderName): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox-backends/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox-backends/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,0BAA0B,EAE1B,yBAAyB,EACzB,YAAY,EACb,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EAEL,KAAK,4BAA4B,EAElC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,mCAAmC,EACnC,KAAK,4BAA4B,GAClC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,0BAA0B,CAAC;CAC1C;AAED,MAAM,WAAW,iCAAiC;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,4BAA4B,CAAC;IACvC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,cAAc,EAAE,2BAA2B,EAAE,CAAC;CAC/C;AAED,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,8BAA8B,EACpC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,yBAAyB,GACnC,YAAY,CAMd;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,4BAA4B,GACrC,4BAA4B,CAS9B;AAED,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,4BAA4B,GACrC,IAAI,CAeN;AAED,wBAAgB,uCAAuC,CACrD,SAAS,EAAE,4BAA4B,GACtC,MAAM,GAAG,IAAI,CAEf;AAED,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,4BAA4B,EACtC,SAAS,EAAE,iCAAiC,GAC3C,wBAAwB,CAkB1B;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,4BAA4B,GACrC,MAAM,CAER"}