@yolk-sdk/sandbox 0.1.0-canary.18

package/dist/vercel/layer.mjs

@@ -0,0 +1,250 @@
+import { SandboxProviderError, unknownToMessage } from "../errors.mjs";
+import { SandboxCommandResult, SandboxPreviewUrl, SandboxResources } from "../model.mjs";
+import { absoluteSandboxCwd, backgroundSandboxProbeMs, defaultSandboxPorts, initialSandboxState, normalizeWorkspaceCwd, sandboxCommandTimeoutMs, sandboxLifecycleOrDefault, sandboxSourceOrDefault, sandboxStateDecision, sandboxTimeoutExtendDeltaMs, touchSandboxState, validateSandboxCommand } from "../lifecycle.mjs";
+import { Sandbox } from "../service.mjs";
+import { makeVercelSandboxName } from "../name.mjs";
+import { SandboxStateStore } from "../state-store.mjs";
+import { VercelSandboxClient, VercelSandboxClientLive } from "./client.mjs";
+import { Array, Clock, Duration, Effect, Layer, Option, Ref, Semaphore } from "effect";
+//#region src/vercel/layer.ts
+const defaultVercelResources = SandboxResources.make({ vcpus: 2 });
+const defaultVercelRuntime = "node24";
+const providerError = (operation, error) => new SandboxProviderError({
+	provider: "vercel",
+	operation,
+	message: `Vercel Sandbox ${operation} failed: ${unknownToMessage(error)}`,
+	underlying: error
+});
+const tryProvider = (operation, body) => Effect.tryPromise({
+	try: body,
+	catch: (error) => providerError(operation, error)
+});
+const lifecycleTimeoutMs = (lifecycle) => {
+	switch (lifecycle._tag) {
+		case "Disposable": return Math.min(lifecycle.idleTtlMs, lifecycle.maxLifetimeMs);
+		case "Persistent": return lifecycle.idleTtlMs;
+	}
+};
+const persistentFlag = (lifecycle) => lifecycle._tag === "Persistent";
+const snapshotExpirationMs = (lifecycle) => lifecycle._tag === "Persistent" ? lifecycle.snapshotExpirationMs : void 0;
+const keepLastSnapshots = (lifecycle) => lifecycle._tag === "Persistent" ? lifecycle.keepLastSnapshots : void 0;
+const previewUrls = (handle, ports) => Effect.forEach(ports, (port) => Effect.try({
+	try: () => handle.domain(port),
+	catch: (error) => error
+}).pipe(Effect.match({
+	onFailure: () => Option.none(),
+	onSuccess: (url) => Option.some(SandboxPreviewUrl.make({
+		port,
+		url
+	}))
+}))).pipe(Effect.map(Array.getSomes));
+const commandOutputOrEmpty = (command) => tryProvider("command.output", command.output).pipe(Effect.catchTag("SandboxProviderError", (error) => Effect.succeed({
+	stdout: "",
+	stderr: error.message
+})));
+const finishedCommandOutputOrEmpty = (command) => tryProvider("command.output", command.output).pipe(Effect.catchTag("SandboxProviderError", (error) => Effect.succeed({
+	stdout: "",
+	stderr: error.message
+})));
+const waitForegroundCommand = (command, timeoutMs) => tryProvider("command.wait", command.wait).pipe(Effect.flatMap((finished) => finishedCommandOutputOrEmpty(finished).pipe(Effect.map((output) => ({
+	exitCode: finished.exitCode,
+	stdout: output.stdout,
+	stderr: output.stderr,
+	timedOut: false
+})))), Effect.timeoutOrElse({
+	duration: Duration.millis(timeoutMs),
+	orElse: () => Effect.gen(function* () {
+		yield* tryProvider("command.kill", () => command.kill("SIGKILL")).pipe(Effect.catchTag("SandboxProviderError", () => Effect.void));
+		const output = yield* commandOutputOrEmpty(command);
+		return {
+			exitCode: null,
+			stdout: output.stdout,
+			stderr: output.stderr,
+			timedOut: true
+		};
+	})
+}));
+const probeBackgroundCommand = (handle, command) => Effect.sleep(Duration.millis(backgroundSandboxProbeMs)).pipe(Effect.flatMap(() => tryProvider("command.get", () => handle.getCommand(command.id))), Effect.flatMap((current) => {
+	if (current.exitCode === null) return Effect.succeed({
+		exitCode: null,
+		stdout: "",
+		stderr: "",
+		timedOut: false,
+		backgroundId: command.id
+	});
+	return commandOutputOrEmpty(current).pipe(Effect.map((output) => ({
+		exitCode: current.exitCode,
+		stdout: output.stdout,
+		stderr: output.stderr,
+		timedOut: false
+	})));
+}));
+const createCommandFiles = (input) => {
+	const commandDir = `${input.workspaceRoot}/.yolk/commands/${input.commandId}`;
+	const commandPath = `${commandDir}/command.sh`;
+	const stdinPath = `${commandDir}/stdin.txt`;
+	const wrapperPath = `${commandDir}/wrapper.sh`;
+	return {
+		wrapperPath,
+		files: [
+			{
+				path: commandPath,
+				content: `#!/usr/bin/env bash\n${input.command}\n`,
+				mode: 493
+			},
+			{
+				path: stdinPath,
+				content: input.stdin ?? ""
+			},
+			{
+				path: wrapperPath,
+				content: `#!/usr/bin/env bash\nbash ${JSON.stringify(commandPath)} < ${JSON.stringify(stdinPath)}\n`,
+				mode: 493
+			}
+		]
+	};
+};
+const makeVercelSandboxLayerWithClient = (config) => Layer.effect(Sandbox, Effect.gen(function* () {
+	const store = yield* SandboxStateStore;
+	const client = yield* VercelSandboxClient;
+	const semaphore = yield* Semaphore.make(1);
+	const commandCounter = yield* Ref.make(0);
+	const lifecycle = sandboxLifecycleOrDefault(config.lifecycle);
+	const source = sandboxSourceOrDefault(config.source);
+	const ports = config.ports ?? defaultSandboxPorts;
+	const resources = config.resources ?? defaultVercelResources;
+	const runtime = config.runtime ?? defaultVercelRuntime;
+	const workspaceRoot = config.workspaceRoot ?? "/vercel/sandbox";
+	const name = makeVercelSandboxName(config.sandboxSessionId);
+	const deleteNamedSandbox = (sandboxName) => tryProvider("get", () => client.get({ name: sandboxName })).pipe(Effect.flatMap((handle) => handle === null ? Effect.void : tryProvider("delete", () => handle.delete())));
+	const createSandbox = (input) => Effect.gen(function* () {
+		const handle = yield* tryProvider("create", () => client.create({
+			name,
+			source,
+			ports,
+			timeoutMs: lifecycleTimeoutMs(lifecycle),
+			resources,
+			runtime,
+			env: config.env,
+			persistent: persistentFlag(lifecycle),
+			snapshotExpirationMs: snapshotExpirationMs(lifecycle),
+			keepLastSnapshots: keepLastSnapshots(lifecycle),
+			networkPolicy: config.networkPolicy
+		}));
+		const state = initialSandboxState({
+			name,
+			nowMs: input.nowMs,
+			lifecycle
+		});
+		yield* store.save({
+			sandboxSessionId: config.sandboxSessionId,
+			state
+		});
+		return {
+			handle,
+			state,
+			workspaceReset: input.workspaceReset
+		};
+	});
+	const touchExistingSandbox = (input) => Effect.gen(function* () {
+		const touched = touchSandboxState({
+			state: input.state,
+			nowMs: input.nowMs,
+			lifecycle
+		});
+		const deltaMs = sandboxTimeoutExtendDeltaMs({
+			before: input.state,
+			after: touched
+		});
+		if (deltaMs > 0) yield* tryProvider("extendTimeout", () => input.handle.extendTimeout(deltaMs));
+		yield* store.save({
+			sandboxSessionId: config.sandboxSessionId,
+			state: touched
+		});
+		return {
+			handle: input.handle,
+			state: touched,
+			workspaceReset: input.workspaceReset
+		};
+	});
+	const ensureSandbox = (nowMs) => Effect.gen(function* () {
+		const loaded = yield* store.load(config.sandboxSessionId);
+		const decision = sandboxStateDecision({
+			state: loaded,
+			name,
+			nowMs
+		});
+		if (decision._tag === "Create") {
+			if (Option.isSome(loaded) && decision.workspaceReset) {
+				yield* deleteNamedSandbox(loaded.value.name);
+				yield* store.clear(config.sandboxSessionId);
+			}
+			return yield* createSandbox({
+				nowMs,
+				workspaceReset: decision.workspaceReset
+			});
+		}
+		const handle = yield* tryProvider("get", () => client.get({ name }));
+		if (handle === null) {
+			yield* store.clear(config.sandboxSessionId);
+			return yield* createSandbox({
+				nowMs,
+				workspaceReset: true
+			});
+		}
+		return yield* touchExistingSandbox({
+			handle,
+			state: decision.state,
+			nowMs,
+			workspaceReset: false
+		});
+	});
+	const nextCommandId = Ref.updateAndGet(commandCounter, (value) => value + 1).pipe(Effect.map((value) => `command-${value}`));
+	const runUnlocked = (input) => Effect.gen(function* () {
+		yield* validateSandboxCommand(input.command);
+		const normalizedCwd = yield* normalizeWorkspaceCwd(input.cwd);
+		const timeoutMs = sandboxCommandTimeoutMs(input.timeoutMs);
+		const active = yield* ensureSandbox(yield* Clock.currentTimeMillis);
+		const commandFiles = createCommandFiles({
+			commandId: yield* nextCommandId,
+			workspaceRoot,
+			command: input.command,
+			stdin: input.stdin
+		});
+		yield* tryProvider("writeFiles", () => active.handle.writeFiles(commandFiles.files));
+		const startedAtMs = yield* Clock.currentTimeMillis;
+		const command = yield* tryProvider("runCommand", () => active.handle.runDetachedCommand({
+			cmd: "bash",
+			args: [commandFiles.wrapperPath],
+			cwd: absoluteSandboxCwd(workspaceRoot, normalizedCwd)
+		}));
+		const output = yield* input.background === true ? probeBackgroundCommand(active.handle, command) : waitForegroundCommand(command, timeoutMs);
+		const endedAtMs = yield* Clock.currentTimeMillis;
+		const urls = yield* previewUrls(active.handle, ports);
+		return SandboxCommandResult.make({
+			exitCode: output.exitCode,
+			stdout: output.stdout,
+			stderr: output.stderr,
+			durationMs: Math.max(0, endedAtMs - startedAtMs),
+			timedOut: output.timedOut,
+			workspaceReset: active.workspaceReset,
+			...output.backgroundId === void 0 ? {} : { backgroundId: output.backgroundId },
+			previewUrls: urls,
+			state: active.state
+		});
+	});
+	return Sandbox.of({
+		run: (input) => semaphore.withPermits(1)(runUnlocked(input)),
+		currentState: store.load(config.sandboxSessionId),
+		delete: Effect.gen(function* () {
+			const loaded = yield* store.load(config.sandboxSessionId);
+			if (Option.isSome(loaded)) yield* deleteNamedSandbox(loaded.value.name);
+			yield* store.clear(config.sandboxSessionId);
+		})
+	});
+}));
+const makeVercelSandboxLayer = (config) => makeVercelSandboxLayerWithClient(config).pipe(Layer.provide(VercelSandboxClientLive));
+//#endregion
+export { makeVercelSandboxLayer, makeVercelSandboxLayerWithClient };
+
+//# sourceMappingURL=layer.mjs.map

