@warlock.js/ai-workspace 4.5.0

package/cjs/index.cjs

@@ -0,0 +1,1609 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let _warlock_js_ai = require("@warlock.js/ai");
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+let node_fs_promises = require("node:fs/promises");
+let _warlock_js_fs = require("@warlock.js/fs");
+let node_child_process = require("node:child_process");
+let node_process = require("node:process");
+
+//#region ../@warlock.js/ai-workspace/src/errors.ts
+/**
+* The workspace policy engine refused an operation — a path escaped the
+* jail (or hit a deny glob), or a shell command's executable was not
+* allowed.
+*
+* **Surface.** This is returned to the agent as tool-error *data*, never
+* a thrown run-killer — the agent reads the failure and self-corrects.
+* Extends the framework `AIError` (category `"tool"`, code
+* `TOOL_EXEC_FAILED`) so it flows through the same typed error contract
+* as every other AI error; branch on `error.type` for the specific
+* violation.
+*
+* @example
+* if (error instanceof WorkspacePolicyError && error.type === "denied-command") {
+*   console.warn(`Blocked command: ${error.command}`);
+* }
+*/
+var WorkspacePolicyError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "WorkspacePolicyError";
+		this.type = options.type;
+		this.path = options.path;
+		this.command = options.command;
+	}
+};
+/**
+* An `editFile` operation was rejected by the read-before-edit guard:
+* the `oldString` was absent, matched non-uniquely without `replaceAll`,
+* or the file's hash no longer matched the supplied `expectHash`.
+*
+* **Surface.** Like {@link WorkspacePolicyError}, returned to the agent
+* as tool-error *data* so it can re-read and retry. Extends `AIError`
+* (category `"tool"`, code `TOOL_EXEC_FAILED`); branch on `error.type`.
+*
+* @example
+* if (error instanceof WorkspaceEditError && error.type === "stale-hash") {
+*   // re-read the file and retry the edit with the fresh hash
+* }
+*/
+var WorkspaceEditError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "WorkspaceEditError";
+		this.type = options.type;
+		this.path = options.path;
+		this.matches = options.matches;
+		this.expectedHash = options.expectedHash;
+		this.actualHash = options.actualHash;
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/policy/policy.ts
+/**
+* Resolve the canonical absolute form of `target`, collapsing any
+* symlinks. `target` may not yet exist (a fresh `writeFile`/`mkdir`),
+* so we realpath the deepest **existing** ancestor and re-attach the
+* non-existent tail — a symlinked ancestor still cannot smuggle the
+* path out of the jail, while genuinely new leaves stay creatable.
+*/
+async function canonicalize$1(target) {
+	let resolvedTarget = node_path.default.resolve(target);
+	const tail = [];
+	while (true) try {
+		const real = await (0, node_fs_promises.realpath)(resolvedTarget);
+		return tail.length > 0 ? node_path.default.join(real, ...tail) : real;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = node_path.default.dirname(resolvedTarget);
+		if (parent === resolvedTarget) return node_path.default.join(resolvedTarget, ...tail);
+		tail.unshift(node_path.default.basename(resolvedTarget));
+		resolvedTarget = parent;
+	}
+}
+/**
+* Whether `child` is contained within `root` (or equals it), comparing
+* canonical absolute paths. Guards against the `/srv/app-evil` vs
+* `/srv/app` prefix-collision by anchoring on a path separator.
+*/
+function isInside(child, root) {
+	const relative = node_path.default.relative(root, child);
+	return relative === "" || !relative.startsWith("..") && !node_path.default.isAbsolute(relative);
+}
+/**
+* Translate a glob (the small subset used by `denyPaths` — `*`, `**`,
+* `?`) into an anchored `RegExp` over a `/`-separated relative path.
+* `**` spans path separators; a single `*` does not.
+*/
+function globToRegExp$1(glob) {
+	let source = "";
+	for (let index = 0; index < glob.length; index++) {
+		const char = glob[index];
+		if (char === "*") {
+			if (glob[index + 1] === "*") {
+				source += ".*";
+				index++;
+				if (glob[index + 1] === "/") index++;
+			} else source += "[^/]*";
+			continue;
+		}
+		if (char === "?") {
+			source += "[^/]";
+			continue;
+		}
+		source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${source}$`);
+}
+/**
+* Whether a workspace-relative (`/`-separated) path matches any of the
+* policy's `denyPaths` globs. A deny glob also blocks everything beneath
+* a matched directory (`".git/**"` blocks `.git/config`).
+*/
+function matchesDeny(relativePath, denyPaths) {
+	return denyPaths.some((glob) => {
+		if (globToRegExp$1(glob).test(relativePath)) return true;
+		if (!glob.includes("*") && !glob.includes("?")) {
+			const prefix = glob.endsWith("/") ? glob : `${glob}/`;
+			return relativePath.startsWith(prefix);
+		}
+		return false;
+	});
+}
+/**
+* Resolve and jail a single input path against a {@link WorkspacePolicy}.
+*
+* The input is resolved against `policy.cwd`, canonicalized (symlinks in
+* existing ancestors collapsed so a symlinked directory cannot escape
+* the jail), then accepted **only** when it sits under `cwd` or one of
+* the `allowPaths` roots. A path that escapes, or that matches any
+* `denyPaths` glob even while inside `cwd`, is rejected with a
+* {@link WorkspacePolicyError} of type `"path-escape"`.
+*
+* @param policy - The bounding policy (its `cwd` is the jail root).
+* @param inputPath - A workspace-relative or absolute path to resolve.
+* @returns The canonical absolute path plus its `/`-separated relative form.
+* @throws {WorkspacePolicyError} When the path escapes the jail or hits a deny glob.
+*
+* @example
+* const { absolutePath } = await resolveInJail(policy, "src/index.ts");
+*/
+async function resolveInJail(policy, inputPath) {
+	const jailRoot = await canonicalize$1(policy.cwd);
+	const absolutePath = await canonicalize$1(node_path.default.isAbsolute(inputPath) ? inputPath : node_path.default.join(policy.cwd, inputPath));
+	const insideCwd = isInside(absolutePath, jailRoot);
+	const allowRoots = policy.allowPaths ?? [];
+	let insideAllow = false;
+	if (!insideCwd) {
+		for (const root of allowRoots) if (isInside(absolutePath, await canonicalize$1(root))) {
+			insideAllow = true;
+			break;
+		}
+	}
+	if (!insideCwd && !insideAllow) throw new WorkspacePolicyError(`Path "${inputPath}" resolves outside the workspace jail.`, {
+		type: "path-escape",
+		path: inputPath
+	});
+	const relativeToJail = insideCwd ? node_path.default.relative(jailRoot, absolutePath).split(node_path.default.sep).join("/") : "";
+	if (insideCwd && policy.denyPaths && policy.denyPaths.length > 0) {
+		if (matchesDeny(relativeToJail, policy.denyPaths)) throw new WorkspacePolicyError(`Path "${inputPath}" is blocked by the workspace deny list.`, {
+			type: "path-escape",
+			path: inputPath
+		});
+	}
+	return {
+		absolutePath,
+		relativePath: relativeToJail
+	};
+}
+/**
+* Extract the leading executable basename from a command line — the
+* token the shell allow/deny policy is keyed on. `"npm run build"` →
+* `"npm"`; `"/usr/bin/node app.js"` → `"node"`; `"node.exe app"` →
+* `"node"` (the `.exe`/`.cmd`/`.bat` Windows extension is stripped).
+*/
+function leadingExecutable(command) {
+	const firstToken = command.trim().split(/\s+/)[0] ?? "";
+	return node_path.default.basename(firstToken).replace(/\.(exe|cmd|bat|com)$/i, "");
+}
+/**
+* Whether a shell command is permitted by the policy's `shell` sub-policy.
+*
+* The command's leading executable basename is matched against
+* `shell.deny` then `shell.allow`. **Deny always wins.** When
+* `shell.allow` is set, the executable MUST appear in it (fail-closed
+* allowlist); when `allow` is absent/empty, any non-denied command is
+* permitted. An absent `shell` block means no command may run at all.
+*
+* Returns a plain `boolean` rather than throwing — the ops layer raises
+* the {@link WorkspacePolicyError} so the thrown context (`command`)
+* lives next to the call site.
+*
+* @example
+* isCommandAllowed({ cwd, shell: { allow: ["npm"] } }, "npm test"); // true
+* isCommandAllowed({ cwd, shell: { allow: ["npm"] } }, "rm -rf /"); // false
+*/
+function isCommandAllowed(policy, command) {
+	const shell = policy.shell;
+	if (!shell) return false;
+	const executable = leadingExecutable(command);
+	if (executable === "") return false;
+	if (shell.deny && shell.deny.includes(executable)) return false;
+	if (shell.allow && shell.allow.length > 0) return shell.allow.includes(executable);
+	return true;
+}
+/**
+* Build the exact environment a spawned process receives — `process.env`
+* is **never** inherited wholesale. The result is
+* `{ ...pick(process.env, inheritEnv), ...shell.env }`, so a command
+* cannot see `PATH` (and thus often cannot find `node`/`npm`) unless the
+* policy opts in via `shell.inheritEnv: ["PATH"]`. Explicit `shell.env`
+* values override inherited ones on key collision.
+*
+* @example
+* buildEnv({ cwd, shell: { inheritEnv: ["PATH"], env: { CI: "1" } } });
+* // → { PATH: <process PATH>, CI: "1" }
+*/
+function buildEnv(policy) {
+	const shell = policy.shell;
+	const env = {};
+	if (!shell) return env;
+	for (const key of shell.inheritEnv ?? []) {
+		const value = process.env[key];
+		if (value !== void 0) env[key] = value;
+	}
+	if (shell.env) for (const [key, value] of Object.entries(shell.env)) env[key] = value;
+	return env;
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/ops.ts
+/** Default line window a read returns when the policy sets no `defaultLines`. */
+const DEFAULT_READ_LINES = 2e3;
+/** Hard ceiling on grep matches returned, so a broad pattern can't flood. */
+const DEFAULT_MAX_GREP_MATCHES = 1e3;
+/** Default per-command output byte cap when the policy sets none. */
+const DEFAULT_MAX_OUTPUT_BYTES = 1e6;
+/**
+* Number the lines of `content` `cat -n` style: a right-aligned line
+* number (min width 6), a tab, then the line. `startLine` is the 1-based
+* number of the first line in the window.
+*/
+function numberLines(content, startLine) {
+	return content.split("\n").map((line, index) => {
+		const lineNumber = startLine + index;
+		return `${String(lineNumber).padStart(6, " ")}\t${line}`;
+	}).join("\n");
+}
+/**
+* Clip a captured stream at `maxBytes` (measured in UTF-8 bytes).
+* Returns the possibly-clipped string plus whether clipping occurred.
+*/
+function capOutput(value, maxBytes) {
+	const bytes = Buffer.from(value, "utf8");
+	if (bytes.byteLength <= maxBytes) return {
+		value,
+		truncated: false
+	};
+	return {
+		value: bytes.subarray(0, maxBytes).toString("utf8"),
+		truncated: true
+	};
+}
+/**
+* Minimal glob match over a `/`-separated relative path. Supports `**`
+* (spans separators), `*` (within a segment), and `?` (one non-separator
+* char) — enough for the workspace's `glob`/grep narrowing without
+* pulling in a runtime dependency.
+*/
+function globToRegExp(glob) {
+	let source = "";
+	for (let index = 0; index < glob.length; index++) {
+		const char = glob[index];
+		if (char === "*") {
+			if (glob[index + 1] === "*") {
+				source += ".*";
+				index++;
+				if (glob[index + 1] === "/") index++;
+			} else source += "[^/]*";
+			continue;
+		}
+		if (char === "?") {
+			source += "[^/]";
+			continue;
+		}
+		source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${source}$`);
+}
+/**
+* The internal, single-instance implementation of {@link WorkspaceOps}.
+* Holds the backend + policy and is the one place the jail, command
+* gating, read caps, and the read-before-edit guard are enforced — both
+* the agent-facing tools and the human-facing direct methods funnel
+* through this object, so there is exactly one set of rules.
+*/
+var Ops = class {
+	constructor(backend, policy) {
+		this.backend = backend;
+		this.policy = policy;
+	}
+	/**
+	* Recursively collect every file under `absDir` as absolute paths,
+	* via the backend's `list` (so it works over disk or the in-memory
+	* mock). Directories are descended; files are accumulated.
+	*/
+	async walkFiles(absDir) {
+		const found = [];
+		const entries = await this.backend.list(absDir);
+		await Promise.all(entries.map(async (entry) => {
+			if (await this.isDirectory(entry)) {
+				const nested = await this.walkFiles(entry);
+				found.push(...nested);
+			} else found.push(entry);
+		}));
+		return found;
+	}
+	/** Whether an absolute path is a directory, by attempting to list it. */
+	async isDirectory(absPath) {
+		try {
+			await this.backend.list(absPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async readFile(inputPath, opts) {
+		const { absolutePath } = await resolveInJail(this.policy, inputPath);
+		const raw = await this.backend.readFile(absolutePath);
+		const hash = (0, _warlock_js_fs.hashString)(raw);
+		const lines = raw.split("\n");
+		const totalLines = lines.length;
+		const offset = Math.max(1, opts?.offset ?? 1);
+		const limit = opts?.limit ?? this.policy.read?.defaultLines ?? DEFAULT_READ_LINES;
+		const startIndex = offset - 1;
+		return {
+			content: numberLines(lines.slice(startIndex, startIndex + limit).join("\n"), offset),
+			hash,
+			totalLines
+		};
+	}
+	async writeFile(inputPath, content) {
+		const { absolutePath } = await resolveInJail(this.policy, inputPath);
+		const parent = node_path.default.dirname(absolutePath);
+		await this.backend.mkdir(parent);
+		await this.backend.writeFile(absolutePath, content);
+		return {
+			hash: (0, _warlock_js_fs.hashString)(content),
+			bytesWritten: Buffer.byteLength(content, "utf8")
+		};
+	}
+	async editFile(input) {
+		const { absolutePath, relativePath } = await resolveInJail(this.policy, input.path);
+		const current = await this.backend.readFile(absolutePath);
+		const currentHash = (0, _warlock_js_fs.hashString)(current);
+		if (input.expectHash !== void 0 && input.expectHash !== currentHash) throw new WorkspaceEditError(`File "${input.path}" changed since it was read; the edit is stale.`, {
+			type: "stale-hash",
+			path: relativePath || input.path,
+			expectedHash: input.expectHash,
+			actualHash: currentHash
+		});
+		const occurrences = countOccurrences(current, input.oldString);
+		if (occurrences === 0) throw new WorkspaceEditError(`The text to replace was not found in "${input.path}".`, {
+			type: "not-found",
+			path: relativePath || input.path,
+			matches: 0
+		});
+		if (occurrences > 1 && !input.replaceAll) throw new WorkspaceEditError(`The text to replace is not unique in "${input.path}" (${occurrences} matches); pass replaceAll or include more surrounding context.`, {
+			type: "not-unique",
+			path: relativePath || input.path,
+			matches: occurrences
+		});
+		const updated = input.replaceAll ? current.split(input.oldString).join(input.newString) : replaceFirst(current, input.oldString, input.newString);
+		await this.backend.writeFile(absolutePath, updated);
+		return {
+			path: relativePath || input.path,
+			replacements: input.replaceAll ? occurrences : 1,
+			hash: (0, _warlock_js_fs.hashString)(updated)
+		};
+	}
+	async exec(command, opts) {
+		if (!isCommandAllowed(this.policy, command)) throw new WorkspacePolicyError(`Command is not permitted by the workspace shell policy: ${command}`, {
+			type: "denied-command",
+			command
+		});
+		const shell = this.policy.shell;
+		const timeoutMs = opts?.timeoutMs ?? shell?.timeoutMs;
+		const maxOutputBytes = shell?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+		const result = await this.backend.exec(command, {
+			cwd: this.policy.cwd,
+			timeoutMs,
+			env: buildEnv(this.policy)
+		});
+		const stdout = capOutput(result.stdout, maxOutputBytes);
+		const stderr = capOutput(result.stderr, maxOutputBytes);
+		return {
+			exitCode: result.exitCode,
+			stdout: stdout.value,
+			stderr: stderr.value,
+			truncated: stdout.truncated || stderr.truncated,
+			timedOut: result.timedOut
+		};
+	}
+	async grep(pattern, opts) {
+		const { absolutePath: jailRoot } = await resolveInJail(this.policy, ".");
+		const flags = opts?.ignoreCase ? "i" : "";
+		const regex = new RegExp(pattern, flags);
+		const globRegex = opts?.glob ? globToRegExp(opts.glob) : void 0;
+		const files = await this.walkFiles(jailRoot);
+		const matches = [];
+		for (const absFile of files) {
+			const relativePath = node_path.default.relative(jailRoot, absFile).split(node_path.default.sep).join("/");
+			if (globRegex && !globRegex.test(relativePath)) continue;
+			if (this.isDenied(relativePath)) continue;
+			let content;
+			try {
+				content = await this.backend.readFile(absFile);
+			} catch {
+				continue;
+			}
+			const lines = content.split("\n");
+			for (let index = 0; index < lines.length; index++) if (regex.test(lines[index])) {
+				matches.push({
+					path: relativePath,
+					line: index + 1,
+					text: lines[index]
+				});
+				if (matches.length >= DEFAULT_MAX_GREP_MATCHES) return {
+					matches,
+					total: matches.length
+				};
+			}
+		}
+		return {
+			matches,
+			total: matches.length
+		};
+	}
+	async glob(pattern) {
+		const { absolutePath: jailRoot } = await resolveInJail(this.policy, ".");
+		const regex = globToRegExp(pattern);
+		const files = await this.walkFiles(jailRoot);
+		const matched = [];
+		for (const absFile of files) {
+			const relativePath = node_path.default.relative(jailRoot, absFile).split(node_path.default.sep).join("/");
+			if (this.isDenied(relativePath)) continue;
+			if (regex.test(relativePath)) matched.push(relativePath);
+		}
+		return matched.sort();
+	}
+	async exists(inputPath) {
+		const { absolutePath } = await resolveInJail(this.policy, inputPath);
+		return this.backend.exists(absolutePath);
+	}
+	async mkdir(inputPath) {
+		const { absolutePath } = await resolveInJail(this.policy, inputPath);
+		await this.backend.mkdir(absolutePath);
+	}
+	async remove(inputPath) {
+		const { absolutePath } = await resolveInJail(this.policy, inputPath);
+		await this.backend.remove(absolutePath);
+	}
+	/** Whether a `/`-separated relative path hits the policy deny list. */
+	isDenied(relativePath) {
+		const denyPaths = this.policy.denyPaths;
+		if (!denyPaths || denyPaths.length === 0) return false;
+		return denyPaths.some((glob) => {
+			if (globToRegExp(glob).test(relativePath)) return true;
+			if (!glob.includes("*") && !glob.includes("?")) {
+				const prefix = glob.endsWith("/") ? glob : `${glob}/`;
+				return relativePath.startsWith(prefix);
+			}
+			return false;
+		});
+	}
+};
+/** Count non-overlapping occurrences of `needle` in `haystack`. */
+function countOccurrences(haystack, needle) {
+	if (needle === "") return 0;
+	let count = 0;
+	let from = 0;
+	while (true) {
+		const index = haystack.indexOf(needle, from);
+		if (index === -1) break;
+		count++;
+		from = index + needle.length;
+	}
+	return count;
+}
+/** Replace the first occurrence of `needle` with `replacement`. */
+function replaceFirst(haystack, needle, replacement) {
+	const index = haystack.indexOf(needle);
+	if (index === -1) return haystack;
+	return haystack.slice(0, index) + replacement + haystack.slice(index + needle.length);
+}
+/**
+* Create the policy-enforced operation layer over a backend.
+*
+* The returned {@link WorkspaceOps} is the single seam both the
+* agent-facing `.tools.*` factories and the human-facing direct methods
+* delegate to — one jail, one command-gate, one read-before-edit guard,
+* regardless of caller. Path inputs are workspace-relative and resolved
+* against `policy.cwd`; escapes and denied commands surface as typed
+* {@link WorkspacePolicyError} / {@link WorkspaceEditError}.
+*
+* @param backend - The dumb IO executor (local disk or in-memory mock).
+* @param policy - The policy that bounds every operation.
+*
+* @example
+* const ops = createOps(localBackend, { cwd: "/srv/api", shell: { allow: ["npm"] } });
+* const { content, hash } = await ops.readFile("src/index.ts");
+*/
+function createOps(backend, policy) {
+	return new Ops(backend, policy);
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/backends/local.ts
+/**
+* Hard ceiling on captured `stdout`/`stderr` per stream, in bytes. The raw
+* executor truncates each stream once this many bytes have accumulated so a
+* runaway command cannot exhaust memory; the ops layer applies its own
+* policy-driven cap (and the `truncated` flag) on top. Generous enough that
+* ordinary command output is never clipped here.
+*/
+const MAX_STREAM_BYTES = 10 * 1024 * 1024;
+/**
+* Append a chunk to a capped list of buffers, tracking the running byte
+* total and stopping once {@link MAX_STREAM_BYTES} is reached. Trailing bytes
+* past the cap are dropped rather than buffered.
+*/
+function pushCapped(chunks, total, chunk) {
+	if (total >= MAX_STREAM_BYTES) return total;
+	const remaining = MAX_STREAM_BYTES - total;
+	if (chunk.length <= remaining) {
+		chunks.push(chunk);
+		return total + chunk.length;
+	}
+	chunks.push(chunk.subarray(0, remaining));
+	return MAX_STREAM_BYTES;
+}
+/**
+* Force-kill a spawned command and its entire process tree.
+*
+* With `shell: true` the command runs under an intermediary shell
+* (`cmd.exe` on Windows, `/bin/sh` elsewhere), so signalling the direct
+* child only reaps the shell — a long-running grandchild (e.g. `node`)
+* would survive, leaving the `exec` promise unsettled. We therefore kill
+* the whole group:
+*   - **Windows** — `taskkill /T /F` walks and terminates the PID's tree.
+*   - **POSIX** — the child is spawned `detached`, becoming its own process
+*     group leader, so `process.kill(-pid)` SIGKILLs the group.
+*/
+function killTree(pid, child) {
+	if (pid === void 0) {
+		child.kill("SIGKILL");
+		return;
+	}
+	if (node_process.platform === "win32") {
+		(0, node_child_process.spawn)("taskkill", [
+			"/pid",
+			String(pid),
+			"/T",
+			"/F"
+		], { windowsHide: true });
+		return;
+	}
+	try {
+		process.kill(-pid, "SIGKILL");
+	} catch {
+		child.kill("SIGKILL");
+	}
+}
+/**
+* The real-disk executor: every filesystem method delegates to
+* `@warlock.js/fs` (never `node:fs`), and {@link LocalBackend.exec} spawns a
+* process via `node:child_process`. It is deliberately **policy-agnostic** —
+* it receives already-resolved absolute paths and an already-resolved
+* environment + timeout from the ops layer, and just performs the side
+* effect. See {@link WorkspaceBackend} for the contract this implements.
+*
+* Constructed via {@link createLocalBackend}; the class itself is internal.
+*/
+var LocalBackend = class {
+	/** Read a file's full UTF-8 content at an absolute path. */
+	async readFile(absPath) {
+		return (0, _warlock_js_fs.getFileAsync)(absPath);
+	}
+	/**
+	* Write full content to an absolute path. Uses `atomicWriteAsync`, so a
+	* concurrent reader never observes a half-written file, and missing parent
+	* directories are created.
+	*/
+	async writeFile(absPath, content) {
+		await (0, _warlock_js_fs.atomicWriteAsync)(absPath, content);
+	}
+	/** Whether anything (file or directory) exists at an absolute path. */
+	async exists(absPath) {
+		return (0, _warlock_js_fs.pathExistsAsync)(absPath);
+	}
+	/** Create a directory (and any missing parents) at an absolute path; idempotent. */
+	async mkdir(absPath) {
+		await (0, _warlock_js_fs.ensureDirectoryAsync)(absPath);
+	}
+	/**
+	* Remove a file or directory tree at an absolute path. Stats the target to
+	* pick the right primitive — `removeDirectoryAsync` (recursive) for a
+	* directory, `unlinkAsync` for anything else. A path that does not exist is
+	* a no-op (both primitives swallow `ENOENT`).
+	*/
+	async remove(absPath) {
+		let isDirectory = false;
+		try {
+			isDirectory = (await (0, _warlock_js_fs.statsAsync)(absPath)).isDirectory();
+		} catch (error) {
+			if (error?.code === "ENOENT") return;
+			throw error;
+		}
+		if (isDirectory) {
+			await (0, _warlock_js_fs.removeDirectoryAsync)(absPath);
+			return;
+		}
+		await (0, _warlock_js_fs.unlinkAsync)(absPath);
+	}
+	/** List immediate children of an absolute directory as absolute paths. */
+	async list(absDir) {
+		return (0, _warlock_js_fs.listAsync)(absDir);
+	}
+	/**
+	* Resolve symlinks and `..` segments to a canonical absolute path — the
+	* primitive the ops-layer jail uses to detect escapes. Delegates to
+	* `node:fs/promises` `realpath`, the one filesystem operation `@warlock.js/fs`
+	* does not expose.
+	*/
+	async realpath(absPath) {
+		return (0, node_fs_promises.realpath)(absPath);
+	}
+	/**
+	* Run a command and capture its outcome. The command line is executed
+	* through the platform shell (`shell: true`) so pipes/operators behave as a
+	* caller would expect; `cwd`, `env`, and the timeout are taken verbatim from
+	* the ops layer (the environment is NOT merged with `process.env`). On
+	* timeout the process is SIGKILLed and `timedOut` is set. `stdout`/`stderr`
+	* are captured and byte-capped per {@link MAX_STREAM_BYTES}.
+	*
+	* Never rejects for a non-zero exit, a missing executable, or a timeout —
+	* those are reported through the resolved {@link WorkspaceBackendExecResult}
+	* so the ops layer can surface them as tool-error data.
+	*/
+	exec(command, opts = {}) {
+		return new Promise((resolve) => {
+			const child = (0, node_child_process.spawn)(command, {
+				cwd: opts.cwd,
+				env: opts.env,
+				shell: true,
+				windowsHide: true,
+				detached: node_process.platform !== "win32"
+			});
+			const stdoutChunks = [];
+			const stderrChunks = [];
+			let stdoutBytes = 0;
+			let stderrBytes = 0;
+			let timedOut = false;
+			let settled = false;
+			const timer = opts.timeoutMs !== void 0 && opts.timeoutMs > 0 ? setTimeout(() => {
+				timedOut = true;
+				killTree(child.pid, child);
+			}, opts.timeoutMs) : void 0;
+			const settle = (exitCode) => {
+				if (settled) return;
+				settled = true;
+				if (timer !== void 0) clearTimeout(timer);
+				resolve({
+					exitCode,
+					stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+					stderr: Buffer.concat(stderrChunks).toString("utf8"),
+					timedOut
+				});
+			};
+			child.stdout?.on("data", (chunk) => {
+				stdoutBytes = pushCapped(stdoutChunks, stdoutBytes, chunk);
+			});
+			child.stderr?.on("data", (chunk) => {
+				stderrBytes = pushCapped(stderrChunks, stderrBytes, chunk);
+			});
+			child.on("error", () => {
+				settle(127);
+			});
+			child.on("close", (code, signal) => {
+				if (code === null) {
+					settle(128 + (signal === "SIGKILL" ? 9 : 1));
+					return;
+				}
+				settle(code);
+			});
+		});
+	}
+};
+/**
+* Create the **local** workspace backend — the default executor that runs the
+* workspace over the real disk (`@warlock.js/fs`) and the local shell
+* (`node:child_process`).
+*
+* The returned object is policy-agnostic: it expects already-jail-resolved
+* absolute paths and an already-resolved environment/timeout from the ops
+* layer. Pair it with {@link WorkspaceOps} for the actual cwd jail,
+* allow/deny lists, hashing, and output policy.
+*
+* @example
+* const backend = createLocalBackend();
+* await backend.writeFile("/srv/app/src/index.ts", "export const x = 1;");
+* const { exitCode } = await backend.exec("node -v", { cwd: "/srv/app" });
+*/
+function createLocalBackend() {
+	return new LocalBackend();
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/backends/mock.ts
+/**
+* Normalize an absolute path to a stable in-memory key: forward slashes,
+* collapsed duplicate separators, and resolved `.` / `..` segments. There
+* are no symlinks in memory, so this is a pure lexical canonicalization —
+* exactly what the backend's `realpath` promises.
+*/
+function canonicalize(absPath) {
+	const unified = absPath.replace(/\\/g, "/");
+	const driveMatch = unified.match(/^([a-zA-Z]:)?\/?/);
+	const prefix = driveMatch ? driveMatch[0] : "";
+	const rest = unified.slice(prefix.length);
+	const resolved = [];
+	for (const segment of rest.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			resolved.pop();
+			continue;
+		}
+		resolved.push(segment);
+	}
+	const joined = resolved.join("/");
+	const normalizedPrefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
+	return joined.length > 0 ? `${normalizedPrefix}${joined}` : normalizedPrefix;
+}
+/** All ancestor directory keys of a canonical path, root-first. */
+function ancestorsOf(canonicalPath) {
+	const lastSlash = canonicalPath.lastIndexOf("/");
+	if (lastSlash <= 0) return [];
+	const parent = canonicalPath.slice(0, lastSlash);
+	const result = ancestorsOf(parent);
+	result.push(parent);
+	return result;
+}
+/**
+* The in-memory executor behind {@link createMockBackend}. Holds the file
+* tree in a `Map`, the directory set in a `Set`, and the scripted command
+* table in a second `Map` — no disk, no child processes, fully
+* deterministic. Construct it via the factory, never directly.
+*/
+var MockBackend = class {
+	constructor(seed) {
+		this.files = /* @__PURE__ */ new Map();
+		this.directories = /* @__PURE__ */ new Set();
+		this.commands = /* @__PURE__ */ new Map();
+		for (const [path, content] of Object.entries(seed?.files ?? {})) {
+			const canonical = canonicalize(path);
+			this.files.set(canonical, content);
+			this.registerAncestorDirectories(canonical);
+		}
+		for (const [command, result] of Object.entries(seed?.commands ?? {})) this.commands.set(command, result);
+	}
+	/** Record every ancestor directory of a path as existing. */
+	registerAncestorDirectories(canonicalPath) {
+		for (const ancestor of ancestorsOf(canonicalPath)) this.directories.add(ancestor);
+	}
+	async readFile(absPath) {
+		const canonical = canonicalize(absPath);
+		const content = this.files.get(canonical);
+		if (content === void 0) throw new Error(`Mock backend: no such file: ${canonical}`);
+		return content;
+	}
+	async writeFile(absPath, content) {
+		const canonical = canonicalize(absPath);
+		this.files.set(canonical, content);
+		this.registerAncestorDirectories(canonical);
+	}
+	async exists(absPath) {
+		const canonical = canonicalize(absPath);
+		return this.files.has(canonical) || this.directories.has(canonical);
+	}
+	async mkdir(absPath) {
+		const canonical = canonicalize(absPath);
+		this.directories.add(canonical);
+		this.registerAncestorDirectories(canonical);
+	}
+	async remove(absPath) {
+		const canonical = canonicalize(absPath);
+		const prefix = `${canonical}/`;
+		for (const file of [...this.files.keys()]) if (file === canonical || file.startsWith(prefix)) this.files.delete(file);
+		for (const directory of [...this.directories]) if (directory === canonical || directory.startsWith(prefix)) this.directories.delete(directory);
+	}
+	async list(absDir) {
+		const canonical = canonicalize(absDir);
+		const prefix = canonical === "/" ? "/" : `${canonical}/`;
+		const children = /* @__PURE__ */ new Set();
+		const collect = (key) => {
+			if (!key.startsWith(prefix) || key === canonical) return;
+			const remainder = key.slice(prefix.length);
+			const nextSlash = remainder.indexOf("/");
+			const childName = nextSlash === -1 ? remainder : remainder.slice(0, nextSlash);
+			if (childName.length > 0) children.add(`${prefix}${childName}`);
+		};
+		for (const file of this.files.keys()) collect(file);
+		for (const directory of this.directories) collect(directory);
+		return [...children].sort();
+	}
+	async realpath(absPath) {
+		return canonicalize(absPath);
+	}
+	async exec(command, _opts) {
+		const scripted = this.commands.get(command);
+		return {
+			exitCode: scripted?.exitCode ?? 0,
+			stdout: scripted?.stdout ?? "",
+			stderr: scripted?.stderr ?? "",
+			timedOut: scripted?.timedOut ?? false
+		};
+	}
+};
+/**
+* Create an in-memory {@link WorkspaceBackend} for fast, disk-free tests.
+*
+* Every IO method operates on a `Map` of `absolutePath -> content` (with a
+* companion directory set), so reads, writes, existence checks, `mkdir`,
+* recursive `remove`, `list`, and `realpath` all run synchronously in
+* memory with no filesystem access. `exec` is **scripted**: a registered
+* `command -> result` table is consulted by exact command line, and any
+* unregistered command resolves to a successful `0`-exit no-op with empty
+* output.
+*
+* `realpath` is a pure lexical canonicalization (forward slashes,
+* collapsed separators, resolved `.`/`..`) — there are no symlinks in
+* memory — which is exactly what the jail resolver expects.
+*
+* The single positional `seed` accepts either the shorthand
+* `Record<string, string>` of file contents (matching the design's
+* `ai.workspace.mock(seed)` signature) or the richer {@link MockBackendSeed}
+* with both `files` and scripted `commands`.
+*
+* @example
+* // Shorthand: seed files only.
+* const backend = createMockBackend({ "/srv/app/src/index.ts": "export const x = 1;" });
+* await backend.readFile("/srv/app/src/index.ts"); // "export const x = 1;"
+*
+* @example
+* // Full seed: files plus a scripted command.
+* const backend = createMockBackend({
+*   files: { "/srv/app/package.json": "{}" },
+*   commands: { "npm test": { exitCode: 1, stderr: "1 failing" } },
+* });
+* await backend.exec("npm test");   // { exitCode: 1, stderr: "1 failing", ... }
+* await backend.exec("echo hi");    // { exitCode: 0, stdout: "", ... } (no-op)
+*/
+function createMockBackend(seed) {
+	return new MockBackend(normalizeSeed(seed));
+}
+/** Coerce the dual-shaped `seed` argument into a {@link MockBackendSeed}. */
+function normalizeSeed(seed) {
+	if (seed === void 0) return;
+	if (isMockBackendSeed(seed)) return seed;
+	return { files: seed };
+}
+/**
+* Whether `seed` is the structured {@link MockBackendSeed} (has a `files`
+* or `commands` key) rather than the flat `path -> content` shorthand. A
+* plain shorthand map whose only key happens to be named `files` is
+* treated as structured — callers wanting that literal path should use the
+* explicit `{ files: { files: "..." } }` form.
+*/
+function isMockBackendSeed(seed) {
+	return typeof seed.files === "object" || typeof seed.commands === "object";
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/tools/schema.ts
+/**
+* Tiny, dependency-free [Standard Schema](https://standardschema.dev)
+* builders for the workspace tools' input validation. The package pins
+* only `@warlock.js/ai` and `@warlock.js/fs` as runtime dependencies, so
+* rather than pull in a schema library we hand-roll the few shapes the
+* file tools need — exactly the pattern `@warlock.js/ai`'s own `tool()`
+* tests use. Each builder returns a `StandardSchemaV1`, which is what
+* `tool({ input })` validates against before calling `execute`.
+*
+* These intentionally cover only the primitive cases the FILE tools
+* require (`string`, `optional string`, `optional number`, `optional
+* boolean`, and an `object` of fields). They are not a general-purpose
+* validator.
+*/
+/** The vendor tag stamped on every issue these builders produce. */
+const VENDOR = "ai-workspace";
+/** Required string field — rejects anything that is not a string. */
+function stringField() {
+	return (value, key) => {
+		if (typeof value === "string") return { value };
+		return { issues: [{
+			message: `"${key}" must be a string`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional string field — accepts `undefined` (the property absent or
+* explicitly undefined) or a string, and rejects every other type.
+*/
+function optionalStringField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "string") return { value };
+		return { issues: [{
+			message: `"${key}" must be a string when provided`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional finite-number field — accepts `undefined` or a finite number,
+* rejecting `NaN`/`Infinity` and non-number types.
+*/
+function optionalNumberField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "number" && Number.isFinite(value)) return { value };
+		return { issues: [{
+			message: `"${key}" must be a finite number when provided`,
+			path: [key]
+		}] };
+	};
+}
+/** Optional boolean field — accepts `undefined` or a boolean. */
+function optionalBooleanField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "boolean") return { value };
+		return { issues: [{
+			message: `"${key}" must be a boolean when provided`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Build a {@link StandardSchemaV1} for a flat object whose every property
+* is validated by a {@link FieldValidator}. The input must be a non-null
+* object; each declared field is validated and the (possibly coerced)
+* values are collected into the typed result. All field issues are merged
+* so the caller sees every problem at once.
+*
+* `T` is constrained to `object` rather than `Record<string, unknown>` so
+* the tool IO `interface`s (which carry no implicit string index
+* signature) satisfy it directly — only the declared keys in `shape` are
+* ever read, so a string index signature is never required.
+*
+* @example
+* const schema = objectSchema<{ path: string; limit?: number }>({
+*   path: stringField(),
+*   limit: optionalNumberField(),
+* });
+*/
+function objectSchema(shape) {
+	return { "~standard": {
+		version: 1,
+		vendor: VENDOR,
+		validate(input) {
+			if (typeof input !== "object" || input === null || Array.isArray(input)) return { issues: [{ message: "input must be an object" }] };
+			const source = input;
+			const issues = [];
+			const result = {};
+			for (const key of Object.keys(shape)) {
+				const field = shape[key];
+				const outcome = field(source[key], key);
+				if ("issues" in outcome) {
+					issues.push(...outcome.issues);
+					continue;
+				}
+				if (outcome.value !== void 0) result[key] = outcome.value;
+			}
+			if (issues.length > 0) return { issues };
+			return { value: result };
+		}
+	} };
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/tools/edit-file.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$2 = "edit_file";
+/** Input schema for the `edit_file` tool. */
+const inputSchema$2 = objectSchema({
+	path: stringField(),
+	oldString: stringField(),
+	newString: stringField(),
+	replaceAll: optionalBooleanField(),
+	expectHash: optionalStringField()
+});
+/**
+* Build the agent-facing `edit_file` tool over a workspace's policy-
+* enforced {@link WorkspaceOps}.
+*
+* The tool validates `{ path, oldString, newString, replaceAll?,
+* expectHash? }` against a Standard Schema, then delegates to
+* `ops.editFile`, which applies the exact-string replacement under the
+* read-before-edit guard and returns the replacement count plus the
+* post-edit `hash`.
+*
+* **Errors flow as data.** A non-unique `oldString` (without
+* `replaceAll`), a missing `oldString`, or a stale `expectHash` cause
+* `ops` to throw a `WorkspaceEditError`; the `tool()` wrapper catches it
+* and surfaces it in the returned `{ error }` field — `invoke()` never
+* throws — so the agent can re-read and retry.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const editTool = makeEditFileTool(ops);
+* const { data, error } = await editTool.invoke({
+*   path: "src/index.ts",
+*   oldString: "const a = 1;",
+*   newString: "const a = 2;",
+*   expectHash,
+* });
+* if (error) console.warn(error.message); // e.g. stale-hash → re-read
+*/
+function makeEditFileTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$2,
+		description: "Replace an exact substring in a workspace file. oldString must match uniquely unless replaceAll is set. Pass expectHash (from read_file) to reject the edit if the file changed since you read it. Returns the number of replacements and the new content hash.",
+		input: inputSchema$2,
+		async execute(input) {
+			return ops.editFile(input);
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/tools/glob.ts
+/**
+* Standard Schema for {@link GlobInput} — a single required `pattern`
+* string. Built on the package's shared, dependency-free schema builders
+* (no schema library, matching the validator idiom the `@warlock.js/ai`
+* tool runtime expects).
+*/
+const globInputSchema = objectSchema({ pattern: stringField() });
+/**
+* Build the agent-facing `glob` tool — resolve a glob pattern to the
+* matching workspace-relative paths within the jail. The returned
+* {@link ToolContract} validates the LLM's arguments, delegates to
+* {@link WorkspaceOps.glob} (which returns a bare sorted `string[]`), and
+* wraps the result in a {@link GlobResult} so the agent always reads a
+* stable `{ paths }` envelope. The jail and `denyPaths` filtering are
+* enforced in the shared ops layer; a policy violation surfaces as typed
+* tool-error *data* via the runtime's `invoke()` wrapper.
+*
+* @param ops - The policy-enforced operation layer to delegate to.
+* @param options - Optional `{ name }` override for the vended tool name.
+* @returns A {@link ToolContract} the agent can call as `glob`.
+*
+* @example
+* const glob = makeGlobTool(ops);
+* const { data } = await glob.invoke({ pattern: "src/models/**\/*.ts" });
+* console.log(data?.paths);
+*/
+function makeGlobTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? "glob",
+		description: "Find files in the workspace whose path matches a glob pattern (supports `*`, `**`, and `?`). Returns the matching workspace-relative paths, sorted.",
+		action: (input) => `Finding files matching ${input.pattern}`,
+		input: globInputSchema,
+		async execute(input) {
+			return { paths: await ops.glob(input.pattern) };
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/tools/grep.ts
+/**
+* Standard Schema for {@link GrepInput} — `pattern` is a required string;
+* `glob` and `ignoreCase` are optional. Built on the package's shared,
+* dependency-free schema builders (no schema library, matching the
+* validator idiom the `@warlock.js/ai` tool runtime expects).
+*/
+const grepInputSchema = objectSchema({
+	pattern: stringField(),
+	glob: optionalStringField(),
+	ignoreCase: optionalBooleanField()
+});
+/**
+* Build the agent-facing `grep` tool — a regex content search across the
+* jailed file set. The returned {@link ToolContract} validates the LLM's
+* arguments, then delegates verbatim to {@link WorkspaceOps.grep}, so the
+* policy jail, `denyPaths` filtering, and match cap are enforced in the
+* single shared ops layer rather than duplicated here. A policy violation
+* (e.g. a jail-resolution failure) surfaces as typed tool-error *data*
+* via the runtime's `invoke()` wrapper, never as a thrown run-killer.
+*
+* @param ops - The policy-enforced operation layer to delegate to.
+* @param options - Optional `{ name }` override for the vended tool name.
+* @returns A {@link ToolContract} the agent can call as `grep`.
+*
+* @example
+* const grep = makeGrepTool(ops);
+* const { data } = await grep.invoke({ pattern: "TODO", glob: "src/*.ts" });
+* console.log(data?.total, data?.matches);
+*/
+function makeGrepTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? "grep",
+		description: "Search file contents across the workspace for a regular-expression pattern. Optionally narrow the scanned files with a glob and match case-insensitively. Returns every matching line with its file path and 1-based line number.",
+		action: (input) => `Searching for /${input.pattern}/`,
+		input: grepInputSchema,
+		async execute(input) {
+			return ops.grep(input.pattern, {
+				glob: input.glob,
+				ignoreCase: input.ignoreCase
+			});
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/tools/read-file.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME$1 = "read_file";
+/** Input schema for the `read_file` tool. */
+const inputSchema$1 = objectSchema({
+	path: stringField(),
+	startLine: optionalNumberField(),
+	limit: optionalNumberField()
+});
+/**
+* Build the agent-facing `read_file` tool over a workspace's policy-
+* enforced {@link WorkspaceOps}.
+*
+* The tool validates `{ path, startLine?, limit? }` against a Standard
+* Schema, then delegates to `ops.readFile`, mapping the result into the
+* agent wire shape {@link ReadFileResult} — the `hash` an agent must
+* carry into a later `edit_file` (read-before-edit), plus the `startLine`
+* / `endLine` / `truncated` window metadata derived from the requested
+* range and the file's `totalLines`.
+*
+* **Errors flow as data.** Policy violations (a jail escape) are thrown
+* by `ops`; the `tool()` wrapper catches them and surfaces them in the
+* returned `{ error }` field — `invoke()` never throws — so the agent can
+* read the failure and self-correct.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const readTool = makeReadFileTool(ops);
+* const { data, error } = await readTool.invoke({ path: "src/index.ts" });
+* if (!error) console.log(data.hash); // feed into edit_file's expectHash
+*/
+function makeReadFileTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME$1,
+		description: "Read a file from the workspace, returning a numbered line window plus the file's content hash. Pass the hash to edit_file's expectHash to guard against editing a stale version. Use startLine/limit to page through large files.",
+		input: inputSchema$1,
+		async execute(input) {
+			const startLine = input.startLine !== void 0 ? Math.max(1, input.startLine) : 1;
+			const { content, hash, totalLines } = await ops.readFile(input.path, {
+				offset: startLine,
+				limit: input.limit
+			});
+			const returnedLines = content.length === 0 ? 0 : content.split("\n").length;
+			const endLine = Math.min(totalLines, startLine + Math.max(returnedLines, 1) - 1);
+			return {
+				content,
+				startLine,
+				endLine,
+				totalLines,
+				truncated: endLine < totalLines,
+				hash
+			};
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/tools/run-shell.ts
+/** The default tool name `run_shell` is exposed to the LLM under. */
+const DEFAULT_RUN_SHELL_TOOL_NAME = "run_shell";
+/**
+* Hand-rolled Standard Schema for {@link RunShellInput}. We validate the
+* model's arguments without a runtime schema dependency: `command` must be
+* a non-empty string, and `timeoutMs` (when present) a positive number.
+* Invalid args surface as a `SchemaValidationError` in the tool result's
+* `error` field rather than reaching `ops.exec`.
+*/
+const runShellInputSchema = { "~standard": {
+	version: 1,
+	vendor: "@warlock.js/ai-workspace",
+	validate: (value) => {
+		if (typeof value !== "object" || value === null) return { issues: [{ message: "expected an object" }] };
+		const candidate = value;
+		if (typeof candidate.command !== "string" || candidate.command.length === 0) return { issues: [{
+			message: "command must be a non-empty string",
+			path: ["command"]
+		}] };
+		if (candidate.timeoutMs !== void 0 && (typeof candidate.timeoutMs !== "number" || candidate.timeoutMs <= 0)) return { issues: [{
+			message: "timeoutMs must be a positive number",
+			path: ["timeoutMs"]
+		}] };
+		const result = { command: candidate.command };
+		if (candidate.timeoutMs !== void 0) result.timeoutMs = candidate.timeoutMs;
+		return { value: result };
+	}
+} };
+/**
+* Build the `run_shell` tool — a {@link ToolContract} that runs a single
+* shell command through the policy-enforced {@link WorkspaceOps} layer.
+*
+* The command's leading executable basename is gated against the shell
+* allow/deny policy by `ops.exec`; a blocked command throws a
+* `WorkspacePolicyError` which the `tool()` runtime catches and surfaces
+* in the result's `error` field (never a thrown run-killer), so the agent
+* reads the refusal as tool data and self-corrects. A command that runs
+* but exits non-zero is *not* an error — its `exitCode`/`stderr` come back
+* in `data` for the agent to inspect.
+*
+* @param ops - The policy-enforced operation layer to delegate `exec` to.
+* @param options - Optional tool-name override.
+*
+* @example
+* const runShell = makeRunShellTool(ops);
+* const { data, error } = await runShell.invoke({ command: "npm run build" });
+* if (error) handleDenied(error);
+* else console.log(data.exitCode, data.stdout);
+*/
+function makeRunShellTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_RUN_SHELL_TOOL_NAME,
+		description: "Run a single shell command inside the workspace. The command's executable must be permitted by the shell policy; output is byte-capped and the run is time-limited. A non-zero exit code is returned as data, not an error.",
+		action: (input) => `Running \`${input.command}\``,
+		input: runShellInputSchema,
+		execute: (input) => ops.exec(input.command, { timeoutMs: input.timeoutMs })
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/tools/run-tests.ts
+/** The default tool name `run_tests` is exposed to the LLM under. */
+const DEFAULT_RUN_TESTS_TOOL_NAME = "run_tests";
+/** The default command run when no `command` override is configured. */
+const DEFAULT_TEST_COMMAND = "npm test";
+/**
+* Hand-rolled Standard Schema for {@link RunTestsInput}. `pattern` is the
+* only field and is optional; when present it must be a string. Validation
+* happens without a runtime schema dependency, mirroring the wider tool
+* layer.
+*/
+const runTestsInputSchema = { "~standard": {
+	version: 1,
+	vendor: "@warlock.js/ai-workspace",
+	validate: (value) => {
+		if (value === void 0 || value === null) return { value: {} };
+		if (typeof value !== "object") return { issues: [{ message: "expected an object" }] };
+		const candidate = value;
+		if (candidate.pattern !== void 0 && typeof candidate.pattern !== "string") return { issues: [{
+			message: "pattern must be a string",
+			path: ["pattern"]
+		}] };
+		const result = {};
+		if (candidate.pattern !== void 0) result.pattern = candidate.pattern;
+		return { value: result };
+	}
+} };
+/**
+* Build the `run_tests` tool — a {@link ToolContract} convenience over
+* `run_shell` that runs the workspace's configured test command through
+* the policy-enforced {@link WorkspaceOps} layer.
+*
+* The base command defaults to `"npm test"` and can be overridden via
+* `options.command`. When the model passes a `pattern`, it is appended to
+* the command as a path/suite filter forwarded to the runner (e.g.
+* `"npm test src/cart"`). Like `run_shell`, the resolved command's
+* executable is gated by the shell policy — a denial surfaces in the
+* result's `error` field — and a non-zero exit (failing tests) comes back
+* as `data` for the agent to read and fix.
+*
+* @param ops - The policy-enforced operation layer to delegate `exec` to.
+* @param options - Optional tool-name and base-command overrides.
+*
+* @example
+* const runTests = makeRunTestsTool(ops, { command: "pnpm test" });
+* const { data } = await runTests.invoke({ pattern: "cart-total" });
+* if (data.exitCode !== 0) inspect(data.stderr);
+*/
+function makeRunTestsTool(ops, options) {
+	const baseCommand = options?.command ?? DEFAULT_TEST_COMMAND;
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_RUN_TESTS_TOOL_NAME,
+		description: "Run the workspace's test suite, optionally narrowed to a path or name pattern forwarded to the test runner. Failing tests return a non-zero exit code as data, not an error.",
+		action: (input) => input.pattern ? `Running tests matching "${input.pattern}"` : "Running tests",
+		input: runTestsInputSchema,
+		execute: (input) => {
+			const command = input.pattern ? `${baseCommand} ${input.pattern}` : baseCommand;
+			return ops.exec(command);
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/tools/write-file.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "write_file";
+/** Input schema for the `write_file` tool. */
+const inputSchema = objectSchema({
+	path: stringField(),
+	content: stringField()
+});
+/**
+* Build the agent-facing `write_file` tool over a workspace's policy-
+* enforced {@link WorkspaceOps}.
+*
+* The tool validates `{ path, content }` against a Standard Schema, then
+* delegates to `ops.writeFile`, which atomically writes the full content
+* (creating parent directories) and returns the byte count and content
+* `hash`. The tool re-attaches the workspace-relative `path` so the
+* result matches the {@link WriteFileResult} wire shape.
+*
+* **Errors flow as data.** A jail escape is thrown by `ops`; the
+* `tool()` wrapper catches it and surfaces it in the returned `{ error }`
+* field — `invoke()` never throws.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const writeTool = makeWriteFileTool(ops);
+* const { data } = await writeTool.invoke({ path: "src/new.ts", content: "export {};" });
+* console.log(data.bytesWritten, data.hash);
+*/
+function makeWriteFileTool(ops, options) {
+	return (0, _warlock_js_ai.tool)({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "Write full content to a workspace file, creating it (and any parent directories) if absent and overwriting it otherwise. The write is atomic. Returns the bytes written and the new content hash.",
+		input: inputSchema,
+		async execute(input) {
+			const { hash, bytesWritten } = await ops.writeFile(input.path, input.content);
+			return {
+				path: input.path,
+				bytesWritten,
+				hash
+			};
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai-workspace/src/workspace.ts
+/**
+* The full set of tool names a writable workspace vends, in a stable
+* canonical order so `tools.all()` is deterministic.
+*/
+const ALL_TOOL_NAMES = [
+	"readFile",
+	"editFile",
+	"writeFile",
+	"runShell",
+	"runTests",
+	"grep",
+	"glob"
+];
+/**
+* The subset a {@link Workspace.readonly} projection exposes — the
+* non-mutating tools only. `editFile` / `writeFile` / `runShell` /
+* `runTests` are deliberately omitted so a reviewer agent has no path to
+* change the tree.
+*/
+const READONLY_TOOL_NAMES = [
+	"readFile",
+	"grep",
+	"glob"
+];
+/**
+* Choose the dumb IO executor for a policy. `"mock"` selects the
+* in-memory backend (hermetic tests); anything else — including the
+* `"local"` default and an absent `backend` — selects the real-disk
+* local backend.
+*/
+function selectBackend(policy) {
+	if (policy.backend === "mock") return createMockBackend();
+	return createLocalBackend();
+}
+/**
+* The internal {@link Workspace} implementation. Holds the resolved
+* backend, the policy, and the single shared {@link WorkspaceOps} seam
+* that both the agent-facing `.tools.*` factories and the human-facing
+* direct methods funnel through — one jail, one rule set, two callers.
+*
+* The `allowedTools` set narrows what `tools.*` will vend and which
+* mutating direct methods are permitted: a full workspace allows every
+* name; a {@link WorkspaceImpl.readonly} projection allows only the
+* read/grep/glob subset and rejects writes/edits/shell/mkdir/remove.
+*
+* Constructed via {@link workspace}; the class itself is internal.
+*/
+var WorkspaceImpl = class WorkspaceImpl {
+	constructor(policy, allowedTools = ALL_TOOL_NAMES) {
+		this.policy = policy;
+		this.allowedTools = new Set(allowedTools);
+		const backend = selectBackend(policy);
+		this.ops = createOps(backend, policy);
+		this.tools = this.buildTools();
+	}
+	/**
+	* Assemble the agent-facing tool namespace. Each factory builds its
+	* tool over the shared `ops`; `all()` returns every *allowed* tool in
+	* canonical order and `pick(...)` returns the named subset (silently
+	* dropping any name this projection does not allow, so a `readonly()`
+	* workspace can never be coaxed into vending a mutating tool).
+	*/
+	buildTools() {
+		const erase = (contract) => contract;
+		const factories = {
+			readFile: (opts) => erase(makeReadFileTool(this.ops, opts)),
+			editFile: (opts) => erase(makeEditFileTool(this.ops, opts)),
+			writeFile: (opts) => erase(makeWriteFileTool(this.ops, opts)),
+			runShell: (opts) => erase(makeRunShellTool(this.ops, opts)),
+			runTests: (opts) => erase(makeRunTestsTool(this.ops, opts)),
+			grep: (opts) => erase(makeGrepTool(this.ops, opts)),
+			glob: (opts) => erase(makeGlobTool(this.ops, opts))
+		};
+		const build = (name, opts) => factories[name](opts);
+		return {
+			all: () => ALL_TOOL_NAMES.filter((name) => this.allowedTools.has(name)).map((name) => build(name)),
+			pick: (...names) => names.filter((name) => this.allowedTools.has(name)).map((name) => build(name)),
+			readFile: (opts) => build("readFile", opts),
+			editFile: (opts) => build("editFile", opts),
+			writeFile: (opts) => build("writeFile", opts),
+			runShell: (opts) => build("runShell", opts),
+			runTests: (opts) => build("runTests", opts),
+			grep: (opts) => build("grep", opts),
+			glob: (opts) => build("glob", opts)
+		};
+	}
+	/**
+	* Reject a mutating direct method on a read-only projection — surfaced
+	* as a {@link WorkspacePolicyError} (the same typed error a denied
+	* command produces) so a caller branches on `error.type`.
+	*/
+	assertWritable(operation) {
+		if (this.allowedTools.has("writeFile")) return;
+		throw new WorkspacePolicyError(`Operation "${operation}" is not permitted on a read-only workspace.`, {
+			type: "denied-command",
+			command: operation
+		});
+	}
+	readFile(filePath, opts) {
+		return this.ops.readFile(filePath, opts);
+	}
+	async writeFile(filePath, content) {
+		this.assertWritable("writeFile");
+		return this.ops.writeFile(filePath, content);
+	}
+	async editFile(input) {
+		this.assertWritable("editFile");
+		return this.ops.editFile(input);
+	}
+	async exec(command, opts) {
+		this.assertWritable("exec");
+		return this.ops.exec(command, opts);
+	}
+	grep(pattern, opts) {
+		return this.ops.grep(pattern, opts);
+	}
+	glob(pattern) {
+		return this.ops.glob(pattern);
+	}
+	exists(filePath) {
+		return this.ops.exists(filePath);
+	}
+	async mkdir(filePath) {
+		this.assertWritable("mkdir");
+		return this.ops.mkdir(filePath);
+	}
+	async remove(filePath) {
+		this.assertWritable("remove");
+		return this.ops.remove(filePath);
+	}
+	/**
+	* A read-only projection over the SAME policy — only the read/grep/glob
+	* tools are vended and every mutating direct method rejects with a
+	* {@link WorkspacePolicyError}. A fresh ops/backend is built from the
+	* identical policy, so the projection sees the same jailed tree.
+	*/
+	readonly() {
+		return new WorkspaceImpl(this.policy, READONLY_TOOL_NAMES);
+	}
+	/**
+	* A sub-jailed view rooted at `subdir` (relative to this workspace's
+	* `cwd`). Returns a brand-new workspace whose policy is this policy
+	* with `cwd` narrowed to `join(cwd, subdir)` — same backend selection,
+	* same allow/deny/shell/read sub-policies, but a tighter jail root.
+	*/
+	scope(subdir) {
+		return new WorkspaceImpl({
+			...this.policy,
+			cwd: node_path.default.join(this.policy.cwd, subdir)
+		}, [...this.allowedTools]);
+	}
+};
+/**
+* Build a {@link Workspace} — the integrator that wires a
+* {@link WorkspacePolicy} to a backend, the shared policy-enforced ops
+* layer, and the seven agent-facing tool factories.
+*
+* The backend is chosen from `policy.backend`: `"mock"` runs in memory
+* (hermetic tests); the `"local"` default (and any absent value) runs
+* over the real disk via `@warlock.js/fs` + `node:child_process`. The
+* returned workspace exposes:
+*
+* - **`tools.*`** — `readFile` / `editFile` / `writeFile` / `runShell` /
+*   `runTests` / `grep` / `glob`, plus `all()` (every tool) and
+*   `pick(...)` (a least-privilege subset).
+* - **direct methods** — `readFile` / `writeFile` / `editFile` / `exec` /
+*   `grep` / `glob` / `exists` / `mkdir` / `remove`, each delegating 1:1
+*   to the shared ops layer.
+* - **`readonly()`** — a projection that vends only read/grep/glob and
+*   rejects every mutating direct method.
+* - **`scope(subdir)`** — a sub-jailed workspace rooted at `subdir`.
+*
+* Available at runtime as `ai.workspace(policy)` once this module is
+* imported (it registers the verb on the shared `ai` object).
+*
+* @param policy - The policy bounding the workspace (its `cwd` is the jail root).
+* @returns A fully-wired {@link Workspace}.
+*
+* @example
+* const ws = workspace({ cwd: "/srv/acme-api", shell: { allow: ["npm"], inheritEnv: ["PATH"] } });
+* const dev = ai.agent({ model, tools: ws.tools.all() });
+* await dev.execute("Make the failing cart-total suite green.");
+*
+* @example
+* // Least-privilege reviewer — no write, no shell.
+* const reviewer = ai.agent({ model, tools: ws.readonly().tools.all() });
+*/
+function workspace(policy) {
+	return new WorkspaceImpl(policy);
+}
+_warlock_js_ai.ai.workspace = workspace;
+
+//#endregion
+exports.WorkspaceEditError = WorkspaceEditError;
+exports.WorkspacePolicyError = WorkspacePolicyError;
+exports.buildEnv = buildEnv;
+exports.createLocalBackend = createLocalBackend;
+exports.createMockBackend = createMockBackend;
+exports.createOps = createOps;
+exports.isCommandAllowed = isCommandAllowed;
+exports.makeEditFileTool = makeEditFileTool;
+exports.makeGlobTool = makeGlobTool;
+exports.makeGrepTool = makeGrepTool;
+exports.makeReadFileTool = makeReadFileTool;
+exports.makeRunShellTool = makeRunShellTool;
+exports.makeRunTestsTool = makeRunTestsTool;
+exports.makeWriteFileTool = makeWriteFileTool;
+exports.resolveInJail = resolveInJail;
+exports.workspace = workspace;
+//# sourceMappingURL=index.cjs.map