@warlock.js/ai-workspace 5.29.0 → 5.31.0

package/esm/ops.mjs

@@ -1,15 +1,32 @@
 import { WorkspaceEditError, WorkspacePolicyError } from "./errors.mjs";
-import { buildEnv, isCommandAllowed, resolveInJail } from "./policy/policy.mjs";
+import { globToRegExp, isInside, matchesAnyGlob } from "./policy/jail.mjs";
+import { checkShellCommand } from "./policy/shell-check.mjs";
+import { buildCommandEnv, resolveInJail } from "./policy/policy.mjs";
+import { ShellJobs } from "./shell-jobs.mjs";
 import path from "node:path";
 import { fs } from "@warlock.js/fs";
 
-//#region ../ai-workspace/src/ops.ts
+//#region ../../packages/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;
+/** Default `list.ignore` when the policy sets none. */
+const DEFAULT_LIST_IGNORE = ["node_modules", ".git"];
+/** Default deepest `depth` a listing may ask for. */
+const DEFAULT_LIST_MAX_DEPTH = 5;
+/** Default most entries one listing returns. */
+const DEFAULT_LIST_MAX_ENTRIES = 500;
+/** Most edits one `multiEdit` call may carry. */
+const MAX_MULTI_EDITS = 100;
+/**
+* Exit code reported for a command refused because its signal was already
+* aborted (the shell convention for an interrupted command). Callers should
+* branch on `cancelled`, not on this number.
+*/
+const CANCELLED_BEFORE_START_EXIT_CODE = 130;
 /**
 * Hard ceiling on `grep` pattern length. A model-controlled regex has no
 * legitimate reason to be this long; longer patterns are rejected outright
@@ -24,57 +41,74 @@ const MAX_GREP_PATTERN_LENGTH = 200;
 * this are skipped rather than scanned.
 */
 const MAX_GREP_LINE_SCAN_LENGTH = 2e3;
-/**
-* 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");
+/** The `cat -n` prefix for a line: right-aligned number (min width 6) and a tab. */
+function linePrefix(lineNumber) {
+	return `${String(lineNumber).padStart(6, " ")}\t`;
 }
 /**
-* Clip a captured stream at `maxBytes` (measured in UTF-8 bytes).
-* Returns the possibly-clipped string plus whether clipping occurred.
+* Clip `value` to at most `maxBytes` UTF-8 bytes without splitting a
+* character: the cut backs off over continuation bytes (`10xxxxxx`) to the
+* start of the character it would have split, so the result never carries
+* a replacement character.
 */
