@yolk-sdk/sandbox 0.1.0-canary.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yolk SDK contributors
+
+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/README.md

@@ -0,0 +1,60 @@
+# @yolk-sdk/sandbox
+
+Effect-native sandbox execution plane primitives plus a Vercel Sandbox adapter for Yolk agents.
+
+## Install
+
+```bash
+pnpm add @yolk-sdk/sandbox@canary effect
+```
+
+Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+
+## Subpaths
+
+| Subpath | Purpose |
+| --- | --- |
+| `@yolk-sdk/sandbox` | Core `Sandbox` service, state store, models, lifecycle helpers, errors |
+| `@yolk-sdk/sandbox/agent` | One trusted `sandbox` tool module for `@yolk-sdk/agent/tools` |
+| `@yolk-sdk/sandbox/vercel` | Vercel Sandbox provider layer |
+| `@yolk-sdk/sandbox/testing` | Fake sandbox + in-memory state store layers |
+
+## Imports
+
+```ts
+import { Sandbox, SandboxStateStore } from '@yolk-sdk/sandbox'
+import { makeSandboxToolModule } from '@yolk-sdk/sandbox/agent'
+import { makeVercelSandboxLayer } from '@yolk-sdk/sandbox/vercel'
+```
+
+## Example
+
+```ts
+import { Effect, Layer } from 'effect'
+import { Sandbox } from '@yolk-sdk/sandbox'
+import { makeVercelSandboxLayer } from '@yolk-sdk/sandbox/vercel'
+import { makeInMemorySandboxStateStoreLayer } from '@yolk-sdk/sandbox/testing'
+
+const layer = makeVercelSandboxLayer({ sandboxSessionId: 'user_1:session_1' }).pipe(
+  Layer.provide(makeInMemorySandboxStateStoreLayer())
+)
+
+const program = Effect.gen(function* () {
+  const sandbox = yield* Sandbox
+  return yield* sandbox.run({ command: 'node --version' })
+}).pipe(Effect.provide(layer))
+```
+
+## Host responsibilities
+
+- Build `sandboxSessionId` from host user/session scope.
+- Provide a durable `SandboxStateStore` adapter.
+- Inject env/secrets and choose source/snapshot/git policy.
+- Run cleanup for expired disposable sandboxes.
+- Own approvals, auth, UI, diffs, commit/push/PR, and audit policy.
+
+## Boundaries
+
+- Core is provider-free and app-free.
+- Vercel SDK imports live only under `@yolk-sdk/sandbox/vercel`.
+- The package exposes one agent tool; hosts decide where to enable it.

package/dist/agent.d.mts

@@ -0,0 +1,48 @@
+import { SandboxCommandResult } from "./model.mjs";
+import { Sandbox, SandboxApi } from "./service.mjs";
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import { ToolCall, ToolResult } from "@yolk-sdk/agent/protocol";
+import { ToolModule, ToolRegistryError } from "@yolk-sdk/agent/tools";
+
+//#region src/agent.d.ts
+declare const sandboxToolName = "sandbox";
+declare const SandboxToolParams: Schema.Struct<{
+  readonly command: Schema.String;
+  readonly cwd: Schema.optional<Schema.NullOr<Schema.String>>;
+  readonly stdin: Schema.optional<Schema.NullOr<Schema.String>>;
+  readonly timeoutSeconds: Schema.optional<Schema.NullOr<Schema.Number>>;
+  readonly background: Schema.optional<Schema.NullOr<Schema.Boolean>>;
+}>;
+type SandboxToolParams = typeof SandboxToolParams.Type;
+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>;
+};
+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'];
+};
+declare const makeSandboxToolResult: (input: {
+  readonly callId: string;
+  readonly result: SandboxCommandResult;
+}) => ToolResult;
+declare const makeSandboxToolModuleFromApi: <Context>(sandbox: SandboxApi, options?: SandboxToolModuleOptions<Context>) => ToolModule<Context>;
+declare const makeSandboxToolModule: <Context>(options?: SandboxToolModuleOptions<Context>) => Effect.Effect<ToolModule<Context>, never, Sandbox>;
+type SandboxToolExecutionInput<Context> = {
+  readonly call: ToolCall;
+  readonly context: Context;
+  readonly params: SandboxToolParams;
+};
+//#endregion
+export { SandboxToolExecutionInput, SandboxToolModuleOptions, SandboxToolParams, SandboxToolStructuredContent, makeSandboxToolModule, makeSandboxToolModuleFromApi, makeSandboxToolResult, sandboxToolName };
+//# sourceMappingURL=agent.d.mts.map

