@warlock.js/ai-workspace 5.30.0 → 5.32.0

package/esm/index.d.mts

@@ -1,20 +1,29 @@
-import { EditFileInput, EditFileResult, ExecOptions, GlobInput, GlobResult, GrepInput, GrepMatch, GrepResult, ReadFileInput, ReadFileResult, RunShellInput, RunShellResult, RunTestsInput, WorkspaceToolName, WriteFileInput, WriteFileResult } from "./contracts/tool-io.type.mjs";
-import { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult } from "./contracts/workspace-backend.contract.mjs";
+import { EditFileInput, EditFileResult, ExecOptions, GlobInput, GlobResult, GrepInput, GrepMatch, GrepResult, ListDirEntry, ListDirEntryType, ListDirInput, ListDirOptions, ListDirResult, MultiEditInput, MultiEditOperation, MultiEditResult, ReadFileInput, ReadFileResult, RunShellBackgroundResult, RunShellInput, RunShellResult, RunTestsInput, ShellJobInfo, ShellJobStatus, ShellKillInput, ShellOutputInput, ShellOutputOptions, ShellOutputResult, StartShellOptions, TodoListResult, TodoWriteInput, WorkspaceTodo, WorkspaceTodoInput, WorkspaceTodoStatus, WorkspaceToolName, WriteFileInput, WriteFileResult } from "./contracts/tool-io.type.mjs";
+import { WorkspaceAllowCommand, WorkspaceBackendType, WorkspaceBackgroundPolicy, WorkspaceCommandCheckContext, WorkspaceCommandPattern, WorkspaceListPolicy, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellInterpreter, WorkspaceShellPolicy } from "./contracts/workspace-policy.type.mjs";
+import { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult, WorkspaceBackendProcess, WorkspaceBackendStartOptions, WorkspaceBackendStat, WorkspaceOutputStream } from "./contracts/workspace-backend.contract.mjs";
 import { WorkspaceOps } from "./contracts/workspace-ops.contract.mjs";
-import { WorkspaceBackendType, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellPolicy } from "./contracts/workspace-policy.type.mjs";
 import { Workspace, WorkspaceTools } from "./contracts/workspace.contract.mjs";
-import { WorkspaceEditError, WorkspaceEditErrorOptions, WorkspaceEditFailure, WorkspacePolicyError, WorkspacePolicyErrorOptions, WorkspacePolicyViolation } from "./errors.mjs";
+import "./contracts/index.mjs";
+import { WorkspaceEditError, WorkspaceEditErrorOptions, WorkspaceEditFailure, WorkspaceJobError, WorkspaceJobErrorOptions, WorkspaceJobFailure, WorkspacePolicyError, WorkspacePolicyErrorOptions, WorkspacePolicyViolation, WorkspaceShellRefusalReason } from "./errors.mjs";
 import { ResolvedPath, buildEnv, isCommandAllowed, resolveInJail } from "./policy/policy.mjs";
+import { WorkspaceShellCheck, WorkspaceShellPath, WorkspaceShellPathAccess, checkShellCommand } from "./policy/shell-check.mjs";
+import { ArgvAnalysis, analyzeArgvCommand, tokenizeCommand } from "./policy/tokenize-command.mjs";
 import { createOps } from "./ops.mjs";
 import { createLocalBackend } from "./backends/local.mjs";
 import { MockBackendSeed, MockExecResult, createMockBackend } from "./backends/mock.mjs";
 import { makeEditFileTool } from "./tools/edit-file.mjs";
 import { MakeGlobToolOptions, makeGlobTool } from "./tools/glob.mjs";
 import { MakeGrepToolOptions, makeGrepTool } from "./tools/grep.mjs";
+import { makeListDirTool } from "./tools/list-dir.mjs";
+import { makeMultiEditTool } from "./tools/multi-edit.mjs";
 import { makeReadFileTool } from "./tools/read-file.mjs";
 import { MakeRunShellToolOptions, makeRunShellTool } from "./tools/run-shell.mjs";
 import { MakeRunTestsToolOptions, makeRunTestsTool } from "./tools/run-tests.mjs";
+import { makeShellKillTool } from "./tools/shell-kill.mjs";
+import { makeShellOutputTool } from "./tools/shell-output.mjs";
+import { TodoStore } from "./todos.mjs";
+import { makeTodoReadTool, makeTodoWriteTool } from "./tools/todo.mjs";
 import { makeWriteFileTool } from "./tools/write-file.mjs";
 import { workspace } from "./workspace.mjs";