-function capOutput(value, maxBytes) {
+function clipUtf8(value, maxBytes) {
 	const bytes = Buffer.from(value, "utf8");
 	if (bytes.byteLength <= maxBytes) return {
 		value,
 		truncated: false
 	};
+	let cut = Math.max(0, maxBytes);
+	while (cut > 0 && ((bytes[cut] ?? 0) & 192) === 128) cut--;
 	return {
-		value: bytes.subarray(0, maxBytes).toString("utf8"),
+		value: bytes.subarray(0, cut).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.
+* Number a window of lines `cat -n` style, keeping the joined output within
+* `maxBytes` UTF-8 bytes (prefixes and newlines included) when a cap is set.
+* A line that does not fit whole is clipped on a character boundary; it is
+* still counted as returned when its prefix and at least one character fit.
 */
-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 += "[^/]*";
+function numberWindow(lines, startLine, maxBytes) {
+	const parts = [];
+	let used = 0;
+	for (let index = 0; index < lines.length; index++) {
+		const prefix = linePrefix(startLine + index);
+		const numbered = prefix + lines[index];
+		const separator = parts.length > 0 ? 1 : 0;
+		if (maxBytes === void 0) {
+			parts.push(numbered);
 			continue;
 		}
-		if (char === "?") {
-			source += "[^/]";
+		const cost = separator + Buffer.byteLength(numbered, "utf8");
+		if (used + cost <= maxBytes) {
+			parts.push(numbered);
+			used += cost;
 			continue;
 		}
-		source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+		const room = maxBytes - used - separator - Buffer.byteLength(prefix, "utf8");
+		const clipped = room > 0 ? clipUtf8(lines[index] ?? "", room).value : "";
+		if (clipped.length > 0) parts.push(prefix + clipped);
+		return {
+			content: parts.join("\n"),
+			returnedLines: parts.length,
+			bytesCapped: true
+		};
 	}
-	return new RegExp(`^${source}$`);
+	return {
+		content: parts.join("\n"),
+		returnedLines: parts.length,
+		bytesCapped: false
+	};
+}
+/**
+* Clip a captured stream at `maxBytes` (measured in UTF-8 bytes), on a
+* character boundary. Returns the possibly-clipped string plus whether
+* clipping occurred.
+*/
+function capOutput(value, maxBytes) {
+	return clipUtf8(value, maxBytes);
 }
 /**
 * A quantifier: `+`, `*`, `?`, or a `{m,n}` bound.
@@ -98,17 +132,29 @@ function isSafeGrepPattern(pattern) {
 	if (pattern.length > MAX_GREP_PATTERN_LENGTH) return false;
 	return !NESTED_QUANTIFIER_PATTERN.test(pattern);
 }
-/**
-* 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) {
+	constructor(backend, policy, runtime) {
 		this.backend = backend;
 		this.policy = policy;
+		this.runtime = runtime;
+		this.pathLocks = /* @__PURE__ */ new Map();
+	}
+	/** Run `task` after every earlier mutation of `absolutePath` has settled. */
+	async withPathLock(absolutePath, task) {
+		const previous = this.pathLocks.get(absolutePath) ?? Promise.resolve();
+		let release = () => {};
+		const current = new Promise((resolve) => {
+			release = resolve;
+		});
+		const tail = previous.then(() => current);
+		this.pathLocks.set(absolutePath, tail);
+		try {
+			await previous;
+			return await task();
+		} finally {
+			release();
+			if (this.pathLocks.get(absolutePath) === tail) this.pathLocks.delete(absolutePath);
+		}
 	}
 	/**
 	* Recursively collect every file under `absDir` as absolute paths,
@@ -143,25 +189,39 @@ var Ops = class {
 		const totalLines = lines.length;
 		const offset = Math.max(1, opts?.offset ?? 1);
 		const limit = opts?.limit ?? this.policy.read?.defaultLines ?? DEFAULT_READ_LINES;
+		const maxBytes = this.policy.read?.maxBytes;
 		const startIndex = offset - 1;
+		const { content, returnedLines, bytesCapped } = numberWindow(lines.slice(startIndex, startIndex + Math.max(0, limit)), offset, maxBytes === void 0 ? void 0 : Math.max(0, Math.floor(maxBytes)));
+		const endLine = offset + returnedLines - 1;
 		return {
-			content: numberLines(lines.slice(startIndex, startIndex + limit).join("\n"), offset),
-			hash,
-			totalLines
+			content,
+			startLine: offset,
+			endLine,
+			totalLines,
+			truncated: bytesCapped || endLine < totalLines,
+			bytesCapped,
+			totalBytes: Buffer.byteLength(raw, "utf8"),
+			hash
 		};
 	}
 	async writeFile(inputPath, content) {
 		const { absolutePath } = await resolveInJail(this.policy, inputPath);
-		const parent = path.dirname(absolutePath);
-		await this.backend.mkdir(parent);
-		await this.backend.writeFile(absolutePath, content);
-		return {
-			hash: fs.hash.string(content),
-			bytesWritten: Buffer.byteLength(content, "utf8")
-		};
+		return this.withPathLock(absolutePath, async () => {
+			const parent = path.dirname(absolutePath);
+			await this.backend.mkdir(parent);
+			await this.backend.writeFile(absolutePath, content);
+			return {
+				hash: fs.hash.string(content),
+				bytesWritten: Buffer.byteLength(content, "utf8")
+			};
+		});
 	}
 	async editFile(input) {
 		const { absolutePath, relativePath } = await resolveInJail(this.policy, input.path);
+		return this.withPathLock(absolutePath, () => this.applyEdit(input, absolutePath, relativePath));
+	}
+	/** The read-check-replace-write of {@link editFile}, run under its path lock. */
+	async applyEdit(input, absolutePath, relativePath) {
 		const current = await this.backend.readFile(absolutePath);
 		const currentHash = fs.hash.string(current);
 		if (input.expectHash !== void 0 && input.expectHash !== currentHash) throw new WorkspaceEditError(`File "${input.path}" changed since it was read; the edit is stale.`, {
@@ -170,48 +230,222 @@ var Ops = class {
 			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);
+		const { content: updated, replacements } = applyReplacement(current, input, input.path, relativePath || input.path);
 		await this.backend.writeFile(absolutePath, updated);
 		return {
 			path: relativePath || input.path,
-			replacements: input.replaceAll ? occurrences : 1,
+			replacements,
 			hash: fs.hash.string(updated)
 		};
 	}
-	async exec(command, opts) {
-		if (!isCommandAllowed(this.policy, command)) throw new WorkspacePolicyError(`Command is not permitted by the workspace shell policy: ${command}`, {
+	async multiEdit(input) {
+		const { absolutePath, relativePath } = await resolveInJail(this.policy, input.path);
+		const shownPath = relativePath || input.path;
+		if (input.edits.length === 0 || input.edits.length > 100) throw new RangeError(`A multi-edit needs between 1 and ${100} edits (got ${input.edits.length}).`);
+		return this.withPathLock(absolutePath, async () => {
+			const current = await this.backend.readFile(absolutePath);
+			const currentHash = fs.hash.string(current);
+			if (input.expectHash !== void 0 && input.expectHash !== currentHash) throw new WorkspaceEditError(`File "${input.path}" changed since it was read; none of the edits were applied.`, {
+				type: "stale-hash",
+				path: shownPath,
+				expectedHash: input.expectHash,
+				actualHash: currentHash
+			});
+			let content = current;
+			let replacements = 0;
+			input.edits.forEach((edit, editIndex) => {
+				const applied = applyReplacement(content, edit, input.path, shownPath, editIndex);
+				content = applied.content;
+				replacements += applied.replacements;
+			});
+			await this.backend.writeFile(absolutePath, content);
+			return {
+				path: shownPath,
+				edits: input.edits.length,
+				replacements,
+				hash: fs.hash.string(content)
+			};
+		});
+	}
+	/**
+	* Check a command line against the shell policy: every command in it
+	* (argv or shell mode), then — shell mode — every redirection target and
+	* `cd` directory against the jail with symlinks resolved.
+	*/
+	async assertCommandAllowed(command) {
+		const verdict = checkShellCommand(this.policy, command);
+		if (!verdict.allowed) throw new WorkspacePolicyError(verdict.message ?? `Command is not permitted by the workspace shell policy: ${command}`, {
 			type: "denied-command",
+			command,
+			...verdict.reason !== void 0 ? { reason: verdict.reason } : {},
+			...verdict.executable !== void 0 ? { executable: verdict.executable } : {},
+			...verdict.path !== void 0 ? { path: verdict.path } : {}
+		});
+		for (const target of verdict.paths) try {
+			await resolveInJail(this.policy, target.path);
+		} catch (error) {
+			if (!(error instanceof WorkspacePolicyError)) throw error;
+			throw new WorkspacePolicyError(target.access === "cwd" ? `\`cd ${target.target}\` resolves (through a symlink) outside the workspace jail or onto a denied path.` : `The redirection target \`${target.target}\` resolves (through a symlink) outside the workspace jail or onto a denied path.`, {
+				type: "denied-command",
+				reason: "path-escape",
+				command,
+				path: target.target
+			});
+		}
+		if (this.runtime.jobs.isDisposed) throw new WorkspacePolicyError("The workspace has been disposed; it cannot run new commands.", {
+			type: "denied-command",
+			reason: "not-allowed",
 			command
 		});
+	}
+	async exec(command, opts) {
+		await this.assertCommandAllowed(command);
+		const signal = opts?.signal;
+		if (signal?.aborted) return {
+			exitCode: CANCELLED_BEFORE_START_EXIT_CODE,
+			stdout: "",
+			stderr: "Command was not executed: the invocation was cancelled before it started.",
+			truncated: false,
+			timedOut: false,
+			cancelled: true
+		};
 		const shell = this.policy.shell;
 		const timeoutMs = opts?.timeoutMs ?? shell?.timeoutMs;
 		const maxOutputBytes = shell?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+		const interpreter = shell?.interpreter ?? "none";
 		const result = await this.backend.exec(command, {
 			cwd: this.policy.cwd,
 			timeoutMs,
-			env: buildEnv(this.policy)
+			env: buildCommandEnv(this.policy),
+			...signal ? { signal } : {},
+			...interpreter !== "none" ? { interpreter } : {}
 		});
 		const stdout = capOutput(result.stdout, maxOutputBytes);
 		const stderr = capOutput(result.stderr, maxOutputBytes);
+		const cancelled = result.cancelled === true;
 		return {
 			exitCode: result.exitCode,
 			stdout: stdout.value,
 			stderr: stderr.value,
 			truncated: stdout.truncated || stderr.truncated,
-			timedOut: result.timedOut
+			timedOut: result.timedOut && !cancelled,
+			cancelled
 		};
 	}
+	async startShell(command, opts) {
+		const background = this.policy.shell?.background;
+		if (background === void 0) throw new WorkspacePolicyError("Background commands are not enabled for this workspace. Run the command without background, or ask for shell.background to be enabled.", {
+			type: "denied-command",
+			reason: "not-allowed",
+			command
+		});
+		await this.assertCommandAllowed(command);
+		const start = this.backend.start?.bind(this.backend);
+		if (start === void 0) throw new WorkspacePolicyError("This workspace backend cannot run background commands.", {
+			type: "denied-command",
+			reason: "not-allowed",
+			command
+		});
+		const shell = this.policy.shell;
+		const interpreter = shell?.interpreter ?? "none";
+		const timeoutMs = lowerOf(background.timeoutMs, opts?.timeoutMs);
+		const env = buildCommandEnv(this.policy);
+		return this.runtime.jobs.start({
+			command,
+			retainBytes: shell?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+			maxJobs: background.maxJobs ?? 4,
+			...timeoutMs !== void 0 ? { timeoutMs } : {},
+			launch: (onOutput) => start(command, {
+				cwd: this.policy.cwd,
+				env,
+				...interpreter !== "none" ? { interpreter } : {},
+				onOutput
+			})
+		});
+	}
+	shellOutput(id, opts) {
+		return this.runtime.jobs.output(id, opts);
+	}
+	shellKill(id) {
+		return this.runtime.jobs.kill(id);
+	}
+	listShells() {
+		return this.runtime.jobs.list();
+	}
+	dispose() {
+		return this.runtime.jobs.dispose();
+	}
+	async listDir(inputPath = ".", opts) {
+		const { absolutePath: root, relativePath: rootRelative } = await resolveInJail(this.policy, inputPath);
+		const { absolutePath: jailRoot } = await resolveInJail(this.policy, ".");
+		const listPolicy = this.policy.list;
+		const maxDepth = Math.max(1, Math.floor(listPolicy?.maxDepth ?? DEFAULT_LIST_MAX_DEPTH));
+		const depth = Math.min(Math.max(1, Math.floor(opts?.depth ?? 1)), maxDepth);
+		const maxEntries = Math.max(1, Math.floor(listPolicy?.maxEntries ?? DEFAULT_LIST_MAX_ENTRIES));
+		const ignore = [...listPolicy?.ignore ?? DEFAULT_LIST_IGNORE, ...opts?.ignore ?? []];
+		const insideCwd = isInside(root, jailRoot);
+		if (!await this.isDirectory(root)) throw new Error(`"${inputPath}" is not a directory in the workspace.`);
+		const entries = [];
+		let level = [root];
+		let truncated = false;
+		for (let currentDepth = 1; currentDepth <= depth && level.length > 0; currentDepth++) {
+			const nextLevel = [];
+			for (const directory of level) {
+				let children;
+				try {
+					children = await this.backend.list(directory);
+				} catch {
+					continue;
+				}
+				children.sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+				for (const child of children) {
+					const relativeToJail = insideCwd ? path.relative(jailRoot, child).split(path.sep).join("/") : child;
+					if (insideCwd && (this.isDenied(relativeToJail) || matchesAnyGlob(relativeToJail, ignore))) continue;
+					const relativeToRoot = path.relative(root, child).split(path.sep).join("/");
+					if (!insideCwd && matchesAnyGlob(relativeToRoot, ignore)) continue;
+					if (entries.length >= maxEntries) {
+						truncated = true;
+						break;
+					}
+					const described = await this.describe(child);
+					entries.push({
+						path: relativeToJail,
+						type: described.type,
+						...described.size !== void 0 ? { size: described.size } : {},
+						depth: currentDepth
+					});
+					if (described.type === "directory") nextLevel.push(child);
+				}
+				if (truncated) break;
+			}
+			if (truncated) break;
+			level = nextLevel;
+		}
+		return {
+			path: insideCwd ? rootRelative || "." : root,
+			entries,
+			truncated
+		};
+	}
+	/** Kind and size of a listed entry; symlinks are reported, never followed. */
+	async describe(absPath) {
+		if (this.backend.stat) try {
+			const stats = await this.backend.stat(absPath);
+			return stats.type === "file" ? {
+				type: "file",
+				size: stats.size
+			} : { type: stats.type };
+		} catch {
+			return { type: "other" };
+		}
+		if (await this.isDirectory(absPath)) try {
+			await resolveInJail(this.policy, absPath);
+			return { type: "directory" };
+		} catch {
+			return { type: "other" };
+		}
+		return { type: "file" };
+	}
 	async grep(pattern, opts) {
 		if (!isSafeGrepPattern(pattern)) throw new WorkspacePolicyError(`Grep pattern is too long or too likely to cause catastrophic regex backtracking: ${pattern}`, {
 			type: "unsafe-pattern",
@@ -235,7 +469,7 @@ var Ops = class {
 			}
 			const lines = content.split("\n");
 			for (let index = 0; index < lines.length; index++) {
-				const line = lines[index];
+				const line = lines[index] ?? "";
 				if (line.length > MAX_GREP_LINE_SCAN_LENGTH) continue;
 				if (regex.test(line)) {
 					matches.push({
@@ -277,22 +511,45 @@ var Ops = class {
 	}
 	async remove(inputPath) {
 		const { absolutePath } = await resolveInJail(this.policy, inputPath);
-		await this.backend.remove(absolutePath);
+		await this.withPathLock(absolutePath, () => 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;
-		});
+		return denyPaths !== void 0 && denyPaths.length > 0 && matchesAnyGlob(relativePath, denyPaths);
 	}
 };
+/** The lower of two optional limits (either may be absent). */
+function lowerOf(policyLimit, requested) {
+	if (requested === void 0 || requested <= 0) return policyLimit;
+	return policyLimit === void 0 ? requested : Math.min(policyLimit, requested);
+}
+/**
+* Apply one exact-string replacement to `content` under the edit rules:
+* `oldString` must occur, and exactly once unless `replaceAll`.
+*/
+function applyReplacement(content, edit, inputPath, shownPath, editIndex) {
+	const occurrences = countOccurrences(content, edit.oldString);
+	const which = editIndex === void 0 ? "" : `Edit ${editIndex + 1}: `;
+	const nothingApplied = editIndex === void 0 ? "" : " None of the edits were applied.";
+	const indexOption = editIndex === void 0 ? {} : { editIndex };
+	if (occurrences === 0) throw new WorkspaceEditError(`${which}The text to replace was not found in "${inputPath}".${nothingApplied}`, {
+		type: "not-found",
+		path: shownPath,
+		matches: 0,
+		...indexOption
+	});
+	if (occurrences > 1 && !edit.replaceAll) throw new WorkspaceEditError(`${which}The text to replace is not unique in "${inputPath}" (${occurrences} matches); pass replaceAll or include more surrounding context.${nothingApplied}`, {
+		type: "not-unique",
+		path: shownPath,
+		matches: occurrences,
+		...indexOption
+	});
+	return {
+		content: edit.replaceAll ? content.split(edit.oldString).join(edit.newString) : replaceFirst(content, edit.oldString, edit.newString),
+		replacements: edit.replaceAll ? occurrences : 1
+	};
+}
 /** Count non-overlapping occurrences of `needle` in `haystack`. */
 function countOccurrences(haystack, needle) {
 	if (needle === "") return 0;
@@ -324,13 +581,15 @@ function replaceFirst(haystack, needle, replacement) {
 *
 * @param backend - The dumb IO executor (local disk or in-memory mock).
 * @param policy - The policy that bounds every operation.
+* @param runtime - State shared with other views of the same workspace
+*   (its background commands); a fresh one when omitted.
 *
 * @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);
+function createOps(backend, policy, runtime) {
+	return new Ops(backend, policy, runtime ?? { jobs: new ShellJobs() });
 }
 
 //#endregion