package/dist/agent.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.mts","names":[],"sources":["../src/agent.ts"],"mappings":";;;;;;;;cAuBa,eAAA;AAAA,cAEP,iBAAA,EAAiB,MAAA,CAAA,MAAA;EAAA;;;;;;KAkCX,iBAAA,UAA2B,iBAAA,CAAkB,IAAI;AAAA,KAEjD,wBAAA;EAAA,SACD,YAAA,GAAe,aAAA;EAAA,SACf,oBAAA;EAAA,SACA,oBAAA;EAAA,SACA,YAAA,GAAe,aAAA;EAAA,SACf,SAAA,IAAa,OAAA,EAAS,OAAA,KAAY,MAAA,CAAO,MAAA,UAAgB,iBAAA;AAAA;AAAA,KAGxD,4BAAA;EAAA,SACD,QAAA;EAAA,SACA,UAAA;EAAA,SACA,QAAA;EAAA,SACA,SAAA;EAAA,SACA,cAAA;EAAA,SACA,YAAA;EAAA,SACA,WAAA,EAAa,oBAAA;EAAA,SACb,KAAA,EAAO,oBAAoB;AAAA;AAAA,cAyIzB,qBAAA,GAAyB,KAAA;EAAA,SAC3B,MAAA;EAAA,SACA,MAAA,EAAQ,oBAAA;AAAA,MAClB,UASA;AAAA,cAwBY,4BAAA,YACX,OAAA,EAAS,UAAA,EACT,OAAA,GAAS,wBAAA,CAAyB,OAAA,MACjC,UAAA,CAAW,OAAA;AAAA,cAsCD,qBAAA,YACX,OAAA,GAAS,wBAAA,CAAyB,OAAA,MACjC,MAAA,CAAO,MAAA,CAAO,UAAA,CAAW,OAAA,UAAiB,OAAA;AAAA,KAMjC,yBAAA;EAAA,SACD,IAAA,EAAM,QAAA;EAAA,SACN,OAAA,EAAS,OAAA;EAAA,SACT,MAAA,EAAQ,iBAAA;AAAA"}

package/dist/agent.mjs

