stitchkit 0.70.6 → 0.72.0

package/dist/agent-runtime-coding-tools.js

@@ -2,13 +2,15 @@ import {
   assertContainedFileCurrent,
   assertContainedParentCurrent,
   containedEntryMetadata,
+  listContainedDirectory,
+  missingContainedDirectories,
   openContainedFile,
   openContainedParent,
   openContainedParentFile,
   readContainedUtf8Handle,
   scanContainedFiles,
   writeContainedFile
-} from "./index-1z5xxfst.js";
+} from "./index-rqpdar1e.js";
 import {
   defineRuntimeTool
 } from "./index-wwst0td5.js";
@@ -16,6 +18,7 @@ import"./index-22by16v6.js";
 import"./index-cby4ar3v.js";
 import"./index-vj3vvpaa.js";
 import {
+  AppError,
   conflict,
   forbidden
 } from "./index-0w9abg87.js";
@@ -23,8 +26,8 @@ import"./index-qyrqwr4c.js";
 import"./index-6k1937bx.js";
 
 // src/agent-runtime/coding-tools.ts
-import path3 from "node:path";
-import { z as z3 } from "zod";
+import path4 from "node:path";
+import { z as z4 } from "zod";
 
 // src/agent-runtime/coding-tool-contract.ts
 import { z } from "zod";