-export { type EditFileInput, type EditFileResult, type ExecOptions, type GlobInput, type GlobResult, type GrepInput, type GrepMatch, type GrepResult, type MakeGlobToolOptions, type MakeGrepToolOptions, type MakeRunShellToolOptions, type MakeRunTestsToolOptions, type MockBackendSeed, type MockExecResult, type ReadFileInput, type ReadFileResult, type ResolvedPath, type RunShellInput, type RunShellResult, type RunTestsInput, type Workspace, type WorkspaceBackend, type WorkspaceBackendExecOptions, type WorkspaceBackendExecResult, type WorkspaceBackendType, WorkspaceEditError, type WorkspaceEditErrorOptions, type WorkspaceEditFailure, type WorkspaceOps, type WorkspacePolicy, WorkspacePolicyError, type WorkspacePolicyErrorOptions, type WorkspacePolicyViolation, type WorkspaceReadPolicy, type WorkspaceShellPolicy, type WorkspaceToolName, type WorkspaceTools, type WriteFileInput, type WriteFileResult, buildEnv, createLocalBackend, createMockBackend, createOps, isCommandAllowed, makeEditFileTool, makeGlobTool, makeGrepTool, makeReadFileTool, makeRunShellTool, makeRunTestsTool, makeWriteFileTool, resolveInJail, workspace };
+export { type ArgvAnalysis, type EditFileInput, type EditFileResult, type ExecOptions, type GlobInput, type GlobResult, type GrepInput, type GrepMatch, type GrepResult, type ListDirEntry, type ListDirEntryType, type ListDirInput, type ListDirOptions, type ListDirResult, type MakeGlobToolOptions, type MakeGrepToolOptions, type MakeRunShellToolOptions, type MakeRunTestsToolOptions, type MockBackendSeed, type MockExecResult, type MultiEditInput, type MultiEditOperation, type MultiEditResult, type ReadFileInput, type ReadFileResult, type ResolvedPath, type RunShellBackgroundResult, type RunShellInput, type RunShellResult, type RunTestsInput, type ShellJobInfo, type ShellJobStatus, type ShellKillInput, type ShellOutputInput, type ShellOutputOptions, type ShellOutputResult, type StartShellOptions, type TodoListResult, TodoStore, type TodoWriteInput, type Workspace, type WorkspaceAllowCommand, type WorkspaceBackend, type WorkspaceBackendExecOptions, type WorkspaceBackendExecResult, type WorkspaceBackendProcess, type WorkspaceBackendStartOptions, type WorkspaceBackendStat, type WorkspaceBackendType, type WorkspaceBackgroundPolicy, type WorkspaceCommandCheckContext, type WorkspaceCommandPattern, WorkspaceEditError, type WorkspaceEditErrorOptions, type WorkspaceEditFailure, WorkspaceJobError, type WorkspaceJobErrorOptions, type WorkspaceJobFailure, type WorkspaceListPolicy, type WorkspaceOps, type WorkspaceOutputStream, type WorkspacePolicy, WorkspacePolicyError, type WorkspacePolicyErrorOptions, type WorkspacePolicyViolation, type WorkspaceReadPolicy, type WorkspaceShellCheck, type WorkspaceShellInterpreter, type WorkspaceShellPath, type WorkspaceShellPathAccess, type WorkspaceShellPolicy, type WorkspaceShellRefusalReason, type WorkspaceTodo, type WorkspaceTodoInput, type WorkspaceTodoStatus, type WorkspaceToolName, type WorkspaceTools, type WriteFileInput, type WriteFileResult, analyzeArgvCommand, buildEnv, checkShellCommand, createLocalBackend, createMockBackend, createOps, isCommandAllowed, makeEditFileTool, makeGlobTool, makeGrepTool, makeListDirTool, makeMultiEditTool, makeReadFileTool, makeRunShellTool, makeRunTestsTool, makeShellKillTool, makeShellOutputTool, makeTodoReadTool, makeTodoWriteTool, makeWriteFileTool, resolveInJail, tokenizeCommand, workspace };
 import "./workspace.mjs";

package/esm/index.mjs

@@ -1,4 +1,6 @@
-import { WorkspaceEditError, WorkspacePolicyError } from "./errors.mjs";
+import { WorkspaceEditError, WorkspaceJobError, WorkspacePolicyError } from "./errors.mjs";
+import { analyzeArgvCommand, tokenizeCommand } from "./policy/tokenize-command.mjs";
+import { checkShellCommand } from "./policy/shell-check.mjs";
 import { buildEnv, isCommandAllowed, resolveInJail } from "./policy/policy.mjs";
 import { createOps } from "./ops.mjs";
 import { createLocalBackend } from "./backends/local.mjs";
@@ -6,10 +8,16 @@ import { createMockBackend } from "./backends/mock.mjs";
 import { makeEditFileTool } from "./tools/edit-file.mjs";
 import { makeGlobTool } from "./tools/glob.mjs";
 import { makeGrepTool } from "./tools/grep.mjs";
+import { makeListDirTool } from "./tools/list-dir.mjs";
+import { makeMultiEditTool } from "./tools/multi-edit.mjs";
 import { makeReadFileTool } from "./tools/read-file.mjs";
 import { makeRunShellTool } from "./tools/run-shell.mjs";
 import { makeRunTestsTool } from "./tools/run-tests.mjs";