@@ -0,0 +1,173 @@
+import { maxSandboxCommandTimeoutMs, normalizeWorkspaceCwd, sandboxCommandTimeoutMs, sandboxToolOutputLimit, validateSandboxCommand } from "./lifecycle.mjs";
+import { Sandbox } from "./service.mjs";
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import { ToolError } from "@yolk-sdk/agent/loop";
+import { ToolResult } from "@yolk-sdk/agent/protocol";
+import { makeTool, modelVisibleToolError } from "@yolk-sdk/agent/tools";
+//#region src/agent.ts
+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." }))))
+});
+const nullToUndefined = (value) => value === null ? void 0 : value;
+const toolError = (message, cause) => new ToolError({
+	tool: sandboxToolName,
+	message,
+	cause
+});
+const modelVisibleSandboxError = (error) => {
+	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) => {
+	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) => {
+	const value = nullToUndefined(timeoutSeconds);
+	if (value === void 0) return Effect.succeed(sandboxCommandTimeoutMs(void 0));
+	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 * 1e3)));
+};
+const normalizeToolParams = (params) => 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, stderr, limit) => {
+	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, output) => [
+	`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 === void 0 ? void 0 : `background_id: ${result.backgroundId}`,
+	"<stdout>",
+	output.stdout,
+	"</stdout>",
+	"<stderr>",
+	output.stderr,
+	"</stderr>"
+].filter((line) => line !== void 0).join("\n");
+const structuredContent = (result, truncated) => ({
+	exitCode: result.exitCode,
+	durationMs: result.durationMs,
+	timedOut: result.timedOut,
+	truncated,
+	workspaceReset: result.workspaceReset,
+	...result.backgroundId === void 0 ? {} : { backgroundId: result.backgroundId },
+	previewUrls: result.previewUrls,
+	state: result.state
+});
+const makeSandboxToolResult = (input) => {
+	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 = (options) => {
+	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 / 1e3)}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");
+};
+const makeSandboxToolModuleFromApi = (sandbox, options = {}) => ({
+	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 !== "sandbox") 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
+			});
+		})
+	})]
+});
+const makeSandboxToolModule = (options = {}) => Effect.gen(function* () {
+	return makeSandboxToolModuleFromApi(yield* Sandbox, options);
+});
+//#endregion
+export { makeSandboxToolModule, makeSandboxToolModuleFromApi, makeSandboxToolResult, sandboxToolName };
+
+//# sourceMappingURL=agent.mjs.map

package/dist/agent.mjs.map

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

package/dist/errors.d.mts

@@ -0,0 +1,44 @@
+import * as Schema from "effect/Schema";
+
+//#region src/errors.d.ts
+declare const SandboxInputErrorCause: Schema.Literals<readonly ["empty_command", "invalid_cwd", "invalid_timeout"]>;
+type SandboxInputErrorCause = typeof SandboxInputErrorCause.Type;
+declare const SandboxInputError_base: Schema.Class<SandboxInputError, Schema.TaggedStruct<"SandboxInputError", {
+  readonly cause: Schema.Literals<readonly ["empty_command", "invalid_cwd", "invalid_timeout"]>;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxInputError extends SandboxInputError_base {}
+declare const SandboxConfigError_base: Schema.Class<SandboxConfigError, Schema.TaggedStruct<"SandboxConfigError", {
+  readonly message: Schema.String;
+  readonly cause: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxConfigError extends SandboxConfigError_base {}
+declare const SandboxExpiredError_base: Schema.Class<SandboxExpiredError, Schema.TaggedStruct<"SandboxExpiredError", {
+  readonly message: Schema.String;
+  readonly expiredAtMs: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxExpiredError extends SandboxExpiredError_base {}
+declare const SandboxStateError_base: Schema.Class<SandboxStateError, Schema.TaggedStruct<"SandboxStateError", {
+  readonly message: Schema.String;
+  readonly cause: Schema.String;
+  readonly underlying: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxStateError extends SandboxStateError_base {}
+declare const SandboxStateStoreError_base: Schema.Class<SandboxStateStoreError, Schema.TaggedStruct<"SandboxStateStoreError", {
+  readonly message: Schema.String;
+  readonly operation: Schema.String;
+  readonly underlying: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxStateStoreError extends SandboxStateStoreError_base {}
+declare const SandboxProviderError_base: Schema.Class<SandboxProviderError, Schema.TaggedStruct<"SandboxProviderError", {
+  readonly provider: Schema.Literal<"vercel">;
+  readonly operation: Schema.String;
+  readonly message: Schema.String;
+  readonly underlying: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxProviderError extends SandboxProviderError_base {}
+type SandboxError = SandboxInputError | SandboxConfigError | SandboxExpiredError | SandboxStateError | SandboxStateStoreError | SandboxProviderError;
+declare const unknownToMessage: (error: unknown) => string;
+//#endregion
+export { SandboxConfigError, SandboxError, SandboxExpiredError, SandboxInputError, SandboxInputErrorCause, SandboxProviderError, SandboxStateError, SandboxStateStoreError, unknownToMessage };
+//# sourceMappingURL=errors.d.mts.map

package/dist/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../src/errors.ts"],"mappings":";;;cAEa,sBAAA,EAAsB,MAAA,CAAA,QAAA;AAAA,KAKvB,sBAAA,UAAgC,sBAAA,CAAuB,IAAI;AAAA,cAAA,sBAAA;;;;cAE1D,iBAAA,SAA0B,sBAMtC;AAAA,cAAG,uBAAA;;;;cAES,kBAAA,SAA2B,uBAMvC;AAAA,cAAG,wBAAA;;;;cAES,mBAAA,SAA4B,wBAMxC;AAAA,cAAG,sBAAA;;;;;cAES,iBAAA,SAA0B,sBAOtC;AAAA,cAAG,2BAAA;;;;;cAES,sBAAA,SAA+B,2BAO3C;AAAA,cAAG,yBAAA;;;;;;cAES,oBAAA,SAA6B,yBAQzC;AAAA,KAEW,YAAA,GACR,iBAAA,GACA,kBAAA,GACA,mBAAA,GACA,iBAAA,GACA,sBAAA,GACA,oBAAA;AAAA,cAES,gBAAA,GAAoB,KAAc"}

package/dist/errors.mjs

@@ -0,0 +1,40 @@
+import * as Schema from "effect/Schema";
+//#region src/errors.ts
+const SandboxInputErrorCause = Schema.Literals([
+	"empty_command",
+	"invalid_cwd",
+	"invalid_timeout"
+]);
+var SandboxInputError = class extends Schema.TaggedErrorClass()("SandboxInputError", {
+	cause: SandboxInputErrorCause,
+	message: Schema.String
+}) {};
+var SandboxConfigError = class extends Schema.TaggedErrorClass()("SandboxConfigError", {
+	message: Schema.String,
+	cause: Schema.String
+}) {};
+var SandboxExpiredError = class extends Schema.TaggedErrorClass()("SandboxExpiredError", {
+	message: Schema.String,
+	expiredAtMs: Schema.Number
+}) {};
+var SandboxStateError = class extends Schema.TaggedErrorClass()("SandboxStateError", {
+	message: Schema.String,
+	cause: Schema.String,
+	underlying: Schema.optional(Schema.Unknown)
+}) {};
+var SandboxStateStoreError = class extends Schema.TaggedErrorClass()("SandboxStateStoreError", {
+	message: Schema.String,
+	operation: Schema.String,
+	underlying: Schema.optional(Schema.Unknown)
+}) {};
+var SandboxProviderError = class extends Schema.TaggedErrorClass()("SandboxProviderError", {
+	provider: Schema.Literal("vercel"),
+	operation: Schema.String,
+	message: Schema.String,
+	underlying: Schema.optional(Schema.Unknown)
+}) {};
+const unknownToMessage = (error) => error instanceof Error ? error.message : String(error);
+//#endregion
+export { SandboxConfigError, SandboxExpiredError, SandboxInputError, SandboxInputErrorCause, SandboxProviderError, SandboxStateError, SandboxStateStoreError, unknownToMessage };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import * as Schema from 'effect/Schema'\n\nexport const SandboxInputErrorCause = Schema.Literals([\n  'empty_command',\n  'invalid_cwd',\n  'invalid_timeout'\n])\nexport type SandboxInputErrorCause = typeof SandboxInputErrorCause.Type\n\nexport class SandboxInputError extends Schema.TaggedErrorClass<SandboxInputError>()(\n  'SandboxInputError',\n  {\n    cause: SandboxInputErrorCause,\n    message: Schema.String\n  }\n) {}\n\nexport class SandboxConfigError extends Schema.TaggedErrorClass<SandboxConfigError>()(\n  'SandboxConfigError',\n  {\n    message: Schema.String,\n    cause: Schema.String\n  }\n) {}\n\nexport class SandboxExpiredError extends Schema.TaggedErrorClass<SandboxExpiredError>()(\n  'SandboxExpiredError',\n  {\n    message: Schema.String,\n    expiredAtMs: Schema.Number\n  }\n) {}\n\nexport class SandboxStateError extends Schema.TaggedErrorClass<SandboxStateError>()(\n  'SandboxStateError',\n  {\n    message: Schema.String,\n    cause: Schema.String,\n    underlying: Schema.optional(Schema.Unknown)\n  }\n) {}\n\nexport class SandboxStateStoreError extends Schema.TaggedErrorClass<SandboxStateStoreError>()(\n  'SandboxStateStoreError',\n  {\n    message: Schema.String,\n    operation: Schema.String,\n    underlying: Schema.optional(Schema.Unknown)\n  }\n) {}\n\nexport class SandboxProviderError extends Schema.TaggedErrorClass<SandboxProviderError>()(\n  'SandboxProviderError',\n  {\n    provider: Schema.Literal('vercel'),\n    operation: Schema.String,\n    message: Schema.String,\n    underlying: Schema.optional(Schema.Unknown)\n  }\n) {}\n\nexport type SandboxError =\n  | SandboxInputError\n  | SandboxConfigError\n  | SandboxExpiredError\n  | SandboxStateError\n  | SandboxStateStoreError\n  | SandboxProviderError\n\nexport const unknownToMessage = (error: unknown) =>\n  error instanceof Error ? error.message : String(error)\n"],"mappings":";;AAEA,MAAa,yBAAyB,OAAO,SAAS;CACpD;CACA;CACA;AACF,CAAC;AAGD,IAAa,oBAAb,cAAuC,OAAO,iBAAoC,EAChF,qBACA;CACE,OAAO;CACP,SAAS,OAAO;AAClB,CACF,EAAE,CAAC;AAEH,IAAa,qBAAb,cAAwC,OAAO,iBAAqC,EAClF,sBACA;CACE,SAAS,OAAO;CAChB,OAAO,OAAO;AAChB,CACF,EAAE,CAAC;AAEH,IAAa,sBAAb,cAAyC,OAAO,iBAAsC,EACpF,uBACA;CACE,SAAS,OAAO;CAChB,aAAa,OAAO;AACtB,CACF,EAAE,CAAC;AAEH,IAAa,oBAAb,cAAuC,OAAO,iBAAoC,EAChF,qBACA;CACE,SAAS,OAAO;CAChB,OAAO,OAAO;CACd,YAAY,OAAO,SAAS,OAAO,OAAO;AAC5C,CACF,EAAE,CAAC;AAEH,IAAa,yBAAb,cAA4C,OAAO,iBAAyC,EAC1F,0BACA;CACE,SAAS,OAAO;CAChB,WAAW,OAAO;CAClB,YAAY,OAAO,SAAS,OAAO,OAAO;AAC5C,CACF,EAAE,CAAC;AAEH,IAAa,uBAAb,cAA0C,OAAO,iBAAuC,EACtF,wBACA;CACE,UAAU,OAAO,QAAQ,QAAQ;CACjC,WAAW,OAAO;CAClB,SAAS,OAAO;CAChB,YAAY,OAAO,SAAS,OAAO,OAAO;AAC5C,CACF,EAAE,CAAC;AAUH,MAAa,oBAAoB,UAC/B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK"}

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+import { SandboxConfigError, SandboxError, SandboxExpiredError, SandboxInputError, SandboxInputErrorCause, SandboxProviderError, SandboxStateError, SandboxStateStoreError } from "./errors.mjs";
+import { DisposableSandboxLifecycle, EmptySandboxInitialSource, GitSandboxInitialSource, PersistentSandboxLifecycle, SandboxCommandInput, SandboxCommandResult, SandboxInitialSource, SandboxLifecycle, SandboxPreviewUrl, SandboxResources, SandboxSnapshotRetention, SandboxState, SnapshotSandboxInitialSource, TarballSandboxInitialSource, VercelSandboxState } from "./model.mjs";
+import { Sandbox, SandboxApi } from "./service.mjs";
+import { backgroundSandboxProbeMs, defaultSandboxCommandTimeoutMs, defaultSandboxIdleTtlMs, defaultSandboxInitialSource, defaultSandboxLifecycle, defaultSandboxMaxLifetimeMs, defaultSandboxPorts, defaultSandboxWorkspaceRoot, maxSandboxCommandTimeoutMs, normalizeWorkspaceCwd, sandboxCommandTimeoutMs, sandboxLifecycleOrDefault, sandboxSourceOrDefault, sandboxStateDecision, sandboxTimeoutExtendDeltaMs, sandboxToolOutputLimit, touchSandboxState, validateSandboxCommand } from "./lifecycle.mjs";
+import { makeVercelSandboxName } from "./name.mjs";
+import { SandboxStateStore, SandboxStateStoreApi } from "./state-store.mjs";
+export { DisposableSandboxLifecycle, EmptySandboxInitialSource, GitSandboxInitialSource, PersistentSandboxLifecycle, Sandbox, type SandboxApi, SandboxCommandInput, SandboxCommandResult, SandboxConfigError, type SandboxError, SandboxExpiredError, SandboxInitialSource, SandboxInputError, SandboxInputErrorCause, SandboxLifecycle, SandboxPreviewUrl, SandboxProviderError, SandboxResources, SandboxSnapshotRetention, SandboxState, SandboxStateError, SandboxStateStore, type SandboxStateStoreApi, SandboxStateStoreError, SnapshotSandboxInitialSource, TarballSandboxInitialSource, VercelSandboxState, backgroundSandboxProbeMs, defaultSandboxCommandTimeoutMs, defaultSandboxIdleTtlMs, defaultSandboxInitialSource, defaultSandboxLifecycle, defaultSandboxMaxLifetimeMs, defaultSandboxPorts, defaultSandboxWorkspaceRoot, makeVercelSandboxName, maxSandboxCommandTimeoutMs, normalizeWorkspaceCwd, sandboxCommandTimeoutMs, sandboxLifecycleOrDefault, sandboxSourceOrDefault, sandboxStateDecision, sandboxTimeoutExtendDeltaMs, sandboxToolOutputLimit, touchSandboxState, validateSandboxCommand };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+import { SandboxConfigError, SandboxExpiredError, SandboxInputError, SandboxInputErrorCause, SandboxProviderError, SandboxStateError, SandboxStateStoreError } from "./errors.mjs";
+import { DisposableSandboxLifecycle, EmptySandboxInitialSource, GitSandboxInitialSource, PersistentSandboxLifecycle, SandboxCommandInput, SandboxCommandResult, SandboxInitialSource, SandboxLifecycle, SandboxPreviewUrl, SandboxResources, SandboxSnapshotRetention, SandboxState, SnapshotSandboxInitialSource, TarballSandboxInitialSource, VercelSandboxState } from "./model.mjs";
+import { backgroundSandboxProbeMs, defaultSandboxCommandTimeoutMs, defaultSandboxIdleTtlMs, defaultSandboxInitialSource, defaultSandboxLifecycle, defaultSandboxMaxLifetimeMs, defaultSandboxPorts, defaultSandboxWorkspaceRoot, maxSandboxCommandTimeoutMs, normalizeWorkspaceCwd, sandboxCommandTimeoutMs, sandboxLifecycleOrDefault, sandboxSourceOrDefault, sandboxStateDecision, sandboxTimeoutExtendDeltaMs, sandboxToolOutputLimit, touchSandboxState, validateSandboxCommand } from "./lifecycle.mjs";
+import { Sandbox } from "./service.mjs";
+import { makeVercelSandboxName } from "./name.mjs";
+import { SandboxStateStore } from "./state-store.mjs";
+export { DisposableSandboxLifecycle, EmptySandboxInitialSource, GitSandboxInitialSource, PersistentSandboxLifecycle, Sandbox, SandboxCommandInput, SandboxCommandResult, SandboxConfigError, SandboxExpiredError, SandboxInitialSource, SandboxInputError, SandboxInputErrorCause, SandboxLifecycle, SandboxPreviewUrl, SandboxProviderError, SandboxResources, SandboxSnapshotRetention, SandboxState, SandboxStateError, SandboxStateStore, SandboxStateStoreError, SnapshotSandboxInitialSource, TarballSandboxInitialSource, VercelSandboxState, backgroundSandboxProbeMs, defaultSandboxCommandTimeoutMs, defaultSandboxIdleTtlMs, defaultSandboxInitialSource, defaultSandboxLifecycle, defaultSandboxMaxLifetimeMs, defaultSandboxPorts, defaultSandboxWorkspaceRoot, makeVercelSandboxName, maxSandboxCommandTimeoutMs, normalizeWorkspaceCwd, sandboxCommandTimeoutMs, sandboxLifecycleOrDefault, sandboxSourceOrDefault, sandboxStateDecision, sandboxTimeoutExtendDeltaMs, sandboxToolOutputLimit, touchSandboxState, validateSandboxCommand };

package/dist/lifecycle.d.mts

@@ -0,0 +1,52 @@
+import { SandboxInputError } from "./errors.mjs";
+import { DisposableSandboxLifecycle, EmptySandboxInitialSource, SandboxInitialSource, SandboxLifecycle, SandboxState, VercelSandboxState } from "./model.mjs";
+import { Effect, Option } from "effect";
+
+//#region src/lifecycle.d.ts
+declare const defaultSandboxIdleTtlMs: number;
+declare const defaultSandboxMaxLifetimeMs: number;
+declare const defaultSandboxCommandTimeoutMs = 120000;
+declare const maxSandboxCommandTimeoutMs = 600000;
+declare const backgroundSandboxProbeMs = 2000;
+declare const sandboxToolOutputLimit = 50000;
+declare const defaultSandboxPorts: ReadonlyArray<number>;
+declare const defaultSandboxWorkspaceRoot = "/vercel/sandbox";
+declare const defaultSandboxLifecycle: DisposableSandboxLifecycle;
+declare const defaultSandboxInitialSource: EmptySandboxInitialSource;
+type SandboxRecreateReason = 'idle_expired' | 'max_expired' | 'name_mismatch';
+type SandboxStateDecision = {
+  readonly _tag: 'UseExisting';
+  readonly state: SandboxState;
+} | {
+  readonly _tag: 'Create';
+  readonly workspaceReset: boolean;
+  readonly reason?: SandboxRecreateReason;
+};
+declare const sandboxLifecycleOrDefault: (lifecycle?: SandboxLifecycle) => SandboxLifecycle;
+declare const sandboxSourceOrDefault: (source?: SandboxInitialSource) => SandboxInitialSource;
+declare const sandboxCommandTimeoutMs: (timeoutMs?: number) => number;
+declare const validateSandboxCommand: (command: string) => Effect.Effect<never, SandboxInputError, never> | Effect.Effect<string, never, never>;
+declare const normalizeWorkspaceCwd: (cwd?: string | null) => Effect.Effect<string, SandboxInputError>;
+declare const absoluteSandboxCwd: (workspaceRoot: string, normalizedCwd: string) => string;
+declare const initialSandboxState: (input: {
+  readonly name: string;
+  readonly nowMs: number;
+  readonly lifecycle: SandboxLifecycle;
+}) => VercelSandboxState;
+declare const touchSandboxState: (input: {
+  readonly state: SandboxState;
+  readonly nowMs: number;
+  readonly lifecycle: SandboxLifecycle;
+}) => VercelSandboxState;
+declare const sandboxTimeoutExtendDeltaMs: (input: {
+  readonly before: SandboxState;
+  readonly after: SandboxState;
+}) => number;
+declare const sandboxStateDecision: (input: {
+  readonly state: Option.Option<SandboxState>;
+  readonly name: string;
+  readonly nowMs: number;
+}) => SandboxStateDecision;
+//#endregion
+export { SandboxRecreateReason, SandboxStateDecision, absoluteSandboxCwd, backgroundSandboxProbeMs, defaultSandboxCommandTimeoutMs, defaultSandboxIdleTtlMs, defaultSandboxInitialSource, defaultSandboxLifecycle, defaultSandboxMaxLifetimeMs, defaultSandboxPorts, defaultSandboxWorkspaceRoot, initialSandboxState, maxSandboxCommandTimeoutMs, normalizeWorkspaceCwd, sandboxCommandTimeoutMs, sandboxLifecycleOrDefault, sandboxSourceOrDefault, sandboxStateDecision, sandboxTimeoutExtendDeltaMs, sandboxToolOutputLimit, touchSandboxState, validateSandboxCommand };
+//# sourceMappingURL=lifecycle.d.mts.map

package/dist/lifecycle.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.mts","names":[],"sources":["../src/lifecycle.ts"],"mappings":";;;;;cAWa,uBAAA;AAAA,cACA,2BAAA;AAAA,cACA,8BAAA;AAAA,cACA,0BAAA;AAAA,cACA,wBAAA;AAAA,cACA,sBAAA;AAAA,cACA,mBAAA,EAAqB,aAAa;AAAA,cAClC,2BAAA;AAAA,cAEA,uBAAA,EAAuB,0BAGlC;AAAA,cAEW,2BAAA,EAA2B,yBAAqC;AAAA,KAEjE,qBAAA;AAAA,KAEA,oBAAA;EAAA,SAEG,IAAA;EAAA,SACA,KAAA,EAAO,YAAA;AAAA;EAAA,SAGP,IAAA;EAAA,SACA,cAAA;EAAA,SACA,MAAA,GAAS,qBAAqB;AAAA;AAAA,cAMhC,yBAAA,GAA6B,SAAA,GAAY,gBAAA,KAAmB,gBACnC;AAAA,cAEzB,sBAAA,GAA0B,MAAA,GAAS,oBAAA,KAAuB,oBAChC;AAAA,cAE1B,uBAAA,GAA2B,SAAkB;AAAA,cAG7C,sBAAA,GAA0B,OAAA,aAAe,MAAA,CAAA,MAAA,QAAA,iBAAA,WAAA,MAAA,CAAA,MAAA;AAAA,cAazC,qBAAA,GAAyB,GAAA,qBAAsB,MAAA,CAAO,MAAM,SAAS,iBAAA;AAAA,cA0CrE,kBAAA,GAAsB,aAAA,UAAuB,aAAqB;AAAA,cAGlE,mBAAA,GAAuB,KAAA;EAAA,SACzB,IAAA;EAAA,SACA,KAAA;EAAA,SACA,SAAA,EAAW,gBAAA;AAAA,MACrB,kBAmBA;AAAA,cAEY,iBAAA,GAAqB,KAAA;EAAA,SACvB,KAAA,EAAO,YAAA;EAAA,SACP,KAAA;EAAA,SACA,SAAA,EAAW,gBAAA;AAAA,MACrB,kBAAA;AAAA,cAiBY,2BAAA,GAA+B,KAAA;EAAA,SACjC,MAAA,EAAQ,YAAA;EAAA,SACR,KAAA,EAAO,YAAY;AAAA;AAAA,cAGjB,oBAAA,GAAwB,KAAA;EAAA,SAC1B,KAAA,EAAO,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,SACrB,IAAA;EAAA,SACA,KAAA;AAAA,MACP,oBAAA"}

package/dist/lifecycle.mjs

@@ -0,0 +1,118 @@
+import { SandboxInputError } from "./errors.mjs";
+import { DisposableSandboxLifecycle, EmptySandboxInitialSource, VercelSandboxState } from "./model.mjs";
+import { Effect, Option } from "effect";
+//#region src/lifecycle.ts
+const defaultSandboxIdleTtlMs = 30 * 6e4;
+const defaultSandboxMaxLifetimeMs = 45 * 6e4;
+const defaultSandboxCommandTimeoutMs = 12e4;
+const maxSandboxCommandTimeoutMs = 6e5;
+const backgroundSandboxProbeMs = 2e3;
+const sandboxToolOutputLimit = 5e4;
+const defaultSandboxPorts = [
+	3e3,
+	5173,
+	4321,
+	8e3
+];
+const defaultSandboxWorkspaceRoot = "/vercel/sandbox";
+const defaultSandboxLifecycle = DisposableSandboxLifecycle.make({
+	idleTtlMs: defaultSandboxIdleTtlMs,
+	maxLifetimeMs: defaultSandboxMaxLifetimeMs
+});
+const defaultSandboxInitialSource = EmptySandboxInitialSource.make({});
+const positiveOr = (value, fallback) => value === void 0 || !Number.isFinite(value) || value <= 0 ? fallback : Math.floor(value);
+const sandboxLifecycleOrDefault = (lifecycle) => lifecycle ?? defaultSandboxLifecycle;
+const sandboxSourceOrDefault = (source) => source ?? defaultSandboxInitialSource;
+const sandboxCommandTimeoutMs = (timeoutMs) => Math.min(maxSandboxCommandTimeoutMs, positiveOr(timeoutMs, defaultSandboxCommandTimeoutMs));
+const validateSandboxCommand = (command) => {
+	if (command.trim().length === 0) return Effect.fail(new SandboxInputError({
+		cause: "empty_command",
+		message: "Sandbox command must not be empty"
+	}));
+	return Effect.succeed(command);
+};
+const normalizeWorkspaceCwd = (cwd) => {
+	if (cwd === void 0 || cwd === null || cwd.trim().length === 0) return Effect.succeed(".");
+	const trimmed = cwd.trim();
+	if (trimmed.startsWith("/") || trimmed.includes("\0")) return Effect.fail(new SandboxInputError({
+		cause: "invalid_cwd",
+		message: "cwd must be workspace-relative"
+	}));
+	const parts = [];
+	for (const segment of trimmed.split("/")) {
+		if (segment.length === 0 || segment === ".") continue;
+		if (segment === "..") {
+			if (parts.pop() === void 0) return Effect.fail(new SandboxInputError({
+				cause: "invalid_cwd",
+				message: "cwd must not escape the workspace"
+			}));
+			continue;
+		}
+		parts.push(segment);
+	}
+	return Effect.succeed(parts.length === 0 ? "." : parts.join("/"));
+};
+const absoluteSandboxCwd = (workspaceRoot, normalizedCwd) => normalizedCwd === "." ? workspaceRoot : `${workspaceRoot}/${normalizedCwd}`;
+const initialSandboxState = (input) => {
+	switch (input.lifecycle._tag) {
+		case "Disposable": return VercelSandboxState.make({
+			name: input.name,
+			createdAtMs: input.nowMs,
+			lastUsedAtMs: input.nowMs,
+			expiresAtMs: input.nowMs + input.lifecycle.idleTtlMs,
+			maxExpiresAtMs: input.nowMs + input.lifecycle.maxLifetimeMs
+		});
+		case "Persistent": return VercelSandboxState.make({
+			name: input.name,
+			createdAtMs: input.nowMs,
+			lastUsedAtMs: input.nowMs,
+			expiresAtMs: input.nowMs + input.lifecycle.idleTtlMs,
+			maxExpiresAtMs: Number.MAX_SAFE_INTEGER
+		});
+	}
+};
+const touchSandboxState = (input) => {
+	switch (input.lifecycle._tag) {
+		case "Disposable": return VercelSandboxState.make({
+			...input.state,
+			lastUsedAtMs: input.nowMs,
+			expiresAtMs: Math.min(input.nowMs + input.lifecycle.idleTtlMs, input.state.maxExpiresAtMs)
+		});
+		case "Persistent": return VercelSandboxState.make({
+			...input.state,
+			lastUsedAtMs: input.nowMs,
+			expiresAtMs: input.nowMs + input.lifecycle.idleTtlMs
+		});
+	}
+};
+const sandboxTimeoutExtendDeltaMs = (input) => Math.max(0, input.after.expiresAtMs - input.before.expiresAtMs);
+const sandboxStateDecision = (input) => {
+	if (Option.isNone(input.state)) return {
+		_tag: "Create",
+		workspaceReset: false
+	};
+	const state = input.state.value;
+	if (state.name !== input.name) return {
+		_tag: "Create",
+		workspaceReset: true,
+		reason: "name_mismatch"
+	};
+	if (input.nowMs >= state.maxExpiresAtMs) return {
+		_tag: "Create",
+		workspaceReset: true,
+		reason: "max_expired"
+	};
+	if (input.nowMs >= state.expiresAtMs) return {
+		_tag: "Create",
+		workspaceReset: true,
+		reason: "idle_expired"
+	};
+	return {
+		_tag: "UseExisting",
+		state
+	};
+};
+//#endregion
+export { absoluteSandboxCwd, backgroundSandboxProbeMs, defaultSandboxCommandTimeoutMs, defaultSandboxIdleTtlMs, defaultSandboxInitialSource, defaultSandboxLifecycle, defaultSandboxMaxLifetimeMs, defaultSandboxPorts, defaultSandboxWorkspaceRoot, initialSandboxState, maxSandboxCommandTimeoutMs, normalizeWorkspaceCwd, sandboxCommandTimeoutMs, sandboxLifecycleOrDefault, sandboxSourceOrDefault, sandboxStateDecision, sandboxTimeoutExtendDeltaMs, sandboxToolOutputLimit, touchSandboxState, validateSandboxCommand };
+
+//# sourceMappingURL=lifecycle.mjs.map