@smithers-orchestrator/sandbox 0.20.3 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/sandbox",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "Sandbox bundle, execution, and transport integration for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -23,14 +23,11 @@
     "@effect/cluster": "^0.58.0",
     "@effect/rpc": "^0.75.0",
     "effect": "^3.21.1",
-    "@smithers-orchestrator/db": "0.20.3",
-    "@smithers-orchestrator/driver": "0.20.3",
-    "@smithers-orchestrator/components": "0.20.3",
-    "@smithers-orchestrator/errors": "0.20.3",
-    "@smithers-orchestrator/engine": "0.20.3",
-    "@smithers-orchestrator/graph": "0.20.3",
-    "@smithers-orchestrator/observability": "0.20.3",
-    "@smithers-orchestrator/scheduler": "0.20.3"
+    "@smithers-orchestrator/db": "0.21.0",
+    "@smithers-orchestrator/driver": "0.21.0",
+    "@smithers-orchestrator/errors": "0.21.0",
+    "@smithers-orchestrator/observability": "0.21.0",
+    "@smithers-orchestrator/scheduler": "0.21.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/ExecuteSandboxOptions.ts

@@ -1,4 +1,5 @@
 import type { SandboxRuntime } from "./SandboxRuntime.ts";
+import type { SandboxDiffBundleLike, SandboxProvider } from "./SandboxProvider.ts";
 
 export type SandboxWorkflow = {
 	db?: unknown;
@@ -31,17 +32,20 @@ export type ExecuteSandboxChildWorkflow = (
 ) => Promise<{ runId: string; status: string; output: unknown }>;
 
 export type ExecuteSandboxOptions = {
-    parentWorkflow?: SandboxWorkflow;
-    sandboxId: string;
-    runtime?: SandboxRuntime;
-    workflow: SandboxChildWorkflowDefinition;
-    executeChildWorkflow: ExecuteSandboxChildWorkflow;
-    input?: unknown;
-    rootDir: string;
-    allowNetwork: boolean;
-    maxOutputBytes: number;
-    toolTimeoutMs: number;
-    reviewDiffs?: boolean;
-    autoAcceptDiffs?: boolean;
-    config?: Record<string, unknown>;
+	parentWorkflow?: SandboxWorkflow;
+	sandboxId: string;
+	provider?: SandboxProvider | string;
+	runtime?: SandboxRuntime;
+	workflow: SandboxChildWorkflowDefinition;
+	executeChildWorkflow: ExecuteSandboxChildWorkflow;
+	applyDiffBundle?: (bundle: SandboxDiffBundleLike, targetDir: string) => Promise<void>;
+	input?: unknown;
+	rootDir: string;
+	allowNetwork: boolean;
+	maxOutputBytes: number;
+	toolTimeoutMs: number;
+	reviewDiffs?: boolean;
+	autoAcceptDiffs?: boolean;
+	allowNested?: boolean;
+	config?: Record<string, unknown>;
 };

package/src/SandboxBundleManifest.ts

@@ -1,6 +1,9 @@
+import type { SandboxDiffBundleLike } from "./SandboxProvider.ts";
+
 export type SandboxBundleManifest = {
-    outputs: unknown;
-    status: "finished" | "failed" | "cancelled";
-    runId?: string;
-    patches?: string[];
+	outputs: unknown;
+	status: "finished" | "failed" | "cancelled";
+	runId?: string;
+	patches?: string[];
+	diffBundle?: SandboxDiffBundleLike;
 };

package/src/SandboxHandle.ts

@@ -1,5 +1,23 @@
 import type { SandboxRuntime } from "./SandboxRuntime.ts";
 
+export type SandboxPortMapping = {
+    host: number;
+    container: number;
+};
+
+export type SandboxVolumeMount = {
+    host: string;
+    container: string;
+    readonly?: boolean;
+};
+
+export type SandboxWorkspaceSpec = {
+    name: string;
+    snapshotId?: string;
+    idleTimeoutSecs?: number;
+    persistence?: "ephemeral" | "sticky";
+};
+
 export type SandboxHandle = {
     runtime: SandboxRuntime;
     runId: string;
@@ -7,6 +25,14 @@ export type SandboxHandle = {
     sandboxRoot: string;
     requestPath: string;
     resultPath: string;
+    image?: string;
+    allowNetwork?: boolean;
+    env?: Record<string, string>;
+    ports?: SandboxPortMapping[];
+    volumes?: SandboxVolumeMount[];
+    memoryLimit?: string;
+    cpuLimit?: string;
+    workspace?: SandboxWorkspaceSpec;
     containerId?: string;
     workspaceId?: string;
 };

package/src/SandboxProvider.ts

@@ -0,0 +1,59 @@
+import type { SandboxChildWorkflowDefinition, SandboxWorkflow, ExecuteSandboxChildWorkflow } from "./ExecuteSandboxOptions.ts";
+
+export type SandboxBundleStatus = "finished" | "failed" | "cancelled";
+
+export type SandboxDiffBundleLike = {
+	seq: number;
+	baseRef: string;
+	patches: Array<{
+		path: string;
+		operation: "add" | "modify" | "delete";
+		diff: string;
+		binaryContent?: string;
+	}>;
+};
+
+export type SandboxProviderRequest = {
+	runId: string;
+	sandboxId: string;
+	input?: unknown;
+	rootDir: string;
+	requestBundlePath: string;
+	resultBundlePath: string;
+	workflow: SandboxChildWorkflowDefinition;
+	parentWorkflow?: SandboxWorkflow;
+	executeChildWorkflow: ExecuteSandboxChildWorkflow;
+	allowNetwork: boolean;
+	maxOutputBytes: number;
+	toolTimeoutMs: number;
+	config: Record<string, unknown>;
+	signal?: AbortSignal;
+	heartbeat: (data?: unknown) => void;
+};
+
+export type SandboxProviderResult =
+	| {
+			bundlePath: string;
+			remoteRunId?: string;
+			workspaceId?: string;
+			containerId?: string;
+	  }
+	| {
+			status: SandboxBundleStatus;
+			output?: unknown;
+			outputs?: unknown;
+			runId?: string;
+			remoteRunId?: string;
+			workspaceId?: string;
+			containerId?: string;
+			diffBundle?: SandboxDiffBundleLike;
+			patches?: Array<{ path: string; content: string }>;
+			artifacts?: Array<{ path: string; content: string }>;
+			streamLogPath?: string | null;
+	  };
+
+export type SandboxProvider = {
+	id: string;
+	run: (request: SandboxProviderRequest) => Promise<SandboxProviderResult> | SandboxProviderResult;
+	cleanup?: (request: SandboxProviderRequest) => Promise<void> | void;
+};

package/src/SandboxTransportConfig.ts

@@ -1,4 +1,5 @@
 import type { SandboxRuntime } from "./SandboxRuntime.ts";
+import type { SandboxPortMapping, SandboxVolumeMount, SandboxWorkspaceSpec } from "./SandboxHandle.ts";
 
 export type SandboxTransportConfig = {
     runId: string;
@@ -6,4 +7,11 @@ export type SandboxTransportConfig = {
     runtime: SandboxRuntime;
     rootDir: string;
     image?: string;
+    allowNetwork?: boolean;
+    env?: Record<string, string>;
+    ports?: SandboxPortMapping[];
+    volumes?: SandboxVolumeMount[];
+    memoryLimit?: string;
+    cpuLimit?: string;
+    workspace?: SandboxWorkspaceSpec;
 };

package/src/bundle.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { lstat, 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";
@@ -27,12 +27,17 @@ async function walkFiles(dir) {
         const entries = await readdir(current, { withFileTypes: true });
         for (const entry of entries) {
             const full = join(current, entry.name);
-            if (entry.isDirectory()) {
+            const info = await lstat(full);
+            if (info.isSymbolicLink()) {
+                throw new SmithersError("TOOL_PATH_ESCAPE", "Sandbox bundle may not contain symlinks.", {
+                    path: relative(dir, full),
+                });
+            }
+            if (info.isDirectory()) {
                 pending.push(full);
             }
-            else if (entry.isFile()) {
+            else if (info.isFile()) {
                 files.push(full);
-                const info = await stat(full);
                 totalBytes += info.size;
             }
         }
@@ -70,6 +75,9 @@ function parseReadmeJson(readme) {
         patches: Array.isArray(manifest.patches)
             ? manifest.patches.filter((v) => typeof v === "string")
             : undefined,
+        diffBundle: manifest.diffBundle && typeof manifest.diffBundle === "object"
+            ? manifest.diffBundle
+            : undefined,
     };
 }
 /**
@@ -85,7 +93,7 @@ function assertPatchPathSafe(bundlePath, 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
+ * @param {{ output: unknown; patches?: Array<{ path: string; content: string }>; artifacts?: Array<{ path: string; content: string }>; runId?: string; status: "finished" | "failed" | "cancelled"; streamLogPath?: string | null; diffBundle?: unknown; }} params
  */
 async function estimateBundleWriteBytes(params) {
     const readmeBytes = Buffer.byteLength(JSON.stringify({
@@ -93,6 +101,7 @@ async function estimateBundleWriteBytes(params) {
         status: params.status,
         runId: params.runId,
         patches: (params.patches ?? []).map((patch) => patch.path),
+        diffBundle: params.diffBundle,
     }, 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);
@@ -102,7 +111,7 @@ async function estimateBundleWriteBytes(params) {
     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
+ * @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 }>; diffBundle?: unknown; }} params
  */
 async function validateSandboxBundleWriteParams(params) {
     assertOptionalStringMaxLength("bundlePath", params.bundlePath, SANDBOX_BUNDLE_PATH_MAX_LENGTH);
@@ -133,7 +142,10 @@ async function validateSandboxBundleWriteParams(params) {
  */
 export async function validateSandboxBundle(bundlePath) {
     const resolvedReadme = resolveSandboxPath(bundlePath, "README.md");
-    const readmeStats = await stat(resolvedReadme).catch(() => null);
+    const readmeStats = await lstat(resolvedReadme).catch(() => null);
+    if (readmeStats?.isSymbolicLink()) {
+        throw new SmithersError("TOOL_PATH_ESCAPE", "Sandbox bundle README.md may not be a symlink.", { bundlePath });
+    }
     if (!readmeStats?.isFile()) {
         throw new SmithersError("INVALID_INPUT", "Sandbox bundle is missing README.md", { bundlePath });
     }
@@ -160,7 +172,10 @@ export async function validateSandboxBundle(bundlePath) {
         assertPatchPathSafe(bundlePath, patchPath);
     }
     const logsPath = resolveSandboxPath(bundlePath, "logs/stream.ndjson");
-    const logsStats = await stat(logsPath).catch(() => null);
+    const logsStats = await lstat(logsPath).catch(() => null);
+    if (logsStats?.isSymbolicLink()) {
+        throw new SmithersError("TOOL_PATH_ESCAPE", "Sandbox bundle logs may not be a symlink.", { bundlePath });
+    }
     return {
         manifest,
         bundleSizeBytes: walked.totalBytes,
@@ -170,7 +185,7 @@ export async function validateSandboxBundle(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
+ * @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 }>; diffBundle?: unknown; }} params
  */
 export async function writeSandboxBundle(params) {
     await validateSandboxBundleWriteParams(params);
@@ -197,5 +212,6 @@ export async function writeSandboxBundle(params) {
         status: params.status,
         runId: params.runId,
         patches: (params.patches ?? []).map((p) => p.path),
+        diffBundle: params.diffBundle,
     }, null, 2), "utf8");
 }

package/src/effect/http-runner.js

@@ -6,6 +6,7 @@ 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";
+import { dockerArgs, normalizeSandboxHandleControls, sandboxRunnerEnv, spawnSandboxCommand } from "./process-runner.js";
 /** @typedef {import("../SandboxTransportConfig.ts").SandboxTransportConfig} SandboxTransportConfig */
 /** @typedef {import("../SandboxHandle.ts").SandboxHandle} SandboxHandle */
 /**
@@ -14,6 +15,7 @@ import { SandboxEntityExecutor } from "./sandbox-entity.js";
  */
 function baseHandle(config) {
     const sandboxRoot = join(config.rootDir, ".smithers", "sandboxes", config.runId, config.sandboxId);
+    const controls = normalizeSandboxHandleControls(config);
     return {
         runtime: config.runtime,
         runId: config.runId,
@@ -21,6 +23,9 @@ function baseHandle(config) {
         sandboxRoot,
         requestPath: join(sandboxRoot, "request"),
         resultPath: join(sandboxRoot, "result"),
+        image: config.image,
+        allowNetwork: Boolean(config.allowNetwork),
+        ...controls,
     };
 }
 /** @type {Layer.Layer<SandboxEntityExecutor, never, never>} */
@@ -29,7 +34,7 @@ export const DockerSandboxExecutorLive = Layer.succeed(SandboxEntityExecutor, Sa
         const handle = baseHandle(config);
         yield* spawnCaptureEffect("docker", ["info"], {
             cwd: config.rootDir,
-            env: process.env,
+            env: sandboxRunnerEnv(),
             timeoutMs: 10_000,
             maxOutputBytes: 200_000,
         }).pipe(Effect.catchAll(() => Effect.fail(new SmithersError("PROCESS_SPAWN_FAILED", "Docker daemon not reachable.", { runtime: "docker" }))));
@@ -50,9 +55,15 @@ export const DockerSandboxExecutorLive = Layer.succeed(SandboxEntityExecutor, Sa
         },
         catch: (cause) => toSmithersError(cause, "ship docker bundle"),
     }),
-    execute: (_command, _handle) => Effect.succeed({ exitCode: 0 }),
+    execute: (command, handle) => spawnSandboxCommand("docker", dockerArgs(command, handle), {
+        cwd: handle.requestPath,
+        runtime: "docker",
+    }),
     collect: (handle) => Effect.succeed({ bundlePath: handle.resultPath }),
-    cleanup: (_handle) => Effect.void,
+    cleanup: (handle) => Effect.tryPromise({
+        try: () => rm(handle.requestPath, { recursive: true, force: true }),
+        catch: (cause) => toSmithersError(cause, "cleanup docker sandbox workspace"),
+    }),
 }));
 /** @type {Layer.Layer<SandboxEntityExecutor, never, never>} */
 export const CodeplaneSandboxExecutorLive = Layer.succeed(SandboxEntityExecutor, SandboxEntityExecutor.of({
@@ -83,8 +94,15 @@ export const CodeplaneSandboxExecutorLive = Layer.succeed(SandboxEntityExecutor,
         },
         catch: (cause) => toSmithersError(cause, "ship codeplane bundle"),
     }),
-    execute: (_command, _handle) => Effect.succeed({ exitCode: 0 }),
+    execute: (command, handle) => Effect.fail(new SmithersError("SANDBOX_EXECUTION_FAILED", "Codeplane sandbox command execution requires the remote Codeplane worker integration.", {
+        runtime: "codeplane",
+        command,
+        workspaceId: handle.workspaceId ?? null,
+    })),
     collect: (handle) => Effect.succeed({ bundlePath: handle.resultPath }),
-    cleanup: (_handle) => Effect.void,
+    cleanup: (handle) => Effect.tryPromise({
+        try: () => rm(handle.requestPath, { recursive: true, force: true }),
+        catch: (cause) => toSmithersError(cause, "cleanup codeplane sandbox workspace"),
+    }),
 }));
 export const SandboxHttpRunner = HttpRunner;