@smithers-orchestrator/sandbox 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@smithers-orchestrator/sandbox",
+  "version": "0.16.0",
+  "description": "Sandbox bundle, execution, and transport integration for Smithers",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@smithers-orchestrator/components": "0.16.0",
+    "@smithers-orchestrator/driver": "0.16.0",
+    "@smithers-orchestrator/errors": "0.16.0",
+    "@smithers-orchestrator/graph": "0.16.0",
+    "@smithers-orchestrator/db": "0.16.0",
+    "@smithers-orchestrator/scheduler": "0.16.0",
+    "@smithers-orchestrator/observability": "0.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsup --dts-only",
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/ExecuteSandboxOptions.ts

@@ -0,0 +1,18 @@
+import type { SmithersWorkflow } from "@smithers-orchestrator/components/SmithersWorkflow";
+import type { ChildWorkflowDefinition } from "@smithers-orchestrator/engine/child-workflow";
+import type { SandboxRuntime } from "./SandboxRuntime.ts";
+
+export type ExecuteSandboxOptions = {
+    parentWorkflow?: SmithersWorkflow<unknown>;
+    sandboxId: string;
+    runtime?: SandboxRuntime;
+    workflow: ChildWorkflowDefinition;
+    input?: unknown;
+    rootDir: string;
+    allowNetwork: boolean;
+    maxOutputBytes: number;
+    toolTimeoutMs: number;
+    reviewDiffs?: boolean;
+    autoAcceptDiffs?: boolean;
+    config?: Record<string, unknown>;
+};

package/src/SandboxBundleManifest.ts

@@ -0,0 +1,6 @@
+export type SandboxBundleManifest = {
+    outputs: unknown;
+    status: "finished" | "failed" | "cancelled";
+    runId?: string;
+    patches?: string[];
+};

package/src/SandboxBundleResult.ts

@@ -0,0 +1,3 @@
+export type SandboxBundleResult = {
+    bundlePath: string;
+};

package/src/SandboxHandle.ts

@@ -0,0 +1,12 @@
+import type { SandboxRuntime } from "./SandboxRuntime.ts";
+
+export type SandboxHandle = {
+    runtime: SandboxRuntime;
+    runId: string;
+    sandboxId: string;
+    sandboxRoot: string;
+    requestPath: string;
+    resultPath: string;
+    containerId?: string;
+    workspaceId?: string;
+};

package/src/SandboxRuntime.ts

@@ -0,0 +1 @@
+export type SandboxRuntime = "bubblewrap" | "docker" | "codeplane";

package/src/SandboxTransportConfig.ts

@@ -0,0 +1,9 @@
+import type { SandboxRuntime } from "./SandboxRuntime.ts";
+
+export type SandboxTransportConfig = {
+    runId: string;
+    sandboxId: string;
+    runtime: SandboxRuntime;
+    rootDir: string;
+    image?: string;
+};

package/src/SandboxTransportService.ts

