@namzu/sandbox 1.1.0

package/dist/backends/docker/index.js

@@ -0,0 +1,645 @@
+/**
+ * `container:docker` backend.
+ *
+ * Spawns one Docker container per `Sandbox` instance via the
+ * `docker` CLI (no node-docker SDK dependency — keeps the package
+ * thin). The container runs the small HTTP worker shipped under
+ * `packages/sandbox/worker/server.js`; the host adapter talks to
+ * it on `127.0.0.1:<random-port>`.
+ *
+ * One container per sandbox, not one per `exec` call: keeps cold-
+ * start out of the hot path. The container goes away in
+ * `destroy()`.
+ *
+ * Trust model:
+ *  - Container is the trust boundary; everything inside is treated
+ *    as untrusted code.
+ *  - Worker only listens on loopback inside its own netns; the
+ *    host adapter reaches it via Docker's port-forward.
+ *  - Outbound network from the worker is restricted by host-side
+ *    firewall config (see {@link DockerBackendConfig.network}) plus
+ *    the egress proxy when one is configured (P3.2).
+ */
+import { spawn } from 'node:child_process';
+import { SANDBOX_DEFAULT_OUTPUTS_PATH, SANDBOX_DEFAULT_SCRATCH_PATH, SANDBOX_DEFAULT_SKILLS_PARENT, SANDBOX_DEFAULT_TOOL_RESULTS_PATH, SANDBOX_DEFAULT_TRANSCRIPTS_PATH, SANDBOX_DEFAULT_UPLOADS_PATH, } from '@namzu/sdk';
+import { ContainerSandboxLayoutValidationError, } from '../../index.js';
+const DEFAULT_DOCKER_BINARY = 'docker';
+const DEFAULT_READY_POLL_MS = 100;
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+const WORKER_PORT_INSIDE_CONTAINER = 2024;
+/**
+ * Build a {@link SandboxBackend} backed by Docker. Construction is
+ * synchronous; the actual container spawns on the first
+ * `create()` call.
+ */
+export function buildDockerBackend(config) {
+    return {
+        tier: 'container',
+        name: 'docker',
+        async create(options) {
+            return await spawnDockerSandbox(config, options);
+        },
+    };
+}
+async function spawnDockerSandbox(config, options) {
+    const resolvedLayout = config.layout;
+    const id = generateSandboxId();
+    const docker = config.dockerBinary ?? DEFAULT_DOCKER_BINARY;
+    const network = config.network ?? 'none';
+    const runtime = config.runtime;
+    const hostReachability = config.hostReachability ?? 'host-port';
+    const containerName = `namzu-sandbox-${id}`;
+    // All bind sources come from the consumer-supplied layout. The
+    // backend never allocates host directories and never removes them
+    // — that pre-existing single-mount mkdtemp path was the source of
+    // the EACCES bug in sibling-container setups (the consumer owns
+    // the host filesystem, the spawned backend can't reach it from
+    // inside its own container's mount namespace). Clean break.
+    let containerStarted = false;
+    async function cleanupOnFailure() {
+        if (containerStarted) {
+            await runOnceQuiet(docker, ['rm', '-f', containerName]);
+        }
+    }
+    let hostPort;
+    let baseUrl;
+    // `outputs` is required by validation, so its containerPath is
+    // always available — the worker uses it as its workspace root.
+    const rootDir = resolvedLayout.outputs.containerPath;
+    try {
+        // Let Docker pick the host port instead of pre-reserving one
+        // in this process. The reservePort()-then-publish-fixed-port
+        // pattern had a TOCTOU window: the OS could hand the port to
+        // another process between our `server.close()` and Docker's
+        // `bind()`. Letting Docker pick (`--publish-all`) and reading
+        // the mapping back via `docker inspect` removes the race.
+        const args = [
+            'run',
+            '--detach',
+            '--rm',
+            '--name',
+            containerName,
+            '--network',
+            network,
+        ];
+        // `--label key=value` flags. Validate first — an empty key or
+        // a key containing `=` would silently produce a malformed
+        // label that downstream `docker ps --filter label=…` queries
+        // could not match reliably. Throw before the spawn so misuse
+        // surfaces during construction, not as a mysterious "container
+        // has no labels" later.
+        if (config.labels) {
+            for (const [key, value] of Object.entries(config.labels)) {
+                if (!key || key.includes('=')) {
+                    throw new Error(`docker label key ${JSON.stringify(key)} is invalid (empty or contains '=')`);
+                }
+                args.push('--label', `${key}=${value}`);
+            }
+        }
+        args.push(...renderLayoutMountArgs(resolvedLayout));
+        // Forward only the workspace root so the worker's lexical
+        // resolver agrees with the bind target. The full layout used
+        // to ride along as `NAMZU_SANDBOX_LAYOUT`, but the worker
+        // never branched on it; the manifest's only consumer was a
+        // log line. A skill loader that needs the manifest will
+        // write it to a bind path the worker reads at startup —
+        // avoids env-size limits, keeps the wire shape minimal.
+        args.push('--env', `NAMZU_SANDBOX_WORKSPACE=${rootDir}`);
+        args.push('--env', `NAMZU_SANDBOX_READ_ROOTS=${renderLayoutReadRootsEnv(resolvedLayout)}`);
+        args.push('--env', `NAMZU_SANDBOX_WRITE_ROOTS=${renderLayoutWriteRootsEnv(resolvedLayout)}`);
+        // Only publish a host port when the consumer is going to reach
+        // the worker through the docker host's loopback (CLI / direct
+        // dev). For `container-network` reachability we leave the port
+        // unpublished — sibling containers reach the worker by its DNS
+        // name on the shared bridge, no host port required.
+        if (hostReachability === 'host-port') {
+            args.push('--publish', `127.0.0.1::${WORKER_PORT_INSIDE_CONTAINER}`);
+        }
+        if (runtime) {
+            args.push('--runtime', runtime);
+        }
+        if (options.memoryLimitMb && options.memoryLimitMb > 0) {
+            args.push('--memory', `${options.memoryLimitMb}m`);
+        }
+        if (options.maxProcesses && options.maxProcesses > 0) {
+            args.push('--pids-limit', String(options.maxProcesses));
+        }
+        for (const [key, value] of Object.entries(options.env ?? {})) {
+            args.push('--env', `${key}=${value}`);
+        }
+        args.push(config.image);
+        await runOnce(docker, args);
+        containerStarted = true;
+        if (hostReachability === 'host-port') {
+            hostPort = await readMappedPort(docker, containerName);
+            baseUrl = `http://127.0.0.1:${hostPort}`;
+            await waitForWorkerReady(baseUrl, config.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS, config.readyPollIntervalMs ?? DEFAULT_READY_POLL_MS);
+        }
+        else {
+            // container-network: connect by container DNS name on the
+            // shared bridge. No host port to read; the SDK consumer is
+            // itself a container on the same bridge.
+            baseUrl = `http://${containerName}:${WORKER_PORT_INSIDE_CONTAINER}`;
+            await waitForWorkerReady(baseUrl, config.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS, config.readyPollIntervalMs ?? DEFAULT_READY_POLL_MS);
+        }
+    }
+    catch (err) {
+        await cleanupOnFailure();
+        throw err;
+    }
+    let status = 'ready';
+    return {
+        id,
+        get status() {
+            return status;
+        },
+        rootDir,
+        environment: detectEnvironment(),
+        async exec(command, argv, opts) {
+            status = 'busy';
+            try {
+                return await execViaWorker(baseUrl, command, argv, opts);
+            }
+            finally {
+                status = 'ready';
+            }
+        },
+        async writeFile(path, content) {
+            const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+            let res;
+            try {
+                res = await fetch(`${baseUrl}/write-file`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({
+                        path,
+                        content: buf.toString('base64'),
+                        encoding: 'base64',
+                    }),
+                });
+            }
+            catch (err) {
+                const cause = err instanceof Error ? err.cause : undefined;
+                const causeMsg = cause instanceof Error
+                    ? `${cause.message}${cause.code ? ` (${cause.code})` : ''}`
+                    : cause
+                        ? String(cause)
+                        : 'unknown';
+                throw new Error(`namzu-sandbox /write-file fetch failed (baseUrl=${baseUrl}, path=${path}): ${err instanceof Error ? err.message : String(err)} — cause: ${causeMsg}`, { cause: err });
+            }
+            if (!res.ok) {
+                throw new Error(`write-file failed: HTTP ${res.status} ${await res.text()}`);
+            }
+        },
+        async readFile(path) {
+            const res = await fetch(`${baseUrl}/read-file`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ path, encoding: 'base64' }),
+            });
+            if (!res.ok) {
+                throw new Error(`read-file failed: HTTP ${res.status} ${await res.text()}`);
+            }
+            const json = (await res.json());
+            if (!json.ok || typeof json.content !== 'string') {
+                throw new Error(json.error ?? 'read-file: no content');
+            }
+            return Buffer.from(json.content, 'base64');
+        },
+        async listFiles(rootPath) {
+            return await listFilesViaWorker(baseUrl, rootPath);
+        },
+        async destroy() {
+            status = 'destroyed';
+            await runOnceQuiet(docker, ['rm', '-f', containerName]);
+            // Backend never allocates host paths — every bind source
+            // comes from the consumer-supplied layout. Container
+            // teardown is sufficient; the consumer's own lifecycle
+            // owns each `hostPath`.
+        },
+    };
+}
+/**
+ * Ask Docker which host port it bound to the worker port. Used
+ * instead of the pre-reserve-then-publish pattern (which had a
+ * TOCTOU race window between this process closing the listening
+ * socket and Docker's bind picking the same port — another
+ * process could grab it in the meantime). Letting Docker
+ * allocate and reading the mapping back is race-free.
+ */
+async function readMappedPort(docker, containerName) {
+    const inspectOutput = await runOnce(docker, [
+        'inspect',
+        '--format',
+        `{{(index (index .NetworkSettings.Ports "${WORKER_PORT_INSIDE_CONTAINER}/tcp") 0).HostPort}}`,
+        containerName,
+    ]);
+    const port = Number(inspectOutput.trim());
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`docker inspect returned no usable host port mapping for ${containerName}: '${inspectOutput}'`);
+    }
+    return port;
+}
+async function execViaWorker(baseUrl, command, argv, opts) {
+    const start = Date.now();
+    let res;
+    try {
+        res = await fetch(`${baseUrl}/execute`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                command,
+                args: argv ?? [],
+                cwd: opts?.cwd,
+                env: opts?.env,
+                timeoutMs: opts?.timeout,
+            }),
+        });
+    }
+    catch (err) {
+        // Surface the underlying transport error (DNS, ECONNREFUSED,
+        // socket-hangup, …) instead of the generic "fetch failed" the
+        // undici client throws. Without `cause`, ops cannot tell whether
+        // the worker died, the bridge dropped, or something else.
+        const cause = err instanceof Error ? err.cause : undefined;
+        const causeMsg = cause instanceof Error
+            ? `${cause.message}${cause.code ? ` (${cause.code})` : ''}`
+            : cause
+                ? String(cause)
+                : 'unknown';
+        throw new Error(`namzu-sandbox /execute fetch failed (baseUrl=${baseUrl}): ${err instanceof Error ? err.message : String(err)} — cause: ${causeMsg}`, { cause: err });
+    }
+    if (!res.ok || !res.body) {
+        throw new Error(`execute failed: HTTP ${res.status} ${await res.text()}`);
+    }
+    let stdout = '';
+    let stderr = '';
+    let exitCode = -1;
+    let timedOut = false;
+    let signal;
+    const decoder = new TextDecoder();
+    const reader = res.body.getReader();
+    let buffered = '';
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buffered += decoder.decode(value, { stream: true });
+        let newlineIdx = buffered.indexOf('\n');
+        while (newlineIdx !== -1) {
+            const line = buffered.slice(0, newlineIdx).trim();
+            buffered = buffered.slice(newlineIdx + 1);
+            if (line) {
+                try {
+                    const event = JSON.parse(line);
+                    if (event.type === 'stdout_delta')
+                        stdout += event.data;
+                    else if (event.type === 'stderr_delta')
+                        stderr += event.data;
+                    else if (event.type === 'result') {
+                        exitCode = event.exitCode;
+                        timedOut = event.timedOut;
+                    }
+                    else if (event.type === 'error') {
+                        throw new Error(event.error);
+                    }
+                }
+                catch (err) {
+                    if (err instanceof SyntaxError) {
+                        // Ignore malformed lines from the worker.
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+            newlineIdx = buffered.indexOf('\n');
+        }
+    }
+    return {
+        exitCode,
+        stdout,
+        stderr,
+        ...(signal ? { signal } : {}),
+        timedOut,
+        durationMs: Date.now() - start,
+    };
+}
+/**
+ * Recursively list regular files under `rootPath` by shelling out to
+ * the worker's `find` (GNU find on the Debian-based reference image).
+ * `-printf` emits one `<path>\t<size>` line per file; any other
+ * non-zero exit (notably `find: '<root>': No such file or directory`)
+ * is mapped to "empty listing" because the agent legitimately may not
+ * have produced anything in `rootPath` yet.
+ */
+async function listFilesViaWorker(baseUrl, rootPath) {
+    const result = await execViaWorker(baseUrl, 'find', [rootPath, '-type', 'f', '-printf', '%p\t%s\n'], undefined);
+    if (result.exitCode !== 0) {
+        // `find` returns non-zero when the root is missing — that just
+        // means "no outputs yet". Other failures (permission errors,
+        // the rare case `find` itself is missing) also fall through to
+        // the empty listing rather than blowing up the caller's drain
+        // flow; the deliverables collector treats absence as "done".
+        return [];
+    }
+    const entries = [];
+    for (const rawLine of result.stdout.split('\n')) {
+        if (!rawLine)
+            continue;
+        const tab = rawLine.indexOf('\t');
+        if (tab < 0)
+            continue;
+        const path = rawLine.slice(0, tab);
+        const size = Number.parseInt(rawLine.slice(tab + 1), 10);
+        if (!path || !Number.isFinite(size))
+            continue;
+        entries.push({ path, size });
+    }
+    return entries;
+}
+function detectEnvironment() {
+    const platform = process.platform;
+    if (platform === 'darwin')
+        return 'macos-seatbelt';
+    if (platform === 'linux')
+        return 'linux-namespace';
+    return 'basic';
+}
+function generateSandboxId() {
+    const random = Math.random().toString(36).slice(2, 10);
+    return `sandbox_${Date.now().toString(36)}_${random}`;
+}
+async function waitForWorkerReady(baseUrl, timeoutMs, pollMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`${baseUrl}/healthz`);
+            if (res.ok)
+                return;
+            lastError = new Error(`healthz HTTP ${res.status}`);
+        }
+        catch (err) {
+            lastError = err;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+    throw new Error(`namzu-sandbox worker did not become ready within ${timeoutMs}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+function runOnce(binary, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve(stdout.trim());
+            else
+                reject(new Error(`${binary} ${args.join(' ')} exited ${code}: ${stderr.trim()}`));
+        });
+    });
+}
+function runOnceQuiet(binary, args) {
+    return new Promise((resolve) => {
+        const child = spawn(binary, args, { stdio: 'ignore' });
+        child.on('error', () => resolve());
+        child.on('close', () => resolve());
+    });
+}
+/**
+ * Skill IDs are user-controlled strings that end up in the in-
+ * container path (`/mnt/skills/<id>`) and on a `--volume` flag the
+ * shell does not see (we use `spawn` argv, not a shell pipeline). So
+ * the regex doesn't have to defend against shell metacharacters — it
+ * exists to keep paths legible (no whitespace, no `..`, no slashes
+ * to escape the `/mnt/skills` prefix). The set is the same shape git
+ * accepts for ref names: alphanumerics, `_`, `-`, `.`. Letting `.`
+ * through enables `pdf-tools.v2`-style versioning; rejecting `..`
+ * specifically guards path traversal even though Docker's bind
+ * resolution doesn't follow it.
+ */
+const SKILL_ID_REGEX = /^[a-zA-Z0-9_.-]+$/;
+/**
+ * Validate and resolve a {@link ContainerSandboxLayout}. Returns a
+ * {@link ResolvedContainerSandboxLayout} with every container path
+ * filled in; throws {@link ContainerSandboxLayoutValidationError}
+ * collecting every violation in one pass.
+ *
+ * Called once at provider construction (`createSandboxProvider`).
+ * Validation surfaces synchronously during host wiring; nothing
+ * downstream re-validates per `provider.create()` call.
+ *
+ * Exported for tests so the validation rules are pinned by golden-
+ * value assertions rather than only exercised through the spawn path.
+ */
+export function resolveLayout(layout) {
+    const reasons = [];
+    // Outputs is required — without it the model has no place to
+    // persist work past container teardown, and the worker has no
+    // rooted workspace for its path resolver. The SDK type marks
+    // outputs required too, but the public type can be circumvented
+    // with `as` casts; runtime check is the contract.
+    if (!layout.outputs) {
+        reasons.push('`outputs` is required (deliverables surface). Pass `layout.outputs.source = { type: "hostDir", hostPath: "..." }`.');
+    }
+    // Skill IDs: regex + substring `..` reject + duplicate check.
+    // Run even if `outputs` is missing so the consumer sees every
+    // problem in one pass — fix-then-rerun loops at this layer are
+    // cheap to avoid.
+    //
+    // Why the substring `..` reject on top of the regex: the regex
+    // `[a-zA-Z0-9_.-]` legitimately allows `.` (so ids like
+    // `pdf-tools.v2` work), but `..` (or any embedded `..` like
+    // `foo..bar`) is a path-traversal segment that, when
+    // interpolated into the default container path
+    // `/mnt/skills/<id>`, lifts the bind out of the skills parent.
+    // Reject any `..` substring outright — there is no legitimate
+    // skill-id shape with consecutive dots.
+    const skillIds = new Set();
+    if (layout.skills) {
+        for (const skill of layout.skills) {
+            if (!SKILL_ID_REGEX.test(skill.id)) {
+                reasons.push(`skill id ${JSON.stringify(skill.id)} contains characters outside [a-zA-Z0-9_.-]`);
+            }
+            else if (skill.id.includes('..')) {
+                reasons.push(`skill id ${JSON.stringify(skill.id)} contains a path-traversal segment ('..')`);
+            }
+            else if (skillIds.has(skill.id)) {
+                reasons.push(`duplicate skill id ${JSON.stringify(skill.id)}`);
+            }
+            else {
+                skillIds.add(skill.id);
+            }
+        }
+    }
+    // Resolve container paths now (before duplicate check) so
+    // duplicate detection sees the actual mount targets, including
+    // defaults applied when `containerPath` is omitted. Defaults
+    // come from `@namzu/sdk`'s exported constants so a Vandal prompt
+    // template generator and the backend agree on a single source of
+    // truth.
+    const resolvedOutputs = layout.outputs
+        ? {
+            source: layout.outputs.source,
+            containerPath: layout.outputs.containerPath ?? SANDBOX_DEFAULT_OUTPUTS_PATH,
+        }
+        : undefined;
+    const resolvedUploads = layout.uploads
+        ? {
+            source: layout.uploads.source,
+            containerPath: layout.uploads.containerPath ?? SANDBOX_DEFAULT_UPLOADS_PATH,
+        }
+        : undefined;
+    const resolvedScratch = layout.scratch
+        ? {
+            source: layout.scratch.source,
+            containerPath: layout.scratch.containerPath ?? SANDBOX_DEFAULT_SCRATCH_PATH,
+        }
+        : undefined;
+    const resolvedToolResults = layout.toolResults
+        ? {
+            source: layout.toolResults.source,
+            containerPath: layout.toolResults.containerPath ?? SANDBOX_DEFAULT_TOOL_RESULTS_PATH,
+        }
+        : undefined;
+    const resolvedTranscripts = layout.transcripts
+        ? {
+            source: layout.transcripts.source,
+            containerPath: layout.transcripts.containerPath ?? SANDBOX_DEFAULT_TRANSCRIPTS_PATH,
+        }
+        : undefined;
+    const resolvedSkills = layout.skills?.map((s) => ({
+        id: s.id,
+        source: s.source,
+        containerPath: s.containerPath ?? `${SANDBOX_DEFAULT_SKILLS_PARENT}/${s.id}`,
+    }));
+    // Duplicate `containerPath` detection across every mount. Two
+    // binds at the same path is a Docker error at the daemon level,
+    // but the daemon's error surfaces inside the container creation
+    // failure mode — much later, with less context. Catch it here.
+    const containerPathOwners = new Map();
+    function track(label, p) {
+        if (!p)
+            return;
+        const prior = containerPathOwners.get(p);
+        if (prior) {
+            reasons.push(`duplicate containerPath ${JSON.stringify(p)} declared by both ${prior} and ${label}`);
+        }
+        else {
+            containerPathOwners.set(p, label);
+        }
+    }
+    track('outputs', resolvedOutputs?.containerPath);
+    track('uploads', resolvedUploads?.containerPath);
+    track('scratch', resolvedScratch?.containerPath);
+    track('toolResults', resolvedToolResults?.containerPath);
+    track('transcripts', resolvedTranscripts?.containerPath);
+    if (resolvedSkills) {
+        for (const skill of resolvedSkills) {
+            track(`skill:${skill.id}`, skill.containerPath);
+        }
+    }
+    if (reasons.length > 0) {
+        throw new ContainerSandboxLayoutValidationError(reasons);
+    }
+    // `outputs` presence was checked above; the non-null assertion is
+    // safe because the validation throws on missing.
+    const resolved = {
+        // biome-ignore lint/style/noNonNullAssertion: validation enforces presence
+        outputs: resolvedOutputs,
+        ...(resolvedUploads ? { uploads: resolvedUploads } : {}),
+        ...(resolvedScratch ? { scratch: resolvedScratch } : {}),
+        ...(resolvedToolResults ? { toolResults: resolvedToolResults } : {}),
+        ...(resolvedTranscripts ? { transcripts: resolvedTranscripts } : {}),
+        ...(resolvedSkills && resolvedSkills.length > 0 ? { skills: resolvedSkills } : {}),
+    };
+    return resolved;
+}
+/**
+ * Render `--volume` flags for a {@link ResolvedContainerSandboxLayout}. Order
+ * is stable (outputs rw, uploads ro, toolResults ro, skills ro,
+ * transcripts ro) so the test golden values stay deterministic.
+ *
+ * Today every `ContainerSandboxMountSource` is `{ type: 'hostDir', hostPath }`.
+ * When future variants land (squashfs / managed volumes), this
+ * function gains a discriminator switch; the single-variant union
+ * keeps tomorrow's exhaustiveness check honest by giving us a
+ * `type` field to switch on without renaming the call sites.
+ */
+/**
+ * Narrow a {@link ContainerSandboxMountSource} to the `hostDir`
+ * variant for backends that only know how to bind-mount from a host
+ * filesystem path (docker, podman, plain Firecracker virtio-fs). Any
+ * other variant (e.g. `azureFileShare` consumed by the ACI backend)
+ * is a hard configuration mismatch — throw at spawn time rather than
+ * render a malformed `--volume` flag the daemon would reject with a
+ * confusing message.
+ */
+function requireHostDir(source, label) {
+    if (source.type !== 'hostDir') {
+        throw new Error(`docker backend cannot consume mount source type ${JSON.stringify(source.type)} for ${label}; expected 'hostDir'. The non-hostDir variants (e.g. 'azureFileShare') belong to managed-container backends.`);
+    }
+    return source;
+}
+export function renderLayoutMountArgs(layout) {
+    const args = [];
+    const outputs = requireHostDir(layout.outputs.source, 'outputs');
+    args.push('--volume', `${outputs.hostPath}:${layout.outputs.containerPath}:rw`);
+    if (layout.uploads) {
+        const uploads = requireHostDir(layout.uploads.source, 'uploads');
+        args.push('--volume', `${uploads.hostPath}:${layout.uploads.containerPath}:ro`);
+    }
+    if (layout.scratch) {
+        // Scratch is RW so the agent can read its own intermediate
+        // drafts back. It is NOT visible to the deliverables collector
+        // because the host directory it binds is a sibling of, not a
+        // child of, the outputs hostPath.
+        const scratch = requireHostDir(layout.scratch.source, 'scratch');
+        args.push('--volume', `${scratch.hostPath}:${layout.scratch.containerPath}:rw`);
+    }
+    if (layout.toolResults) {
+        const toolResults = requireHostDir(layout.toolResults.source, 'toolResults');
+        args.push('--volume', `${toolResults.hostPath}:${layout.toolResults.containerPath}:ro`);
+    }
+    if (layout.skills) {
+        for (const skill of layout.skills) {
+            const skillSrc = requireHostDir(skill.source, `skill ${skill.id}`);
+            args.push('--volume', `${skillSrc.hostPath}:${skill.containerPath}:ro`);
+        }
+    }
+    if (layout.transcripts) {
+        const transcripts = requireHostDir(layout.transcripts.source, 'transcripts');
+        args.push('--volume', `${transcripts.hostPath}:${layout.transcripts.containerPath}:ro`);
+    }
+    return args;
+}
+export function renderLayoutReadRootsEnv(layout) {
+    const roots = [
+        layout.outputs.containerPath,
+        layout.uploads?.containerPath,
+        layout.scratch?.containerPath,
+        layout.toolResults?.containerPath,
+        layout.transcripts?.containerPath,
+        ...(layout.skills?.map((skill) => skill.containerPath) ?? []),
+    ].filter((root) => Boolean(root));
+    return Array.from(new Set(roots)).join(':');
+}
+/**
+ * Writable container roots. Only the RW mounts go here — uploads,
+ * tool-results, transcripts, and skills are read-only and must stay
+ * out of WRITE_ROOTS or the agent's `write`/`append` could clobber
+ * source files the host considers immutable.
+ */
+export function renderLayoutWriteRootsEnv(layout) {
+    const roots = [layout.outputs.containerPath, layout.scratch?.containerPath].filter((root) => Boolean(root));
+    return Array.from(new Set(roots)).join(':');
+}
+//# sourceMappingURL=index.js.map