package/dist/vercel/layer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer.mjs","names":["Arr"],"sources":["../../src/vercel/layer.ts"],"sourcesContent":["import { Array as Arr, Clock, Duration, Effect, Layer, Option, Ref, Semaphore } from 'effect'\nimport {\n  absoluteSandboxCwd,\n  backgroundSandboxProbeMs,\n  defaultSandboxPorts,\n  defaultSandboxWorkspaceRoot,\n  initialSandboxState,\n  normalizeWorkspaceCwd,\n  sandboxCommandTimeoutMs,\n  sandboxLifecycleOrDefault,\n  sandboxSourceOrDefault,\n  sandboxStateDecision,\n  sandboxTimeoutExtendDeltaMs,\n  touchSandboxState,\n  validateSandboxCommand\n} from '../lifecycle.ts'\nimport { makeVercelSandboxName } from '../name.ts'\nimport {\n  SandboxCommandResult,\n  type SandboxCommandInput,\n  SandboxPreviewUrl,\n  SandboxResources,\n  type SandboxInitialSource,\n  type SandboxLifecycle,\n  type SandboxState\n} from '../model.ts'\nimport { Sandbox } from '../service.ts'\nimport { SandboxStateStore } from '../state-store.ts'\nimport { SandboxProviderError, unknownToMessage } from '../errors.ts'\nimport type { SandboxError } from '../errors.ts'\nimport {\n  VercelSandboxClient,\n  VercelSandboxClientLive,\n  type VercelDetachedCommand,\n  type VercelNetworkPolicy,\n  type VercelSandboxHandle,\n  type VercelSandboxRuntime\n} from './client.ts'\n\nexport type VercelSandboxLayerConfig = {\n  readonly sandboxSessionId: string\n  readonly lifecycle?: SandboxLifecycle\n  readonly source?: SandboxInitialSource\n  readonly env?: Readonly<Record<string, string>>\n  readonly ports?: ReadonlyArray<number>\n  readonly resources?: SandboxResources\n  readonly runtime?: VercelSandboxRuntime\n  readonly networkPolicy?: VercelNetworkPolicy\n  readonly workspaceRoot?: string\n}\n\ntype ActiveSandbox = {\n  readonly handle: VercelSandboxHandle\n  readonly state: SandboxState\n  readonly workspaceReset: boolean\n}\n\ntype CommandRunOutput = {\n  readonly exitCode: number | null\n  readonly stdout: string\n  readonly stderr: string\n  readonly timedOut: boolean\n  readonly backgroundId?: string\n}\n\nconst defaultVercelResources = SandboxResources.make({ vcpus: 2 })\nconst defaultVercelRuntime: VercelSandboxRuntime = 'node24'\n\nconst providerError = (operation: string, error: unknown) =>\n  new SandboxProviderError({\n    provider: 'vercel',\n    operation,\n    message: `Vercel Sandbox ${operation} failed: ${unknownToMessage(error)}`,\n    underlying: error\n  })\n\nconst tryProvider = <A>(operation: string, body: () => Promise<A>) =>\n  Effect.tryPromise({\n    try: body,\n    catch: error => providerError(operation, error)\n  })\n\nconst lifecycleTimeoutMs = (lifecycle: SandboxLifecycle) => {\n  switch (lifecycle._tag) {\n    case 'Disposable':\n      return Math.min(lifecycle.idleTtlMs, lifecycle.maxLifetimeMs)\n    case 'Persistent':\n      return lifecycle.idleTtlMs\n  }\n}\n\nconst persistentFlag = (lifecycle: SandboxLifecycle) => lifecycle._tag === 'Persistent'\n\nconst snapshotExpirationMs = (lifecycle: SandboxLifecycle) =>\n  lifecycle._tag === 'Persistent' ? lifecycle.snapshotExpirationMs : undefined\n\nconst keepLastSnapshots = (lifecycle: SandboxLifecycle) =>\n  lifecycle._tag === 'Persistent' ? lifecycle.keepLastSnapshots : undefined\n\nconst previewUrls = (handle: VercelSandboxHandle, ports: ReadonlyArray<number>) =>\n  Effect.forEach(ports, port =>\n    Effect.try({\n      try: () => handle.domain(port),\n      catch: error => error\n    }).pipe(\n      Effect.match({\n        onFailure: () => Option.none<SandboxPreviewUrl>(),\n        onSuccess: url => Option.some(SandboxPreviewUrl.make({ port, url }))\n      })\n    )\n  ).pipe(Effect.map(Arr.getSomes))\n\nconst commandOutputOrEmpty = (command: VercelDetachedCommand) =>\n  tryProvider('command.output', command.output).pipe(\n    Effect.catchTag('SandboxProviderError', error =>\n      Effect.succeed({\n        stdout: '',\n        stderr: error.message\n      })\n    )\n  )\n\nconst finishedCommandOutputOrEmpty = (command: {\n  readonly output: () => Promise<{ readonly stdout: string; readonly stderr: string }>\n}) =>\n  tryProvider('command.output', command.output).pipe(\n    Effect.catchTag('SandboxProviderError', error =>\n      Effect.succeed({\n        stdout: '',\n        stderr: error.message\n      })\n    )\n  )\n\nconst waitForegroundCommand = (\n  command: VercelDetachedCommand,\n  timeoutMs: number\n): Effect.Effect<CommandRunOutput, SandboxProviderError> =>\n  tryProvider('command.wait', command.wait).pipe(\n    Effect.flatMap(finished =>\n      finishedCommandOutputOrEmpty(finished).pipe(\n        Effect.map(output => ({\n          exitCode: finished.exitCode,\n          stdout: output.stdout,\n          stderr: output.stderr,\n          timedOut: false\n        }))\n      )\n    ),\n    Effect.timeoutOrElse({\n      duration: Duration.millis(timeoutMs),\n      orElse: () =>\n        Effect.gen(function* () {\n          yield* tryProvider('command.kill', () => command.kill('SIGKILL')).pipe(\n            Effect.catchTag('SandboxProviderError', () => Effect.void)\n          )\n          const output = yield* commandOutputOrEmpty(command)\n\n          return {\n            exitCode: null,\n            stdout: output.stdout,\n            stderr: output.stderr,\n            timedOut: true\n          }\n        })\n    })\n  )\n\nconst probeBackgroundCommand = (\n  handle: VercelSandboxHandle,\n  command: VercelDetachedCommand\n): Effect.Effect<CommandRunOutput, SandboxProviderError> =>\n  Effect.sleep(Duration.millis(backgroundSandboxProbeMs)).pipe(\n    Effect.flatMap(() => tryProvider('command.get', () => handle.getCommand(command.id))),\n    Effect.flatMap(current => {\n      if (current.exitCode === null) {\n        return Effect.succeed({\n          exitCode: null,\n          stdout: '',\n          stderr: '',\n          timedOut: false,\n          backgroundId: command.id\n        })\n      }\n\n      return commandOutputOrEmpty(current).pipe(\n        Effect.map(output => ({\n          exitCode: current.exitCode,\n          stdout: output.stdout,\n          stderr: output.stderr,\n          timedOut: false\n        }))\n      )\n    })\n  )\n\nconst createCommandFiles = (input: {\n  readonly commandId: string\n  readonly workspaceRoot: string\n  readonly command: string\n  readonly stdin?: string\n}) => {\n  const commandDir = `${input.workspaceRoot}/.yolk/commands/${input.commandId}`\n  const commandPath = `${commandDir}/command.sh`\n  const stdinPath = `${commandDir}/stdin.txt`\n  const wrapperPath = `${commandDir}/wrapper.sh`\n\n  return {\n    wrapperPath,\n    files: [\n      {\n        path: commandPath,\n        content: `#!/usr/bin/env bash\\n${input.command}\\n`,\n        mode: 0o755\n      },\n      {\n        path: stdinPath,\n        content: input.stdin ?? ''\n      },\n      {\n        path: wrapperPath,\n        content: `#!/usr/bin/env bash\\nbash ${JSON.stringify(commandPath)} < ${JSON.stringify(stdinPath)}\\n`,\n        mode: 0o755\n      }\n    ]\n  }\n}\n\nexport const makeVercelSandboxLayerWithClient = (config: VercelSandboxLayerConfig) =>\n  Layer.effect(\n    Sandbox,\n    Effect.gen(function* () {\n      const store = yield* SandboxStateStore\n      const client = yield* VercelSandboxClient\n      const semaphore = yield* Semaphore.make(1)\n      const commandCounter = yield* Ref.make(0)\n      const lifecycle = sandboxLifecycleOrDefault(config.lifecycle)\n      const source = sandboxSourceOrDefault(config.source)\n      const ports = config.ports ?? defaultSandboxPorts\n      const resources = config.resources ?? defaultVercelResources\n      const runtime = config.runtime ?? defaultVercelRuntime\n      const workspaceRoot = config.workspaceRoot ?? defaultSandboxWorkspaceRoot\n      const name = makeVercelSandboxName(config.sandboxSessionId)\n\n      const deleteNamedSandbox = (sandboxName: string) =>\n        tryProvider('get', () => client.get({ name: sandboxName })).pipe(\n          Effect.flatMap(handle =>\n            handle === null\n              ? Effect.void\n              : tryProvider('delete', () => handle.delete())\n          )\n        )\n\n      const createSandbox = (input: { readonly nowMs: number; readonly workspaceReset: boolean }) =>\n        Effect.gen(function* () {\n          const handle = yield* tryProvider('create', () =>\n            client.create({\n              name,\n              source,\n              ports,\n              timeoutMs: lifecycleTimeoutMs(lifecycle),\n              resources,\n              runtime,\n              env: config.env,\n              persistent: persistentFlag(lifecycle),\n              snapshotExpirationMs: snapshotExpirationMs(lifecycle),\n              keepLastSnapshots: keepLastSnapshots(lifecycle),\n              networkPolicy: config.networkPolicy\n            })\n          )\n          const state = initialSandboxState({ name, nowMs: input.nowMs, lifecycle })\n          yield* store.save({ sandboxSessionId: config.sandboxSessionId, state })\n\n          return { handle, state, workspaceReset: input.workspaceReset }\n        })\n\n      const touchExistingSandbox = (input: {\n        readonly handle: VercelSandboxHandle\n        readonly state: SandboxState\n        readonly nowMs: number\n        readonly workspaceReset: boolean\n      }) =>\n        Effect.gen(function* () {\n          const touched = touchSandboxState({\n            state: input.state,\n            nowMs: input.nowMs,\n            lifecycle\n          })\n          const deltaMs = sandboxTimeoutExtendDeltaMs({ before: input.state, after: touched })\n\n          if (deltaMs > 0) {\n            yield* tryProvider('extendTimeout', () => input.handle.extendTimeout(deltaMs))\n          }\n\n          yield* store.save({ sandboxSessionId: config.sandboxSessionId, state: touched })\n\n          return {\n            handle: input.handle,\n            state: touched,\n            workspaceReset: input.workspaceReset\n          }\n        })\n\n      const ensureSandbox = (nowMs: number): Effect.Effect<ActiveSandbox, SandboxError> =>\n        Effect.gen(function* () {\n          const loaded = yield* store.load(config.sandboxSessionId)\n          const decision = sandboxStateDecision({ state: loaded, name, nowMs })\n\n          if (decision._tag === 'Create') {\n            if (Option.isSome(loaded) && decision.workspaceReset) {\n              yield* deleteNamedSandbox(loaded.value.name)\n              yield* store.clear(config.sandboxSessionId)\n            }\n\n            return yield* createSandbox({ nowMs, workspaceReset: decision.workspaceReset })\n          }\n\n          const handle = yield* tryProvider('get', () => client.get({ name }))\n\n          if (handle === null) {\n            yield* store.clear(config.sandboxSessionId)\n            return yield* createSandbox({ nowMs, workspaceReset: true })\n          }\n\n          return yield* touchExistingSandbox({\n            handle,\n            state: decision.state,\n            nowMs,\n            workspaceReset: false\n          })\n        })\n\n      const nextCommandId = Ref.updateAndGet(commandCounter, value => value + 1).pipe(\n        Effect.map(value => `command-${value}`)\n      )\n\n      const runUnlocked = (input: SandboxCommandInput) =>\n        Effect.gen(function* () {\n          yield* validateSandboxCommand(input.command)\n          const normalizedCwd = yield* normalizeWorkspaceCwd(input.cwd)\n          const timeoutMs = sandboxCommandTimeoutMs(input.timeoutMs)\n          const nowMs = yield* Clock.currentTimeMillis\n          const active = yield* ensureSandbox(nowMs)\n          const id = yield* nextCommandId\n          const commandFiles = createCommandFiles({\n            commandId: id,\n            workspaceRoot,\n            command: input.command,\n            stdin: input.stdin\n          })\n\n          yield* tryProvider('writeFiles', () => active.handle.writeFiles(commandFiles.files))\n\n          const startedAtMs = yield* Clock.currentTimeMillis\n          const command = yield* tryProvider('runCommand', () =>\n            active.handle.runDetachedCommand({\n              cmd: 'bash',\n              args: [commandFiles.wrapperPath],\n              cwd: absoluteSandboxCwd(workspaceRoot, normalizedCwd)\n            })\n          )\n          const output = yield* (input.background === true\n            ? probeBackgroundCommand(active.handle, command)\n            : waitForegroundCommand(command, timeoutMs))\n          const endedAtMs = yield* Clock.currentTimeMillis\n          const urls = yield* previewUrls(active.handle, ports)\n\n          return SandboxCommandResult.make({\n            exitCode: output.exitCode,\n            stdout: output.stdout,\n            stderr: output.stderr,\n            durationMs: Math.max(0, endedAtMs - startedAtMs),\n            timedOut: output.timedOut,\n            workspaceReset: active.workspaceReset,\n            ...(output.backgroundId === undefined ? {} : { backgroundId: output.backgroundId }),\n            previewUrls: urls,\n            state: active.state\n          })\n        })\n\n      return Sandbox.of({\n        run: input => semaphore.withPermits(1)(runUnlocked(input)),\n        currentState: store.load(config.sandboxSessionId),\n        delete: Effect.gen(function* () {\n          const loaded = yield* store.load(config.sandboxSessionId)\n          if (Option.isSome(loaded)) {\n            yield* deleteNamedSandbox(loaded.value.name)\n          }\n          yield* store.clear(config.sandboxSessionId)\n        })\n      })\n    })\n  )\n\nexport const makeVercelSandboxLayer = (config: VercelSandboxLayerConfig) =>\n  makeVercelSandboxLayerWithClient(config).pipe(Layer.provide(VercelSandboxClientLive))\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@yolk-sdk/sandbox",
+  "version": "0.1.0-canary.18",
+  "description": "Effect-native sandbox execution plane primitives and Vercel Sandbox adapter for Yolk agents.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magoz/yolk-sdk.git",
+    "directory": "packages/sandbox"
+  },
+  "bugs": {
+    "url": "https://github.com/magoz/yolk-sdk/issues"
+  },
+  "homepage": "https://github.com/magoz/yolk-sdk#readme",
+  "keywords": [
+    "sandbox",
+    "agents",
+    "execution",
+    "vercel",
+    "effect"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.mts",
+      "import": "./dist/agent.mjs",
+      "default": "./dist/agent.mjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.mts",
+      "import": "./dist/testing/index.mjs",
+      "default": "./dist/testing/index.mjs"
+    },
+    "./vercel": {
+      "types": "./dist/vercel/index.d.mts",
+      "import": "./dist/vercel/index.mjs",
+      "default": "./dist/vercel/index.mjs"
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "dist/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@vercel/sandbox": "2.2.1",
+    "effect": "4.0.0-beta.65",
+    "@yolk-sdk/agent": "^0.1.0-canary.18"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:run": "vitest run --passWithNoTests"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,304 @@
+import { Effect } from 'effect'
+import * as Schema from 'effect/Schema'
+import { ToolError } from '@yolk-sdk/agent/loop'
+import { ToolResult, type ToolCall } from '@yolk-sdk/agent/protocol'
+import {
+  makeTool,
+  modelVisibleToolError,
+  type ModelVisibleToolError,
+  type ToolModule,
+  type ToolRegistryError
+} from '@yolk-sdk/agent/tools'
+import {
+  maxSandboxCommandTimeoutMs,
+  normalizeWorkspaceCwd,
+  sandboxCommandTimeoutMs,
+  sandboxToolOutputLimit,
+  validateSandboxCommand
+} from './lifecycle.ts'
+import type { SandboxError, SandboxExpiredError, SandboxInputError } from './errors.ts'
+import type { SandboxApi } from './service.ts'
+import { Sandbox } from './service.ts'
+import type { SandboxCommandResult } from './model.ts'
+
+export const sandboxToolName = 'sandbox'
+
+const SandboxToolParams = Schema.Struct({
+  command: Schema.String.pipe(
+    Schema.annotate({ description: 'Shell command to run. Multiline commands are allowed.' })
+  ),
+  cwd: Schema.optional(
+    Schema.NullOr(
+      Schema.String.pipe(
+        Schema.annotate({ description: 'Workspace-relative working directory. Absolute paths are rejected.' })
+      )
+    )
+  ),
+  stdin: Schema.optional(
+    Schema.NullOr(
+      Schema.String.pipe(
+        Schema.annotate({ description: 'Optional stdin text passed to the command.' })
+      )
+    )
+  ),
+  timeoutSeconds: Schema.optional(
+    Schema.NullOr(
+      Schema.Number.pipe(
+        Schema.annotate({ description: 'Foreground timeout in seconds. Default 120, max 600.' })
+      )
+    )
+  ),
+  background: Schema.optional(
+    Schema.NullOr(
+      Schema.Boolean.pipe(
+        Schema.annotate({ description: 'Start command in background and return after a quick probe.' })
+      )
+    )
+  )
+})
+
+export type SandboxToolParams = typeof SandboxToolParams.Type
+
+export type SandboxToolModuleOptions<Context> = {
+  readonly capabilities?: ReadonlyArray<string>
+  readonly workspaceDescription?: string
+  readonly lifecycleDescription?: string
+  readonly previewPorts?: ReadonlyArray<number>
+  readonly isEnabled?: (context: Context) => Effect.Effect<boolean, ToolRegistryError>
+}
+
+export type SandboxToolStructuredContent = {
+  readonly exitCode: number | null
+  readonly durationMs: number
+  readonly timedOut: boolean
+  readonly truncated: boolean
+  readonly workspaceReset: boolean
+  readonly backgroundId?: string
+  readonly previewUrls: SandboxCommandResult['previewUrls']
+  readonly state: SandboxCommandResult['state']
+}
+
+type OutputSlice = {
+  readonly stdout: string
+  readonly stderr: string
+  readonly truncated: boolean
+}
+
+const nullToUndefined = <A>(value: A | null | undefined) => value === null ? undefined : value
+
+const toolError = (message: string, cause: ToolError['cause']) =>
+  new ToolError({
+    tool: sandboxToolName,
+    message,
+    cause
+  })
+
+const modelVisibleSandboxError = (
+  error: SandboxInputError | SandboxExpiredError
+): ModelVisibleToolError => {
+  switch (error._tag) {
+    case 'SandboxInputError':
+      return modelVisibleToolError({
+        tool: sandboxToolName,
+        message: error.message,
+        reason: 'invalid_input'
+      })
+    case 'SandboxExpiredError':
+      return modelVisibleToolError({
+        tool: sandboxToolName,
+        message: error.message,
+        reason: 'unavailable',
+        details: { expiredAtMs: error.expiredAtMs }
+      })
+  }
+}
+
+const sandboxInfraToolError = (error: Exclude<SandboxError, SandboxInputError | SandboxExpiredError>) => {
+  switch (error._tag) {
+    case 'SandboxConfigError':
+      return toolError(error.message, 'invalid_input')
+    case 'SandboxProviderError':
+      return toolError(error.message, 'execution')
+    case 'SandboxStateError':
+    case 'SandboxStateStoreError':
+      return toolError(error.message, 'unavailable')
+  }
+}
+
+const normalizeTimeoutMs = (timeoutSeconds: number | null | undefined) => {
+  const value = nullToUndefined(timeoutSeconds)
+
+  if (value === undefined) {
+    return Effect.succeed(sandboxCommandTimeoutMs(undefined))
+  }
+
+  if (!Number.isFinite(value) || value <= 0) {
+    return Effect.fail(
+      modelVisibleToolError({
+        tool: sandboxToolName,
+        message: 'timeoutSeconds must be greater than 0',
+        reason: 'invalid_input'
+      })
+    )
+  }
+
+  return Effect.succeed(sandboxCommandTimeoutMs(Math.floor(value * 1_000)))
+}
+
+const normalizeToolParams = (params: SandboxToolParams) =>
+  Effect.gen(function* () {
+    const command = yield* validateSandboxCommand(params.command).pipe(
+      Effect.mapError(modelVisibleSandboxError)
+    )
+    const cwd = yield* normalizeWorkspaceCwd(params.cwd).pipe(
+      Effect.mapError(modelVisibleSandboxError)
+    )
+    const timeoutMs = yield* normalizeTimeoutMs(params.timeoutSeconds)
+
+    return {
+      command,
+      cwd,
+      stdin: nullToUndefined(params.stdin),
+      timeoutMs,
+      background: nullToUndefined(params.background)
+    }
+  })
+
+const truncateOutputs = (stdout: string, stderr: string, limit: number): OutputSlice => {
+  if (stdout.length + stderr.length <= limit) {
+    return { stdout, stderr, truncated: false }
+  }
+
+  const initialStderrBudget = Math.min(stderr.length, Math.floor(limit / 2))
+  const initialStdoutBudget = Math.min(stdout.length, limit - initialStderrBudget)
+  const unused = limit - initialStdoutBudget - initialStderrBudget
+  const stdoutBudget = Math.min(stdout.length, initialStdoutBudget + unused)
+  const stderrBudget = Math.min(stderr.length, limit - stdoutBudget)
+
+  return {
+    stdout: stdout.slice(0, stdoutBudget),
+    stderr: stderr.slice(0, stderrBudget),
+    truncated: true
+  }
+}
+
+const formatSandboxToolContent = (result: SandboxCommandResult, output: OutputSlice) =>
+  [
+    `exit_code: ${result.exitCode === null ? 'null' : String(result.exitCode)}`,
+    `duration_ms: ${result.durationMs}`,
+    `truncated: ${output.truncated}`,
+    `timed_out: ${result.timedOut}`,
+    `workspace_reset: ${result.workspaceReset}`,
+    result.backgroundId === undefined ? undefined : `background_id: ${result.backgroundId}`,
+    '<stdout>',
+    output.stdout,
+    '</stdout>',
+    '<stderr>',
+    output.stderr,
+    '</stderr>'
+  ].filter(line => line !== undefined).join('\n')
+
+const structuredContent = (
+  result: SandboxCommandResult,
+  truncated: boolean
+): SandboxToolStructuredContent => ({
+  exitCode: result.exitCode,
+  durationMs: result.durationMs,
+  timedOut: result.timedOut,
+  truncated,
+  workspaceReset: result.workspaceReset,
+  ...(result.backgroundId === undefined ? {} : { backgroundId: result.backgroundId }),
+  previewUrls: result.previewUrls,
+  state: result.state
+})
+
+export const makeSandboxToolResult = (input: {
+  readonly callId: string
+  readonly result: SandboxCommandResult
+}) => {
+  const output = truncateOutputs(input.result.stdout, input.result.stderr, sandboxToolOutputLimit)
+
+  return ToolResult.make({
+    toolCallId: input.callId,
+    content: formatSandboxToolContent(input.result, output),
+    isError: input.result.timedOut || (input.result.exitCode !== null && input.result.exitCode !== 0),
+    structuredContent: structuredContent(input.result, output.truncated)
+  })
+}
+
+const sandboxToolDescription = <Context>(options: SandboxToolModuleOptions<Context>) => {
+  const capabilities = options.capabilities ?? [
+    'run project commands such as typechecks, lint, tests, and builds',
+    'edit files with shell tools such as apply_patch when available',
+    'start dev servers and use preview ports',
+    'run browser checks through agent-browser when available'
+  ]
+  const ports = options.previewPorts ?? []
+
+  return [
+    'Run one non-interactive bash command inside a real sandbox workspace.',
+    options.workspaceDescription ?? 'The working directory is the sandbox workspace root.',
+    options.lifecycleDescription ?? 'The sandbox is disposable and may reset after idle or max lifetime expiry.',
+    `Foreground timeout defaults to 120s and is capped at ${Math.floor(maxSandboxCommandTimeoutMs / 1_000)}s.`,
+    'Use workspace-relative cwd only; absolute paths and workspace escapes are rejected.',
+    'Use stdin for large patches, scripts, or data.',
+    'Set background=true for long-running servers; the tool returns after a quick probe.',
+    ports.length === 0 ? 'Preview URLs are returned when configured by the host.' : `Preview ports: ${ports.join(', ')}.`,
+    `Available capabilities:\n${capabilities.map(capability => `- ${capability}`).join('\n')}`
+  ].join('\n\n')
+}
+
+export const makeSandboxToolModuleFromApi = <Context>(
+  sandbox: SandboxApi,
+  options: SandboxToolModuleOptions<Context> = {}
+): ToolModule<Context> => ({
+  id: 'sandbox',
+  tools: [
+    makeTool({
+      name: sandboxToolName,
+      description: sandboxToolDescription(options),
+      parameters: SandboxToolParams,
+      access: 'destructive',
+      isEnabled: options.isEnabled,
+      invalidParamsMessage: error => `Invalid sandbox arguments: ${error instanceof Error ? error.message : String(error)}`,
+      execute: ({ call, params }) =>
+        Effect.gen(function* () {
+          if (call.name !== sandboxToolName) {
+            return yield* Effect.fail(toolError(`Tool is not configured: ${call.name}`, 'not_found'))
+          }
+
+          const normalized = yield* normalizeToolParams(params)
+          const result = yield* sandbox.run(normalized).pipe(
+            Effect.mapError(error => {
+              switch (error._tag) {
+                case 'SandboxInputError':
+                case 'SandboxExpiredError':
+                  return modelVisibleSandboxError(error)
+                case 'SandboxConfigError':
+                case 'SandboxProviderError':
+                case 'SandboxStateError':
+                case 'SandboxStateStoreError':
+                  return sandboxInfraToolError(error)
+              }
+            })
+          )
+
+          return makeSandboxToolResult({ callId: call.id, result })
+        })
+    })
+  ]
+})
+
+export const makeSandboxToolModule = <Context>(
+  options: SandboxToolModuleOptions<Context> = {}
+): Effect.Effect<ToolModule<Context>, never, Sandbox> =>
+  Effect.gen(function* () {
+    const sandbox = yield* Sandbox
+    return makeSandboxToolModuleFromApi(sandbox, options)
+  })
+
+export type SandboxToolExecutionInput<Context> = {
+  readonly call: ToolCall
+  readonly context: Context
+  readonly params: SandboxToolParams
+}