@@ -36,6 +39,7 @@ var AgentCodingToolLimitsSchema = z.object({
   maxShellArgumentBytes: z.int().positive(),
   maxShellOutputBytes: z.int().positive(),
   maxArtifactBytes: z.int().positive(),
+  maxListEntries: z.int().positive(),
   maxSearchResults: z.int().positive(),
   maxSearchFiles: z.int().positive(),
   maxSearchDepth: z.int().nonnegative(),
@@ -48,7 +52,8 @@ var AgentCodingToolAuthorizationSchema = z.discriminatedUnion("operation", [
     operation: z.literal("write"),
     path: z.string().min(1),
     bytes: z.int().nonnegative(),
-    overwrite: z.boolean()
+    overwrite: z.boolean(),
+    createsDirectories: z.array(z.string().min(1))
   }).strict(),
   z.object({
     operation: z.literal("search"),
@@ -56,7 +61,7 @@ var AgentCodingToolAuthorizationSchema = z.discriminatedUnion("operation", [
     mode: z.enum(["path", "content"])
   }).strict(),
   z.object({
-    operation: z.literal("patch"),
+    operation: z.literal("edit"),
     path: z.string().min(1),
     baseSha256: z.string().length(64),
     resultSha256: z.string().length(64),
@@ -64,6 +69,12 @@ var AgentCodingToolAuthorizationSchema = z.discriminatedUnion("operation", [
     replacements: z.int().positive(),
     dryRun: z.boolean()
   }).strict(),
+  z.object({ operation: z.literal("list"), path: z.string().min(1) }).strict(),
+  z.object({
+    operation: z.literal("glob"),
+    pattern: z.string().min(1),
+    path: z.string().min(1)
+  }).strict(),
   z.object({
     operation: z.literal("artifact-read"),
     reference: z.string().min(1),
@@ -95,7 +106,11 @@ var FileWriteInputSchema = z.object({
   content: z.string(),
   overwrite: z.boolean().default(false)
 }).strict();
-var FileWriteOutputSchema = z.object({ path: z.string().min(1), bytes: z.int().nonnegative() }).strict();
+var FileWriteOutputSchema = z.object({
+  path: z.string().min(1),
+  bytes: z.int().nonnegative(),
+  createdDirectories: z.array(z.string().min(1))
+}).strict();
 function createShellInputSchema(executableNames) {
   if (executableNames.length === 0) {
     throw new Error("A command tool requires at least one executable alias");
@@ -132,6 +147,7 @@ var DEFAULT_LIMITS = {
   maxShellArgumentBytes: 65536,
   maxShellOutputBytes: 262144,
   maxArtifactBytes: 4194304,
+  maxListEntries: 500,
   maxSearchResults: 100,
   maxSearchFiles: 1e4,
   maxSearchDepth: 32,
@@ -149,23 +165,89 @@ import { realpath as realpath2 } from "node:fs/promises";
 // src/agent-runtime/coding-tool-paths.ts
 import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
+
+// src/agent-runtime/coding-tool-refusals.ts
+var REFUSAL_STATUS = {
+  BAD_REQUEST: 400,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409
+};
+function codingRefusal(code, message, options = {}) {
+  throw new AppError(code, message, REFUSAL_STATUS[code], { message, ...options.details }, options.hint);
+}
+function codingPathRefusal(code, message, path, options = {}) {
+  codingRefusal(code, message, {
+    details: { path, ...options.details },
+    ...options.hint && { hint: options.hint }
+  });
+}
+function refuseMissingCodingPath(error, relative) {
+  const code = error?.code;
+  if (error instanceof Error && error.message.includes("is not a regular file")) {
+    codingPathRefusal("BAD_REQUEST", "This path is not a regular file", relative, {
+      hint: "Use list_directory to see what is here."
+    });
+  }
+  if (code === "ENOENT") {
+    codingPathRefusal("NOT_FOUND", "This path does not exist", relative, {
+      hint: "Use list_directory or glob to find the right path."
+    });
+  }
+  if (code === "ENOTDIR") {
+    codingPathRefusal("BAD_REQUEST", "A segment of this path is not a directory", relative, {
+      hint: "Check the path with list_directory."
+    });
+  }
+  if (code === "ELOOP") {
+    codingPathRefusal("FORBIDDEN", "This path is a symlink, which is not followed", relative, {
+      hint: "Read or write the target directly, by its own workspace-relative path."
+    });
+  }
+  if (code === "EISDIR") {
+    codingPathRefusal("BAD_REQUEST", "This path is not a regular file", relative, {
+      hint: "Use list_directory to see what is here."
+    });
+  }
+  throw error;
+}
+
+// src/agent-runtime/coding-tool-paths.ts
 function within(root, target) {
   const relative = path.relative(root, target);
   return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
 }
 function inputPath(root, requested, maxPathBytes) {
   if (new TextEncoder().encode(requested).byteLength > maxPathBytes) {
-    throw new Error("Coding tool path exceeds maxPathBytes");
+    codingRefusal("BAD_REQUEST", `Path exceeds the ${maxPathBytes}-byte limit`, {
+      details: { maxPathBytes },
+      hint: "Use a shorter workspace-relative path."
+    });
+  }
+  if (path.isAbsolute(requested)) {
+    codingRefusal("BAD_REQUEST", "Paths must be relative to the workspace root", {
+      details: { path: requested },
+      hint: "Drop the leading slash and pass a path relative to the workspace root."
+    });
   }
-  if (path.isAbsolute(requested))
-    throw new Error("Coding tool paths must be relative");
   const resolved = path.resolve(root, requested);
-  if (!within(root, resolved))
-    throw new Error("Coding tool path escapes its root");
+  if (!within(root, resolved)) {
+    codingRefusal("FORBIDDEN", "Path escapes the workspace root", {
+      details: { path: requested },
+      hint: "Stay inside the workspace; `..` segments that leave the root are refused."
+    });
+  }
   return resolved;
 }
 function boundedCodingRelativePath(requested, maxPathBytes) {
   inputPath(path.parse(process.cwd()).root, requested, maxPathBytes);
+  const segments = requested.split(/[\\/]/u);
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    codingRefusal("FORBIDDEN", "Path segments must name real entries under the root", {
+      details: { path: requested },
+      hint: "Pass a plain workspace-relative path — `.`, `..` and empty segments are refused."
+    });
+  }
   return requested;
 }
 async function existingCodingPath(root, requested, maxPathBytes) {
@@ -237,7 +319,7 @@ function createFileCodingTools(config, limits) {
     handler: async ({ input }) => {
       const root = await realpath2(config.root);
       const relative = boundedCodingRelativePath(input.path, limits.maxPathBytes);
-      const handle = await openContainedFile(root, relative);
+      const handle = await openContainedFile(root, relative).catch((error) => refuseMissingCodingPath(error, relative));
       const maximum = Math.min(input.maxBytes ?? limits.maxReadBytes, limits.maxReadBytes);
       let selected;
       let size;
@@ -246,8 +328,11 @@ function createFileCodingTools(config, limits) {
         await authorizeCodingTool(config, { operation: "read", path: relative });
         await assertContainedFileCurrent(root, relative, handle);
         const metadata = await handle.stat();
-        if (!metadata.isFile())
-          throw new Error("Coding read path is not a regular file");
+        if (!metadata.isFile()) {
+          codingPathRefusal("BAD_REQUEST", "This path is not a regular file", relative, {
+            hint: "Use list_directory to see what is here."
+          });
+        }
         size = metadata.size;
         const length = Math.min(maximum, Math.max(0, size - input.offset));
         selected = Buffer.alloc(length);
@@ -281,21 +366,46 @@ function createFileCodingTools(config, limits) {
       const root = await realpath2(config.root);
       const relative = boundedCodingRelativePath(input.path, limits.maxPathBytes);
       const bytes = Buffer.byteLength(input.content);
-      if (bytes > limits.maxWriteBytes)
-        throw new Error("Coding tool write exceeds maxWriteBytes");
-      const parent = await openContainedParent(root, relative);
-      try {
-        await authorizeCodingTool(config, {
-          operation: "write",
-          path: relative,
-          bytes,
-          overwrite: input.overwrite
+      if (bytes > limits.maxWriteBytes) {
+        codingPathRefusal("BAD_REQUEST", `The content is ${bytes} bytes, over the ${limits.maxWriteBytes}-byte limit`, relative, {
+          details: { bytes, maxWriteBytes: limits.maxWriteBytes },
+          hint: "Write a smaller file, or split it."
         });
+      }
+      const createsDirectories = await missingContainedDirectories(root, relative).catch((error) => {
+        if (error.code === "ENOTDIR") {
+          codingPathRefusal("CONFLICT", "A segment of this path is not a directory", relative, {
+            hint: "Write under a different path, or remove the file blocking it."
+          });
+        }
+        throw error;
+      });
+      await authorizeCodingTool(config, {
+        operation: "write",
+        path: relative,
+        bytes,
+        overwrite: input.overwrite,
+        createsDirectories
+      });
+      const parent = await openContainedParent(root, relative, { create: true }).catch((error) => {
+        const code = error.code;
+        if (code === "ENOTDIR" || error instanceof Error && error.message.includes("ancestor is not a directory")) {
+          codingPathRefusal("CONFLICT", "A segment of this path is not a directory", relative, {
+            details: { createsDirectories },
+            hint: "Write under a different path, or remove the file blocking it."
+          });
+        }
+        throw error;
+      });
+      try {
         await assertContainedParentCurrent(root, relative, parent.handle);
+        const current = await containedEntryMetadata(parent);
         if (input.overwrite) {
-          const current = await containedEntryMetadata(parent);
-          if (current?.isSymbolicLink())
-            throw new Error("Coding tools do not overwrite symlinks");
+          if (current?.isSymbolicLink()) {
+            codingPathRefusal("FORBIDDEN", "This path is a symlink", relative, {
+              hint: "Coding tools never write through symlinks; write to the target directly."
+            });
+          }
           await writeContainedFile({
             parent,
             content: input.content,
@@ -303,19 +413,23 @@ function createFileCodingTools(config, limits) {
             ...current && { mode: current.mode }
           });
         } else {
+          if (current) {
+            codingPathRefusal("CONFLICT", "This file already exists", relative, {
+              hint: "Pass overwrite: true to replace it, or edit_file to change part of it."
+            });
+          }
           await writeContainedFile({ parent, content: input.content, replace: false });
         }
       } finally {
         await parent.handle.close();
       }
-      return { path: relative, bytes };
+      return { path: relative, bytes, createdDirectories: createsDirectories };
     }
   });
   return [read, write];
 }
 
-// src/agent-runtime/coding-tool-search-patch.ts
-import { createHash as createHash2 } from "node:crypto";
+// src/agent-runtime/coding-tool-listing.ts
 import { realpath as realpath3 } from "node:fs/promises";
 import path2 from "node:path";
 import { z as z2 } from "zod";
@@ -328,29 +442,190 @@ var DEFAULT_EXCLUDED_DIRECTORIES = [
   "dist",
   "node_modules"
 ];
-var SearchInputSchema = z2.object({ query: z2.string().min(1), mode: z2.enum(["path", "content"]).default("content") }).strict();
-var SearchOutputSchema = z2.object({
-  matches: z2.array(z2.object({ path: z2.string().min(1), line: z2.int().positive().optional() }).strict()),
+var ListInputSchema = z2.object({ path: z2.string().min(1).default(".") }).strict();
+var ListOutputSchema = z2.object({
+  path: z2.string().min(1),
+  entries: z2.array(z2.object({
+    name: z2.string().min(1),
+    kind: z2.enum(["file", "directory", "symlink", "other"]),
+    bytes: z2.int().nonnegative().optional(),
+    excluded: z2.boolean().optional()
+  }).strict()),
+  truncated: z2.boolean()
+}).strict();
+var GlobInputSchema = z2.object({ pattern: z2.string().min(1), path: z2.string().min(1).default(".") }).strict();
+var GlobOutputSchema = z2.object({
+  paths: z2.array(z2.string().min(1)),
   truncated: z2.boolean(),
-  scannedFiles: z2.int().nonnegative(),
+  resultTruncated: z2.boolean(),
   skippedDirectories: z2.int().nonnegative(),
-  skippedSymlinks: z2.int().nonnegative()
+  scannedFiles: z2.int().nonnegative()
 }).strict();
-var PatchInputSchema = z2.object({
-  path: z2.string().min(1),
-  baseSha256: z2.string().length(64),
-  oldText: z2.string().min(1),
-  newText: z2.string(),
-  replaceAll: z2.boolean().default(false),
-  dryRun: z2.boolean().default(true)
+function compileWorkspaceGlob(pattern) {
+  let source = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === "*") {
+      if (pattern[index + 1] === "*") {
+        if (pattern[index + 2] === "/") {
+          source += "(?:[^/]+/)*";
+          index += 2;
+          continue;
+        }
+        source += ".*";
+        index += 1;
+        continue;
+      }
+      source += "[^/]*";
+      continue;
+    }
+    if (character === "?") {
+      source += "[^/]";
+      continue;
+    }
+    source += character?.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") ?? "";
+  }
+  return new RegExp(`^${source}$`);
+}
+function createListingCodingTools(config, limits) {
+  const excluded = new Set(config.search?.excludeDirectories ?? DEFAULT_EXCLUDED_DIRECTORIES);
+  const list = defineRuntimeTool({
+    name: "list_directory",
+    description: "List the direct entries of one workspace directory.",
+    identity: { serviceName: "coding", action: "list-directory", method: "POST" },
+    input: ListInputSchema,
+    output: ListOutputSchema,
+    transports: ["AGENT"],
+    handler: async ({ input }) => {
+      const root = await realpath3(config.root);
+      const relative = input.path === "." ? "." : boundedCodingRelativePath(input.path, limits.maxPathBytes);
+      await authorizeCodingTool(config, { operation: "list", path: relative });
+      const listing = await listContainedDirectory(root, relative, limits.maxListEntries).catch((error) => {
+        if (error instanceof Error && error.message.includes("ancestor is not a directory")) {
+          codingPathRefusal("BAD_REQUEST", "This path is not a directory", relative, {
+            hint: "Pass a directory; use read_file for a file."
+          });
+        }
+        if (error.code === "ENOENT") {
+          codingPathRefusal("NOT_FOUND", "This directory does not exist", relative, {
+            hint: "List a parent directory to see what is there."
+          });
+        }
+        return refuseMissingCodingPath(error, relative);
+      });
+      return {
+        path: relative,
+        entries: listing.entries.map((entry) => ({
+          ...entry,
+          ...entry.kind === "directory" && excluded.has(entry.name) && { excluded: true }
+        })),
+        truncated: listing.truncated
+      };
+    }
+  });
+  const glob = defineRuntimeTool({
+    name: "glob",
+    description: "List workspace files matching a `**`/`*`/`?` pattern.",
+    identity: { serviceName: "coding", action: "glob", method: "POST" },
+    input: GlobInputSchema,
+    output: GlobOutputSchema,
+    transports: ["AGENT"],
+    handler: async ({ input }) => {
+      const relative = input.path === "." ? "." : boundedCodingRelativePath(input.path, limits.maxPathBytes);
+      await authorizeCodingTool(config, {
+        operation: "glob",
+        pattern: input.pattern,
+        path: relative
+      });
+      let matcher;
+      try {
+        matcher = compileWorkspaceGlob(input.pattern);
+      } catch {
+        codingRefusal("BAD_REQUEST", "This glob pattern could not be compiled", {
+          details: { pattern: input.pattern },
+          hint: "Use only `**`, `*` and `?`."
+        });
+      }
+      const root = await realpath3(config.root);
+      const scan = await scanContainedFiles({
+        root,
+        maxDepth: limits.maxSearchDepth,
+        maxFiles: limits.maxSearchFiles,
+        symlinks: "skip",
+        excludeDirectory: (directory) => directory.split(path2.sep).some((segment) => excluded.has(segment))
+      });
+      const prefix = relative === "." ? "" : `${relative}${path2.sep}`;
+      const matched = scan.files.filter((file) => file.relative.startsWith(prefix)).map((file) => file.relative).filter((candidate) => matcher.test(candidate.slice(prefix.length))).sort();
+      const paths = matched.slice(0, limits.maxSearchResults);
+      return {
+        paths,
+        truncated: scan.truncated,
+        resultTruncated: matched.length > paths.length,
+        skippedDirectories: scan.skippedDirectories,
+        scannedFiles: scan.files.length
+      };
+    }
+  });
+  return [list, glob];
+}
+
+// src/agent-runtime/coding-tool-search-patch.ts
+import { createHash as createHash2 } from "node:crypto";
+import { realpath as realpath4 } from "node:fs/promises";
+import path3 from "node:path";
+import { z as z3 } from "zod";
+var SearchInputSchema = z3.object({
+  query: z3.string().min(1),
+  mode: z3.enum(["path", "content"]).default("content"),
+  regex: z3.boolean().default(false),
+  context: z3.int().nonnegative().max(10).default(0),
+  include: z3.string().min(1).optional()
 }).strict();
-var PatchOutputSchema = z2.object({
-  path: z2.string().min(1),
-  baseSha256: z2.string().length(64),
-  resultSha256: z2.string().length(64),
-  replacements: z2.int().positive(),
-  bytes: z2.int().nonnegative(),
-  applied: z2.boolean()
+var SearchOutputSchema = z3.object({
+  matches: z3.array(z3.object({
+    path: z3.string().min(1),
+    line: z3.int().positive().optional(),
+    text: z3.string().optional(),
+    before: z3.array(z3.string()).optional(),
+    after: z3.array(z3.string()).optional()
+  }).strict()),
+  truncated: z3.boolean(),
+  scannedFiles: z3.int().nonnegative(),
+  skippedDirectories: z3.int().nonnegative(),
+  skippedSymlinks: z3.int().nonnegative()
+}).strict();
+function compileSearchRegex(pattern) {
+  if (/\\[1-9]/.test(pattern) || /\(\?<?[=!]/.test(pattern)) {
+    codingRefusal("BAD_REQUEST", "This pattern uses a construct search does not allow", {
+      details: { pattern },
+      hint: "Backreferences and lookaround are refused because they cannot be bounded. Rewrite without them."
+    });
+  }
+  try {
+    return new RegExp(pattern);
+  } catch (error) {
+    codingRefusal("BAD_REQUEST", "This pattern is not a valid regular expression", {
+      details: { pattern, reason: error instanceof Error ? error.message : "unknown" },
+      hint: "Fix the expression, or pass regex: false to search for it literally."
+    });
+  }
+}
+var MAX_SEARCHED_LINE_BYTES = 8192;
+var EditInputSchema = z3.object({
+  path: z3.string().min(1),
+  oldText: z3.string().min(1),
+  newText: z3.string(),
+  replaceAll: z3.boolean().default(false),
+  expectedSha256: z3.string().length(64).optional(),
+  dryRun: z3.boolean().default(false)
+}).strict();
+var EditOutputSchema = z3.object({
+  path: z3.string().min(1),
+  baseSha256: z3.string().length(64),
+  sha256: z3.string().length(64),
+  replacements: z3.int().positive(),
+  bytes: z3.int().nonnegative(),
+  applied: z3.boolean()
 }).strict();
 function sha256(value) {
   return createHash2("sha256").update(value).digest("hex");
@@ -369,7 +644,7 @@ function createSearchAndPatchCodingTools(config, limits) {
         query: input.query,
         mode: input.mode
       });
-      const root = await realpath3(config.root);
+      const root = await realpath4(config.root);
       const excluded = new Set(config.search?.excludeDirectories ?? DEFAULT_EXCLUDED_DIRECTORIES);
       const scan = await scanContainedFiles({
         root,
@@ -380,13 +655,26 @@ function createSearchAndPatchCodingTools(config, limits) {
           readMaxBytes: limits.maxReadBytes,
           skipUnreadable: true
         },
-        excludeDirectory: (relative) => relative.split(path2.sep).some((segment) => excluded.has(segment))
+        excludeDirectory: (relative) => relative.split(path3.sep).some((segment) => excluded.has(segment))
       });
+      const matcher = input.regex ? compileSearchRegex(input.query) : null;
+      const included = input.include ? compileWorkspaceGlob(input.include) : null;
+      const hit = (line) => {
+        if (line.length > MAX_SEARCHED_LINE_BYTES)
+          return false;
+        if (matcher) {
+          matcher.lastIndex = 0;
+          return matcher.test(line);
+        }
+        return line.includes(input.query);
+      };
       const matches = [];
       let truncated = false;
       for (const file of scan.files) {
+        if (included && !included.test(file.relative))
+          continue;
         if (input.mode === "path") {
-          if (file.relative.includes(input.query))
+          if (hit(file.relative))
             matches.push({ path: file.relative });
         } else {
           const text = file.content?.text;
@@ -395,11 +683,20 @@ function createSearchAndPatchCodingTools(config, limits) {
           const lines = text.split(`
 `);
           for (let index = 0;index < lines.length; index += 1) {
-            if (lines[index]?.includes(input.query)) {
-              matches.push({ path: file.relative, line: index + 1 });
-              if (matches.length >= limits.maxSearchResults)
-                break;
-            }
+            const line = lines[index];
+            if (line === undefined || !hit(line))
+              continue;
+            matches.push({
+              path: file.relative,
+              line: index + 1,
+              text: line,
+              ...input.context > 0 && {
+                before: lines.slice(Math.max(0, index - input.context), index),
+                after: lines.slice(index + 1, index + 1 + input.context)
+              }
+            });
+            if (matches.length >= limits.maxSearchResults)
+              break;
           }
         }
         if (matches.length >= limits.maxSearchResults) {
@@ -416,78 +713,92 @@ function createSearchAndPatchCodingTools(config, limits) {
       };
     }
   });
-  const patch = defineRuntimeTool({
-    name: "apply_patch",
-    description: "Dry-run or atomically apply one exact guarded UTF-8 file patch.",
-    identity: { serviceName: "coding", action: "patch-file", method: "POST" },
-    input: PatchInputSchema,
-    output: PatchOutputSchema,
+  const edit = defineRuntimeTool({
+    name: "edit_file",
+    description: "Replace an exact snippet in one workspace file.",
+    identity: { serviceName: "coding", action: "edit-file", method: "POST" },
+    input: EditInputSchema,
+    output: EditOutputSchema,
     transports: ["AGENT"],
     handler: async ({ input }) => {
-      const root = await realpath3(config.root);
+      const root = await realpath4(config.root);
       const relative = boundedCodingRelativePath(input.path, limits.maxPathBytes);
-      const parent = await openContainedParent(root, relative);
+      const parent = await openContainedParent(root, relative).catch((error) => refuseMissingCodingPath(error, relative));
       try {
-        const initial = await openContainedParentFile(parent);
-        const read = await readContainedUtf8Handle(initial, limits.maxWriteBytes).finally(() => initial.close());
-        const source = read.text;
-        const baseSha256 = sha256(source);
-        if (baseSha256 !== input.baseSha256)
-          conflict("Coding patch base digest is stale");
-        const count = textOccurrences(source, input.oldText);
-        if (count === 0)
-          throw new Error("Coding patch text was not found");
-        if (!input.replaceAll && count !== 1)
-          throw new Error("Coding patch text is not unique");
-        const replacements = input.replaceAll ? count : 1;
-        const changed = input.replaceAll ? source.replaceAll(input.oldText, input.newText) : source.replace(input.oldText, input.newText);
-        const bytes = Buffer.byteLength(changed);
-        const resultSha256 = sha256(changed);
-        if (bytes > limits.maxWriteBytes)
-          throw new Error("Coding patch exceeds maxWriteBytes");
-        await authorizeCodingTool(config, {
-          operation: "patch",
-          path: relative,
-          baseSha256,
-          resultSha256,
-          resultBytes: bytes,
-          replacements,
-          dryRun: input.dryRun
-        });
-        await assertContainedParentCurrent(root, relative, parent.handle);
-        if (!input.dryRun) {
-          await withCodingPathLock(`${root}:${relative}`, async () => {
-            const currentHandle = await openContainedParentFile(parent);
-            const current = await readContainedUtf8Handle(currentHandle, limits.maxWriteBytes).finally(() => currentHandle.close());
-            if (sha256(current.text) !== baseSha256)
-              conflict("Coding patch base digest became stale before apply");
+        return await withCodingPathLock(`${root}:${relative}`, async () => {
+          const handle = await openContainedParentFile(parent).catch((error) => refuseMissingCodingPath(error, relative));
+          const read = await readContainedUtf8Handle(handle, limits.maxWriteBytes).finally(() => handle.close());
+          const source = read.text;
+          const baseSha256 = sha256(source);
+          if (input.expectedSha256 !== undefined && baseSha256 !== input.expectedSha256) {
+            conflict("The file changed since it was read", {
+              message: "The file changed since it was read",
+              path: relative,
+              expectedSha256: input.expectedSha256,
+              actualSha256: baseSha256
+            });
+          }
+          const count = textOccurrences(source, input.oldText);
+          if (count === 0) {
+            codingPathRefusal("NOT_FOUND", "oldText does not appear in this file", relative, {
+              details: { occurrences: 0 },
+              hint: "Read the file and copy the snippet exactly, including indentation."
+            });
+          }
+          if (!input.replaceAll && count !== 1) {
+            codingPathRefusal("CONFLICT", `oldText appears ${count} times, so the edit is ambiguous`, relative, {
+              details: { occurrences: count },
+              hint: "Lengthen the snippet until it is unique, or pass replaceAll: true."
+            });
+          }
+          const replacements = input.replaceAll ? count : 1;
+          const changed = input.replaceAll ? source.replaceAll(input.oldText, input.newText) : source.replace(input.oldText, input.newText);
+          const bytes = Buffer.byteLength(changed);
+          const resultSha256 = sha256(changed);
+          if (bytes > limits.maxWriteBytes) {
+            codingPathRefusal("BAD_REQUEST", `The result would be ${bytes} bytes, over the ${limits.maxWriteBytes}-byte limit`, relative, {
+              details: { bytes, maxWriteBytes: limits.maxWriteBytes },
+              hint: "Make a smaller edit, or split the file."
+            });
+          }
+          await authorizeCodingTool(config, {
+            operation: "edit",
+            path: relative,
+            baseSha256,
+            resultSha256,
+            resultBytes: bytes,
+            replacements,
+            dryRun: input.dryRun
+          });
+          await assertContainedParentCurrent(root, relative, parent.handle);
+          if (!input.dryRun) {
             await writeContainedFile({
               parent,
               content: changed,
               replace: true,
-              mode: current.mode
+              mode: read.mode
             });
-          });
-        }
-        return {
-          path: relative,
-          baseSha256,
-          resultSha256,
-          replacements,
-          bytes,
-          applied: !input.dryRun
-        };
+          }
+          return {
+            path: relative,
+            baseSha256,
+            sha256: resultSha256,
+            replacements,
+            bytes,
+            applied: !input.dryRun
+          };
+        });
       } finally {
         await parent.handle.close();
       }
     }
   });
-  return [search, patch];
+  return [search, edit];
 }
 
 // src/agent-runtime/coding-tool-shell.ts
 import { spawn } from "node:child_process";
-import { realpath as realpath4, stat } from "node:fs/promises";
+import { realpath as realpath5, stat } from "node:fs/promises";
 async function runShell(input) {
   const stdoutHeader = Buffer.from(`--- stdout ---
 `);
@@ -654,7 +965,7 @@ function createShellCodingTool(config, limits) {
       const executable = executables[input.executable];
       if (!executable)
         throw new Error("Coding tool executable is not declared");
-      const root = await realpath4(config.root);
+      const root = await realpath5(config.root);
       const cwd = await existingCodingPath(root, input.cwd, limits.maxPathBytes);
       if (!(await stat(cwd.absolute)).isDirectory()) {
         throw new Error("Coding tool cwd is not a directory");
@@ -684,7 +995,9 @@ function createShellCodingTool(config, limits) {
 
 // src/agent-runtime/coding-tools.ts
 var AGENT_CODING_TOOL_NAMES = {
-  applyPatch: "apply_patch",
+  editFile: "edit_file",
+  glob: "glob",
+  listDirectory: "list_directory",
   readFile: "read_file",
   readOutput: "read_output",
   runCommand: "run_command",
@@ -692,10 +1005,10 @@ var AGENT_CODING_TOOL_NAMES = {
   writeFile: "write_file"
 };
 function createAgentCodingTools(config) {
-  if (!path3.isAbsolute(config.root))
+  if (!path4.isAbsolute(config.root))
     throw new Error("Coding tool root must be absolute");
   for (const executable of Object.values(config.executables ?? {})) {
-    if (!path3.isAbsolute(executable)) {
+    if (!path4.isAbsolute(executable)) {
       throw new Error("Coding tool executables must be absolute paths");
     }
   }
@@ -707,17 +1020,17 @@ function createAgentCodingTools(config) {
       name: AGENT_CODING_TOOL_NAMES.readOutput,
       description: "Read a bounded byte slice from one opaque coding output artifact.",
       identity: { serviceName: "coding", action: "read-artifact", method: "POST" },
-      input: z3.object({
-        reference: z3.string().min(1),
-        offset: z3.int().nonnegative().default(0),
-        maxBytes: z3.int().positive().optional()
+      input: z4.object({
+        reference: z4.string().min(1),
+        offset: z4.int().nonnegative().default(0),
+        maxBytes: z4.int().positive().optional()
       }).strict(),
-      output: z3.object({
-        reference: z3.string().min(1),
-        offset: z3.int().nonnegative(),
-        text: z3.string(),
-        bytes: z3.int().nonnegative(),
-        totalBytes: z3.int().nonnegative().optional()
+      output: z4.object({
+        reference: z4.string().min(1),
+        offset: z4.int().nonnegative(),
+        text: z4.string(),
+        bytes: z4.int().nonnegative(),
+        totalBytes: z4.int().nonnegative().optional()
       }).strict(),
       transports: ["AGENT"],
       handler: async ({ input }) => {
@@ -751,6 +1064,7 @@ function createAgentCodingTools(config) {
   const commandTools = Object.keys(config.executables ?? {}).length ? [createShellCodingTool(config, limits)] : [];
   return [
     ...createFileCodingTools(config, limits),
+    ...createListingCodingTools(config, limits),
     ...createSearchAndPatchCodingTools(config, limits),
     ...commandTools,
     ...artifactTools