@@ -0,0 +1,15 @@
+import type { Effect } from "effect";
+import type { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import type { SandboxTransportConfig } from "./SandboxTransportConfig.ts";
+import type { SandboxHandle } from "./SandboxHandle.ts";
+import type { SandboxBundleResult } from "./SandboxBundleResult.ts";
+
+export type SandboxTransportService = {
+    readonly create: (config: SandboxTransportConfig) => Effect.Effect<SandboxHandle, SmithersError>;
+    readonly ship: (bundlePath: string, handle: SandboxHandle) => Effect.Effect<void, SmithersError>;
+    readonly execute: (command: string, handle: SandboxHandle) => Effect.Effect<{
+        exitCode: number;
+    }, SmithersError>;
+    readonly collect: (handle: SandboxHandle) => Effect.Effect<SandboxBundleResult, SmithersError>;
+    readonly cleanup: (handle: SandboxHandle) => Effect.Effect<void, SmithersError>;
+};

package/src/ValidatedSandboxBundle.ts

@@ -0,0 +1,9 @@
+import type { SandboxBundleManifest } from "./SandboxBundleManifest.ts";
+
+export type ValidatedSandboxBundle = {
+    manifest: SandboxBundleManifest;
+    bundleSizeBytes: number;
+    patchFiles: string[];
+    logsPath: string | null;
+    bundlePath: string;
+};

package/src/bundle.js

@@ -0,0 +1,201 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { assertJsonPayloadWithinBounds, assertOptionalArrayMaxLength, assertOptionalStringMaxLength, } from "@smithers-orchestrator/db/input-bounds";
+import { resolveSandboxPath } from "./sandboxPath.js";
+/** @typedef {import("./SandboxBundleManifest.ts").SandboxBundleManifest} SandboxBundleManifest */
+/** @typedef {import("./ValidatedSandboxBundle.ts").ValidatedSandboxBundle} ValidatedSandboxBundle */
+
+export const SANDBOX_MAX_BUNDLE_BYTES = 100 * 1024 * 1024; // 100MB
+export const SANDBOX_MAX_README_BYTES = 5 * 1024 * 1024; // 5MB
+export const SANDBOX_MAX_PATCH_FILES = 1000;
+export const SANDBOX_BUNDLE_RUN_ID_MAX_LENGTH = 256;
+export const SANDBOX_BUNDLE_PATH_MAX_LENGTH = 1024;
+export const SANDBOX_BUNDLE_OUTPUT_MAX_DEPTH = 16;
+export const SANDBOX_BUNDLE_OUTPUT_MAX_ARRAY_LENGTH = 512;
+export const SANDBOX_BUNDLE_OUTPUT_MAX_STRING_LENGTH = 64 * 1024;
+/**
+ * @param {string} dir
+ * @returns {Promise<WalkResult>}
+ */
+async function walkFiles(dir) {
+    const pending = [dir];
+    const files = [];
+    let totalBytes = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                pending.push(full);
+            }
+            else if (entry.isFile()) {
+                files.push(full);
+                const info = await stat(full);
+                totalBytes += info.size;
+            }
+        }
+    }
+    return { files, totalBytes };
+}
+/**
+ * @param {string} readme
+ * @returns {SandboxBundleManifest}
+ */
+function parseReadmeJson(readme) {
+    const trimmed = readme.trim();
+    if (trimmed.length === 0) {
+        throw new SmithersError("INVALID_INPUT", "Sandbox bundle README.md is empty.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        throw new SmithersError("INVALID_INPUT", "Sandbox bundle README.md must contain valid JSON.");
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new SmithersError("INVALID_INPUT", "Sandbox bundle README.md JSON must be an object.");
+    }
+    const manifest = parsed;
+    const status = manifest.status;
+    if (status !== "finished" && status !== "failed" && status !== "cancelled") {
+        throw new SmithersError("INVALID_INPUT", "Sandbox bundle README.md must include status: finished | failed | cancelled.");
+    }
+    return {
+        outputs: manifest.outputs,
+        status,
+        runId: typeof manifest.runId === "string" ? manifest.runId : undefined,
+        patches: Array.isArray(manifest.patches)
+            ? manifest.patches.filter((v) => typeof v === "string")
+            : undefined,
+    };
+}
+/**
+ * @param {string} bundlePath
+ * @param {string} patchPath
+ */
+function assertPatchPathSafe(bundlePath, patchPath) {
+    const base = resolveSandboxPath(bundlePath, "patches");
+    const resolved = resolveSandboxPath(bundlePath, patchPath);
+    const rel = relative(base, resolved);
+    if (rel.startsWith("..") || rel === "") {
+        throw new SmithersError("TOOL_PATH_ESCAPE", `Sandbox patch path escapes bundle root: ${patchPath}`, { patchPath });
+    }
+}
+/**
+ * @param {{ output: unknown; patches?: Array<{ path: string; content: string }>; artifacts?: Array<{ path: string; content: string }>; runId?: string; status: "finished" | "failed" | "cancelled"; streamLogPath?: string | null; }} params
+ */
+async function estimateBundleWriteBytes(params) {
+    const readmeBytes = Buffer.byteLength(JSON.stringify({
+        outputs: params.output,
+        status: params.status,
+        runId: params.runId,
+        patches: (params.patches ?? []).map((patch) => patch.path),
+    }, null, 2), "utf8");
+    const patchBytes = (params.patches ?? []).reduce((total, patch) => total + Buffer.byteLength(patch.content, "utf8"), 0);
+    const artifactBytes = (params.artifacts ?? []).reduce((total, artifact) => total + Buffer.byteLength(artifact.content, "utf8"), 0);
+    const streamLogBytes = params.streamLogPath
+        ? (await stat(params.streamLogPath).catch(() => null))?.size ?? 0
+        : 0;
+    return readmeBytes + patchBytes + artifactBytes + streamLogBytes;
+}
+/**
+ * @param {{ bundlePath: string; output: unknown; status: "finished" | "failed" | "cancelled"; runId?: string; streamLogPath?: string | null; patches?: Array<{ path: string; content: string }>; artifacts?: Array<{ path: string; content: string }>; }} params
+ */
+async function validateSandboxBundleWriteParams(params) {
+    assertOptionalStringMaxLength("bundlePath", params.bundlePath, SANDBOX_BUNDLE_PATH_MAX_LENGTH);
+    assertOptionalStringMaxLength("runId", params.runId, SANDBOX_BUNDLE_RUN_ID_MAX_LENGTH);
+    assertOptionalArrayMaxLength("patches", params.patches, SANDBOX_MAX_PATCH_FILES);
+    assertOptionalArrayMaxLength("artifacts", params.artifacts, SANDBOX_MAX_PATCH_FILES);
+    if (params.output !== undefined) {
+        assertJsonPayloadWithinBounds("output", params.output, {
+            maxArrayLength: SANDBOX_BUNDLE_OUTPUT_MAX_ARRAY_LENGTH,
+            maxDepth: SANDBOX_BUNDLE_OUTPUT_MAX_DEPTH,
+            maxStringLength: SANDBOX_BUNDLE_OUTPUT_MAX_STRING_LENGTH,
+        });
+    }
+    for (const patch of params.patches ?? []) {
+        assertOptionalStringMaxLength("patch.path", patch.path, SANDBOX_BUNDLE_PATH_MAX_LENGTH);
+    }
+    for (const artifact of params.artifacts ?? []) {
+        assertOptionalStringMaxLength("artifact.path", artifact.path, SANDBOX_BUNDLE_PATH_MAX_LENGTH);
+    }
+    const estimatedBytes = await estimateBundleWriteBytes(params);
+    if (estimatedBytes > SANDBOX_MAX_BUNDLE_BYTES) {
+        throw new SmithersError("INVALID_INPUT", `Sandbox bundle exceeds ${SANDBOX_MAX_BUNDLE_BYTES} bytes`, { maxBytes: SANDBOX_MAX_BUNDLE_BYTES, estimatedBytes });
+    }
+}
+/**
+ * @param {string} bundlePath
+ * @returns {Promise<ValidatedSandboxBundle>}
+ */
+export async function validateSandboxBundle(bundlePath) {
+    const resolvedReadme = resolveSandboxPath(bundlePath, "README.md");
+    const readmeStats = await stat(resolvedReadme).catch(() => null);
+    if (!readmeStats?.isFile()) {
+        throw new SmithersError("INVALID_INPUT", "Sandbox bundle is missing README.md", { bundlePath });
+    }
+    if (readmeStats.size > SANDBOX_MAX_README_BYTES) {
+        throw new SmithersError("INVALID_INPUT", `Sandbox bundle README.md exceeds ${SANDBOX_MAX_README_BYTES} bytes`, { bundlePath, maxBytes: SANDBOX_MAX_README_BYTES });
+    }
+    const readmeRaw = await readFile(resolvedReadme, "utf8");
+    const manifest = parseReadmeJson(readmeRaw);
+    const walked = await walkFiles(bundlePath);
+    if (walked.totalBytes > SANDBOX_MAX_BUNDLE_BYTES) {
+        throw new SmithersError("INVALID_INPUT", `Sandbox bundle exceeds ${SANDBOX_MAX_BUNDLE_BYTES} bytes`, { bundlePath, maxBytes: SANDBOX_MAX_BUNDLE_BYTES });
+    }
+    const patchFiles = walked.files
+        .filter((file) => relative(bundlePath, file).startsWith("patches/"))
+        .filter((file) => file.endsWith(".patch"))
+        .map((file) => relative(bundlePath, file));
+    if (patchFiles.length > SANDBOX_MAX_PATCH_FILES) {
+        throw new SmithersError("INVALID_INPUT", `Sandbox bundle has too many patch files (max ${SANDBOX_MAX_PATCH_FILES}).`, { patchCount: patchFiles.length, maxPatches: SANDBOX_MAX_PATCH_FILES });
+    }
+    for (const patchPath of patchFiles) {
+        assertPatchPathSafe(bundlePath, patchPath);
+    }
+    for (const patchPath of manifest.patches ?? []) {
+        assertPatchPathSafe(bundlePath, patchPath);
+    }
+    const logsPath = resolveSandboxPath(bundlePath, "logs/stream.ndjson");
+    const logsStats = await stat(logsPath).catch(() => null);
+    return {
+        manifest,
+        bundleSizeBytes: walked.totalBytes,
+        patchFiles,
+        logsPath: logsStats?.isFile() ? logsPath : null,
+        bundlePath,
+    };
+}
+/**
+ * @param {{ bundlePath: string; output: unknown; status: "finished" | "failed" | "cancelled"; runId?: string; streamLogPath?: string | null; patches?: Array<{ path: string; content: string }>; artifacts?: Array<{ path: string; content: string }>; }} params
+ */
+export async function writeSandboxBundle(params) {
+    await validateSandboxBundleWriteParams(params);
+    await mkdir(params.bundlePath, { recursive: true });
+    await mkdir(join(params.bundlePath, "patches"), { recursive: true });
+    await mkdir(join(params.bundlePath, "artifacts"), { recursive: true });
+    await mkdir(join(params.bundlePath, "logs"), { recursive: true });
+    for (const patch of params.patches ?? []) {
+        const file = resolveSandboxPath(params.bundlePath, patch.path);
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, patch.content, "utf8");
+    }
+    for (const artifact of params.artifacts ?? []) {
+        const file = resolveSandboxPath(params.bundlePath, artifact.path);
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, artifact.content, "utf8");
+    }
+    if (params.streamLogPath) {
+        const logContent = await readFile(params.streamLogPath, "utf8").catch(() => "");
+        await writeFile(resolveSandboxPath(params.bundlePath, "logs/stream.ndjson"), logContent, "utf8");
+    }
+    await writeFile(resolveSandboxPath(params.bundlePath, "README.md"), JSON.stringify({
+        outputs: params.output,
+        status: params.status,
+        runId: params.runId,
+        patches: (params.patches ?? []).map((p) => p.path),
+    }, null, 2), "utf8");
+}

