@warlock.js/ai-workspace 4.5.0

package/esm/ops.mjs

@@ -0,0 +1,294 @@
+import { WorkspaceEditError, WorkspacePolicyError } from "./errors.mjs";
+import { buildEnv, isCommandAllowed, resolveInJail } from "./policy/policy.mjs";
+import path from "node:path";
+import { hashString } from "@warlock.js/fs";
+
+//#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 = 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 = path.dirname(absolutePath);
+		await this.backend.mkdir(parent);
+		await this.backend.writeFile(absolutePath, content);
+		return {
+			hash: 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 = 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: 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 = path.relative(jailRoot, absFile).split(path.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 = path.relative(jailRoot, absFile).split(path.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
+export { createOps };
+//# sourceMappingURL=ops.mjs.map

package/esm/ops.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-workspace/src/ops.ts"],"sourcesContent":["import path from \"node:path\";\nimport { hashString } from \"@warlock.js/fs\";\nimport { WorkspaceEditError, WorkspacePolicyError } from \"./errors\";\nimport { buildEnv, isCommandAllowed, resolveInJail } from \"./policy/policy\";\nimport type {\n  EditFileInput,\n  EditFileResult,\n  GrepMatch,\n  GrepResult,\n  RunShellResult,\n  WorkspaceBackend,\n  WorkspaceOps,\n  WorkspacePolicy,\n} from \"./contracts\";\n\n/** Default line window a read returns when the policy sets no `defaultLines`. */\nconst DEFAULT_READ_LINES = 2000;\n/** Hard ceiling on grep matches returned, so a broad pattern can't flood. */\nconst DEFAULT_MAX_GREP_MATCHES = 1000;\n/** Default per-command output byte cap when the policy sets none. */\nconst DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;\n\n/**\n * Number the lines of `content` `cat -n` style: a right-aligned line\n * number (min width 6), a tab, then the line. `startLine` is the 1-based\n * number of the first line in the window.\n */\nfunction numberLines(content: string, startLine: number): string {\n  const lines = content.split(\"\\n\");\n\n  return lines\n    .map((line, index) => {\n      const lineNumber = startLine + index;\n\n      return `${String(lineNumber).padStart(6, \" \")}\\t${line}`;\n    })\n    .join(\"\\n\");\n}\n\n/**\n * Clip a captured stream at `maxBytes` (measured in UTF-8 bytes).\n * Returns the possibly-clipped string plus whether clipping occurred.\n */\nfunction capOutput(value: string, maxBytes: number): { value: string; truncated: boolean } {\n  const bytes = Buffer.from(value, \"utf8\");\n\n  if (bytes.byteLength <= maxBytes) {\n    return { value, truncated: false };\n  }\n\n  // Slice on a byte boundary; `toString` tolerates a split multi-byte\n  // char at the tail by emitting the replacement character, which is\n  // acceptable for a truncated diagnostic stream.\n  return { value: bytes.subarray(0, maxBytes).toString(\"utf8\"), truncated: true };\n}\n\n/**\n * Minimal glob match over a `/`-separated relative path. Supports `**`\n * (spans separators), `*` (within a segment), and `?` (one non-separator\n * char) — enough for the workspace's `glob`/grep narrowing without\n * pulling in a runtime dependency.\n */\nfunction globToRegExp(glob: string): RegExp {\n  let source = \"\";\n\n  for (let index = 0; index < glob.length; index++) {\n    const char = glob[index];\n\n    if (char === \"*\") {\n      if (glob[index + 1] === \"*\") {\n        source += \".*\";\n        index++;\n\n        if (glob[index + 1] === \"/\") {\n          index++;\n        }\n      } else {\n        source += \"[^/]*\";\n      }\n\n      continue;\n    }\n\n    if (char === \"?\") {\n      source += \"[^/]\";\n\n      continue;\n    }\n\n    source += char.replace(/[.+^${}()|[\\]\\\\]/g, \"\\\\$&\");\n  }\n\n  return new RegExp(`^${source}$`);\n}\n\n/**\n * The internal, single-instance implementation of {@link WorkspaceOps}.\n * Holds the backend + policy and is the one place the jail, command\n * gating, read caps, and the read-before-edit guard are enforced — both\n * the agent-facing tools and the human-facing direct methods funnel\n * through this object, so there is exactly one set of rules.\n */\nclass Ops implements WorkspaceOps {\n  public constructor(\n    private readonly backend: WorkspaceBackend,\n    private readonly policy: WorkspacePolicy,\n  ) {}\n\n  /**\n   * Recursively collect every file under `absDir` as absolute paths,\n   * via the backend's `list` (so it works over disk or the in-memory\n   * mock). Directories are descended; files are accumulated.\n   */\n  private async walkFiles(absDir: string): Promise<string[]> {\n    const found: string[] = [];\n    const entries = await this.backend.list(absDir);\n\n    await Promise.all(\n      entries.map(async (entry) => {\n        // A child is a directory iff listing it succeeds; the backend\n        // throws/returns for a file. Probe via `exists` + a list guard.\n        const isDir = await this.isDirectory(entry);\n\n        if (isDir) {\n          const nested = await this.walkFiles(entry);\n          found.push(...nested);\n        } else {\n          found.push(entry);\n        }\n      }),\n    );\n\n    return found;\n  }\n\n  /** Whether an absolute path is a directory, by attempting to list it. */\n  private async isDirectory(absPath: string): Promise<boolean> {\n    try {\n      await this.backend.list(absPath);\n\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  public async readFile(\n    inputPath: string,\n    opts?: { offset?: number; limit?: number },\n  ): Promise<{ content: string; hash: string; totalLines: number }> {\n    const { absolutePath } = await resolveInJail(this.policy, inputPath);\n    const raw = await this.backend.readFile(absolutePath);\n\n    // Hash the content the backend returned (SHA-256 via @warlock.js/fs),\n    // not the on-disk file — the mock backend keeps content in memory,\n    // and hashing the returned bytes is what the stale-edit guard later\n    // compares against, so it must be the SAME source of truth.\n    const hash = hashString(raw);\n\n    const lines = raw.split(\"\\n\");\n    const totalLines = lines.length;\n\n    const offset = Math.max(1, opts?.offset ?? 1);\n    const limit = opts?.limit ?? this.policy.read?.defaultLines ?? DEFAULT_READ_LINES;\n\n    const startIndex = offset - 1;\n    const window = lines.slice(startIndex, startIndex + limit);\n    const content = numberLines(window.join(\"\\n\"), offset);\n\n    return { content, hash, totalLines };\n  }\n\n  public async writeFile(\n    inputPath: string,\n    content: string,\n  ): Promise<{ hash: string; bytesWritten: number }> {\n    const { absolutePath } = await resolveInJail(this.policy, inputPath);\n\n    // Ensure the parent directory exists before writing the leaf.\n    const parent = path.dirname(absolutePath);\n    await this.backend.mkdir(parent);\n\n    await this.backend.writeFile(absolutePath, content);\n\n    return {\n      hash: hashString(content),\n      bytesWritten: Buffer.byteLength(content, \"utf8\"),\n    };\n  }\n\n  public async editFile(input: EditFileInput): Promise<EditFileResult> {\n    const { absolutePath, relativePath } = await resolveInJail(this.policy, input.path);\n    const current = await this.backend.readFile(absolutePath);\n    const currentHash = hashString(current);\n\n    // Stale-hash guard: if the caller pinned a hash and the file moved\n    // underneath them, refuse so they re-read before clobbering.\n    if (input.expectHash !== undefined && input.expectHash !== currentHash) {\n      throw new WorkspaceEditError(\n        `File \"${input.path}\" changed since it was read; the edit is stale.`,\n        {\n          type: \"stale-hash\",\n          path: relativePath || input.path,\n          expectedHash: input.expectHash,\n          actualHash: currentHash,\n        },\n      );\n    }\n\n    const occurrences = countOccurrences(current, input.oldString);\n\n    if (occurrences === 0) {\n      throw new WorkspaceEditError(\n        `The text to replace was not found in \"${input.path}\".`,\n        { type: \"not-found\", path: relativePath || input.path, matches: 0 },\n      );\n    }\n\n    if (occurrences > 1 && !input.replaceAll) {\n      throw new WorkspaceEditError(\n        `The text to replace is not unique in \"${input.path}\" (${occurrences} matches); ` +\n          `pass replaceAll or include more surrounding context.`,\n        { type: \"not-unique\", path: relativePath || input.path, matches: occurrences },\n      );\n    }\n\n    const updated = input.replaceAll\n      ? current.split(input.oldString).join(input.newString)\n      : replaceFirst(current, input.oldString, input.newString);\n\n    await this.backend.writeFile(absolutePath, updated);\n\n    return {\n      path: relativePath || input.path,\n      replacements: input.replaceAll ? occurrences : 1,\n      hash: hashString(updated),\n    };\n  }\n\n  public async exec(\n    command: string,\n    opts?: { timeoutMs?: number },\n  ): Promise<RunShellResult> {\n    if (!isCommandAllowed(this.policy, command)) {\n      throw new WorkspacePolicyError(\n        `Command is not permitted by the workspace shell policy: ${command}`,\n        { type: \"denied-command\", command },\n      );\n    }\n\n    const shell = this.policy.shell;\n    const timeoutMs = opts?.timeoutMs ?? shell?.timeoutMs;\n    const maxOutputBytes = shell?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;\n\n    const result = await this.backend.exec(command, {\n      cwd: this.policy.cwd,\n      timeoutMs,\n      env: buildEnv(this.policy),\n    });\n\n    const stdout = capOutput(result.stdout, maxOutputBytes);\n    const stderr = capOutput(result.stderr, maxOutputBytes);\n\n    return {\n      exitCode: result.exitCode,\n      stdout: stdout.value,\n      stderr: stderr.value,\n      truncated: stdout.truncated || stderr.truncated,\n      timedOut: result.timedOut,\n    };\n  }\n\n  public async grep(\n    pattern: string,\n    opts?: { glob?: string; ignoreCase?: boolean },\n  ): Promise<GrepResult> {\n    const { absolutePath: jailRoot } = await resolveInJail(this.policy, \".\");\n    const flags = opts?.ignoreCase ? \"i\" : \"\";\n    const regex = new RegExp(pattern, flags);\n    const globRegex = opts?.glob ? globToRegExp(opts.glob) : undefined;\n\n    const files = await this.walkFiles(jailRoot);\n    const matches: GrepMatch[] = [];\n\n    for (const absFile of files) {\n      const relativePath = path.relative(jailRoot, absFile).split(path.sep).join(\"/\");\n\n      if (globRegex && !globRegex.test(relativePath)) {\n        continue;\n      }\n\n      // Skip files the deny list would block (e.g. `.git/**`).\n      if (this.isDenied(relativePath)) {\n        continue;\n      }\n\n      let content: string;\n\n      try {\n        content = await this.backend.readFile(absFile);\n      } catch {\n        // Unreadable entry (vanished, binary handle) — skip, don't fail.\n        continue;\n      }\n\n      const lines = content.split(\"\\n\");\n\n      for (let index = 0; index < lines.length; index++) {\n        if (regex.test(lines[index])) {\n          matches.push({ path: relativePath, line: index + 1, text: lines[index] });\n\n          if (matches.length >= DEFAULT_MAX_GREP_MATCHES) {\n            return { matches, total: matches.length };\n          }\n        }\n      }\n    }\n\n    return { matches, total: matches.length };\n  }\n\n  public async glob(pattern: string): Promise<string[]> {\n    const { absolutePath: jailRoot } = await resolveInJail(this.policy, \".\");\n    const regex = globToRegExp(pattern);\n\n    const files = await this.walkFiles(jailRoot);\n    const matched: string[] = [];\n\n    for (const absFile of files) {\n      const relativePath = path.relative(jailRoot, absFile).split(path.sep).join(\"/\");\n\n      if (this.isDenied(relativePath)) {\n        continue;\n      }\n\n      if (regex.test(relativePath)) {\n        matched.push(relativePath);\n      }\n    }\n\n    return matched.sort();\n  }\n\n  public async exists(inputPath: string): Promise<boolean> {\n    const { absolutePath } = await resolveInJail(this.policy, inputPath);\n\n    return this.backend.exists(absolutePath);\n  }\n\n  public async mkdir(inputPath: string): Promise<void> {\n    const { absolutePath } = await resolveInJail(this.policy, inputPath);\n\n    await this.backend.mkdir(absolutePath);\n  }\n\n  public async remove(inputPath: string): Promise<void> {\n    const { absolutePath } = await resolveInJail(this.policy, inputPath);\n\n    await this.backend.remove(absolutePath);\n  }\n\n  /** Whether a `/`-separated relative path hits the policy deny list. */\n  private isDenied(relativePath: string): boolean {\n    const denyPaths = this.policy.denyPaths;\n\n    if (!denyPaths || denyPaths.length === 0) {\n      return false;\n    }\n\n    return denyPaths.some((glob) => {\n      if (globToRegExp(glob).test(relativePath)) {\n        return true;\n      }\n\n      if (!glob.includes(\"*\") && !glob.includes(\"?\")) {\n        const prefix = glob.endsWith(\"/\") ? glob : `${glob}/`;\n\n        return relativePath.startsWith(prefix);\n      }\n\n      return false;\n    });\n  }\n}\n\n/** Count non-overlapping occurrences of `needle` in `haystack`. */\nfunction countOccurrences(haystack: string, needle: string): number {\n  if (needle === \"\") {\n    return 0;\n  }\n\n  let count = 0;\n  let from = 0;\n\n  // eslint-disable-next-line no-constant-condition\n  while (true) {\n    const index = haystack.indexOf(needle, from);\n\n    if (index === -1) {\n      break;\n    }\n\n    count++;\n    from = index + needle.length;\n  }\n\n  return count;\n}\n\n/** Replace the first occurrence of `needle` with `replacement`. */\nfunction replaceFirst(haystack: string, needle: string, replacement: string): string {\n  const index = haystack.indexOf(needle);\n\n  if (index === -1) {\n    return haystack;\n  }\n\n  return haystack.slice(0, index) + replacement + haystack.slice(index + needle.length);\n}\n\n/**\n * Create the policy-enforced operation layer over a backend.\n *\n * The returned {@link WorkspaceOps} is the single seam both the\n * agent-facing `.tools.*` factories and the human-facing direct methods\n * delegate to — one jail, one command-gate, one read-before-edit guard,\n * regardless of caller. Path inputs are workspace-relative and resolved\n * against `policy.cwd`; escapes and denied commands surface as typed\n * {@link WorkspacePolicyError} / {@link WorkspaceEditError}.\n *\n * @param backend - The dumb IO executor (local disk or in-memory mock).\n * @param policy - The policy that bounds every operation.\n *\n * @example\n * const ops = createOps(localBackend, { cwd: \"/srv/api\", shell: { allow: [\"npm\"] } });\n * const { content, hash } = await ops.readFile(\"src/index.ts\");\n */\nexport function createOps(\n  backend: WorkspaceBackend,\n  policy: WorkspacePolicy,\n): WorkspaceOps {\n  return new Ops(backend, policy);\n}\n"],"mappings":"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"}

package/esm/policy/policy.d.mts

@@ -0,0 +1,71 @@
+import { WorkspacePolicy } from "../contracts/workspace-policy.type.mjs";
+//#region ../@warlock.js/ai-workspace/src/policy/policy.d.ts
+/**
+ * The outcome of resolving a workspace-relative (or absolute) input path
+ * against the jail — the canonical absolute location the backend should
+ * touch, plus the workspace-relative form (POSIX-style, `/`-separated)
+ * the agent and tool results echo back.
+ */
+interface ResolvedPath {
+  /** Canonical absolute path (symlinks in existing ancestors collapsed). */
+  absolutePath: string;
+  /**
+   * The path relative to `policy.cwd`, `/`-separated regardless of OS,
+   * used in tool results so the agent always sees stable workspace paths.
+   * Empty string when the resolved path IS the jail root.
+   */
+  relativePath: string;
+}
+/**
+ * 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");
+ */
+declare function resolveInJail(policy: WorkspacePolicy, inputPath: string): Promise<ResolvedPath>;
+/**
+ * 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
+ */
+declare function isCommandAllowed(policy: WorkspacePolicy, command: string): boolean;
+/**
+ * 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" }
+ */
+declare function buildEnv(policy: WorkspacePolicy): Record<string, string>;
+//#endregion
+export { ResolvedPath, buildEnv, isCommandAllowed, resolveInJail };
+//# sourceMappingURL=policy.d.mts.map

package/esm/policy/policy.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/policy/policy.ts"],"mappings":";;;;;AAWA;;;UAAiB,YAAA;EAQH;EANZ,YAAA;EAkJiC;;;;;EA5IjC,YAAY;AAAA;;;;;;;AA+IS;AA+EvB;;;;;;;;AAEiB;AAyCjB;;iBA7HsB,aAAA,CACpB,MAAA,EAAQ,eAAA,EACR,SAAA,WACC,OAAA,CAAQ,YAAA;;;;;;AA0H8C;;;;;;;;;;;;iBA3CzC,gBAAA,CACd,MAAA,EAAQ,eAAe,EACvB,OAAA;;;;;;;;;;;;;iBAyCc,QAAA,CAAS,MAAA,EAAQ,eAAA,GAAkB,MAAM"}

package/esm/policy/policy.mjs

@@ -0,0 +1,184 @@
+import { WorkspacePolicyError } from "../errors.mjs";
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+
+//#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(target) {
+	let resolvedTarget = path.resolve(target);
+	const tail = [];
+	while (true) try {
+		const real = await realpath(resolvedTarget);
+		return tail.length > 0 ? path.join(real, ...tail) : real;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = path.dirname(resolvedTarget);
+		if (parent === resolvedTarget) return path.join(resolvedTarget, ...tail);
+		tail.unshift(path.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 = path.relative(root, child);
+	return relative === "" || !relative.startsWith("..") && !path.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(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(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(policy.cwd);
+	const absolutePath = await canonicalize(path.isAbsolute(inputPath) ? inputPath : path.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(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 ? path.relative(jailRoot, absolutePath).split(path.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 path.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
+export { buildEnv, isCommandAllowed, resolveInJail };
+//# sourceMappingURL=policy.mjs.map

package/esm/policy/policy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/policy/policy.ts"],"sourcesContent":["import path from \"node:path\";\nimport { realpath } from \"node:fs/promises\";\nimport { WorkspacePolicyError } from \"../errors\";\nimport type { WorkspacePolicy } from \"../contracts\";\n\n/**\n * The outcome of resolving a workspace-relative (or absolute) input path\n * against the jail — the canonical absolute location the backend should\n * touch, plus the workspace-relative form (POSIX-style, `/`-separated)\n * the agent and tool results echo back.\n */\nexport interface ResolvedPath {\n  /** Canonical absolute path (symlinks in existing ancestors collapsed). */\n  absolutePath: string;\n  /**\n   * The path relative to `policy.cwd`, `/`-separated regardless of OS,\n   * used in tool results so the agent always sees stable workspace paths.\n   * Empty string when the resolved path IS the jail root.\n   */\n  relativePath: string;\n}\n\n/**\n * Resolve the canonical absolute form of `target`, collapsing any\n * symlinks. `target` may not yet exist (a fresh `writeFile`/`mkdir`),\n * so we realpath the deepest **existing** ancestor and re-attach the\n * non-existent tail — a symlinked ancestor still cannot smuggle the\n * path out of the jail, while genuinely new leaves stay creatable.\n */\nasync function canonicalize(target: string): Promise<string> {\n  let resolvedTarget = path.resolve(target);\n  const tail: string[] = [];\n\n  // Walk up until an existing ancestor is found (or we hit the root).\n  // eslint-disable-next-line no-constant-condition\n  while (true) {\n    try {\n      const real = await realpath(resolvedTarget);\n\n      return tail.length > 0 ? path.join(real, ...tail) : real;\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code;\n\n      // Only ENOENT means \"this segment doesn't exist yet\" — keep\n      // walking up. Any other error (EACCES, ELOOP, …) is a real fault.\n      if (code !== \"ENOENT\") {\n        throw error;\n      }\n\n      const parent = path.dirname(resolvedTarget);\n\n      // Reached the filesystem root without finding an existing\n      // ancestor — give back the lexically-resolved path unchanged.\n      if (parent === resolvedTarget) {\n        return path.join(resolvedTarget, ...tail);\n      }\n\n      tail.unshift(path.basename(resolvedTarget));\n      resolvedTarget = parent;\n    }\n  }\n}\n\n/**\n * Whether `child` is contained within `root` (or equals it), comparing\n * canonical absolute paths. Guards against the `/srv/app-evil` vs\n * `/srv/app` prefix-collision by anchoring on a path separator.\n */\nfunction isInside(child: string, root: string): boolean {\n  const relative = path.relative(root, child);\n\n  return (\n    relative === \"\" ||\n    (!relative.startsWith(\"..\") && !path.isAbsolute(relative))\n  );\n}\n\n/**\n * Translate a glob (the small subset used by `denyPaths` — `*`, `**`,\n * `?`) into an anchored `RegExp` over a `/`-separated relative path.\n * `**` spans path separators; a single `*` does not.\n */\nfunction globToRegExp(glob: string): RegExp {\n  let source = \"\";\n\n  for (let index = 0; index < glob.length; index++) {\n    const char = glob[index];\n\n    if (char === \"*\") {\n      if (glob[index + 1] === \"*\") {\n        // `**` — match across segments (and an optional trailing slash).\n        source += \".*\";\n        index++;\n\n        if (glob[index + 1] === \"/\") {\n          index++;\n        }\n      } else {\n        // `*` — match within a single segment.\n        source += \"[^/]*\";\n      }\n\n      continue;\n    }\n\n    if (char === \"?\") {\n      source += \"[^/]\";\n\n      continue;\n    }\n\n    // Escape everything else so it matches literally.\n    source += char.replace(/[.+^${}()|[\\]\\\\]/g, \"\\\\$&\");\n  }\n\n  return new RegExp(`^${source}$`);\n}\n\n/**\n * Whether a workspace-relative (`/`-separated) path matches any of the\n * policy's `denyPaths` globs. A deny glob also blocks everything beneath\n * a matched directory (`\".git/**\"` blocks `.git/config`).\n */\nfunction matchesDeny(relativePath: string, denyPaths: string[]): boolean {\n  return denyPaths.some((glob) => {\n    if (globToRegExp(glob).test(relativePath)) {\n      return true;\n    }\n\n    // A bare directory glob (`\".git\"`, `\"node_modules\"`) should also\n    // block its contents, mirroring how `\".git/**\"` would behave.\n    if (!glob.includes(\"*\") && !glob.includes(\"?\")) {\n      const prefix = glob.endsWith(\"/\") ? glob : `${glob}/`;\n\n      return relativePath.startsWith(prefix);\n    }\n\n    return false;\n  });\n}\n\n/**\n * Resolve and jail a single input path against a {@link WorkspacePolicy}.\n *\n * The input is resolved against `policy.cwd`, canonicalized (symlinks in\n * existing ancestors collapsed so a symlinked directory cannot escape\n * the jail), then accepted **only** when it sits under `cwd` or one of\n * the `allowPaths` roots. A path that escapes, or that matches any\n * `denyPaths` glob even while inside `cwd`, is rejected with a\n * {@link WorkspacePolicyError} of type `\"path-escape\"`.\n *\n * @param policy - The bounding policy (its `cwd` is the jail root).\n * @param inputPath - A workspace-relative or absolute path to resolve.\n * @returns The canonical absolute path plus its `/`-separated relative form.\n * @throws {WorkspacePolicyError} When the path escapes the jail or hits a deny glob.\n *\n * @example\n * const { absolutePath } = await resolveInJail(policy, \"src/index.ts\");\n */\nexport async function resolveInJail(\n  policy: WorkspacePolicy,\n  inputPath: string,\n): Promise<ResolvedPath> {\n  const jailRoot = await canonicalize(policy.cwd);\n  const requested = path.isAbsolute(inputPath)\n    ? inputPath\n    : path.join(policy.cwd, inputPath);\n  const absolutePath = await canonicalize(requested);\n\n  const insideCwd = isInside(absolutePath, jailRoot);\n  const allowRoots = policy.allowPaths ?? [];\n  let insideAllow = false;\n\n  if (!insideCwd) {\n    for (const root of allowRoots) {\n      const canonicalRoot = await canonicalize(root);\n\n      if (isInside(absolutePath, canonicalRoot)) {\n        insideAllow = true;\n\n        break;\n      }\n    }\n  }\n\n  if (!insideCwd && !insideAllow) {\n    throw new WorkspacePolicyError(\n      `Path \"${inputPath}\" resolves outside the workspace jail.`,\n      { type: \"path-escape\", path: inputPath },\n    );\n  }\n\n  // `denyPaths` is evaluated relative to the jail root and wins even\n  // when the path is comfortably inside `cwd`.\n  const relativeToJail = insideCwd\n    ? path.relative(jailRoot, absolutePath).split(path.sep).join(\"/\")\n    : \"\";\n\n  if (insideCwd && policy.denyPaths && policy.denyPaths.length > 0) {\n    if (matchesDeny(relativeToJail, policy.denyPaths)) {\n      throw new WorkspacePolicyError(\n        `Path \"${inputPath}\" is blocked by the workspace deny list.`,\n        { type: \"path-escape\", path: inputPath },\n      );\n    }\n  }\n\n  return { absolutePath, relativePath: relativeToJail };\n}\n\n/**\n * Extract the leading executable basename from a command line — the\n * token the shell allow/deny policy is keyed on. `\"npm run build\"` →\n * `\"npm\"`; `\"/usr/bin/node app.js\"` → `\"node\"`; `\"node.exe app\"` →\n * `\"node\"` (the `.exe`/`.cmd`/`.bat` Windows extension is stripped).\n */\nfunction leadingExecutable(command: string): string {\n  const trimmed = command.trim();\n  const firstToken = trimmed.split(/\\s+/)[0] ?? \"\";\n  const base = path.basename(firstToken);\n\n  return base.replace(/\\.(exe|cmd|bat|com)$/i, \"\");\n}\n\n/**\n * Whether a shell command is permitted by the policy's `shell` sub-policy.\n *\n * The command's leading executable basename is matched against\n * `shell.deny` then `shell.allow`. **Deny always wins.** When\n * `shell.allow` is set, the executable MUST appear in it (fail-closed\n * allowlist); when `allow` is absent/empty, any non-denied command is\n * permitted. An absent `shell` block means no command may run at all.\n *\n * Returns a plain `boolean` rather than throwing — the ops layer raises\n * the {@link WorkspacePolicyError} so the thrown context (`command`)\n * lives next to the call site.\n *\n * @example\n * isCommandAllowed({ cwd, shell: { allow: [\"npm\"] } }, \"npm test\"); // true\n * isCommandAllowed({ cwd, shell: { allow: [\"npm\"] } }, \"rm -rf /\"); // false\n */\nexport function isCommandAllowed(\n  policy: WorkspacePolicy,\n  command: string,\n): boolean {\n  const shell = policy.shell;\n\n  // No shell sub-policy ⇒ fail-closed: nothing may run.\n  if (!shell) {\n    return false;\n  }\n\n  const executable = leadingExecutable(command);\n\n  if (executable === \"\") {\n    return false;\n  }\n\n  // Deny wins over everything else.\n  if (shell.deny && shell.deny.includes(executable)) {\n    return false;\n  }\n\n  // An allowlist, when present, is exhaustive.\n  if (shell.allow && shell.allow.length > 0) {\n    return shell.allow.includes(executable);\n  }\n\n  // No allowlist: anything not explicitly denied is permitted.\n  return true;\n}\n\n/**\n * Build the exact environment a spawned process receives — `process.env`\n * is **never** inherited wholesale. The result is\n * `{ ...pick(process.env, inheritEnv), ...shell.env }`, so a command\n * cannot see `PATH` (and thus often cannot find `node`/`npm`) unless the\n * policy opts in via `shell.inheritEnv: [\"PATH\"]`. Explicit `shell.env`\n * values override inherited ones on key collision.\n *\n * @example\n * buildEnv({ cwd, shell: { inheritEnv: [\"PATH\"], env: { CI: \"1\" } } });\n * // → { PATH: <process PATH>, CI: \"1\" }\n */\nexport function buildEnv(policy: WorkspacePolicy): Record<string, string> {\n  const shell = policy.shell;\n  const env: Record<string, string> = {};\n\n  if (!shell) {\n    return env;\n  }\n\n  for (const key of shell.inheritEnv ?? []) {\n    const value = process.env[key];\n\n    if (value !== undefined) {\n      env[key] = value;\n    }\n  }\n\n  if (shell.env) {\n    for (const [key, value] of Object.entries(shell.env)) {\n      env[key] = value;\n    }\n  }\n\n  return env;\n}\n"],"mappings":"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"}

package/esm/tools/edit-file.d.mts

@@ -0,0 +1,40 @@
+import { EditFileInput, EditFileResult } from "../contracts/tool-io.type.mjs";
+import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/edit-file.d.ts
+/**
+ * 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
+ */
+declare function makeEditFileTool(ops: WorkspaceOps, options?: {
+  name?: string;
+}): ToolContract<EditFileInput, EditFileResult>;
+//#endregion
+export { makeEditFileTool };
+//# sourceMappingURL=edit-file.d.mts.map