reeval 0.8.0 → 0.10.0

package/dist/environment-DNjRk0nU.js

@@ -0,0 +1,1133 @@
+import { t as isObjectLike } from "./object-CLf2-tNq.js";
+import { n as UsageError } from "./errors-B6BSMs03.js";
+import { t as parseDuration } from "./duration-CEOQww97.js";
+import { d as refusal, f as valueAt, i as durationSchema, l as nonEmpty, o as genericProblem, r as durationProblem, s as got, t as closest, u as oneOf } from "./shared-DYpIb1BI.js";
+import { n as SECRET_NAME } from "./redact-DJ9JCShu.js";
+import { i as PACKAGE_DIR, n as COMPILED } from "./root-DICDHCtp.js";
+import picomatch from "picomatch";
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, resolve, sep } from "node:path";
+import { z } from "zod";
+import { isIP } from "node:net";
+import { fileURLToPath } from "node:url";
+//#region src/contract/docker.ts
+/** Docker's memory size: bytes, or a number with `b`, `k`, `m` or `g`. */
+const MEMORY = /^\d+(\.\d+)?[bkmg]?$/i;
+const installStepSchema = z.union([nonEmpty(), z.strictObject({
+	run: nonEmpty().describe("The shell command."),
+	timeout: durationSchema.optional()
+})]).describe("A `docker({ install })` command, baked into a cached image layer: no secrets, root, cwd `/`.");
+/** Every field but `kind` and `dockerfile`, shared by the descriptor and `docker()`'s options. */
+const fields = {
+	id: nonEmpty().optional().describe("Cell id; defaults to `docker` (`podman`), or `docker:<image>` for other images, plus an install hash."),
+	image: nonEmpty().optional().describe("An image that already has the harness baked in, used as is."),
+	from: nonEmpty().optional().describe("A Debian or Ubuntu based toolchain image; reeval bakes Node and the harness on top, cached."),
+	install: z.array(installStepSchema).min(1).optional().describe("Baked onto the sandbox image in one build container: in order, no secrets, no workspace."),
+	maxConcurrent: z.number().optional().describe("The most Docker sandboxes at once, across the run, whatever their image."),
+	root: z.boolean().optional().describe("Run the agent, setup steps and checks as root, with the capabilities `apt-get` needs, instead of the unprivileged `reeval` user. For evals that install system packages at run time."),
+	capabilities: z.array(z.string().regex(/^(CAP_)?[A-Z_]+$/)).optional().describe("Linux capabilities to add back, e.g. `['NET_RAW']`; every other one is dropped."),
+	memory: z.union([z.string().regex(MEMORY), z.int().positive()]).optional().describe("The container's memory: `'4g'` (default), `'512m'`, or bytes."),
+	swap: z.union([z.string().regex(MEMORY), z.int().nonnegative()]).optional().describe("Swap on top of `memory`, in the same units. Default: as much as `memory`; `0` makes `memory` the hard ceiling. A host without swap has none to give."),
+	cpus: z.number().positive().optional().describe("CPUs the container may use, fractions allowed. Default 2, capped at the Docker host's."),
+	pids: z.int().positive().optional().describe("Processes and threads at once. Default 1024.")
+};
+const BASES = [
+	"image",
+	"from",
+	"dockerfile"
+];
+function oneRecipe(value, ctx) {
+	const bases = BASES.filter((k) => value[k] !== void 0);
+	if (bases.length > 1) ctx.addIssue({
+		code: "custom",
+		message: "one base",
+		params: { bases }
+	});
+	else if (value.dockerfile !== void 0 && value.install !== void 0) ctx.addIssue({
+		code: "custom",
+		message: "dockerfile or install"
+	});
+}
+const dockerSandboxSchema = z.strictObject({
+	kind: z.literal("docker"),
+	engine: z.enum(["docker", "podman"]).optional().describe("The container CLI the sandbox runs on: `podman` for `podman()`, Docker when unset."),
+	...fields,
+	dockerfile: nonEmpty().optional().describe("A Dockerfile, absolute or relative to the directory of the file it's written in, built from its directory with `REEVAL_BASE` set to reeval's sandbox image and cached by content hash.")
+}).superRefine(oneRecipe).describe("A local Docker container, made by `docker()`, or a Podman one, made by `podman()`.");
+const fakeSandboxSchema = z.strictObject({
+	kind: z.literal("fake"),
+	id: nonEmpty().optional().describe("Cell id; defaults to `fake`."),
+	dir: nonEmpty().optional().describe("Parent directory for the per-eval workspace (defaults to the OS temp dir)."),
+	maxConcurrent: z.number().optional().describe("The most attempts on this sandbox kind at once, across the run.")
+}).describe("A temp directory on the host instead of a container, made by `fakeSandbox()`.");
+/** `docker()`'s argument: the descriptor's fields, with `dockerfile` relative or a `file:` URL. */
+const dockerOptionsSchema = z.strictObject({
+	...fields,
+	dockerfile: z.union([nonEmpty(), z.instanceof(URL)]).optional().describe("Relative to the file that calls `docker()`, or an absolute path or `URL`.")
+}).superRefine(oneRecipe);
+const DOCKER_HINTS = {
+	steps: "install",
+	run: "install",
+	setup: "install",
+	image_steps: "install",
+	file: "dockerfile",
+	build: "dockerfile",
+	base: "from",
+	user: "root",
+	privileged: "root",
+	capAdd: "capabilities",
+	caps: "capabilities",
+	mem: "memory",
+	memoryLimit: "memory",
+	memorySwap: "swap",
+	memswap: "swap",
+	cpu: "cpus",
+	pidsLimit: "pids"
+};
+/** The sentence for a field whose value the schema refused, given the value. */
+const FIELD = {
+	id: (v) => `docker({ id }) must be a non-empty string (got ${got(v)})`,
+	image: (v) => `docker({ image }) must be a non-empty string (got ${got(v)})`,
+	from: (v) => `docker({ from }) must be a non-empty string (got ${got(v)})`,
+	root: (v) => `docker({ root }) is true or false (got ${got(v)})`,
+	capabilities: (v) => `docker({ capabilities }) takes Linux capability names, e.g. capabilities: ['NET_RAW'] (got ${got(v)})`,
+	memory: (v) => `docker({ memory }) takes a size such as '4g' or '512m', or bytes (got ${got(v)})`,
+	swap: (v) => `docker({ swap }) takes a size such as '2g' or '512m', bytes, or 0 for none (got ${got(v)})`,
+	cpus: (v) => `docker({ cpus }) takes a number of CPUs above zero, e.g. 1.5 (got ${typeof v === "number" ? String(v) : got(v)})`,
+	pids: (v) => `docker({ pids }) takes a whole number of processes above zero (got ${got(v)})`,
+	maxConcurrent: (v) => `docker({ maxConcurrent }) takes a number (got ${got(v)})`,
+	kind: (v) => `a Docker sandbox's kind is "docker" (got ${got(v)})`,
+	engine: (v) => `a Docker sandbox's engine is "docker" or "podman" (got ${got(v)})`,
+	dockerfile: (v) => `docker({ dockerfile }) takes a path, e.g. dockerfile: './Dockerfile' (got ${got(v)})`,
+	install: (v) => `docker({ install }) takes a non-empty list of shell commands, e.g. install: ['apt-get update && apt-get install -y jq'] (got ${got(v)})`
+};
+/** Which refusal to report when there are several: the order `docker()` has always checked in. */
+const ORDER = [
+	"kind",
+	"engine",
+	"id",
+	"image",
+	"from",
+	"root",
+	"capabilities",
+	"memory",
+	"swap",
+	"cpus",
+	"pids"
+];
+function installMessage(step) {
+	const { run, timeout } = typeof step === "object" && step !== null ? step : {};
+	const keys = typeof step === "object" && step !== null ? Object.keys(step) : [];
+	if (typeof run === "string" && run.trim()) {
+		const extra = keys.find((k) => k !== "run" && k !== "timeout");
+		if (extra) return `docker({ install }) command "${run}" has an unknown key "${extra}"; a command is a string or { run, timeout? }.${closest(extra, ["timeout"]) ? " Did you mean \"timeout\"?" : ""}`;
+		const problem = timeout === void 0 ? void 0 : durationProblem(timeout);
+		if (problem) return `docker({ install }) command "${run}": ${problem}`;
+	}
+	return `docker({ install }) commands are strings or { run, timeout? } objects (got ${got(step)})`;
+}
+/** reeval's sentence for the first thing Zod refused, in the words `docker()` has always used. */
+function explainDocker(issue, value) {
+	const options = value;
+	if (issue.code === "unrecognized_keys" && issue.path.length === 0) {
+		const key = issue.keys[0];
+		if (key === "environment" || key === "env") return `Unknown docker() option "${key}". The sandbox is what's baked into the image; variables and secrets belong in defineEnvironment({ env }).`;
+		return `Unknown docker() option "${key}".${DOCKER_HINTS[key] ? ` Did you mean "${DOCKER_HINTS[key]}"?` : ""}`;
+	}
+	if (issue.code === "custom") {
+		const { bases } = issue.params ?? {};
+		return bases ? `docker() takes one base image, but got ${bases.join(" and ")}. Use image (has the harness), from (a toolchain image reeval bakes the harness onto) or dockerfile.` : "docker() takes dockerfile or install, not both: put the install commands in the Dockerfile as RUN lines, so there's one recipe for the image.";
+	}
+	const key = String(issue.path[0]);
+	if (key === "install" && issue.path.length > 1) return installMessage(options.install[issue.path[1]]);
+	return (FIELD[key] ?? ((v) => `docker({ ${key} }) is invalid (got ${got(v)})`))(options[key]);
+}
+function explainFake(issue, value) {
+	if (issue.code === "unrecognized_keys" && issue.path.length === 0) {
+		const key = issue.keys[0];
+		const near = closest(key, Object.keys(fakeSandboxSchema.shape));
+		return `Unknown fakeSandbox() option "${key}".${near ? ` Did you mean "${near}"?` : ""}`;
+	}
+	const key = String(issue.path[0]);
+	const v = value[key];
+	return key === "maxConcurrent" ? `fakeSandbox({ maxConcurrent }) takes a number (got ${got(v)})` : `fakeSandbox({ ${key} }) must be a non-empty string (got ${got(v)})`;
+}
+/** A refusal in the words of the function that makes the sandbox: `podman({ memory })`. */
+const named = (problem, engine) => problem && engine === "podman" ? problem.replace(/\bdocker\(/g, "podman(").replace(/\bA Docker sandbox/g, "A Podman sandbox") : problem;
+/** `docker()`'s (or `podman()`'s) options, checked; throws reeval's sentence for the first problem. */
+function checkDockerOptions(options, engine) {
+	const problem = named(refusal(dockerOptionsSchema, options, explainDocker, { order: ORDER }), engine);
+	if (problem) throw new UsageError(problem);
+}
+/**
+* What's wrong with a sandbox descriptor of a known kind from any source (a declaration tree, a
+* config), or undefined. `maxConcurrent` is left to the check that names where it was set.
+*/
+function sandboxProblem(value) {
+	return value.kind === "docker" ? named(refusal(dockerSandboxSchema, value, explainDocker, {
+		order: ORDER,
+		skip: ["maxConcurrent"]
+	}), value.engine) : refusal(fakeSandboxSchema, value, explainFake, { skip: ["maxConcurrent"] });
+}
+//#endregion
+//#region src/contract/plain.ts
+/** A host environment variable's name. */
+const VAR = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A host name, or `*.` and a domain for its subdomains. */
+const HOST = /^(?:\*\.)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/i;
+/** Why `host` isn't a host name or `*.` pattern, or undefined when it is one. */
+function badHost(host) {
+	if (typeof host === "string" && HOST.test(host)) {
+		const name = host.replace(/^\*\./, "");
+		if (/(?:^|\.)\d+$/.test(name) && (name !== host || isIP(name) !== 4)) return `'${host}' isn't a host name or an IPv4 address, and a *. pattern never matches an address.`;
+		if (name !== host && !name.includes(".")) return `'${host}' would allow every host under .${name}; name the domain, e.g. '*.example.${name}'.`;
+		return;
+	}
+	if (typeof host === "string" && /^[a-z]+:\/\//i.test(host)) return `hosts are host names, not URLs: use '${new URL(host).hostname}' (got '${host}')`;
+	if (typeof host === "string" && /^[^:/]+:\d+$/.test(host)) return `hosts are host names without a port: use '${host.split(":")[0]}' (got '${host}')`;
+	return `${JSON.stringify(host)} isn't a host. Use a name like 'api.example.com', or '*.example.com' for its subdomains.`;
+}
+const host = z.string().superRefine((value, ctx) => {
+	const bad = badHost(value);
+	if (bad) ctx.addIssue({
+		code: "custom",
+		message: bad
+	});
+});
+const gatePolicySchema = z.union([z.literal("all"), z.strictObject({ passRate: z.number().gt(0).max(1) })]).describe("How a cell's attempts decide its outcome: `'all'` (the default) passes only when every attempt passes (pass^k); `{ passRate }` passes when its pass@1 (passes over passes and fails) is at least that share.");
+const egressPolicySchema = z.union([
+	z.literal("allow-all"),
+	z.literal("deny-all"),
+	z.strictObject({ allow: z.array(host).readonly() })
+]).describe("Where the sandbox may connect: anywhere (`'allow-all'`, the default), nowhere (`'deny-all'`), or only the listed hosts (`'*.example.com'` matches subdomains). Under a restricted policy the harness's own hosts, brokered secrets' `hosts` and MCP servers' hosts are allowed too; any other request gets a refusal, and the attempt goes on.");
+const substituteInSchema = z.enum([
+	"header",
+	"query",
+	"body"
+]).describe("`header` values, the `query` string, or the request `body`.");
+const secretSchema = z.strictObject({
+	kind: z.literal("secret"),
+	from: z.string().regex(VAR, "needs a host variable name").optional().describe("The host variable; defaults to the key it's set under."),
+	optional: z.boolean().optional().describe("When the host variable is unset, skip it (the record says so) instead of failing."),
+	to: z.enum(["agent", "checks"]).optional().describe("`agent` (default): the container's environment. `checks`: only `c.exec` and `setup` steps."),
+	hosts: z.array(host).min(1).optional().describe("Brokers the secret: the sandbox gets a per-attempt placeholder, and the Docker egress gateway swaps in the real value only on HTTPS requests to these hosts (`*.example.com` for subdomains)."),
+	in: z.array(substituteInSchema).min(1).optional().describe("Where in a request to those hosts the gateway substitutes; defaults to `['header']`.")
+}).superRefine((secret, ctx) => {
+	if (secret.in && !secret.hosts) ctx.addIssue({
+		code: "custom",
+		path: ["in"],
+		message: "in only applies to a brokered secret; add hosts"
+	});
+}).describe("A host environment variable, redacted everywhere reeval writes and recorded by name only. Made by the `secret` helper of `defineEnvironment` and `defineConfig` callbacks.");
+const secretTemplateSchema = z.strictObject({
+	kind: z.literal("secret-template"),
+	template: z.string().describe("The string, with `${NAME}` for each host variable to substitute.")
+}).describe("`secret.template('Bearer ${TOKEN}')`: host variables substituted into a string, for MCP headers.");
+const envValueSchema = z.union([z.string(), secretSchema]).describe("A variable's value: a literal string, or a host secret.");
+const envVarsSchema = z.record(z.string(), envValueSchema).describe("Environment variables by name.");
+const hostFileSchema = z.strictObject({
+	kind: z.literal("file"),
+	path: nonEmpty().describe("Its path on the host, absolute or relative to the directory of the file it's written in.")
+}).describe("A file on the host, read when an attempt starts. Made by the `file` helper.");
+const skillPlacementSchema = z.enum(["harness", "workspace"]).describe("`harness` (default): the agent's own skills, via its adapter. `workspace`: its repo skill dir.");
+const ONLY = "The skill names to keep; default every one found.";
+const EXCLUDE = "Paths in each skill directory to leave out, gitignore-style.";
+const skill = (source, fields) => z.strictObject({
+	kind: z.literal("skill"),
+	placement: skillPlacementSchema,
+	source: z.literal(source),
+	...fields
+});
+const skillSourceSchema = z.discriminatedUnion("source", [
+	skill("local", {
+		path: nonEmpty().describe("A host directory with a `SKILL.md`, or a directory of them."),
+		only: z.array(z.string()).optional().describe(ONLY),
+		exclude: z.array(z.string()).optional().describe(EXCLUDE)
+	}),
+	skill("git", {
+		repo: nonEmpty().describe("As written: a URL, `github:owner/repo`, or a GitHub `/tree/<ref>/<path>` URL."),
+		ref: z.string().optional().describe("A branch, tag or commit SHA; unset is the remote's `HEAD`."),
+		path: z.string().optional().describe("The directory in the repository to read skills from."),
+		only: z.array(z.string()).optional().describe(ONLY),
+		exclude: z.array(z.string()).optional().describe(EXCLUDE)
+	}),
+	skill("registry", {
+		id: z.string().regex(/^[\w.-]+\/[\w.-]+@[a-z0-9-]+$/).describe("A skills.sh id, `owner/repo@skill`."),
+		version: z.string().optional().describe("A git ref of the skill's repository.")
+	}),
+	skill("npm", {
+		spec: nonEmpty().describe("A pinned npm package spec."),
+		path: z.string().describe("The directory in the package to read skills from; default `skills`."),
+		only: z.array(z.string()).optional().describe(ONLY),
+		exclude: z.array(z.string()).optional().describe(EXCLUDE)
+	}),
+	skill("inline", {
+		name: z.string().describe("The skill's name, as in `SKILL.md`'s frontmatter."),
+		description: z.string().describe("The skill's description, as in `SKILL.md`'s frontmatter."),
+		content: z.string().describe("The body of `SKILL.md`."),
+		files: z.record(z.string(), z.string()).describe("Other files in the skill directory, by relative path.")
+	})
+]).describe("Skills to place for the agent, made by the `skill` helper.");
+const mcpServerSchema = z.discriminatedUnion("transport", [z.strictObject({
+	kind: z.literal("mcp"),
+	transport: z.literal("stdio"),
+	command: nonEmpty().describe("The command that starts the server in the sandbox."),
+	args: z.array(z.string()),
+	env: envVarsSchema.describe("Variables the server process gets.")
+}), z.strictObject({
+	kind: z.literal("mcp"),
+	transport: z.enum(["http", "sse"]).describe("Streamable HTTP, or the older SSE transport."),
+	url: z.url("must be a URL"),
+	headers: z.record(z.string(), z.union([
+		z.string(),
+		secretSchema,
+		secretTemplateSchema
+	])).describe("Request headers, with secrets brokered by the egress gateway.")
+})]).describe("An MCP server the agent gets, made by the `mcp` helper: a command in the sandbox, or a URL.");
+const gitWorkspaceSchema = z.strictObject({
+	kind: z.literal("git"),
+	repo: nonEmpty().describe("As written: a URL, `github:owner/repo`, or a local path."),
+	url: nonEmpty().describe("What reeval fetches: the clone URL, or an absolute path for a local repository."),
+	ref: z.string().optional().describe("A branch, tag or commit SHA; unset is the remote's `HEAD`."),
+	path: z.string().optional().describe("A directory in the repository whose contents become the workspace."),
+	init: z.boolean().optional().describe("Give the workspace a `.git`: one commit of the fetched tree, with no remote."),
+	token: z.string().superRefine((token, ctx) => {
+		if (!VAR.test(token) || /^(?:gh[opsur]_|github_pat_)/.test(token)) ctx.addIssue({
+			code: "custom",
+			message: "token names the host variable that holds the token, e.g. token: 'GITHUB_TOKEN'. Don't put the token itself in the eval."
+		});
+	}).optional().describe("The host variable holding a token for the fetch; read on the host only.")
+}).describe("A git repository (or one directory of it) the workspace starts as, from the `git` helper. `url` is what reeval fetches: the clone URL, or an absolute path for a local repository.");
+/** Every key any object in `schema` takes, for "Did you mean". */
+function keysOf(schema) {
+	const def = schema.def;
+	if (def.shape) return Object.keys(def.shape);
+	if (def.options) return [...new Set(def.options.flatMap(keysOf))];
+	return def.innerType ? keysOf(def.innerType) : [];
+}
+/**
+* What's wrong with a descriptor that arrived as data, in terms of the helper that makes it
+* (`call`, e.g. `secret` or `skill.git`), or undefined when it's sound.
+*/
+function descriptorProblem(schema, value, call) {
+	return refusal(schema, value, (issue, v) => {
+		if (issue.code === "unrecognized_keys") {
+			const key = issue.keys[0];
+			const near = closest(key, keysOf(schema));
+			return `${call}() has no "${key}" field${issue.path.length ? ` in ${String(issue.path.join("."))}` : ""}.${near ? ` Did you mean "${near}"?` : ""}`;
+		}
+		if (issue.code === "custom") return `${call}(): ${issue.message}`;
+		if (issue.code === "invalid_union" && issue.path.length === 1) {
+			const key = String(issue.path[0]);
+			const values = schema.def.options?.flatMap((o) => [...o.shape[key]?._zod.values ?? []]);
+			return `${call.split(".")[0]}() ${key} is ${oneOf(values ?? [])} (got ${got(valueAt(v, issue.path))})`;
+		}
+		return genericProblem(call, issue, v);
+	});
+}
+const GATE_SHAPE = "is 'all' (every attempt passes) or { passRate } with a share above 0 and at most 1, e.g. gate: { passRate: 0.8 }";
+/** reeval's sentence for a gate that isn't one, or undefined. */
+const gateProblem = (value, where) => refusal(gatePolicySchema, value, () => `gate in ${where} ${GATE_SHAPE} (got ${got(value)})`);
+const EGRESS_SHAPE = `is 'allow-all' (the default), 'deny-all', or { allow: ['api.example.com', '*.example.org'] }`;
+/** reeval's sentence for an egress policy that isn't one, or undefined. */
+function egressProblem(value, where) {
+	return refusal(egressPolicySchema, value, () => {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			const list = Array.isArray(value) ? ` For a list of hosts, use { allow: ${got(value)} }.` : "";
+			return `egress in ${where} ${EGRESS_SHAPE} (got ${got(value)}).${list}`;
+		}
+		const key = Object.keys(value).find((k) => k !== "allow");
+		if (key !== void 0) return `Unknown egress key "${key}" in ${where}.${key === "deny" ? " A policy lists what's allowed; everything else is refused." : key === "hosts" || key === "allowedHosts" ? " Did you mean \"allow\"?" : " A policy is { allow: ['api.example.com'] }."}`;
+		const allow = value.allow;
+		if (!Array.isArray(allow)) return `egress in ${where} ${EGRESS_SHAPE} (got ${got(value)})`;
+		return `egress.allow in ${where}: ${allow.map(badHost).find(Boolean)}`;
+	});
+}
+//#endregion
+//#region src/contract/environment.ts
+/** An environment's or layer's name, which names its cells. */
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._@+-]*$/;
+const sandboxDescriptorSchema = z.union([fakeSandboxSchema, dockerSandboxSchema]);
+const setupStepSchema = z.union([nonEmpty(), z.strictObject({
+	run: nonEmpty().describe("The shell command."),
+	timeout: durationSchema.optional().describe("Default 5m."),
+	cwd: nonEmpty().optional().describe("Relative to the workspace, or absolute; default the workspace.")
+})]).describe("Runs in every attempt before the agent starts, with secrets, outside the eval timeout: a shell command, or `{ run, timeout?, cwd? }`.");
+const environmentSpecSchema = z.strictObject({
+	sandbox: sandboxDescriptorSchema.optional().describe("Where the attempt runs: `docker()` or `fakeSandbox()`. A child's `extend` / `extendEnvironment` replaces the parent's entirely when it sets one; install is not merged onto the parent image."),
+	workspace: gitWorkspaceSchema.optional().describe("The code the workspace starts as, before `files`, `rules` and `setup`; a child's replaces its parent's."),
+	env: envVarsSchema.optional().describe("Variables and secrets for the sandbox, merged by name over the parent's."),
+	egress: egressPolicySchema.optional().describe("Replaces the inherited policy; an `extend` child's replaces its parent's."),
+	files: z.record(z.string(), z.union([z.string(), hostFileSchema])).optional().describe("Workspace-relative, or `~/` for home."),
+	rules: z.union([z.string(), hostFileSchema]).optional().describe("Project rules, written where the harness's agent reads them: `AGENTS.md`, or `CLAUDE.md` for Claude Code."),
+	setup: z.array(setupStepSchema).optional().describe("Shell commands run in every attempt before the agent starts; a child's run after its parent's."),
+	skills: z.array(skillSourceSchema).optional().describe("Skills placed for the agent."),
+	mcp: z.record(z.string(), mcpServerSchema).optional().describe("MCP servers the agent gets, by name.")
+}).describe("What an eval runs in: the declarative, phased spec of one environment.");
+const environmentLayerSchema = z.strictObject({
+	name: z.string().regex(NAME).describe("The name passed to `defineEnvironment` or `extend`."),
+	spec: environmentSpecSchema.describe("The spec as that layer wrote it, before merging.")
+}).describe("One environment in an `extend` chain.");
+const environmentDataSchema = z.strictObject({
+	kind: z.literal("environment"),
+	name: z.string().regex(NAME).describe("The name it was defined or extended under, which names its cells."),
+	layers: z.array(environmentLayerSchema).readonly().describe("Its `extend` chain, root first.")
+}).describe("An `Environment` as data, as JSON carries it: without `extend` / `extendEnvironment`.");
+//#endregion
+//#region src/environment.ts
+var DefinitionError = class extends Error {
+	name = "DefinitionError";
+};
+const SPEC_KEYS = [
+	"sandbox",
+	"workspace",
+	"env",
+	"egress",
+	"files",
+	"rules",
+	"setup",
+	"skills",
+	"mcp"
+];
+/** Image fields that belong on `sandbox: docker({ … })`, not as sibling keys. */
+const SANDBOX_KEYS = [
+	"image",
+	"install",
+	"dockerfile",
+	"from"
+];
+const SPEC_HINTS = {
+	exec: "setup",
+	steps: "setup",
+	run: "setup",
+	vars: "env",
+	secrets: "env",
+	network: "egress",
+	networkPolicy: "egress",
+	skill: "skills",
+	file: "files",
+	agents: "rules",
+	use: "extend",
+	repo: "workspace",
+	git: "workspace",
+	template: "workspace"
+};
+const isSecret = (value) => isObjectLike(value) && value.kind === "secret";
+const isSecretTemplate = (value) => isObjectLike(value) && value.kind === "secret-template";
+const isHostFile = (value) => isObjectLike(value) && value.kind === "file";
+const isEnvironment = (value) => isObjectLike(value) && value.kind === "environment" && Array.isArray(value.layers);
+const OWN_DIRS = COMPILED ? [join(PACKAGE_DIR, sep)] : ["src", "dist"].map((dir) => join(PACKAGE_DIR, dir, sep));
+/** The directory of the file that called into reeval, from the stack; relative paths resolve here. */
+function callerDir() {
+	const limit = Error.stackTraceLimit;
+	Error.stackTraceLimit = 30;
+	const stack = (/* @__PURE__ */ new Error()).stack ?? "";
+	Error.stackTraceLimit = limit;
+	for (const line of stack.split("\n").slice(1)) {
+		const match = /(?:\(|at )((?:file:\/\/)?\/[^()]*?|[A-Za-z]:[\\/][^()]*?):\d+:\d+\)?\s*$/.exec(line);
+		if (!match?.[1]) continue;
+		const file = normalize(match[1].startsWith("file://") ? fileURLToPath(match[1]) : match[1]);
+		if (OWN_DIRS.some((d) => file.startsWith(d)) || file.includes(`${sep}node_modules${sep}`)) continue;
+		return dirname(file);
+	}
+}
+/** A path as written, or a `file:` URL, made absolute against `base`. */
+const toPath = (value, base) => {
+	const path = value instanceof URL ? fileURLToPath(value) : value;
+	return isAbsolute(path) ? path : resolve(base, path);
+};
+/**
+* A tarball or folder spec (`./x.tgz`, `../pkg`, `/abs`, `file:…`) as an absolute path, resolved
+* like `file()`; npm resolves relative ones against its working directory, reeval's cache.
+*/
+const localNpmSpec = (spec, base) => {
+	const path = spec.startsWith("file:") ? spec.slice(5) : spec;
+	return /^\.{1,2}(?:\/|$)/.test(path) || isAbsolute(path) ? toPath(path, base) : spec;
+};
+const SUBSTITUTE_IN = [
+	"header",
+	"query",
+	"body"
+];
+/** Throws unless `value` is `'allow-all'`, `'deny-all'` or `{ allow: [hosts] }`. */
+function checkEgress(value, where, Err = DefinitionError) {
+	const problem = egressProblem(value, where);
+	if (problem) throw new Err(problem);
+}
+const SECRET_HOSTS = Object.freeze({
+	gemini: Object.freeze(["generativelanguage.googleapis.com"]),
+	openai: Object.freeze(["api.openai.com"]),
+	anthropic: Object.freeze(["api.anthropic.com"]),
+	github: Object.freeze(["api.github.com", "uploads.github.com"])
+});
+function secretOptions(options, what) {
+	const to = options.to ?? "agent";
+	if (to !== "agent" && to !== "checks") throw new DefinitionError(`${what}: to is 'agent' or 'checks' (got ${JSON.stringify(to)})`);
+	const { hosts } = options;
+	if (hosts !== void 0) {
+		if (!Array.isArray(hosts) || hosts.length === 0) throw new DefinitionError(`${what}: hosts must list the hosts the secret is sent to, e.g. hosts: ['api.example.com'] or secret.hosts.gemini (got ${JSON.stringify(hosts)})`);
+		for (const host of hosts) {
+			const bad = badHost(host);
+			if (bad) throw new DefinitionError(`${what}: ${bad}`);
+		}
+	}
+	if (options.in !== void 0) {
+		if (hosts === void 0) throw new DefinitionError(`${what}: in only applies to a brokered secret; add hosts, e.g. { hosts: ['api.example.com'], in: ${JSON.stringify(options.in)} }`);
+		if ((Array.isArray(options.in) ? options.in.filter((i) => !SUBSTITUTE_IN.includes(i)) : [options.in]).length || options.in.length === 0) throw new DefinitionError(`${what}: in lists where the gateway substitutes: 'header', 'query' and/or 'body' (got ${JSON.stringify(options.in)})`);
+	}
+	return {
+		...options.optional ? { optional: true } : {},
+		...to === "checks" ? { to } : {},
+		...hosts ? { hosts: [...hosts] } : {},
+		...options.in ? { in: [...new Set(options.in)] } : {}
+	};
+}
+/** Where an MCP server's header secrets are brokered to by default: its own host, over HTTPS. */
+function mcpHosts(url) {
+	try {
+		const u = new URL(url);
+		return u.protocol === "https:" ? [u.hostname] : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Every secret among `env` and the layers' env and MCP servers, layered as the attempt resolves
+* them: a later layer's variable or MCP server replaces an earlier one of the same name.
+*/
+function plannedSecrets(env, layers) {
+	const vars = { ...env };
+	const servers = /* @__PURE__ */ new Map();
+	for (const { spec } of layers) {
+		Object.assign(vars, spec.env);
+		for (const [name, server] of Object.entries(spec.mcp ?? {})) servers.set(name, server);
+	}
+	const out = /* @__PURE__ */ new Map();
+	const add = (label, from, hosts, checksOnly = false, optional = false) => out.set(`${label}\0${from}`, {
+		label,
+		from,
+		...hosts ? { hosts } : {},
+		...checksOnly ? { checksOnly } : {},
+		...optional ? { optional } : {}
+	});
+	const fromVars = (values, prefix) => {
+		for (const [name, value] of Object.entries(values)) if (isSecret(value)) add(`${prefix}${name}`, value.from ?? name, value.hosts, value.to === "checks", value.optional === true);
+	};
+	fromVars(vars, "");
+	for (const [server, s] of servers) {
+		if (s.transport === "stdio") {
+			fromVars(s.env, `mcp.${server}.env.`);
+			continue;
+		}
+		const own = mcpHosts(s.url);
+		for (const [header, value] of Object.entries(s.headers)) {
+			const label = `mcp.${server}.headers.${header}`;
+			if (isSecret(value)) add(label, value.from ?? header, value.hosts ?? own);
+			if (isSecretTemplate(value)) for (const [, name] of value.template.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g)) add(label, name, own);
+		}
+	}
+	return [...out.values()];
+}
+/** The secrets the sandbox gets as real values: no `hosts`, and none implied by an MCP URL. */
+const unbrokeredSecrets = (env, layers) => plannedSecrets(env, layers).flatMap(({ hosts, ...s }) => hosts ? [] : [s]);
+function secretHelper() {
+	const secret = ((options = {}) => ({
+		kind: "secret",
+		...secretOptions(options, "secret()")
+	}));
+	secret.fromEnv = (host, options = {}) => {
+		if (typeof host !== "string" || !VAR.test(host)) throw new DefinitionError(`secret.fromEnv(${JSON.stringify(host)}) needs a host variable name: letters, digits and _, not starting with a digit, e.g. secret.fromEnv('API_KEY')`);
+		return {
+			kind: "secret",
+			from: host,
+			...secretOptions(options, `secret.fromEnv("${host}")`)
+		};
+	};
+	secret.template = (template) => ({
+		kind: "secret-template",
+		template
+	});
+	secret.hosts = SECRET_HOSTS;
+	return secret;
+}
+const MOVING = /^(?:main|master|HEAD|trunk|develop|dev|latest)$/;
+/** A git ref that isn't a commit SHA or a version-like tag. */
+const isMovingRef = (ref) => ref === void 0 || MOVING.test(ref) || !/^(?:[0-9a-f]{7,40}|v?\d+(?:\.\d+)*(?:[-+].*)?)$/.test(ref);
+/** `github:owner/repo` and GitHub `/tree/<ref>/<path>` URLs, as a clone URL plus ref and path. */
+function parseGitRepo(repo) {
+	const short = /^github:([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(repo);
+	if (short) return { url: `https://github.com/${short[1]}.git` };
+	const tree = /^https:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/tree\/([^/]+)(?:\/(.+))?$/.exec(repo);
+	if (tree) return {
+		url: `https://github.com/${tree[1]}.git`,
+		ref: tree[2],
+		path: tree[3]
+	};
+	return { url: repo };
+}
+/** `repo#ref:path`, as the plan and the record name a git workspace. */
+const workspaceLabel = (w) => `${w.repo}${w.ref ? `#${w.ref}` : ""}${w.path ? `:${w.path}` : ""}`;
+/** The workspace an attempt starts as: the last layer that sets one. */
+const workspaceOf = (layers) => layers.findLast((l) => l.spec.workspace)?.spec.workspace;
+/** The paths the layers' `files` write, sorted. */
+const filesOf = (layers) => [...new Set(layers.flatMap((l) => Object.keys(l.spec.files ?? {})))].sort();
+/** A URL with its password (or an https username, which is where tokens go) masked. */
+function credentialsIn(repo) {
+	if (!URL.canParse(repo)) return void 0;
+	const u = new URL(repo);
+	if (!u.password && !(u.username && /^https?:$/.test(u.protocol))) return void 0;
+	u.username = u.username && "***";
+	u.password = u.password && "***";
+	return u.href;
+}
+const GIT_OPTIONS = [
+	"ref",
+	"path",
+	"init",
+	"token"
+];
+const isLocalPath = (repo) => /^\.{1,2}(?:\/|$)/.test(repo) || isAbsolute(repo);
+function gitHelper(base) {
+	return (repo, options = {}) => {
+		const written = repo instanceof URL ? repo.href : repo;
+		if (typeof written !== "string" || !written.trim()) throw new DefinitionError(`git() needs a repository: a URL, github:owner/repo or a local path (got ${JSON.stringify(repo)})`);
+		const what = `git(${JSON.stringify(written)})`;
+		const masked = credentialsIn(written);
+		if (masked) throw new DefinitionError(`git(${JSON.stringify(masked)}): the URL has a password or token in it. reeval fetches the repository on the host with your own git credentials (a credential helper, gh auth setup-git or an SSH key), and the sandbox never gets them; remove it from the URL.`);
+		if (typeof options !== "object" || options === null || Array.isArray(options)) throw new DefinitionError(`${what}: options are { ref?, path? }`);
+		const extra = Object.keys(options).filter((k) => !GIT_OPTIONS.includes(k));
+		if (extra.length) {
+			const hint = extra.includes("branch") || extra.includes("tag") ? " Use ref for a branch, tag or commit." : "";
+			throw new DefinitionError(`${what}: unknown option "${extra.join("\", \"")}"; it takes ${GIT_OPTIONS.slice(0, -1).join(", ")} and ${GIT_OPTIONS.at(-1)}.${hint}`);
+		}
+		const local = repo instanceof URL ? repo.protocol === "file:" : isLocalPath(written);
+		const parsed = local ? { url: toPath(repo, base) } : parseGitRepo(written);
+		const ref = options.ref ?? parsed.ref;
+		if (ref !== void 0 && (typeof ref !== "string" || !ref.trim() || ref.startsWith("-"))) throw new DefinitionError(`${what}: ref is a branch, tag or commit SHA (got ${JSON.stringify(ref)})`);
+		const path = options.path ?? parsed.path;
+		if (path !== void 0) {
+			const clean = typeof path === "string" ? path.replace(/\/+$/, "") : path;
+			if (typeof clean !== "string" || !clean || clean.includes("\\") || clean.startsWith("/") || clean.split("/").some((p) => p === ".." || p === "." || p === "")) throw new DefinitionError(`${what}: path is a directory in the repository, relative, with forward slashes and no . or .. (got ${JSON.stringify(path)})`);
+		}
+		const cleanPath = path?.replace(/\/+$/, "");
+		const { init, token } = options;
+		if (init !== void 0 && typeof init !== "boolean") throw new DefinitionError(`${what}: init is true or false (got ${JSON.stringify(init)})`);
+		if (token !== void 0) {
+			if (typeof token !== "string" || !VAR.test(token) || /^(?:gh[opsur]_|github_pat_)/.test(token)) throw new DefinitionError(`${what}: token names the host variable that holds the token, e.g. token: 'GITHUB_TOKEN'. Don't put the token itself in the eval.`);
+			if (local || !/^https?:\/\//.test(parsed.url)) throw new DefinitionError(`${what}: token only works with an https:// URL; for SSH or a local repository, git uses this machine's own credentials`);
+		}
+		return {
+			kind: "git",
+			repo: "ref" in parsed || "path" in parsed ? parsed.url.replace(/\.git$/, "") : written,
+			url: parsed.url,
+			...ref ? { ref } : {},
+			...cleanPath ? { path: cleanPath } : {},
+			...init ? { init } : {},
+			...token ? { token } : {}
+		};
+	};
+}
+/**
+* What a skill directory leaves out of the sandbox unless `exclude` says otherwise: eval material
+* (skill-creator keeps `evals/` in the skill), run history and reeval eval files. `.git` is always left out.
+*/
+const DEFAULT_SKILL_EXCLUDE = [
+	"/evals/",
+	".history/",
+	"*.eval.ts"
+];
+function skillHelper(base) {
+	const placement = (p) => {
+		if (p === void 0 || p === "harness" || p === "workspace") return p ?? "harness";
+		throw new DefinitionError(`skill({ placement }) is 'harness' or 'workspace' (got ${JSON.stringify(p)})`);
+	};
+	const exclude = (e) => {
+		if (e === void 0) return {};
+		if (!Array.isArray(e) || e.some((p) => typeof p !== "string" || !p.replace(/\//g, ""))) throw new DefinitionError(`skill({ exclude }) must be a list of paths or globs, e.g. ['/evals/', '*.eval.ts'] (got ${JSON.stringify(e)})`);
+		return { exclude: [...e] };
+	};
+	return {
+		local: (path, o = {}) => ({
+			kind: "skill",
+			source: "local",
+			path: toPath(path, base),
+			...o.only ? { only: [...o.only] } : {},
+			...exclude(o.exclude),
+			placement: placement(o.placement)
+		}),
+		git: (repo, o = {}) => {
+			if (typeof repo !== "string" || !repo) throw new DefinitionError(`skill.git() needs a repository URL, e.g. skill.git('https://github.com/acme/skills') (got ${JSON.stringify(repo)})`);
+			const parsed = parseGitRepo(repo);
+			const ref = o.ref ?? parsed.ref;
+			const path = o.path ?? parsed.path;
+			return {
+				kind: "skill",
+				source: "git",
+				repo,
+				...ref ? { ref } : {},
+				...path ? { path } : {},
+				...o.only ? { only: [...o.only] } : {},
+				...exclude(o.exclude),
+				placement: placement(o.placement)
+			};
+		},
+		registry: (id, o = {}) => {
+			if (!/^[\w.-]+\/[\w.-]+@[a-z0-9-]+$/.test(id)) throw new DefinitionError(`skill.registry(${JSON.stringify(id)}) needs an id like owner/repo@skill, e.g. skill.registry('acme/skills@review')`);
+			return {
+				kind: "skill",
+				source: "registry",
+				id,
+				...o.version ? { version: o.version } : {},
+				placement: placement(o.placement)
+			};
+		},
+		npm: (spec, o = {}) => ({
+			kind: "skill",
+			source: "npm",
+			spec: localNpmSpec(spec, base),
+			path: o.path ?? "skills",
+			...o.only ? { only: [...o.only] } : {},
+			...exclude(o.exclude),
+			placement: placement(o.placement)
+		}),
+		inline: (skill, o = {}) => ({
+			kind: "skill",
+			source: "inline",
+			name: skill.name,
+			description: skill.description,
+			content: skill.content,
+			files: { ...skill.files },
+			placement: placement(o.placement)
+		})
+	};
+}
+/**
+* What `directory()` leaves out unless `defaultIgnores: false`: dependency, build-output, cache
+* and editor directories, in its `glob` syntax. `build/` and `target/` are anchored to the top of
+* the directory, where Flutter, Dart, Gradle and Cargo put their output, since a nested one can be
+* source. `vendor/` isn't here: a committed Go or PHP vendor directory is what an offline build needs.
+*/
+const DEFAULT_DIRECTORY_IGNORES = Object.freeze([
+	"node_modules/",
+	".DS_Store",
+	"dist/",
+	".next/",
+	".turbo/",
+	"coverage/",
+	".cache/",
+	"__pycache__/",
+	".venv/",
+	"venv/",
+	".pytest_cache/",
+	".mypy_cache/",
+	"*.pyc",
+	".dart_tool/",
+	"/build/",
+	"/target/",
+	".gradle/",
+	".idea/",
+	".vscode/"
+]);
+/**
+* A gitignore-style pattern as a test of a file's path, matched by picomatch: a pattern without an
+* inner `/` matches a name at any depth, a leading `/` anchors, a trailing `/` names a directory,
+* and a pattern also matches every file in a directory it names.
+*/
+function globTest(pattern) {
+	const dirOnly = pattern.endsWith("/");
+	const body = pattern.replace(/\/+$/, "").replaceAll("[!", "[^");
+	const glob = body.includes("/") ? body.replace(/^\/+/, "") : `**/${body}`;
+	const self = picomatch(glob, { dot: true });
+	const inside = picomatch(`${glob}/**/*`, { dot: true });
+	return (path, isDir = false) => inside(path) || (isDir || !dirOnly) && self(path);
+}
+/**
+* `glob` as a test of a directory-relative file path: the last pattern that matches decides, a
+* `!` one excluding; a file no pattern matches is in unless some pattern includes.
+*/
+function globFilter(patterns) {
+	const rules = patterns.map((p) => ({
+		include: !p.startsWith("!"),
+		test: globTest(p.replace(/^!/, ""))
+	}));
+	const start = !rules.some((r) => r.include);
+	return (path, isDir) => rules.reduce((keep, r) => r.test(path, isDir) ? r.include : keep, start);
+}
+const DIRECTORY_OPTIONS = [
+	"into",
+	"glob",
+	"defaultIgnores"
+];
+function directoryHelper(base) {
+	return (path, options = {}) => {
+		const written = path instanceof URL ? path.href : path;
+		const what = `directory(${JSON.stringify(written)})`;
+		if (typeof written !== "string" || !written) throw new DefinitionError(`directory() needs a path to a directory, relative to this file (got ${JSON.stringify(path)})`);
+		if (typeof options !== "object" || options === null || Array.isArray(options)) throw new DefinitionError(`${what}: options are { into?, glob?, defaultIgnores? }`);
+		const extra = Object.keys(options).filter((k) => !DIRECTORY_OPTIONS.includes(k));
+		if (extra.length) {
+			const hint = extra.includes("ignore") || extra.includes("exclude") ? " Exclude with a '!' pattern in glob, e.g. glob: ['!dist/']." : "";
+			throw new DefinitionError(`${what}: unknown option "${extra.join("\", \"")}"; it takes into, glob and defaultIgnores.${hint}`);
+		}
+		const { into, glob = [], defaultIgnores = true } = options;
+		if (into !== void 0 && (typeof into !== "string" || into.includes("\\") || isAbsolute(into) || into.split("/").some((p) => p === ".."))) throw new DefinitionError(`${what}: into is a directory relative to the workspace (or ~/…), with forward slashes and no .. (got ${JSON.stringify(into)})`);
+		if (!Array.isArray(glob) || glob.some((p) => typeof p !== "string" || !p.replace(/^!/, "").replace(/\//g, ""))) throw new DefinitionError(`${what}: glob is a list of patterns, e.g. ['src/**', 'package.json', '!**/*.test.ts'] (got ${JSON.stringify(glob)})`);
+		if (typeof defaultIgnores !== "boolean") throw new DefinitionError(`${what}: defaultIgnores is true or false (got ${JSON.stringify(defaultIgnores)})`);
+		const root = toPath(path, base);
+		const stat = statSync(root, { throwIfNoEntry: false });
+		if (!stat) throw new DefinitionError(`${what}: ${root} doesn't exist`);
+		if (!stat.isDirectory()) throw new DefinitionError(`${what}: ${root} is a file, not a directory. Use file(${JSON.stringify(written)}) for one file.`);
+		const skip = defaultIgnores ? globFilter(DEFAULT_DIRECTORY_IGNORES) : () => false;
+		const keep = globFilter(glob);
+		const prefix = into?.replace(/\/+$/, "").replace(/^\.\/?/, "");
+		const files = {};
+		const walk = (dir, rel, seen) => {
+			for (const name of readdirSync(dir).sort()) {
+				if (name === ".git") continue;
+				const full = join(dir, name);
+				const relPath = rel ? `${rel}/${name}` : name;
+				const target = statSync(full, { throwIfNoEntry: false });
+				if (!target) throw new DefinitionError(`${what}: ${relPath} is a symlink to something that doesn't exist. Remove it, or leave it out with glob: ['!${relPath}'].`);
+				if (target.isDirectory()) {
+					if (skip(relPath, true)) continue;
+					const real = realpathSync(full);
+					if (seen.includes(real)) throw new DefinitionError(`${what}: ${relPath} is a symlink to a directory that contains it. Leave it out with glob: ['!${relPath}/'].`);
+					walk(full, relPath, [...seen, real]);
+				} else if (target.isFile() && !skip(relPath) && keep(relPath)) files[prefix ? `${prefix}/${relPath}` : relPath] = {
+					kind: "file",
+					path: full
+				};
+			}
+		};
+		walk(root, "", [realpathSync(root)]);
+		if (Object.keys(files).length === 0) throw new DefinitionError(`${what}: no files in ${root}${glob.length || defaultIgnores ? ` match (glob ${JSON.stringify(glob)}${defaultIgnores ? ", after the default ignores such as node_modules/ and dist/; defaultIgnores: false keeps them" : ""})` : ""}. Empty directories aren't seeded; create one with a setup step.`);
+		return files;
+	};
+}
+const mcpHelper = {
+	stdio: (command, args = [], o = {}) => {
+		if (typeof command !== "string" || !command) throw new DefinitionError(`mcp.stdio() needs a command, e.g. mcp.stdio('npx', ['-y', 'server']) (got ${JSON.stringify(command)})`);
+		return {
+			kind: "mcp",
+			transport: "stdio",
+			command,
+			args: [...args],
+			env: { ...o.env }
+		};
+	},
+	http: (url, o = {}) => ({
+		kind: "mcp",
+		transport: "http",
+		url,
+		headers: { ...o.headers }
+	}),
+	sse: (url, o = {}) => ({
+		kind: "mcp",
+		transport: "sse",
+		url,
+		headers: { ...o.headers }
+	})
+};
+/** The helpers a callback gets, with relative paths resolving against `base`. */
+function helpersFor(base) {
+	return {
+		secret: secretHelper(),
+		skill: skillHelper(base),
+		mcp: mcpHelper,
+		file: (path) => ({
+			kind: "file",
+			path: toPath(path, base)
+		}),
+		directory: directoryHelper(base),
+		git: gitHelper(base)
+	};
+}
+/** Throws on env variables that aren't strings or secrets, or look like literal secrets. */
+function checkEnv(env, where, Err = DefinitionError) {
+	if (typeof env !== "object" || env === null || Array.isArray(env)) throw new Err(`env in ${where} must be an object of variables, e.g. env: { NODE_ENV: 'test' } (got ${JSON.stringify(env)})`);
+	for (const [name, value] of Object.entries(env)) {
+		if (!VAR.test(name)) throw new Err(`env.${name} in ${where} isn't a valid variable name: use letters, digits and _, not starting with a digit`);
+		if (isSecret(value)) {
+			const problem = descriptorProblem(secretSchema, value, "secret");
+			if (problem) throw new Err(`env.${name} in ${where}: ${problem}`);
+			continue;
+		}
+		if (typeof value !== "string") throw new Err(`env.${name} in ${where} must be a string or secret.fromEnv() (got ${JSON.stringify(value)})`);
+		if (SECRET_NAME.test(name)) throw new Err(`env.${name} in ${where} is a literal string. Pass secrets with secret.fromEnv() so they're redacted and never recorded.`);
+	}
+}
+const stepCommand = (step) => typeof step === "string" ? step : step.run;
+function checkSpec(spec, where) {
+	if (typeof spec !== "object" || spec === null || Array.isArray(spec)) throw new DefinitionError(`${where} must be an object or a callback that returns one (got ${JSON.stringify(spec)})`);
+	for (const key of Object.keys(spec)) {
+		if (SPEC_KEYS.includes(key)) continue;
+		if (SANDBOX_KEYS.includes(key)) {
+			const value = spec[key];
+			throw new DefinitionError(`"${key}" isn't an environment field (${where}). Put the image on the sandbox: sandbox: docker({ ${key === "image" ? typeof value === "string" ? "from" : "install" : key}: … }).`);
+		}
+		const near = SPEC_HINTS[key] ?? closest(key, SPEC_KEYS);
+		throw new DefinitionError(`Unknown field "${key}" in ${where}.${near ? ` Did you mean "${near}"?` : ""}`);
+	}
+	const s = spec;
+	if (s.sandbox !== void 0) checkSandbox(s.sandbox, where);
+	if (s.workspace !== void 0 && s.workspace?.kind !== "git") throw new DefinitionError(`workspace in ${where} must come from the git helper, e.g. workspace: git('https://github.com/acme/app', { ref: 'v1.0.0' }) (got ${JSON.stringify(s.workspace)})`);
+	if (s.workspace !== void 0) {
+		const problem = descriptorProblem(gitWorkspaceSchema, s.workspace, "git");
+		if (problem) throw new DefinitionError(`workspace in ${where}: ${problem}`);
+	}
+	if (s.env !== void 0) checkEnv(s.env, where);
+	if (s.egress !== void 0) checkEgress(s.egress, where);
+	const list = (key, value) => {
+		if (value !== void 0 && !Array.isArray(value)) throw new DefinitionError(`${key} in ${where} must be a list (got ${JSON.stringify(value)})`);
+		return value ?? [];
+	};
+	for (const [i, step] of list("setup", s.setup).entries()) {
+		const run = typeof step === "string" ? step : isObjectLike(step) ? step.run : void 0;
+		if (typeof run !== "string" || !run.trim()) throw new DefinitionError(`setup[${i}] in ${where} must be a command string or { run, timeout?, cwd? } (got ${JSON.stringify(step)})`);
+		if (typeof step === "string") continue;
+		const extra = Object.keys(step).filter((k) => ![
+			"run",
+			"timeout",
+			"cwd"
+		].includes(k));
+		if (extra.length) throw new DefinitionError(`setup step "${run}" in ${where} has an unknown key "${extra[0]}"; a step is a string or { run, timeout?, cwd? }.`);
+		const { cwd, timeout } = step;
+		if (timeout !== void 0) try {
+			parseDuration(timeout);
+		} catch (error) {
+			throw new DefinitionError(`setup step "${run}" in ${where}: ${error.message}`);
+		}
+		if (cwd !== void 0 && (typeof cwd !== "string" || !cwd.trim())) throw new DefinitionError(`setup step "${run}" in ${where}: cwd must be a directory path, relative to the workspace or absolute (got ${JSON.stringify(cwd)})`);
+	}
+	for (const [i, skill] of list("skills", s.skills).entries()) {
+		if (skill?.kind !== "skill") throw new DefinitionError(`skills in ${where} must come from the skill helper, e.g. skills: [skill.local('./skills')] (got ${JSON.stringify(skill)})`);
+		const call = `skill.${String(skill.source)}`;
+		const problem = descriptorProblem(skillSourceSchema, skill, call);
+		if (problem) throw new DefinitionError(`skills[${i}] in ${where}: ${problem}`);
+	}
+	for (const [name, server] of Object.entries(s.mcp ?? {})) {
+		if (server?.kind !== "mcp") throw new DefinitionError(`mcp.${name} in ${where} must come from the mcp helper, e.g. mcp.stdio('npx', ['-y', 'server']) (got ${JSON.stringify(server)})`);
+		const call = `mcp.${String(server.transport)}`;
+		const problem = descriptorProblem(mcpServerSchema, server, call);
+		if (problem) throw new DefinitionError(`mcp.${name} in ${where}: ${problem}`);
+	}
+	for (const [path, value] of Object.entries(s.files ?? {})) {
+		const key = `files[${JSON.stringify(path)}] in ${where}`;
+		if (path.includes("\\")) throw new DefinitionError(`${key}: use forward slashes (${path.replaceAll("\\", "/")})`);
+		const rest = path.startsWith("~/") ? path.slice(2) : path;
+		if (!rest || isAbsolute(rest) || rest.split("/").includes("..")) throw new DefinitionError(`${key}: paths are relative to the workspace, or start with ~/ for the home directory, and never use ..`);
+		if (typeof value !== "string" && !isHostFile(value)) throw new DefinitionError(`${key} must be a string or file(path) (got ${JSON.stringify(value)})`);
+		const problem = isHostFile(value) && descriptorProblem(hostFileSchema, value, "file");
+		if (problem) throw new DefinitionError(`${key}: ${problem}`);
+	}
+	if (s.rules !== void 0 && typeof s.rules !== "string" && !isHostFile(s.rules)) throw new DefinitionError(`rules in ${where} must be markdown or file(path) (got ${JSON.stringify(s.rules)})`);
+	const rules = isHostFile(s.rules) && descriptorProblem(hostFileSchema, s.rules, "file");
+	if (rules) throw new DefinitionError(`rules in ${where}: ${rules}`);
+	const rest = refusal(environmentSpecSchema, s, (issue, value) => `${where}: ${genericProblem("", issue, value)}`);
+	if (rest) throw new DefinitionError(rest);
+	return structuredClone(s);
+}
+const NAME_RULE = "a name of letters, digits, \".\", \"_\", \"@\", \"+\" or \"-\"";
+/** The envelope of environment data: its name and layers, each layer's spec only as an object. */
+const environmentEnvelope = environmentDataSchema.extend({ layers: z.array(z.strictObject({
+	name: z.string().regex(NAME),
+	spec: z.record(z.string(), z.unknown())
+})) });
+/**
+* What's wrong with an environment as data (from another language, or built by hand), in the
+* words `defineEnvironment` uses for each layer's spec, or undefined. `option` names the option
+* (`environment`, `compare.baseline`, …) and `where` the eval or config that set it.
+*/
+function environmentDataProblem(value, option, at) {
+	const env = value;
+	const where = `${option} in ${at}`;
+	const envelope = refusal(environmentEnvelope, value, (issue) => {
+		const [key, index, field] = issue.path;
+		const layer = index === void 0 ? void 0 : env.layers[index];
+		if (issue.code === "unrecognized_keys") {
+			const what = layer ? `layer ${index} of the environment` : "the environment";
+			return `${where}: ${what} has no "${issue.keys[0]}" field`;
+		}
+		if (key === "name") return `${where} needs ${NAME_RULE} (got ${got(env.name)})`;
+		if (field === "name") return `${where}: layer ${index} of "${env.name}" needs ${NAME_RULE} (got ${got(layer?.name)})`;
+		if (field === "spec") return `${where}: layer "${layer?.name}" of "${env.name}" needs its spec, an object (got ${got(layer?.spec)})`;
+		return `${where}: ${genericProblem("environment", issue, value)}`;
+	});
+	if (envelope) return envelope;
+	for (const layer of env.layers) try {
+		const of = option === "environment" ? at : where;
+		checkSpec(layer.spec, `layer "${layer.name}" of environment "${env.name}" in ${of}`);
+	} catch (error) {
+		if (error instanceof DefinitionError) return error.message;
+		throw error;
+	}
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isPath = (value) => typeof value === "string" && value !== "";
+/**
+* A sandbox descriptor written as data with its host paths made absolute against `base`, as
+* `docker({ dockerfile })` and `fakeSandbox({ dir })` resolve theirs: a Dockerfile, which must be
+* a file, and a fake sandbox's `dir`. Any other value is left for the checks to name.
+*/
+function sandboxPaths(value, base, field, missing) {
+	if (!isRecord(value)) return value;
+	if (value.kind === "docker" && isPath(value.dockerfile)) {
+		const full = toPath(value.dockerfile, base);
+		if (!statSync(full, { throwIfNoEntry: false })?.isFile()) missing(`${field}.dockerfile`, full);
+		return {
+			...value,
+			dockerfile: full
+		};
+	}
+	return value.kind === "fake" && isPath(value.dir) ? {
+		...value,
+		dir: toPath(value.dir, base)
+	} : value;
+}
+/**
+* An environment spec written as data with its host paths made absolute against `base`, as the
+* helpers resolve theirs: host files in `files` and `rules`, a local skill's `path`, a local npm
+* skill spec, a local git workspace's `url`, and the sandbox's. Only a non-empty string changes,
+* and an absolute path stays as written.
+*/
+function specPaths(value, base, field, missing) {
+	if (!isRecord(value)) return value;
+	const hostFile = (v) => isRecord(v) && v.kind === "file" && isPath(v.path) ? {
+		...v,
+		path: toPath(v.path, base)
+	} : v;
+	const skill = (v) => {
+		if (!isRecord(v)) return v;
+		if (v.source === "local" && isPath(v.path)) return {
+			...v,
+			path: toPath(v.path, base)
+		};
+		return v.source === "npm" && isPath(v.spec) ? {
+			...v,
+			spec: localNpmSpec(v.spec, base)
+		} : v;
+	};
+	const out = { ...value };
+	const prefix = field ? `${field}.` : "";
+	if ("sandbox" in value) out.sandbox = sandboxPaths(value.sandbox, base, `${prefix}sandbox`, missing);
+	const { workspace, files, rules, skills } = value;
+	if (isRecord(workspace) && isPath(workspace.url) && isLocalPath(workspace.url)) out.workspace = {
+		...workspace,
+		url: toPath(workspace.url, base)
+	};
+	if (isRecord(files)) out.files = Object.fromEntries(Object.entries(files).map(([k, v]) => [k, hostFile(v)]));
+	if ("rules" in value) out.rules = hostFile(rules);
+	if (Array.isArray(skills)) out.skills = skills.map(skill);
+	return out;
+}
+/**
+* An environment written as data with each layer's spec given absolute host paths against `base`,
+* as `specPaths` gives one spec. Anything that isn't environment data is left for the checks.
+*/
+function environmentPaths(value, base, field, missing) {
+	if (!isRecord(value) || !Array.isArray(value.layers)) return value;
+	return {
+		...value,
+		layers: value.layers.map((layer, i) => isRecord(layer) ? {
+			...layer,
+			spec: specPaths(layer.spec, base, `${field}.layers[${i}].spec`, missing)
+		} : layer)
+	};
+}
+function buildSpec(input, where, base) {
+	const spec = typeof input === "function" ? input(helpersFor(base)) : input;
+	if (spec instanceof Promise || typeof spec?.then === "function") throw new DefinitionError(`${where} returned a Promise. The callback runs once at definition time and must return the environment synchronously; fetch remote content in a setup step instead.`);
+	const missing = (field, full) => {
+		throw new DefinitionError(`${field} in ${where}: ${full} doesn't exist. Paths are relative to the file that defines the environment.`);
+	};
+	return checkSpec(specPaths(spec, base, "", missing), where);
+}
+/** An environment from its data, as a declaration tree carries it: `extendEnvironment` works again. */
+const environmentFrom = (data) => makeEnvironment(data.name, [...data.layers]);
+function makeEnvironment(name, layers) {
+	const env = {
+		kind: "environment",
+		name,
+		layers: Object.freeze(layers)
+	};
+	const extend = (child, input) => {
+		checkName(child, `${name}.extend`);
+		const where = `${name}.extend("${child}")`;
+		const base = callerDir() ?? process.cwd();
+		return makeEnvironment(child, [...layers, {
+			name: child,
+			spec: buildSpec(input, where, base)
+		}]);
+	};
+	Object.defineProperty(env, "extendEnvironment", {
+		enumerable: false,
+		value: extend
+	});
+	Object.defineProperty(env, "extend", {
+		enumerable: false,
+		value: extend
+	});
+	return Object.freeze(env);
+}
+function checkName(name, what) {
+	if (typeof name !== "string" || !NAME.test(name)) throw new DefinitionError(`${what} needs a name of letters, digits, ".", "_", "@", "+" or "-" (got ${JSON.stringify(name)})`);
+}
+/**
+* What an eval runs in: the sandbox, skills, MCP servers, files, rules, variables, secrets and
+* setup steps. Pass a spec, or a callback that destructures the typed helpers it needs:
+*
+*     defineEnvironment('genkit', ({ secret, skill }) => ({
+*       sandbox: docker({ from: 'node:24-bookworm' }),
+*       env: { GOOGLE_GENAI_API_KEY: secret.fromEnv('GOOGLE_GENERATIVE_AI_API_KEY') },
+*       skills: [skill.local('../skills/genkit')],
+*     }))
+*
+* The callback runs once, synchronously. Relative paths resolve against the calling file.
+* `extend` / `extendEnvironment` replace `sandbox` entirely when the child sets one; when
+* the child omits it, the parent's sandbox is kept. A bare `defineEnvironment('plain', {})`
+* that is not an extend uses the cascaded option sandbox, else implicit Docker.
+*/
+function defineEnvironment(name, input) {
+	checkName(name, "defineEnvironment");
+	const base = callerDir() ?? process.cwd();
+	return makeEnvironment(name, [{
+		name,
+		spec: buildSpec(input, `defineEnvironment("${name}")`, base)
+	}]);
+}
+/** The control of a compare without a `baseline` when nothing in the cascade sets an environment. */
+const EMPTY_BASELINE = "baseline";
+/**
+* An environment with no layers. As a compare's empty control it uses the first
+* variant's sandbox when that variant sets one, else the cascaded option sandbox,
+* else the implicit default Docker sandbox.
+*/
+const emptyEnvironment = (name) => makeEnvironment(name, []);
+/** The last layer that sets `sandbox`, else `fallback` (the cascaded option sandbox). */
+const sandboxOf = (layers, fallback) => layers.findLast((l) => l.spec.sandbox)?.spec.sandbox ?? fallback;
+/** The sandbox an environment names, else `fallback`. */
+const environmentSandbox = (env, fallback) => sandboxOf(env?.layers ?? [], fallback);
+function checkSandbox(value, where) {
+	const kind = isObjectLike(value) ? value.kind : void 0;
+	if (!isObjectLike(value) || kind !== "docker" && kind !== "fake") throw new DefinitionError(`sandbox in ${where} must come from docker(), podman() or fakeSandbox() (got ${JSON.stringify(value)})`);
+	const max = value.maxConcurrent;
+	if (max !== void 0 && !(typeof max === "number" && Number.isInteger(max) && max >= 1)) throw new DefinitionError(`sandbox.maxConcurrent in ${where} must be a whole number of at least 1 (got ${String(max)})`);
+	const problem = sandboxProblem(value);
+	if (problem) throw new DefinitionError(`sandbox in ${where}: ${problem}`);
+}
+function applied(env) {
+	if (!env) return {
+		name: "-",
+		parent: null,
+		layers: []
+	};
+	return {
+		name: env.name,
+		parent: env.layers.at(-2)?.name ?? null,
+		layers: [...env.layers]
+	};
+}
+//#endregion
+export { workspaceLabel as A, parseGitRepo as C, stepCommand as D, sandboxPaths as E, envVarsSchema as F, gatePolicySchema as I, gateProblem as L, environmentDataSchema as M, sandboxDescriptorSchema as N, toPath as O, egressPolicySchema as P, checkDockerOptions as R, mcpHosts as S, sandboxOf as T, isEnvironment as _, callerDir as a, isSecret as b, defineEnvironment as c, environmentFrom as d, environmentPaths as f, helpersFor as g, globFilter as h, applied as i, workspaceOf as j, unbrokeredSecrets as k, emptyEnvironment as l, filesOf as m, DEFAULT_SKILL_EXCLUDE as n, checkEgress as o, environmentSandbox as p, EMPTY_BASELINE as r, checkEnv as s, DEFAULT_DIRECTORY_IGNORES as t, environmentDataProblem as u, isHostFile as v, plannedSecrets as w, isSecretTemplate as x, isMovingRef as y, sandboxProblem as z };
+
+//# sourceMappingURL=environment-DNjRk0nU.js.map