@effect-agent/sandbox-local 0.0.1-beta.0

package/dist/index.d.mts

@@ -0,0 +1,20 @@
+import { Sandbox, SandboxImplementation } from "@effect-agent/sandbox";
+import { Layer } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
+//#region src/local-sandbox.d.ts
+/**
+ * The only implementation identity produced by this package. It deliberately states that local
+ * process execution is unisolated development tooling, not a security sandbox.
+ */
+declare const unisolatedImplementation: SandboxImplementation;
+/**
+ * Development-only local process adapter with its `ChildProcessSpawner` requirement kept visible
+ * so composition roots and tests can inject a spawner double. It is unisolated and must never be
+ * used as a security boundary for untrusted code or commands.
+ */
+declare const sandboxLayer: Layer.Layer<Sandbox, never, ChildProcessSpawner>;
+/** A scoped Node process implementation whose events are always labeled `unisolated`. */
+declare const layer: Layer.Layer<Sandbox>;
+//#endregion
+export { layer, sandboxLayer, unisolatedImplementation };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,151 @@
+import { Sandbox, SandboxExitError, SandboxExited, SandboxImplementation, SandboxOutput, SandboxOutputLimitError, SandboxResourceUse, SandboxSpawnError, SandboxStarted, SandboxTimeoutError, SandboxUnsupportedRequestError } from "@effect-agent/sandbox";
+import { NodeServices } from "@effect/platform-node";
+import { Clock, Config, Duration, Effect, Layer, Option, Ref, Stream } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
+//#region src/local-sandbox.ts
+/**
+* The only implementation identity produced by this package. It deliberately states that local
+* process execution is unisolated development tooling, not a security sandbox.
+*/
+const unisolatedImplementation = SandboxImplementation.make({
+	isolation: "unisolated",
+	identity: "local-process"
+});
+const zeroOutput = {
+	stdout: 0,
+	stderr: 0
+};
+const unsupported = (feature, message) => SandboxUnsupportedRequestError.make({
+	implementation: unisolatedImplementation,
+	feature,
+	message
+});
+const validateRequest = (request) => {
+	if (request.runtime.kind !== "unisolated-process") return Effect.fail(unsupported("runtime", "The local process runner only accepts runtime.kind 'unisolated-process'."));
+	if (request.mounts.length > 0) return Effect.fail(unsupported("mounts", "The unisolated local process runner cannot enforce mount access modes."));
+	if (request.network._tag !== "NetworkDisabled") return Effect.fail(unsupported("network", "The unisolated local process runner cannot enforce workload network policy."));
+	if (request.limits.cpuCores !== void 0) return Effect.fail(unsupported("cpu-limit", "The unisolated local process runner cannot enforce CPU limits."));
+	if (request.limits.memoryBytes !== void 0) return Effect.fail(unsupported("memory-limit", "The unisolated local process runner cannot enforce memory limits."));
+	if (request.secretHandles.length > 0) return Effect.fail(unsupported("secret-handles", "The unisolated local process runner does not resolve secret handles into an environment."));
+	if (request.artifactRules.length > 0) return Effect.fail(unsupported("artifacts", "The unisolated local process runner does not collect artifacts."));
+	return Effect.void;
+};
+const spawnError = (request, message, cause) => SandboxSpawnError.make({
+	implementation: unisolatedImplementation,
+	command: request.command,
+	message,
+	...cause === void 0 ? {} : { cause }
+});
+const environmentFromAllowlist = Effect.fn("LocalSandbox.environmentFromAllowlist")(function* (request) {
+	const environment = {};
+	for (const name of request.environment.allow) {
+		const value = yield* Config.option(Config.string(name)).pipe(Effect.mapError((error) => spawnError(request, `Could not read allowed environment variable '${name}': ${error.message}`, error)));
+		if (Option.isSome(value)) environment[name] = value.value;
+	}
+	return environment;
+});
+const outputEvent = (counts, stream, bytes, decoder, limit) => Ref.modify(counts, (current) => {
+	const streamBytes = current[stream] + bytes.byteLength;
+	const next = {
+		...current,
+		[stream]: streamBytes
+	};
+	return [next.stdout + next.stderr, next];
+}).pipe(Effect.flatMap((observed) => observed > limit ? Effect.fail(SandboxOutputLimitError.make({
+	implementation: unisolatedImplementation,
+	stream,
+	limit,
+	observed
+})) : Effect.succeed(SandboxOutput.make({
+	eventVersion: 1,
+	implementation: unisolatedImplementation,
+	stream,
+	text: decoder.decode(bytes, { stream: true }),
+	bytes: bytes.byteLength
+}))));
+/**
+* Emits any text the streaming decoder still holds once its source stream ends. The final decode
+* must run at end-of-stream, not at pipeline construction, so the flush is suspended; a trailing
+* incomplete UTF-8 sequence surfaces as replacement text. Its raw bytes were already counted when
+* the chunk arrived, so the flush event carries zero bytes.
+*/
+const flushDecoder = (stream, decoder) => Stream.suspend(() => {
+	const text = decoder.decode();
+	return text.length === 0 ? Stream.empty : Stream.succeed(SandboxOutput.make({
+		eventVersion: 1,
+		implementation: unisolatedImplementation,
+		stream,
+		text,
+		bytes: 0
+	}));
+});
+const makeExecute = (spawner) => (request) => Stream.unwrap(Effect.gen(function* () {
+	yield* validateRequest(request);
+	const startedAt = yield* Clock.currentTimeMillis;
+	const counts = yield* Ref.make(zeroOutput);
+	const stdoutDecoder = new TextDecoder();
+	const stderrDecoder = new TextDecoder();
+	const environment = yield* environmentFromAllowlist(request);
+	const command = ChildProcess.make(request.command, request.args, {
+		cwd: request.cwd,
+		env: environment,
+		extendEnv: false,
+		stdout: "pipe",
+		stderr: "pipe"
+	});
+	const child = yield* spawner.spawn(command).pipe(Effect.mapError((error) => spawnError(request, error.message, error)));
+	const streamOutput = (stream, decoder) => {
+		return (stream === "stdout" ? child.stdout : child.stderr).pipe(Stream.mapError((error) => spawnError(request, error.message, error)), Stream.mapEffect((bytes) => outputEvent(counts, stream, bytes, decoder, request.limits.maxOutputBytes)), Stream.concat(flushDecoder(stream, decoder)));
+	};
+	const terminal = Stream.unwrap(Effect.gen(function* () {
+		const exitCode = yield* child.exitCode.pipe(Effect.mapError((error) => SandboxExitError.make({
+			cause: error,
+			implementation: unisolatedImplementation,
+			exitCode: -1,
+			message: error.message
+		})));
+		const endedAt = yield* Clock.currentTimeMillis;
+		const output = yield* Ref.get(counts);
+		const resourceUse = SandboxResourceUse.make({
+			wallTime: Duration.millis(endedAt - startedAt),
+			stdoutBytes: output.stdout,
+			stderrBytes: output.stderr
+		});
+		const exited = SandboxExited.make({
+			eventVersion: 1,
+			implementation: unisolatedImplementation,
+			exitCode,
+			resourceUse,
+			artifacts: []
+		});
+		return exitCode === 0 ? Stream.succeed(exited) : Stream.concat(Stream.succeed(exited), Stream.fail(SandboxExitError.make({
+			implementation: unisolatedImplementation,
+			exitCode,
+			message: `Unisolated local process exited with code ${exitCode}.`
+		})));
+	}));
+	return Stream.concat(Stream.succeed(SandboxStarted.make({
+		eventVersion: 1,
+		implementation: unisolatedImplementation,
+		runtime: request.runtime
+	})), Stream.concat(Stream.merge(streamOutput("stdout", stdoutDecoder), streamOutput("stderr", stderrDecoder)), terminal)).pipe(Stream.interruptWhen(Effect.sleep(request.limits.maxWallTime).pipe(Effect.andThen(Effect.fail(SandboxTimeoutError.make({
+		implementation: unisolatedImplementation,
+		maxWallTime: request.limits.maxWallTime
+	}))))));
+})).pipe(Stream.withSpan("LocalSandbox.execute"));
+/**
+* Development-only local process adapter with its `ChildProcessSpawner` requirement kept visible
+* so composition roots and tests can inject a spawner double. It is unisolated and must never be
+* used as a security boundary for untrusted code or commands.
+*/
+const sandboxLayer = Layer.effect(Sandbox)(Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner;
+	return Sandbox.of({ execute: makeExecute(spawner) });
+}));
+/** A scoped Node process implementation whose events are always labeled `unisolated`. */
+const layer = sandboxLayer.pipe(Layer.provide(NodeServices.layer));
+//#endregion
+export { layer, sandboxLayer, unisolatedImplementation };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/local-sandbox.ts"],"sourcesContent":["import {\n  Sandbox,\n  SandboxExited,\n  SandboxExitError,\n  SandboxImplementation,\n  SandboxOutput,\n  SandboxOutputLimitError,\n  SandboxResourceUse,\n  SandboxSpawnError,\n  SandboxStarted,\n  SandboxTimeoutError,\n  SandboxUnsupportedRequestError,\n  type SandboxError,\n  type SandboxEvent,\n  type SandboxExecute,\n  type SandboxRequest,\n} from \"@effect-agent/sandbox\";\nimport { NodeServices } from \"@effect/platform-node\";\nimport { Clock, Config, Duration, Effect, Layer, Option, Ref, Stream } from \"effect\";\nimport { ChildProcess } from \"effect/unstable/process\";\nimport { ChildProcessSpawner } from \"effect/unstable/process/ChildProcessSpawner\";\n\n/**\n * The only implementation identity produced by this package. It deliberately states that local\n * process execution is unisolated development tooling, not a security sandbox.\n */\nexport const unisolatedImplementation = SandboxImplementation.make({\n  isolation: \"unisolated\",\n  identity: \"local-process\",\n});\n\ntype OutputStream = \"stdout\" | \"stderr\";\ntype OutputCounts = Readonly<Record<OutputStream, number>>;\n\nconst zeroOutput: OutputCounts = { stdout: 0, stderr: 0 };\n\nconst unsupported = (\n  feature: Parameters<typeof SandboxUnsupportedRequestError.make>[0][\"feature\"],\n  message: string,\n) =>\n  SandboxUnsupportedRequestError.make({\n    implementation: unisolatedImplementation,\n    feature,\n    message,\n  });\n\nconst validateRequest = (request: SandboxRequest): Effect.Effect<void, SandboxError> => {\n  if (request.runtime.kind !== \"unisolated-process\") {\n    return Effect.fail(\n      unsupported(\n        \"runtime\",\n        \"The local process runner only accepts runtime.kind 'unisolated-process'.\",\n      ),\n    );\n  }\n  if (request.mounts.length > 0) {\n    return Effect.fail(\n      unsupported(\n        \"mounts\",\n        \"The unisolated local process runner cannot enforce mount access modes.\",\n      ),\n    );\n  }\n  if (request.network._tag !== \"NetworkDisabled\") {\n    return Effect.fail(\n      unsupported(\n        \"network\",\n        \"The unisolated local process runner cannot enforce workload network policy.\",\n      ),\n    );\n  }\n  if (request.limits.cpuCores !== undefined) {\n    return Effect.fail(\n      unsupported(\"cpu-limit\", \"The unisolated local process runner cannot enforce CPU limits.\"),\n    );\n  }\n  if (request.limits.memoryBytes !== undefined) {\n    return Effect.fail(\n      unsupported(\n        \"memory-limit\",\n        \"The unisolated local process runner cannot enforce memory limits.\",\n      ),\n    );\n  }\n  if (request.secretHandles.length > 0) {\n    return Effect.fail(\n      unsupported(\n        \"secret-handles\",\n        \"The unisolated local process runner does not resolve secret handles into an environment.\",\n      ),\n    );\n  }\n  if (request.artifactRules.length > 0) {\n    return Effect.fail(\n      unsupported(\"artifacts\", \"The unisolated local process runner does not collect artifacts.\"),\n    );\n  }\n  return Effect.void;\n};\n\nconst spawnError = (request: SandboxRequest, message: string, cause?: unknown) =>\n  SandboxSpawnError.make({\n    implementation: unisolatedImplementation,\n    command: request.command,\n    message,\n    ...(cause === undefined ? {} : { cause }),\n  });\n\nconst environmentFromAllowlist = Effect.fn(\"LocalSandbox.environmentFromAllowlist\")(function* (\n  request: SandboxRequest,\n) {\n  const environment: Record<string, string> = {};\n  for (const name of request.environment.allow) {\n    const value = yield* Config.option(Config.string(name)).pipe(\n      Effect.mapError((error) =>\n        spawnError(\n          request,\n          `Could not read allowed environment variable '${name}': ${error.message}`,\n          error,\n        ),\n      ),\n    );\n    if (Option.isSome(value)) {\n      environment[name] = value.value;\n    }\n  }\n  return environment;\n});\n\nconst outputEvent = (\n  counts: Ref.Ref<OutputCounts>,\n  stream: OutputStream,\n  bytes: Uint8Array,\n  decoder: TextDecoder,\n  limit: number,\n): Effect.Effect<SandboxOutput, SandboxOutputLimitError> =>\n  Ref.modify(counts, (current) => {\n    const streamBytes = current[stream] + bytes.byteLength;\n    const next = { ...current, [stream]: streamBytes };\n    return [next.stdout + next.stderr, next] as const;\n  }).pipe(\n    Effect.flatMap((observed) =>\n      observed > limit\n        ? Effect.fail(\n            SandboxOutputLimitError.make({\n              implementation: unisolatedImplementation,\n              stream,\n              limit,\n              observed,\n            }),\n          )\n        : Effect.succeed(\n            SandboxOutput.make({\n              eventVersion: 1,\n              implementation: unisolatedImplementation,\n              stream,\n              text: decoder.decode(bytes, { stream: true }),\n              bytes: bytes.byteLength,\n            }),\n          ),\n    ),\n  );\n\n/**\n * Emits any text the streaming decoder still holds once its source stream ends. The final decode\n * must run at end-of-stream, not at pipeline construction, so the flush is suspended; a trailing\n * incomplete UTF-8 sequence surfaces as replacement text. Its raw bytes were already counted when\n * the chunk arrived, so the flush event carries zero bytes.\n */\nconst flushDecoder = (stream: OutputStream, decoder: TextDecoder): Stream.Stream<SandboxOutput> =>\n  Stream.suspend(() => {\n    const text = decoder.decode();\n    return text.length === 0\n      ? Stream.empty\n      : Stream.succeed(\n          SandboxOutput.make({\n            eventVersion: 1,\n            implementation: unisolatedImplementation,\n            stream,\n            text,\n            bytes: 0,\n          }),\n        );\n  });\n\nconst makeExecute =\n  (spawner: ChildProcessSpawner[\"Service\"]): SandboxExecute =>\n  (request) =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        yield* validateRequest(request);\n        const startedAt = yield* Clock.currentTimeMillis;\n        const counts = yield* Ref.make(zeroOutput);\n        const stdoutDecoder = new TextDecoder();\n        const stderrDecoder = new TextDecoder();\n        const environment = yield* environmentFromAllowlist(request);\n        const command = ChildProcess.make(request.command, request.args, {\n          cwd: request.cwd,\n          env: environment,\n          extendEnv: false,\n          stdout: \"pipe\",\n          stderr: \"pipe\",\n        });\n        const child = yield* spawner\n          .spawn(command)\n          .pipe(Effect.mapError((error) => spawnError(request, error.message, error)));\n\n        const streamOutput = (stream: OutputStream, decoder: TextDecoder) => {\n          const source = stream === \"stdout\" ? child.stdout : child.stderr;\n          return source.pipe(\n            Stream.mapError((error) => spawnError(request, error.message, error)),\n            Stream.mapEffect((bytes) =>\n              outputEvent(counts, stream, bytes, decoder, request.limits.maxOutputBytes),\n            ),\n            Stream.concat(flushDecoder(stream, decoder)),\n          );\n        };\n\n        const terminal = Stream.unwrap(\n          Effect.gen(function* () {\n            const exitCode = yield* child.exitCode.pipe(\n              Effect.mapError((error) =>\n                SandboxExitError.make({\n                  cause: error,\n                  implementation: unisolatedImplementation,\n                  exitCode: -1,\n                  message: error.message,\n                }),\n              ),\n            );\n            const endedAt = yield* Clock.currentTimeMillis;\n            const output = yield* Ref.get(counts);\n            const resourceUse = SandboxResourceUse.make({\n              wallTime: Duration.millis(endedAt - startedAt),\n              stdoutBytes: output.stdout,\n              stderrBytes: output.stderr,\n            });\n            const exited = SandboxExited.make({\n              eventVersion: 1,\n              implementation: unisolatedImplementation,\n              exitCode,\n              resourceUse,\n              artifacts: [],\n            });\n            return exitCode === 0\n              ? Stream.succeed<SandboxEvent>(exited)\n              : Stream.concat(\n                  Stream.succeed<SandboxEvent>(exited),\n                  Stream.fail(\n                    SandboxExitError.make({\n                      implementation: unisolatedImplementation,\n                      exitCode,\n                      message: `Unisolated local process exited with code ${exitCode}.`,\n                    }),\n                  ),\n                );\n          }),\n        );\n\n        const execution = Stream.concat(\n          Stream.succeed<SandboxEvent>(\n            SandboxStarted.make({\n              eventVersion: 1,\n              implementation: unisolatedImplementation,\n              runtime: request.runtime,\n            }),\n          ),\n          Stream.concat(\n            Stream.merge(\n              streamOutput(\"stdout\", stdoutDecoder),\n              streamOutput(\"stderr\", stderrDecoder),\n            ),\n            terminal,\n          ),\n        );\n\n        return execution.pipe(\n          Stream.interruptWhen(\n            Effect.sleep(request.limits.maxWallTime).pipe(\n              Effect.andThen(\n                Effect.fail(\n                  SandboxTimeoutError.make({\n                    implementation: unisolatedImplementation,\n                    maxWallTime: request.limits.maxWallTime,\n                  }),\n                ),\n              ),\n            ),\n          ),\n        );\n      }),\n    ).pipe(Stream.withSpan(\"LocalSandbox.execute\"));\n\n/**\n * Development-only local process adapter with its `ChildProcessSpawner` requirement kept visible\n * so composition roots and tests can inject a spawner double. It is unisolated and must never be\n * used as a security boundary for untrusted code or commands.\n */\nexport const sandboxLayer: Layer.Layer<Sandbox, never, ChildProcessSpawner> = Layer.effect(Sandbox)(\n  Effect.gen(function* () {\n    const spawner = yield* ChildProcessSpawner;\n    return Sandbox.of({ execute: makeExecute(spawner) });\n  }),\n);\n\n/** A scoped Node process implementation whose events are always labeled `unisolated`. */\nexport const layer: Layer.Layer<Sandbox> = sandboxLayer.pipe(Layer.provide(NodeServices.layer));\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@effect-agent/sandbox-local",
+  "version": "0.0.1-beta.0",
+  "description": "Node-local child-process Sandbox adapter for Effect Agent; honestly labeled unisolated development tooling, not a security boundary.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danieljvdm/effect-agent.git",
+    "directory": "packages/sandbox-local"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "vp test --passWithNoTests"
+  },
+  "dependencies": {
+    "@effect-agent/sandbox": "0.0.0",
+    "@effect/platform-node": "4.0.0-beta.102",
+    "effect": "4.0.0-beta.102"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-beta.102",
+    "@types/node": "26.1.2",
+    "typescript": "7.0.2",
+    "vite-plus": "0.2.6"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./local-sandbox.ts";

package/src/local-sandbox.ts

@@ -0,0 +1,307 @@
+import {
+  Sandbox,
+  SandboxExited,
+  SandboxExitError,
+  SandboxImplementation,
+  SandboxOutput,
+  SandboxOutputLimitError,
+  SandboxResourceUse,
+  SandboxSpawnError,
+  SandboxStarted,
+  SandboxTimeoutError,
+  SandboxUnsupportedRequestError,
+  type SandboxError,
+  type SandboxEvent,
+  type SandboxExecute,
+  type SandboxRequest,
+} from "@effect-agent/sandbox";
+import { NodeServices } from "@effect/platform-node";
+import { Clock, Config, Duration, Effect, Layer, Option, Ref, Stream } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
+
+/**
+ * The only implementation identity produced by this package. It deliberately states that local
+ * process execution is unisolated development tooling, not a security sandbox.
+ */
+export const unisolatedImplementation = SandboxImplementation.make({
+  isolation: "unisolated",
+  identity: "local-process",
+});
+
+type OutputStream = "stdout" | "stderr";
+type OutputCounts = Readonly<Record<OutputStream, number>>;
+
+const zeroOutput: OutputCounts = { stdout: 0, stderr: 0 };
+
+const unsupported = (
+  feature: Parameters<typeof SandboxUnsupportedRequestError.make>[0]["feature"],
+  message: string,
+) =>
+  SandboxUnsupportedRequestError.make({
+    implementation: unisolatedImplementation,
+    feature,
+    message,
+  });
+
+const validateRequest = (request: SandboxRequest): Effect.Effect<void, SandboxError> => {
+  if (request.runtime.kind !== "unisolated-process") {
+    return Effect.fail(
+      unsupported(
+        "runtime",
+        "The local process runner only accepts runtime.kind 'unisolated-process'.",
+      ),
+    );
+  }
+  if (request.mounts.length > 0) {
+    return Effect.fail(
+      unsupported(
+        "mounts",
+        "The unisolated local process runner cannot enforce mount access modes.",
+      ),
+    );
+  }
+  if (request.network._tag !== "NetworkDisabled") {
+    return Effect.fail(
+      unsupported(
+        "network",
+        "The unisolated local process runner cannot enforce workload network policy.",
+      ),
+    );
+  }
+  if (request.limits.cpuCores !== undefined) {
+    return Effect.fail(
+      unsupported("cpu-limit", "The unisolated local process runner cannot enforce CPU limits."),
+    );
+  }
+  if (request.limits.memoryBytes !== undefined) {
+    return Effect.fail(
+      unsupported(
+        "memory-limit",
+        "The unisolated local process runner cannot enforce memory limits.",
+      ),
+    );
+  }
+  if (request.secretHandles.length > 0) {
+    return Effect.fail(
+      unsupported(
+        "secret-handles",
+        "The unisolated local process runner does not resolve secret handles into an environment.",
+      ),
+    );
+  }
+  if (request.artifactRules.length > 0) {
+    return Effect.fail(
+      unsupported("artifacts", "The unisolated local process runner does not collect artifacts."),
+    );
+  }
+  return Effect.void;
+};
+
+const spawnError = (request: SandboxRequest, message: string, cause?: unknown) =>
+  SandboxSpawnError.make({
+    implementation: unisolatedImplementation,
+    command: request.command,
+    message,
+    ...(cause === undefined ? {} : { cause }),
+  });
+
+const environmentFromAllowlist = Effect.fn("LocalSandbox.environmentFromAllowlist")(function* (
+  request: SandboxRequest,
+) {
+  const environment: Record<string, string> = {};
+  for (const name of request.environment.allow) {
+    const value = yield* Config.option(Config.string(name)).pipe(
+      Effect.mapError((error) =>
+        spawnError(
+          request,
+          `Could not read allowed environment variable '${name}': ${error.message}`,
+          error,
+        ),
+      ),
+    );
+    if (Option.isSome(value)) {
+      environment[name] = value.value;
+    }
+  }
+  return environment;
+});
+
+const outputEvent = (
+  counts: Ref.Ref<OutputCounts>,
+  stream: OutputStream,
+  bytes: Uint8Array,
+  decoder: TextDecoder,
+  limit: number,
+): Effect.Effect<SandboxOutput, SandboxOutputLimitError> =>
+  Ref.modify(counts, (current) => {
+    const streamBytes = current[stream] + bytes.byteLength;
+    const next = { ...current, [stream]: streamBytes };
+    return [next.stdout + next.stderr, next] as const;
+  }).pipe(
+    Effect.flatMap((observed) =>
+      observed > limit
+        ? Effect.fail(
+            SandboxOutputLimitError.make({
+              implementation: unisolatedImplementation,
+              stream,
+              limit,
+              observed,
+            }),
+          )
+        : Effect.succeed(
+            SandboxOutput.make({
+              eventVersion: 1,
+              implementation: unisolatedImplementation,
+              stream,
+              text: decoder.decode(bytes, { stream: true }),
+              bytes: bytes.byteLength,
+            }),
+          ),
+    ),
+  );
+
+/**
+ * Emits any text the streaming decoder still holds once its source stream ends. The final decode
+ * must run at end-of-stream, not at pipeline construction, so the flush is suspended; a trailing
+ * incomplete UTF-8 sequence surfaces as replacement text. Its raw bytes were already counted when
+ * the chunk arrived, so the flush event carries zero bytes.
+ */
+const flushDecoder = (stream: OutputStream, decoder: TextDecoder): Stream.Stream<SandboxOutput> =>
+  Stream.suspend(() => {
+    const text = decoder.decode();
+    return text.length === 0
+      ? Stream.empty
+      : Stream.succeed(
+          SandboxOutput.make({
+            eventVersion: 1,
+            implementation: unisolatedImplementation,
+            stream,
+            text,
+            bytes: 0,
+          }),
+        );
+  });
+
+const makeExecute =
+  (spawner: ChildProcessSpawner["Service"]): SandboxExecute =>
+  (request) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        yield* validateRequest(request);
+        const startedAt = yield* Clock.currentTimeMillis;
+        const counts = yield* Ref.make(zeroOutput);
+        const stdoutDecoder = new TextDecoder();
+        const stderrDecoder = new TextDecoder();
+        const environment = yield* environmentFromAllowlist(request);
+        const command = ChildProcess.make(request.command, request.args, {
+          cwd: request.cwd,
+          env: environment,
+          extendEnv: false,
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        const child = yield* spawner
+          .spawn(command)
+          .pipe(Effect.mapError((error) => spawnError(request, error.message, error)));
+
+        const streamOutput = (stream: OutputStream, decoder: TextDecoder) => {
+          const source = stream === "stdout" ? child.stdout : child.stderr;
+          return source.pipe(
+            Stream.mapError((error) => spawnError(request, error.message, error)),
+            Stream.mapEffect((bytes) =>
+              outputEvent(counts, stream, bytes, decoder, request.limits.maxOutputBytes),
+            ),
+            Stream.concat(flushDecoder(stream, decoder)),
+          );
+        };
+
+        const terminal = Stream.unwrap(
+          Effect.gen(function* () {
+            const exitCode = yield* child.exitCode.pipe(
+              Effect.mapError((error) =>
+                SandboxExitError.make({
+                  cause: error,
+                  implementation: unisolatedImplementation,
+                  exitCode: -1,
+                  message: error.message,
+                }),
+              ),
+            );
+            const endedAt = yield* Clock.currentTimeMillis;
+            const output = yield* Ref.get(counts);
+            const resourceUse = SandboxResourceUse.make({
+              wallTime: Duration.millis(endedAt - startedAt),
+              stdoutBytes: output.stdout,
+              stderrBytes: output.stderr,
+            });
+            const exited = SandboxExited.make({
+              eventVersion: 1,
+              implementation: unisolatedImplementation,
+              exitCode,
+              resourceUse,
+              artifacts: [],
+            });
+            return exitCode === 0
+              ? Stream.succeed<SandboxEvent>(exited)
+              : Stream.concat(
+                  Stream.succeed<SandboxEvent>(exited),
+                  Stream.fail(
+                    SandboxExitError.make({
+                      implementation: unisolatedImplementation,
+                      exitCode,
+                      message: `Unisolated local process exited with code ${exitCode}.`,
+                    }),
+                  ),
+                );
+          }),
+        );
+
+        const execution = Stream.concat(
+          Stream.succeed<SandboxEvent>(
+            SandboxStarted.make({
+              eventVersion: 1,
+              implementation: unisolatedImplementation,
+              runtime: request.runtime,
+            }),
+          ),
+          Stream.concat(
+            Stream.merge(
+              streamOutput("stdout", stdoutDecoder),
+              streamOutput("stderr", stderrDecoder),
+            ),
+            terminal,
+          ),
+        );
+
+        return execution.pipe(
+          Stream.interruptWhen(
+            Effect.sleep(request.limits.maxWallTime).pipe(
+              Effect.andThen(
+                Effect.fail(
+                  SandboxTimeoutError.make({
+                    implementation: unisolatedImplementation,
+                    maxWallTime: request.limits.maxWallTime,
+                  }),
+                ),
+              ),
+            ),
+          ),
+        );
+      }),
+    ).pipe(Stream.withSpan("LocalSandbox.execute"));
+
+/**
+ * Development-only local process adapter with its `ChildProcessSpawner` requirement kept visible
+ * so composition roots and tests can inject a spawner double. It is unisolated and must never be
+ * used as a security boundary for untrusted code or commands.
+ */
+export const sandboxLayer: Layer.Layer<Sandbox, never, ChildProcessSpawner> = Layer.effect(Sandbox)(
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner;
+    return Sandbox.of({ execute: makeExecute(spawner) });
+  }),
+);
+
+/** A scoped Node process implementation whose events are always labeled `unisolated`. */
+export const layer: Layer.Layer<Sandbox> = sandboxLayer.pipe(Layer.provide(NodeServices.layer));