package/src/effect/http-runner.js

@@ -0,0 +1,90 @@
+import { HttpRunner } from "@effect/cluster";
+import { mkdir, cp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { Effect, Layer } from "effect";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { spawnCaptureEffect } from "@smithers-orchestrator/driver/child-process";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { SandboxEntityExecutor } from "./sandbox-entity.js";
+/** @typedef {import("../SandboxTransportConfig.ts").SandboxTransportConfig} SandboxTransportConfig */
+/** @typedef {import("../SandboxHandle.ts").SandboxHandle} SandboxHandle */
+/**
+ * @param {SandboxTransportConfig} config
+ * @returns {SandboxHandle}
+ */
+function baseHandle(config) {
+    const sandboxRoot = join(config.rootDir, ".smithers", "sandboxes", config.runId, config.sandboxId);
+    return {
+        runtime: config.runtime,
+        runId: config.runId,
+        sandboxId: config.sandboxId,
+        sandboxRoot,
+        requestPath: join(sandboxRoot, "request"),
+        resultPath: join(sandboxRoot, "result"),
+    };
+}
+/** @type {Layer.Layer<SandboxEntityExecutor, never, never>} */
+export const DockerSandboxExecutorLive = Layer.succeed(SandboxEntityExecutor, SandboxEntityExecutor.of({
+    create: (config) => Effect.gen(function* () {
+        const handle = baseHandle(config);
+        yield* spawnCaptureEffect("docker", ["info"], {
+            cwd: config.rootDir,
+            env: process.env,
+            timeoutMs: 10_000,
+            maxOutputBytes: 200_000,
+        }).pipe(Effect.catchAll(() => Effect.fail(new SmithersError("PROCESS_SPAWN_FAILED", "Docker daemon not reachable.", { runtime: "docker" }))));
+        yield* Effect.tryPromise({
+            try: async () => {
+                await mkdir(handle.requestPath, { recursive: true });
+                await mkdir(handle.resultPath, { recursive: true });
+            },
+            catch: (cause) => toSmithersError(cause, "create docker sandbox workspace"),
+        });
+        return handle;
+    }),
+    ship: (bundlePath, handle) => Effect.tryPromise({
+        try: async () => {
+            await rm(handle.requestPath, { recursive: true, force: true });
+            await mkdir(handle.requestPath, { recursive: true });
+            await cp(bundlePath, handle.requestPath, { recursive: true });
+        },
+        catch: (cause) => toSmithersError(cause, "ship docker bundle"),
+    }),
+    execute: (_command, _handle) => Effect.succeed({ exitCode: 0 }),
+    collect: (handle) => Effect.succeed({ bundlePath: handle.resultPath }),
+    cleanup: (_handle) => Effect.void,
+}));
+/** @type {Layer.Layer<SandboxEntityExecutor, never, never>} */
+export const CodeplaneSandboxExecutorLive = Layer.succeed(SandboxEntityExecutor, SandboxEntityExecutor.of({
+    create: (config) => Effect.gen(function* () {
+        const apiUrl = process.env.CODEPLANE_API_URL;
+        const apiKey = process.env.CODEPLANE_API_KEY;
+        if (!apiUrl || !apiKey) {
+            yield* Effect.fail(new SmithersError("INVALID_INPUT", "Codeplane runtime requires CODEPLANE_API_URL and CODEPLANE_API_KEY."));
+        }
+        const handle = baseHandle(config);
+        yield* Effect.tryPromise({
+            try: async () => {
+                await mkdir(handle.requestPath, { recursive: true });
+                await mkdir(handle.resultPath, { recursive: true });
+            },
+            catch: (cause) => toSmithersError(cause, "create codeplane sandbox workspace"),
+        });
+        return {
+            ...handle,
+            workspaceId: `${config.runId}:${config.sandboxId}`,
+        };
+    }),
+    ship: (bundlePath, handle) => Effect.tryPromise({
+        try: async () => {
+            await rm(handle.requestPath, { recursive: true, force: true });
+            await mkdir(handle.requestPath, { recursive: true });
+            await cp(bundlePath, handle.requestPath, { recursive: true });
+        },
+        catch: (cause) => toSmithersError(cause, "ship codeplane bundle"),
+    }),
+    execute: (_command, _handle) => Effect.succeed({ exitCode: 0 }),
+    collect: (handle) => Effect.succeed({ bundlePath: handle.resultPath }),
+    cleanup: (_handle) => Effect.void,
+}));
+export const SandboxHttpRunner = HttpRunner;

package/src/effect/sandbox-entity.js

@@ -0,0 +1,134 @@
+import { Entity, ShardingConfig } from "@effect/cluster";
+import * as Rpc from "@effect/rpc/Rpc";
+import { Context, Effect, Layer, Schema } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+const SandboxRuntimeSchema = Schema.Literal("bubblewrap", "docker", "codeplane");
+const SandboxTransportConfigSchema = Schema.Struct({
+    runId: Schema.String,
+    sandboxId: Schema.String,
+    runtime: SandboxRuntimeSchema,
+    rootDir: Schema.String,
+    image: Schema.optional(Schema.String),
+});
+const SandboxHandleSchema = Schema.Struct({
+    runtime: SandboxRuntimeSchema,
+    runId: Schema.String,
+    sandboxId: Schema.String,
+    sandboxRoot: Schema.String,
+    requestPath: Schema.String,
+    resultPath: Schema.String,
+    containerId: Schema.optional(Schema.String),
+    workspaceId: Schema.optional(Schema.String),
+});
+const SandboxBundleResultSchema = Schema.Struct({
+    bundlePath: Schema.String,
+});
+const SandboxExecuteResultSchema = Schema.Struct({
+    exitCode: Schema.Number,
+});
+const SandboxShipPayloadSchema = Schema.Struct({
+    bundlePath: Schema.String,
+    handle: SandboxHandleSchema,
+});
+const SandboxExecutePayloadSchema = Schema.Struct({
+    command: Schema.String,
+    handle: SandboxHandleSchema,
+});
+const SandboxHandlePayloadSchema = Schema.Struct({
+    handle: SandboxHandleSchema,
+});
+const SandboxCreateRpc = Rpc.make("create", {
+    payload: SandboxTransportConfigSchema,
+    success: SandboxHandleSchema,
+    error: Schema.Unknown,
+});
+const SandboxShipRpc = Rpc.make("ship", {
+    payload: SandboxShipPayloadSchema,
+    success: Schema.Void,
+    error: Schema.Unknown,
+});
+const SandboxExecuteRpc = Rpc.make("execute", {
+    payload: SandboxExecutePayloadSchema,
+    success: SandboxExecuteResultSchema,
+    error: Schema.Unknown,
+});
+const SandboxCollectRpc = Rpc.make("collect", {
+    payload: SandboxHandlePayloadSchema,
+    success: SandboxBundleResultSchema,
+    error: Schema.Unknown,
+});
+const SandboxCleanupRpc = Rpc.make("cleanup", {
+    payload: SandboxHandlePayloadSchema,
+    success: Schema.Void,
+    error: Schema.Unknown,
+});
+export const SandboxEntity = Entity.make("Sandbox", [
+    SandboxCreateRpc,
+    SandboxShipRpc,
+    SandboxExecuteRpc,
+    SandboxCollectRpc,
+    SandboxCleanupRpc,
+]);
+/** @typedef {import("../SandboxTransportService.ts").SandboxTransportService} SandboxTransportService */
+const SandboxEntityExecutorTag = /** @type {Context.TagClass<SandboxEntityExecutor, "SandboxEntityExecutor", SandboxTransportService>} */ (
+    Context.Tag("SandboxEntityExecutor")()
+);
+export class SandboxEntityExecutor extends SandboxEntityExecutorTag {
+}
+/**
+ * @param {{ runId: string; sandboxId: string; }} input
+ * @returns {string}
+ */
+export function makeSandboxEntityId(input) {
+    return `${input.runId}:${input.sandboxId}`;
+}
+const SandboxEntityLayer = SandboxEntity.toLayer(Effect.gen(function* () {
+    const executor = yield* SandboxEntityExecutor;
+    return SandboxEntity.of({
+        create: ({ payload }) => executor.create(payload),
+        ship: ({ payload }) => executor.ship(payload.bundlePath, payload.handle),
+        execute: ({ payload }) => executor.execute(payload.command, payload.handle),
+        collect: ({ payload }) => executor.collect(payload.handle),
+        cleanup: ({ payload }) => executor.cleanup(payload.handle),
+    });
+}));
+/**
+ * @param {unknown} error
+ * @param {string} operation
+ * @param {Record<string, unknown>} details
+ * @returns {SmithersError}
+ */
+function sandboxEntityError(error, operation, details) {
+    return toSmithersError(error, `sandbox entity ${operation} failed`, {
+        code: "SANDBOX_EXECUTION_FAILED",
+        details,
+    });
+}
+/**
+ * @template R, E
+ * @param {Layer.Layer<SandboxEntityExecutor, E, R>} executorLayer
+ */
+export const makeSandboxTransportServiceEffect = (executorLayer) => Effect.gen(function* () {
+    const makeClient = yield* Entity.makeTestClient(SandboxEntity, SandboxEntityLayer.pipe(Layer.provide(executorLayer))).pipe(Effect.provide(ShardingConfig.layer()));
+    /**
+ * @template A
+ * @param {{ runId: string; sandboxId: string }} input
+ * @param {string} operation
+ * @param {Record<string, unknown>} details
+ * @param {(client: SandboxEntityClient) => Effect.Effect<A, unknown>} f
+ */
+    const withClient = (input, operation, details, f) => makeClient(makeSandboxEntityId(input)).pipe(Effect.flatMap((client) => f(client)), Effect.mapError((error) => sandboxEntityError(error, operation, {
+        runId: input.runId,
+        sandboxId: input.sandboxId,
+        ...details,
+    })));
+    /** @type {SandboxTransportService} */
+    const service = {
+        create: (config) => withClient(config, "create", { runtime: config.runtime, rootDir: config.rootDir }, (client) => client.create(config)),
+        ship: (bundlePath, handle) => withClient(handle, "ship", { bundlePath }, (client) => client.ship({ bundlePath, handle })),
+        execute: (command, handle) => withClient(handle, "execute", { command }, (client) => client.execute({ command, handle })),
+        collect: (handle) => withClient(handle, "collect", {}, (client) => client.collect({ handle })),
+        cleanup: (handle) => withClient(handle, "cleanup", {}, (client) => client.cleanup({ handle })),
+    };
+    return service;
+});

package/src/effect/socket-runner.js

@@ -0,0 +1,62 @@
+import { SocketRunner } from "@effect/cluster";
+import { mkdir, cp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { Effect, Layer } from "effect";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { SandboxEntityExecutor } from "./sandbox-entity.js";
+/** @typedef {import("../SandboxTransportConfig.ts").SandboxTransportConfig} SandboxTransportConfig */
+/** @typedef {import("../SandboxHandle.ts").SandboxHandle} SandboxHandle */
+/**
+ * @param {SandboxTransportConfig} config
+ * @returns {SandboxHandle}
+ */
+function baseHandle(config) {
+    const sandboxRoot = join(config.rootDir, ".smithers", "sandboxes", config.runId, config.sandboxId);
+    return {
+        runtime: config.runtime,
+        runId: config.runId,
+        sandboxId: config.sandboxId,
+        sandboxRoot,
+        requestPath: join(sandboxRoot, "request"),
+        resultPath: join(sandboxRoot, "result"),
+    };
+}
+/** @type {Layer.Layer<SandboxEntityExecutor, never, never>} */
+export const BubblewrapSandboxExecutorLive = Layer.succeed(SandboxEntityExecutor, SandboxEntityExecutor.of({
+    create: (config) => Effect.gen(function* () {
+        if (process.platform === "linux") {
+            const bwrap = typeof Bun !== "undefined" ? Bun.which("bwrap") : null;
+            if (!bwrap) {
+                yield* Effect.fail(new SmithersError("PROCESS_SPAWN_FAILED", "Bubblewrap runtime requested but `bwrap` is not installed. Install bubblewrap (package: bubblewrap) or use runtime=\"docker\".", { runtime: "bubblewrap" }));
+            }
+        }
+        if (process.platform === "darwin") {
+            const sandboxExec = typeof Bun !== "undefined" ? Bun.which("sandbox-exec") : null;
+            if (!sandboxExec) {
+                yield* Effect.fail(new SmithersError("PROCESS_SPAWN_FAILED", "bubblewrap runtime on macOS requires `sandbox-exec` for fallback isolation.", { runtime: "bubblewrap" }));
+            }
+        }
+        const handle = baseHandle(config);
+        yield* Effect.tryPromise({
+            try: async () => {
+                await mkdir(handle.requestPath, { recursive: true });
+                await mkdir(handle.resultPath, { recursive: true });
+            },
+            catch: (cause) => toSmithersError(cause, "create sandbox workspace"),
+        });
+        return handle;
+    }),
+    ship: (bundlePath, handle) => Effect.tryPromise({
+        try: async () => {
+            await rm(handle.requestPath, { recursive: true, force: true });
+            await mkdir(handle.requestPath, { recursive: true });
+            await cp(bundlePath, handle.requestPath, { recursive: true });
+        },
+        catch: (cause) => toSmithersError(cause, "ship sandbox bundle"),
+    }),
+    execute: (_command, _handle) => Effect.succeed({ exitCode: 0 }),
+    collect: (handle) => Effect.succeed({ bundlePath: handle.resultPath }),
+    cleanup: (_handle) => Effect.void,
+}));
+export const SandboxSocketRunner = SocketRunner;

package/src/execute.js

@@ -0,0 +1,373 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Effect, Metric } from "effect";
+import { SmithersDb } from "@smithers-orchestrator/db/adapter";
+import { trackEvent, sandboxTransportDurationMs } from "@smithers-orchestrator/observability/metrics";
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { errorToJson } from "@smithers-orchestrator/errors/errorToJson";
+import { requireTaskRuntime } from "@smithers-orchestrator/driver/task-runtime";
+import { executeChildWorkflow } from "@smithers-orchestrator/engine/child-workflow";
+import { validateSandboxBundle, writeSandboxBundle } from "./bundle.js";
+import { SandboxTransport, layerForSandboxRuntime, resolveSandboxRuntime, } from "./transport.js";
+/** @typedef {import("./ExecuteSandboxOptions.ts").ExecuteSandboxOptions} ExecuteSandboxOptions */
+/** @typedef {import("./SandboxRuntime.ts").SandboxRuntime} SandboxRuntime */
+/** @typedef {import("./SandboxHandle.ts").SandboxHandle} SandboxHandle */
+/** @typedef {import("./SandboxTransportService.ts").SandboxTransportService} SandboxTransportService */
+/** @typedef {import("@smithers-orchestrator/observability/SmithersEvent").SmithersEvent} SmithersEvent */
+
+const DEFAULT_MAX_CONCURRENT_SANDBOXES = 10;
+/**
+ * @param {ConstructorParameters<typeof SmithersDb>[0]} db
+ * @param {SmithersEvent} event
+ * @returns {Promise<void>}
+ */
+async function emitSandboxEvent(db, event) {
+    const adapter = new SmithersDb(db);
+    await adapter.insertEventWithNextSeq({
+        runId: event.runId,
+        timestampMs: event.timestampMs,
+        type: event.type,
+        payloadJson: JSON.stringify(event),
+    });
+    await Effect.runPromise(trackEvent(event));
+}
+/**
+ * @param {string} path
+ * @returns {Promise<number>}
+ */
+async function directorySize(path) {
+    const info = await stat(path).catch(() => null);
+    if (!info)
+        return 0;
+    if (info.isFile())
+        return info.size;
+    return 0;
+}
+/**
+ * @template A
+ * @param {SandboxRuntime} runtime
+ * @param {Effect.Effect<A, SmithersError, SandboxTransport>} effect
+ * @returns {Effect.Effect<A, SmithersError, never>}
+ */
+function runtimeServiceEffect(runtime, effect) {
+    return effect.pipe(Effect.provide(layerForSandboxRuntime(runtime)));
+}
+/**
+ * @template A
+ * @param {SandboxRuntime} runtime
+ * @param {Effect.Effect<A, SmithersError, SandboxTransport>} effect
+ * @returns {Promise<A>}
+ */
+async function transportCall(runtime, effect) {
+    const started = performance.now();
+    const value = await Effect.runPromise(runtimeServiceEffect(runtime, effect));
+    await Effect.runPromise(Metric.update(sandboxTransportDurationMs, performance.now() - started));
+    return value;
+}
+/**
+ * @template A
+ * @param {(svc: SandboxTransportService) => Effect.Effect<A, SmithersError>} fn
+ * @returns {Effect.Effect<A, SmithersError, SandboxTransport>}
+ */
+function sandboxTransport(fn) {
+    return Effect.flatMap(SandboxTransport, fn);
+}
+/**
+ * @param {SandboxHandle | null} handle
+ * @param {string} sandboxId
+ * @returns {SandboxHandle}
+ */
+function requireSandboxHandle(handle, sandboxId) {
+    if (handle)
+        return handle;
+    throw new SmithersError("SANDBOX_EXECUTION_FAILED", `Sandbox ${sandboxId} did not initialize correctly.`, { sandboxId });
+}
+/**
+ * @returns {number}
+ */
+function resolveMaxConcurrentSandboxes() {
+    const raw = process.env.SMITHERS_MAX_CONCURRENT_SANDBOXES;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return DEFAULT_MAX_CONCURRENT_SANDBOXES;
+    }
+    return Math.floor(parsed);
+}
+/**
+ * @param {unknown} status
+ * @returns {boolean}
+ */
+function isSandboxActive(status) {
+    if (typeof status !== "string")
+        return false;
+    return status !== "finished" && status !== "failed" && status !== "cancelled";
+}
+/**
+ * @param {ExecuteSandboxOptions} options
+ * @returns {Promise<unknown>}
+ */
+export async function executeSandbox(options) {
+    const runtime = requireTaskRuntime();
+    runtime.heartbeat({
+        sandboxId: options.sandboxId,
+        stage: "initializing",
+        progress: 0,
+    });
+    const adapter = new SmithersDb(runtime.db);
+    const requestedRuntime = options.runtime ?? "bubblewrap";
+    const selectedRuntime = resolveSandboxRuntime(requestedRuntime);
+    const createdAtMs = nowMs();
+    const configJson = JSON.stringify({
+        runtime: requestedRuntime,
+        selectedRuntime,
+        allowNetwork: options.allowNetwork,
+        maxOutputBytes: options.maxOutputBytes,
+        toolTimeoutMs: options.toolTimeoutMs,
+        reviewDiffs: options.reviewDiffs ?? true,
+        autoAcceptDiffs: Boolean(options.autoAcceptDiffs),
+        ...options.config,
+    });
+    const sandboxRoot = join(options.rootDir, ".smithers", "sandboxes", runtime.runId, options.sandboxId);
+    const requestBundlePath = join(sandboxRoot, "request-bundle");
+    /**
+   * @param {string} childRunId
+   */
+    const childLogPath = (childRunId) => join(options.rootDir, ".smithers", "executions", childRunId, "logs", "stream.ndjson");
+    let handle = null;
+    try {
+        const existingSandboxes = await adapter.listSandboxes(runtime.runId);
+        const activeSandboxCount = existingSandboxes.filter((row) => isSandboxActive(row?.status)).length;
+        const maxConcurrent = resolveMaxConcurrentSandboxes();
+        if (activeSandboxCount >= maxConcurrent) {
+            throw new SmithersError("SANDBOX_EXECUTION_FAILED", `Sandbox concurrency limit reached for run ${runtime.runId} (${maxConcurrent}).`, {
+                runId: runtime.runId,
+                maxConcurrent,
+                activeSandboxCount,
+            });
+        }
+        await adapter.upsertSandbox({
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            remoteRunId: null,
+            workspaceId: null,
+            containerId: null,
+            configJson,
+            status: "pending",
+            shippedAtMs: null,
+            completedAtMs: null,
+            bundlePath: null,
+        });
+        await emitSandboxEvent(runtime.db, {
+            type: "SandboxCreated",
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            configJson,
+            timestampMs: createdAtMs,
+        });
+        runtime.heartbeat({
+            sandboxId: options.sandboxId,
+            stage: "created",
+            progress: 10,
+        });
+        await mkdir(requestBundlePath, { recursive: true });
+        await writeFile(join(requestBundlePath, "README.md"), JSON.stringify({
+            status: "pending",
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            input: options.input ?? {},
+        }, null, 2), "utf8");
+        const transportConfig = {
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            rootDir: options.rootDir,
+            image: options.config?.image ?? undefined,
+        };
+        handle = await transportCall(selectedRuntime, sandboxTransport((svc) => svc.create(transportConfig)));
+        const sandboxHandle = requireSandboxHandle(handle, options.sandboxId);
+        await transportCall(selectedRuntime, sandboxTransport((svc) => svc.ship(requestBundlePath, sandboxHandle)));
+        const bundleSizeBytes = await directorySize(join(requestBundlePath, "README.md"));
+        await emitSandboxEvent(runtime.db, {
+            type: "SandboxShipped",
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            bundleSizeBytes,
+            timestampMs: nowMs(),
+        });
+        runtime.heartbeat({
+            sandboxId: options.sandboxId,
+            stage: "shipped",
+            progress: 25,
+        });
+        await adapter.upsertSandbox({
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            remoteRunId: null,
+            workspaceId: sandboxHandle.workspaceId ?? null,
+            containerId: sandboxHandle.containerId ?? null,
+            configJson,
+            status: "shipped",
+            shippedAtMs: nowMs(),
+            completedAtMs: null,
+            bundlePath: null,
+        });
+        await transportCall(selectedRuntime, sandboxTransport((svc) => svc.execute("smithers up bundle.tsx", sandboxHandle)));
+        runtime.heartbeat({
+            sandboxId: options.sandboxId,
+            stage: "executing",
+            progress: 40,
+        });
+        const childStartedMs = performance.now();
+        const child = await executeChildWorkflow(options.parentWorkflow, {
+            workflow: options.workflow,
+            input: options.input,
+            parentRunId: runtime.runId,
+            rootDir: options.rootDir,
+            allowNetwork: options.allowNetwork,
+            maxOutputBytes: options.maxOutputBytes,
+            toolTimeoutMs: options.toolTimeoutMs,
+            signal: runtime.signal,
+        });
+        runtime.heartbeat({
+            sandboxId: options.sandboxId,
+            stage: "child-finished",
+            progress: 70,
+            childRunId: child.runId,
+            childStatus: child.status,
+        });
+        await emitSandboxEvent(runtime.db, {
+            type: "SandboxHeartbeat",
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            remoteRunId: child.runId,
+            progress: 1,
+            timestampMs: nowMs(),
+        });
+        await writeSandboxBundle({
+            bundlePath: sandboxHandle.resultPath,
+            output: child.output,
+            status: child.status === "finished" ? "finished" : "failed",
+            runId: child.runId,
+            streamLogPath: childLogPath(child.runId),
+        });
+        const collected = await transportCall(selectedRuntime, sandboxTransport((svc) => svc.collect(sandboxHandle)));
+        const validated = await validateSandboxBundle(collected.bundlePath);
+        runtime.heartbeat({
+            sandboxId: options.sandboxId,
+            stage: "bundle-collected",
+            progress: 85,
+            bundlePath: validated.bundlePath,
+            patchCount: validated.patchFiles.length,
+        });
+        await emitSandboxEvent(runtime.db, {
+            type: "SandboxBundleReceived",
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            bundleSizeBytes: validated.bundleSizeBytes,
+            patchCount: validated.patchFiles.length,
+            hasOutputs: validated.manifest.outputs !== undefined,
+            timestampMs: nowMs(),
+        });
+        const reviewDiffs = options.reviewDiffs ?? true;
+        if (reviewDiffs && validated.patchFiles.length > 0) {
+            await emitSandboxEvent(runtime.db, {
+                type: "SandboxDiffReviewRequested",
+                runId: runtime.runId,
+                sandboxId: options.sandboxId,
+                patchCount: validated.patchFiles.length,
+                totalDiffLines: 0,
+                timestampMs: nowMs(),
+            });
+            if (!options.autoAcceptDiffs) {
+                await emitSandboxEvent(runtime.db, {
+                    type: "SandboxDiffRejected",
+                    runId: runtime.runId,
+                    sandboxId: options.sandboxId,
+                    reason: "Diff review approval is required before applying sandbox patches.",
+                    timestampMs: nowMs(),
+                });
+                throw new SmithersError("INVALID_INPUT", "Sandbox produced patches that require review approval.", {
+                    sandboxId: options.sandboxId,
+                    patchCount: validated.patchFiles.length,
+                });
+            }
+            await emitSandboxEvent(runtime.db, {
+                type: "SandboxDiffAccepted",
+                runId: runtime.runId,
+                sandboxId: options.sandboxId,
+                patchCount: validated.patchFiles.length,
+                timestampMs: nowMs(),
+            });
+        }
+        await adapter.upsertSandbox({
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            remoteRunId: child.runId,
+            workspaceId: sandboxHandle.workspaceId ?? null,
+            containerId: sandboxHandle.containerId ?? null,
+            configJson,
+            status: validated.manifest.status,
+            shippedAtMs: createdAtMs,
+            completedAtMs: nowMs(),
+            bundlePath: validated.bundlePath,
+        });
+        await emitSandboxEvent(runtime.db, {
+            type: "SandboxCompleted",
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            remoteRunId: child.runId,
+            runtime: selectedRuntime,
+            status: validated.manifest.status,
+            durationMs: performance.now() - childStartedMs,
+            timestampMs: nowMs(),
+        });
+        runtime.heartbeat({
+            sandboxId: options.sandboxId,
+            stage: "completed",
+            progress: 100,
+            status: validated.manifest.status,
+        });
+        return validated.manifest.outputs;
+    }
+    catch (error) {
+        await adapter.upsertSandbox({
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            remoteRunId: null,
+            workspaceId: handle?.workspaceId ?? null,
+            containerId: handle?.containerId ?? null,
+            configJson,
+            status: "failed",
+            shippedAtMs: createdAtMs,
+            completedAtMs: nowMs(),
+            bundlePath: handle?.resultPath ?? null,
+        });
+        await emitSandboxEvent(runtime.db, {
+            type: "SandboxFailed",
+            runId: runtime.runId,
+            sandboxId: options.sandboxId,
+            runtime: selectedRuntime,
+            error: errorToJson(error),
+            timestampMs: nowMs(),
+        });
+        runtime.heartbeat({
+            sandboxId: options.sandboxId,
+            stage: "failed",
+            progress: 100,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+    finally {
+        if (handle) {
+            await transportCall(selectedRuntime, sandboxTransport((svc) => svc.cleanup(handle))).catch(() => undefined);
+        }
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,140 @@
+import * as _smithers_observability_SmithersEvent from '@smithers-orchestrator/observability/SmithersEvent';
+import { SmithersWorkflow } from '@smithers-orchestrator/components/SmithersWorkflow';
+import { ChildWorkflowDefinition } from '@smithers-orchestrator/engine/child-workflow';
+import { Context, Effect, Layer } from 'effect';
+import { SmithersError } from '@smithers-orchestrator/errors/SmithersError';
+
+type SandboxBundleManifest$1 = {
+    outputs: unknown;
+    status: "finished" | "failed" | "cancelled";
+    runId?: string;
+    patches?: string[];
+};
+
+type ValidatedSandboxBundle$1 = {
+    manifest: SandboxBundleManifest$1;
+    bundleSizeBytes: number;
+    patchFiles: string[];
+    logsPath: string | null;
+    bundlePath: string;
+};
+
+/**
+ * @param {string} bundlePath
+ * @returns {Promise<ValidatedSandboxBundle>}
+ */
+declare function validateSandboxBundle(bundlePath: string): Promise<ValidatedSandboxBundle>;
+/**
+ * @param {{ bundlePath: string; output: unknown; status: "finished" | "failed" | "cancelled"; runId?: string; streamLogPath?: string | null; patches?: Array<{ path: string; content: string }>; artifacts?: Array<{ path: string; content: string }>; }} params
+ */
+declare function writeSandboxBundle(params: {
+    bundlePath: string;
+    output: unknown;
+    status: "finished" | "failed" | "cancelled";
+    runId?: string;
+    streamLogPath?: string | null;
+    patches?: Array<{
+        path: string;
+        content: string;
+    }>;
+    artifacts?: Array<{
+        path: string;
+        content: string;
+    }>;
+}): Promise<void>;
+/** @typedef {import("./SandboxBundleManifest.ts").SandboxBundleManifest} SandboxBundleManifest */
+/** @typedef {import("./ValidatedSandboxBundle.ts").ValidatedSandboxBundle} ValidatedSandboxBundle */
+declare const SANDBOX_MAX_BUNDLE_BYTES: number;
+declare const SANDBOX_MAX_README_BYTES: number;
+declare const SANDBOX_MAX_PATCH_FILES: 1000;
+declare const SANDBOX_BUNDLE_RUN_ID_MAX_LENGTH: 256;
+declare const SANDBOX_BUNDLE_PATH_MAX_LENGTH: 1024;
+declare const SANDBOX_BUNDLE_OUTPUT_MAX_DEPTH: 16;
+declare const SANDBOX_BUNDLE_OUTPUT_MAX_ARRAY_LENGTH: 512;
+declare const SANDBOX_BUNDLE_OUTPUT_MAX_STRING_LENGTH: number;
+type SandboxBundleManifest = SandboxBundleManifest$1;
+type ValidatedSandboxBundle = ValidatedSandboxBundle$1;
+
+type SandboxRuntime$1 = "bubblewrap" | "docker" | "codeplane";
+
+type SandboxTransportConfig$1 = {
+    runId: string;
+    sandboxId: string;
+    runtime: SandboxRuntime$1;
+    rootDir: string;
+    image?: string;
+};
+
+type SandboxHandle = {
+    runtime: SandboxRuntime$1;
+    runId: string;
+    sandboxId: string;
+    sandboxRoot: string;
+    requestPath: string;
+    resultPath: string;
+    containerId?: string;
+    workspaceId?: string;
+};
+
+type SandboxBundleResult$1 = {
+    bundlePath: string;
+};
+
+type SandboxTransportService = {
+    readonly create: (config: SandboxTransportConfig$1) => Effect.Effect<SandboxHandle, SmithersError>;
+    readonly ship: (bundlePath: string, handle: SandboxHandle) => Effect.Effect<void, SmithersError>;
+    readonly execute: (command: string, handle: SandboxHandle) => Effect.Effect<{
+        exitCode: number;
+    }, SmithersError>;
+    readonly collect: (handle: SandboxHandle) => Effect.Effect<SandboxBundleResult$1, SmithersError>;
+    readonly cleanup: (handle: SandboxHandle) => Effect.Effect<void, SmithersError>;
+};
+
+type ExecuteSandboxOptions$1 = {
+    parentWorkflow?: SmithersWorkflow<unknown>;
+    sandboxId: string;
+    runtime?: SandboxRuntime$1;
+    workflow: ChildWorkflowDefinition;
+    input?: unknown;
+    rootDir: string;
+    allowNetwork: boolean;
+    maxOutputBytes: number;
+    toolTimeoutMs: number;
+    reviewDiffs?: boolean;
+    autoAcceptDiffs?: boolean;
+    config?: Record<string, unknown>;
+};
+
+/**
+ * @param {ExecuteSandboxOptions} options
+ * @returns {Promise<unknown>}
+ */
+declare function executeSandbox(options: ExecuteSandboxOptions): Promise<unknown>;
+type ExecuteSandboxOptions = ExecuteSandboxOptions$1;
+type SmithersEvent = _smithers_observability_SmithersEvent.SmithersEvent;
+
+declare class SandboxEntityExecutor extends Context.TagClassShape<"SandboxEntityExecutor", SandboxTransportService> {
+}
+
+/**
+ * @template R, E
+ * @param {Layer.Layer<SandboxEntityExecutor, E, R>} executorLayer
+ * @returns {Layer.Layer<SandboxTransport, E, R>}
+ */
+declare function makeSandboxTransportLayer<R, E>(executorLayer: Layer.Layer<SandboxEntityExecutor, E, R>): Layer.Layer<SandboxTransport, E, R>;
+/**
+ * @param {SandboxRuntime} runtime
+ */
+declare function layerForSandboxRuntime(runtime: SandboxRuntime): Layer.Layer<SandboxTransport, never, never>;
+/**
+ * @param {SandboxRuntime} requested
+ * @returns {SandboxRuntime}
+ */
+declare function resolveSandboxRuntime(requested: SandboxRuntime): SandboxRuntime;
+declare class SandboxTransport extends Context.TagClassShape<"SandboxTransport", SandboxTransportService> {
+}
+type SandboxBundleResult = SandboxBundleResult$1;
+type SandboxTransportConfig = SandboxTransportConfig$1;
+type SandboxRuntime = SandboxRuntime$1;
+
+export { type ExecuteSandboxOptions, SANDBOX_BUNDLE_OUTPUT_MAX_ARRAY_LENGTH, SANDBOX_BUNDLE_OUTPUT_MAX_DEPTH, SANDBOX_BUNDLE_OUTPUT_MAX_STRING_LENGTH, SANDBOX_BUNDLE_PATH_MAX_LENGTH, SANDBOX_BUNDLE_RUN_ID_MAX_LENGTH, SANDBOX_MAX_BUNDLE_BYTES, SANDBOX_MAX_PATCH_FILES, SANDBOX_MAX_README_BYTES, type SandboxBundleManifest, type SandboxBundleResult, SandboxTransport, type SandboxTransportConfig, type SmithersEvent, type ValidatedSandboxBundle, executeSandbox, layerForSandboxRuntime, makeSandboxTransportLayer, resolveSandboxRuntime, validateSandboxBundle, writeSandboxBundle };

package/src/index.js

@@ -0,0 +1,3 @@
+export * from "./bundle.js";
+export * from "./execute.js";
+export * from "./transport.js";

package/src/sandboxPath.js

@@ -0,0 +1,67 @@
+import { resolve, isAbsolute, sep, dirname } from "node:path";
+import { realpath } from "node:fs/promises";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/**
+ * @param {string} rootDir
+ * @param {string} inputPath
+ * @returns {string}
+ */
+export function resolveSandboxPath(rootDir, inputPath) {
+    if (!inputPath || typeof inputPath !== "string") {
+        throw new SmithersError("TOOL_PATH_INVALID", "Path must be a string");
+    }
+    const resolved = isAbsolute(inputPath)
+        ? resolve(inputPath)
+        : resolve(rootDir, inputPath);
+    const root = resolve(rootDir);
+    if (!resolved.startsWith(root + sep) && resolved !== root) {
+        throw new SmithersError("TOOL_PATH_ESCAPE", "Path escapes sandbox root");
+    }
+    return resolved;
+}
+/**
+ * @param {string} rootDir
+ * @param {string} resolvedPath
+ */
+export function assertPathWithinRootEffect(rootDir, resolvedPath) {
+    return Effect.gen(function* () {
+        const root = yield* Effect.tryPromise({
+            try: () => realpath(resolve(rootDir)),
+            catch: (cause) => toSmithersError(cause, "realpath root"),
+        });
+        let current = resolvedPath;
+        while (true) {
+            const result = yield* Effect.either(Effect.tryPromise({
+                try: () => realpath(current),
+                catch: (cause) => toSmithersError(cause, "realpath check"),
+            }));
+            if (result._tag === "Right") {
+                const target = result.right;
+                if (target !== root && !target.startsWith(root + sep)) {
+                    return yield* Effect.fail(new SmithersError("TOOL_PATH_ESCAPE", "Path escapes sandbox root (via symlink)"));
+                }
+                return;
+            }
+            const err = result.left;
+            const cause = err?.cause ?? err;
+            const code = cause?.code;
+            if (code && code !== "ENOENT" && code !== "ENOTDIR") {
+                return yield* Effect.fail(err);
+            }
+            const parent = dirname(current);
+            if (parent === current) {
+                return yield* Effect.fail(new SmithersError("TOOL_PATH_ESCAPE", "Path escapes sandbox root (via symlink)"));
+            }
+            current = parent;
+        }
+    });
+}
+/**
+ * @param {string} rootDir
+ * @param {string} resolvedPath
+ */
+export async function assertPathWithinRoot(rootDir, resolvedPath) {
+    return Effect.runPromise(assertPathWithinRootEffect(rootDir, resolvedPath));
+}

package/src/transport.js

@@ -0,0 +1,51 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./SandboxBundleResult.ts").SandboxBundleResult} SandboxBundleResult */
+/** @typedef {import("./SandboxHandle.ts").SandboxHandle} SandboxHandle */
+/** @typedef {import("./SandboxTransportConfig.ts").SandboxTransportConfig} SandboxTransportConfig */
+/** @typedef {import("./SandboxTransportService.ts").SandboxTransportService} SandboxTransportService */
+// @smithers-type-exports-end
+
+import { Context, Effect, Layer } from "effect";
+import { CodeplaneSandboxExecutorLive, DockerSandboxExecutorLive, } from "./effect/http-runner.js";
+import { SandboxEntityExecutor, makeSandboxTransportServiceEffect, } from "./effect/sandbox-entity.js";
+import { BubblewrapSandboxExecutorLive } from "./effect/socket-runner.js";
+import {} from "@smithers-orchestrator/errors/SmithersError";
+/** @typedef {import("./SandboxRuntime.ts").SandboxRuntime} SandboxRuntime */
+
+const SandboxTransportTag = /** @type {Context.TagClass<SandboxTransport, "SandboxTransport", SandboxTransportService>} */ (
+    Context.Tag("SandboxTransport")()
+);
+export class SandboxTransport extends SandboxTransportTag {
+}
+/**
+ * @template R, E
+ * @param {Layer.Layer<SandboxEntityExecutor, E, R>} executorLayer
+ * @returns {Layer.Layer<SandboxTransport, E, R>}
+ */
+export function makeSandboxTransportLayer(executorLayer) {
+    return Layer.scoped(SandboxTransport, makeSandboxTransportServiceEffect(executorLayer).pipe(Effect.map((service) => SandboxTransport.of(service))));
+}
+/**
+ * @param {SandboxRuntime} runtime
+ */
+export function layerForSandboxRuntime(runtime) {
+    switch (runtime) {
+        case "docker":
+            return makeSandboxTransportLayer(DockerSandboxExecutorLive);
+        case "codeplane":
+            return makeSandboxTransportLayer(CodeplaneSandboxExecutorLive);
+        case "bubblewrap":
+        default:
+            return makeSandboxTransportLayer(BubblewrapSandboxExecutorLive);
+    }
+}
+/**
+ * @param {SandboxRuntime} requested
+ * @returns {SandboxRuntime}
+ */
+export function resolveSandboxRuntime(requested) {
+    if (requested !== "docker")
+        return requested;
+    const hasDocker = typeof Bun !== "undefined" ? Boolean(Bun.which("docker")) : false;
+    return hasDocker ? "docker" : "bubblewrap";
+}