+import { makeShellKillTool } from "./tools/shell-kill.mjs";
+import { makeShellOutputTool } from "./tools/shell-output.mjs";
+import { TodoStore } from "./todos.mjs";
+import { makeTodoReadTool, makeTodoWriteTool } from "./tools/todo.mjs";
 import { makeWriteFileTool } from "./tools/write-file.mjs";
 import { workspace } from "./workspace.mjs";
 
-export { WorkspaceEditError, WorkspacePolicyError, buildEnv, createLocalBackend, createMockBackend, createOps, isCommandAllowed, makeEditFileTool, makeGlobTool, makeGrepTool, makeReadFileTool, makeRunShellTool, makeRunTestsTool, makeWriteFileTool, resolveInJail, workspace };
+export { TodoStore, WorkspaceEditError, WorkspaceJobError, WorkspacePolicyError, analyzeArgvCommand, buildEnv, checkShellCommand, createLocalBackend, createMockBackend, createOps, isCommandAllowed, makeEditFileTool, makeGlobTool, makeGrepTool, makeListDirTool, makeMultiEditTool, makeReadFileTool, makeRunShellTool, makeRunTestsTool, makeShellKillTool, makeShellOutputTool, makeTodoReadTool, makeTodoWriteTool, makeWriteFileTool, resolveInJail, tokenizeCommand, workspace };

package/esm/ops.d.mts

@@ -1,7 +1,24 @@
+import { WorkspacePolicy } from "./contracts/workspace-policy.type.mjs";
 import { WorkspaceBackend } from "./contracts/workspace-backend.contract.mjs";
 import { WorkspaceOps } from "./contracts/workspace-ops.contract.mjs";
-import { WorkspacePolicy } from "./contracts/workspace-policy.type.mjs";
+import "./contracts/index.mjs";
+import { ShellJobs } from "./shell-jobs.mjs";
 //#region ../../packages/ai-workspace/src/ops.d.ts
+/**
+ * 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.
+ */
+/**
+ * State an ops layer shares with the other projections of the same
+ * workspace (`readonly()`, `scope()`): the background commands it owns.
+ */
+export interface OpsRuntime {
+  /** The workspace's background commands. */
+  jobs: ShellJobs;
+}
 /**
  * Create the policy-enforced operation layer over a backend.
  *
@@ -14,12 +31,13 @@ import { WorkspacePolicy } from "./contracts/workspace-policy.type.mjs";
  *
  * @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");
  */
-declare function createOps(backend: WorkspaceBackend, policy: WorkspacePolicy): WorkspaceOps;
+export declare function createOps(backend: WorkspaceBackend, policy: WorkspacePolicy, runtime?: OpsRuntime): WorkspaceOps;
 //#endregion
-export { createOps };
 //# sourceMappingURL=ops.d.mts.map

package/esm/ops.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ops.d.mts","names":[],"sources":["../../../../../../../packages/ai-workspace/src/ops.ts"],"mappings":";;;;;;;;;AAunBA;;;;;;;;;;;;iBAAgB,SAAA,CACd,OAAA,EAAS,gBAAA,EACT,MAAA,EAAQ,eAAA,GACP,YAAA"}
+{"version":3,"file":"ops.d.mts","names":[],"sources":["../../../../../../../packages/ai-workspace/src/ops.ts"],"mappings":";;;;;;;;;;;;;;;;;iBA8LiB;;EAEf,MAAM;;;;;;;;;;;;;;;;;;;;;wBAitBQ,UACd,SAAS,kBACT,QAAQ,iBACR,UAAU,aACT"}

package/esm/ops.mjs

@@ -1,5 +1,8 @@
 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";
 
@@ -10,6 +13,14 @@ const DEFAULT_READ_LINES = 2e3;
 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
@@ -100,32 +111,6 @@ function capOutput(value, maxBytes) {
 	return clipUtf8(value, maxBytes);
 }
 /**
-* 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}$`);
-}
-/**
 * A quantifier: `+`, `*`, `?`, or a `{m,n}` bound.
 */
 const QUANTIFIER_SOURCE = String.raw`[+*?]|\{\d*,?\d*\}`;
@@ -147,17 +132,11 @@ 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. */
@@ -251,30 +230,76 @@ 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,
@@ -287,11 +312,13 @@ var Ops = class {
 		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),
-			...signal ? { signal } : {}
+			env: buildCommandEnv(this.policy),
+			...signal ? { signal } : {},
+			...interpreter !== "none" ? { interpreter } : {}
 		});
 		const stdout = capOutput(result.stdout, maxOutputBytes);
 		const stderr = capOutput(result.stderr, maxOutputBytes);
@@ -305,6 +332,120 @@ var Ops = class {
 			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",
@@ -328,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({
@@ -375,17 +516,40 @@ var Ops = class {
 	/** 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;
@@ -417,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