stitchkit 0.88.0 → 0.89.0

package/dist/index-cp20z0n6.js

@@ -0,0 +1,1351 @@
+import {
+  assertContainedFileCurrent,
+  assertContainedParentCurrent,
+  containedEntryMetadata,
+  listContainedDirectory,
+  missingContainedDirectories,
+  openContainedFile,
+  openContainedParent,
+  openContainedParentFile,
+  readContainedUtf8Handle,
+  scanContainedFiles,
+  writeContainedFile
+} from "./index-bn2cjajt.js";
+import {
+  missingSandboxRestrictions,
+  probeAgentProcessSandbox
+} from "./index-gskm1k5a.js";
+import {
+  AppError,
+  conflict,
+  forbidden
+} from "./index-0w9abg87.js";
+import {
+  defineRuntimeTool
+} from "./index-kc6h6hg0.js";
+
+// src/agent-runtime/coding-tool-contract.ts
+import { z } from "zod";
+var AgentCodingToolLimitsSchema = z.object({
+  maxPathBytes: z.int().positive(),
+  maxReadBytes: z.int().positive(),
+  maxWriteBytes: z.int().positive(),
+  maxShellArguments: z.int().positive(),
+  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(),
+  shellTimeoutMs: z.int().positive(),
+  shellTerminationGraceMs: z.int().positive()
+}).strict();
+var AgentCodingToolAuthorizationSchema = z.discriminatedUnion("operation", [
+  z.object({ operation: z.literal("read"), path: z.string().min(1) }).strict(),
+  z.object({
+    operation: z.literal("write"),
+    path: z.string().min(1),
+    bytes: z.int().nonnegative(),
+    overwrite: z.boolean(),
+    createsDirectories: z.array(z.string().min(1))
+  }).strict(),
+  z.object({
+    operation: z.literal("search"),
+    query: z.string().min(1),
+    mode: z.enum(["path", "content"])
+  }).strict(),
+  z.object({
+    operation: z.literal("edit"),
+    path: z.string().min(1),
+    baseSha256: z.string().length(64),
+    resultSha256: z.string().length(64),
+    resultBytes: z.int().nonnegative(),
+    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),
+    offset: z.int().nonnegative(),
+    maxBytes: z.int().positive()
+  }).strict(),
+  z.object({
+    operation: z.literal("artifact-search"),
+    reference: z.string().min(1),
+    query: z.string().min(1),
+    maxMatches: z.int().positive()
+  }).strict(),
+  z.object({
+    operation: z.literal("shell"),
+    executable: z.string().min(1),
+    args: z.array(z.string()),
+    cwd: z.string().min(1)
+  }).strict()
+]);
+var AgentCodingToolPathAuthorizationSchema = z.object({ path: z.string().min(1) }).strict();
+var CodingDeniedEntrySchema = z.object({
+  path: z.string().min(1),
+  kind: z.enum(["file", "directory", "symlink", "other"])
+}).strict();
+var FileReadInputSchema = z.object({
+  path: z.string().min(1),
+  offset: z.int().nonnegative().default(0),
+  maxBytes: z.int().positive().optional()
+}).strict();
+var FileReadOutputSchema = z.object({
+  path: z.string().min(1),
+  text: z.string(),
+  bytes: z.int().nonnegative(),
+  sha256: z.string().length(64),
+  truncated: z.boolean(),
+  nextOffset: z.int().nonnegative().optional()
+}).strict();
+var FileWriteInputSchema = z.object({
+  path: z.string().min(1),
+  content: z.string(),
+  overwrite: z.boolean().default(false)
+}).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");
+  }
+  return z.object({
+    executable: z.enum(executableNames),
+    args: z.array(z.string()).default([]),
+    cwd: z.string().min(1).default(".")
+  }).strict();
+}
+var ShellInputSchema = z.object({
+  executable: z.string().min(1),
+  args: z.array(z.string()).default([]),
+  cwd: z.string().min(1).default(".")
+}).strict();
+var ShellOutputSchema = z.object({
+  executable: z.string().min(1),
+  exitCode: z.int().nullable(),
+  signal: z.string().nullable(),
+  stdout: z.string(),
+  stderr: z.string(),
+  outcome: z.enum(["exited", "timeout", "output-limit", "cancelled"]),
+  artifact: z.object({
+    reference: z.string().min(1),
+    bytes: z.int().nonnegative(),
+    truncated: z.boolean(),
+    headBytes: z.int().nonnegative(),
+    tailBytes: z.int().nonnegative(),
+    omittedBytes: z.int().nonnegative()
+  }).strict().optional()
+}).strict();
+var DEFAULT_LIMITS = {
+  maxPathBytes: 4096,
+  maxReadBytes: 262144,
+  maxWriteBytes: 262144,
+  maxShellArguments: 128,
+  maxShellArgumentBytes: 65536,
+  maxShellOutputBytes: 262144,
+  maxArtifactBytes: 4194304,
+  maxListEntries: 500,
+  maxSearchResults: 100,
+  maxSearchFiles: 1e4,
+  maxSearchDepth: 32,
+  shellTimeoutMs: 30000,
+  shellTerminationGraceMs: 250
+};
+function resolveCodingToolLimits(input) {
+  return AgentCodingToolLimitsSchema.parse({ ...DEFAULT_LIMITS, ...input });
+}
+
+// src/agent-runtime/coding-tools.ts
+import path4 from "node:path";
+import { z as z4 } from "zod";
+
+// src/agent-runtime/coding-tool-files.ts
+import { createHash } from "node:crypto";
+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,
+  SANDBOX_UNAVAILABLE: 503,
+  SANDBOX_INSUFFICIENT: 503
+};
+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) {
+    codingRefusal("BAD_REQUEST", `Path exceeds the ${maxPathBytes}-byte limit`, {
+      details: { maxPathBytes },
+      hint: "Use a shorter workspace-relative path."
+    });
+  }
+  if (path.isAbsolute(requested)) {
+    const relative = path.relative(root, requested);
+    const recoveryPath = within(root, requested) ? relative.split(path.sep).join("/") || "." : undefined;
+    codingRefusal("BAD_REQUEST", "Paths must be relative to the workspace root", {
+      details: { path: requested, ...recoveryPath && { recoveryPath } },
+      hint: recoveryPath ? `Use the workspace-relative path \`${recoveryPath}\`.` : "Pass a path relative to the workspace root; absolute paths outside it have no workspace-relative equivalent."
+    });
+  }
+  const resolved = path.resolve(root, requested);
+  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(root, requested, maxPathBytes) {
+  if (path.isAbsolute(requested))
+    inputPath(root, requested, maxPathBytes);
+  if (requested.includes("\\")) {
+    codingRefusal("FORBIDDEN", "Path separators must be `/`", {
+      details: { path: requested },
+      hint: "Use `/` between segments; a backslash is refused because the workspace walk reads it as a separator."
+    });
+  }
+  const segments = requested.split("/");
+  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."
+    });
+  }
+  inputPath(root, requested, maxPathBytes);
+  return requested;
+}
+async function existingCodingPath(root, requested, maxPathBytes) {
+  const resolved = await realpath(inputPath(root, requested, maxPathBytes));
+  if (!within(root, resolved))
+    throw new Error("Coding tool path resolves outside its root");
+  return { absolute: resolved, relative: path.relative(root, resolved) || "." };
+}
+async function authorizeCodingTool(config, request) {
+  const parsed = AgentCodingToolAuthorizationSchema.parse(request);
+  if (!await config.authorize(parsed))
+    forbidden("Coding tool permission denied");
+}
+async function isCodingPathAuthorized(config, path2) {
+  if (!config.authorizePath)
+    return true;
+  const parsed = AgentCodingToolPathAuthorizationSchema.parse({ path: path2 });
+  return await config.authorizePath(parsed);
+}
+async function authorizeCodingPath(config, path2) {
+  if (!await isCodingPathAuthorized(config, path2)) {
+    codingRefusal("FORBIDDEN", "Coding tool path permission denied", {
+      details: { path: path2 },
+      hint: "The host policy refused this path or a directory above it."
+    });
+  }
+}
+async function authorizeCodingPathChain(config, relative) {
+  if (!config.authorizePath)
+    return;
+  const segments = relative === "." ? ["."] : relative.split("/");
+  for (let depth = 1;depth <= segments.length; depth += 1) {
+    await authorizeCodingPath(config, segments.slice(0, depth).join("/"));
+  }
+}
+var codingPathLocks = new Map;
+async function withCodingPathLock(target, work) {
+  const previous = codingPathLocks.get(target) ?? Promise.resolve();
+  let release = () => {
+    return;
+  };
+  const current = new Promise((resolve) => {
+    release = resolve;
+  });
+  const queued = previous.then(() => current);
+  codingPathLocks.set(target, queued);
+  await previous;
+  try {
+    return await work();
+  } finally {
+    release();
+    if (codingPathLocks.get(target) === queued)
+      codingPathLocks.delete(target);
+  }
+}
+function textOccurrences(source, search) {
+  let count = 0;
+  let offset = 0;
+  while (offset <= source.length - search.length) {
+    const found = source.indexOf(search, offset);
+    if (found < 0)
+      break;
+    count += 1;
+    offset = found + search.length;
+  }
+  return count;
+}
+
+// src/agent-runtime/coding-tool-utf8.ts
+function sequenceLength(lead) {
+  if (lead < 128)
+    return 1;
+  if ((lead & 224) === 192)
+    return 2;
+  if ((lead & 240) === 224)
+    return 3;
+  if ((lead & 248) === 240)
+    return 4;
+  return;
+}
+function utf8AlignedEnd(data, start, limit) {
+  const safe = Math.max(start, Math.min(start + limit, data.byteLength));
+  for (let back = 1;back <= 4 && safe - back >= start; back += 1) {
+    const byte = data[safe - back];
+    if ((byte & 192) === 128)
+      continue;
+    const length = sequenceLength(byte);
+    if (length === undefined)
+      return safe;
+    if (back >= length)
+      return safe;
+    const sequenceEnd = safe - back + length;
+    return sequenceEnd <= data.byteLength ? sequenceEnd : safe - back;
+  }
+  return safe;
+}
+function utf8AlignedStart(data, start, end) {
+  let safe = Math.max(0, Math.min(start, end));
+  while (safe < end && (data[safe] & 192) === 128)
+    safe += 1;
+  return safe;
+}
+
+// src/agent-runtime/coding-tool-files.ts
+async function digestFile(handle, size) {
+  const hash = createHash("sha256");
+  const chunk = Buffer.alloc(Math.min(64 * 1024, Math.max(1, size)));
+  for (let position = 0;position < size; ) {
+    const length = Math.min(chunk.byteLength, size - position);
+    const { bytesRead } = await handle.read(chunk, 0, length, position);
+    if (bytesRead === 0)
+      break;
+    hash.update(chunk.subarray(0, bytesRead));
+    position += bytesRead;
+  }
+  return hash.digest("hex");
+}
+function createFileCodingTools(config, limits) {
+  const read = defineRuntimeTool({
+    name: "read_file",
+    description: "Read a bounded UTF-8 slice from a host-authorized workspace file.",
+    identity: { serviceName: "coding", action: "read-file", method: "POST" },
+    input: FileReadInputSchema,
+    output: FileReadOutputSchema,
+    transports: ["AGENT"],
+    handler: async ({ input }) => {
+      const root = await realpath2(config.root);
+      const relative = boundedCodingRelativePath(root, input.path, limits.maxPathBytes);
+      await authorizeCodingPathChain(config, 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 start = input.offset;
+      let size;
+      let sha256;
+      try {
+        await authorizeCodingTool(config, { operation: "read", path: relative });
+        await assertContainedFileCurrent(root, relative, handle);
+        const metadata = await handle.stat();
+        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 + 4, Math.max(0, size - input.offset));
+        selected = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(selected, 0, length, input.offset);
+        selected = selected.subarray(0, bytesRead);
+        if (input.offset > 0) {
+          const aligned = utf8AlignedStart(selected, 0, selected.byteLength);
+          start = input.offset + aligned;
+          selected = selected.subarray(aligned);
+        }
+        if (selected.byteLength > maximum) {
+          selected = selected.subarray(0, utf8AlignedEnd(selected, 0, maximum));
+        }
+        sha256 = await digestFile(handle, size);
+      } finally {
+        await handle.close();
+      }
+      let text;
+      try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(selected);
+      } catch {
+        codingPathRefusal("BAD_REQUEST", "The selected file bytes are not valid UTF-8", relative, {
+          details: { reason: "invalid_utf8" },
+          hint: "Use a binary-capable reader or convert the file to UTF-8."
+        });
+      }
+      const end = start + selected.byteLength;
+      const truncated = end < size;
+      return {
+        path: relative,
+        text,
+        bytes: selected.byteLength,
+        sha256,
+        truncated,
+        ...truncated && { nextOffset: end }
+      };
+    }
+  });
+  const write = defineRuntimeTool({
+    name: "write_file",
+    description: "Write bounded UTF-8 content to a host-authorized workspace file.",
+    identity: { serviceName: "coding", action: "write-file", method: "POST" },
+    input: FileWriteInputSchema,
+    output: FileWriteOutputSchema,
+    transports: ["AGENT"],
+    handler: async ({ input }) => {
+      const root = await realpath2(config.root);
+      const relative = boundedCodingRelativePath(root, input.path, limits.maxPathBytes);
+      await authorizeCodingPathChain(config, relative);
+      const bytes = Buffer.byteLength(input.content);
+      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) {
+          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,
+            replace: true,
+            ...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, createdDirectories: createsDirectories };
+    }
+  });
+  return [read, write];
+}
+
+// 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";
+var DEFAULT_EXCLUDED_DIRECTORIES = [
+  ".git",
+  ".next",
+  ".stitchkit",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules"
+];
+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(),
+  denied: z2.array(CodingDeniedEntrySchema).optional(),
+  deniedTruncated: z2.boolean().optional()
+}).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(),
+  resultTruncated: z2.boolean(),
+  skippedDirectories: z2.int().nonnegative(),
+  scannedFiles: z2.int().nonnegative(),
+  denied: z2.array(CodingDeniedEntrySchema).optional(),
+  deniedTruncated: z2.boolean().optional()
+}).strict();
+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(root, input.path, limits.maxPathBytes);
+      await authorizeCodingPathChain(config, relative);
+      await authorizeCodingTool(config, { operation: "list", path: relative });
+      const listing = await listContainedDirectory(root, relative, limits.maxListEntries, (candidate) => isCodingPathAuthorized(config, candidate)).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,
+        ...listing.denied.length > 0 && {
+          denied: listing.denied.map((entry) => ({
+            path: relative === "." ? entry.name : path2.join(relative, entry.name),
+            kind: entry.kind
+          })),
+          deniedTruncated: listing.deniedTruncated
+        }
+      };
+    }
+  });
+  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 root = await realpath3(config.root);
+      const relative = input.path === "." ? "." : boundedCodingRelativePath(root, input.path, limits.maxPathBytes);
+      await authorizeCodingPathChain(config, relative);
+      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 scan = await scanContainedFiles({
+        root,
+        maxDepth: limits.maxSearchDepth,
+        maxFiles: limits.maxSearchFiles,
+        symlinks: "skip",
+        excludeDirectory: (directory) => directory.split(path2.sep).some((segment) => excluded.has(segment)),
+        authorizePath: (candidate) => isCodingPathAuthorized(config, candidate)
+      });
+      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);
+      const scopedDenied = scan.denied.filter((entry) => entry.relative.startsWith(prefix));
+      const denied = scopedDenied.slice(0, limits.maxSearchResults).map((entry) => ({
+        path: entry.relative,
+        kind: entry.kind
+      }));
+      return {
+        paths,
+        truncated: scan.truncated,
+        resultTruncated: matched.length > paths.length,
+        skippedDirectories: scan.skippedDirectories,
+        scannedFiles: scan.files.length,
+        ...denied.length > 0 && {
+          denied,
+          deniedTruncated: scan.deniedTruncated || scopedDenied.length > denied.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).describe("Anchored `**`/`*`/`?` pattern matched against the whole workspace-relative path. `*` does not cross `/`; use `**/` to include matching files in subdirectories.").optional()
+}).strict();
+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().describe("Files admitted by include and host authorization that reached path or content comparison."),
+  skippedDirectories: z3.int().nonnegative(),
+  skippedSymlinks: z3.int().nonnegative(),
+  denied: z3.array(CodingDeniedEntrySchema).optional(),
+  deniedTruncated: z3.boolean().optional(),
+  hint: z3.string().min(1).optional()
+}).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");
+}
+function createSearchAndPatchCodingTools(config, limits) {
+  const search = defineRuntimeTool({
+    name: "search_files",
+    description: "Search bounded relative paths or UTF-8 file content under the workspace root.",
+    identity: { serviceName: "coding", action: "search", method: "POST" },
+    input: SearchInputSchema,
+    output: SearchOutputSchema,
+    transports: ["AGENT"],
+    handler: async ({ input }) => {
+      await authorizeCodingTool(config, {
+        operation: "search",
+        query: input.query,
+        mode: input.mode
+      });
+      const root = await realpath4(config.root);
+      await authorizeCodingPath(config, ".");
+      const excluded = new Set(config.search?.excludeDirectories ?? DEFAULT_EXCLUDED_DIRECTORIES);
+      const included = input.include ? compileWorkspaceGlob(input.include) : null;
+      let rejectedByInclude = 0;
+      const scan = await scanContainedFiles({
+        root,
+        maxDepth: limits.maxSearchDepth,
+        maxFiles: limits.maxSearchFiles,
+        symlinks: "skip",
+        ...input.mode === "content" && {
+          readMaxBytes: limits.maxReadBytes,
+          skipUnreadable: true
+        },
+        excludeDirectory: (relative) => relative.split(path3.sep).some((segment) => excluded.has(segment)),
+        includeFile: (candidate) => {
+          if (included && !included.test(candidate)) {
+            rejectedByInclude += 1;
+            return false;
+          }
+          return true;
+        },
+        authorizePath: (candidate) => isCodingPathAuthorized(config, candidate)
+      });
+      const matcher = input.regex ? compileSearchRegex(input.query) : 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 (input.mode === "path") {
+          if (hit(file.relative))
+            matches.push({ path: file.relative });
+        } else {
+          const text = file.content?.text;
+          if (text === undefined)
+            continue;
+          const lines = text.split(`
+`);
+          for (let index = 0;index < lines.length; index += 1) {
+            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) {
+          truncated = true;
+          break;
+        }
+      }
+      return {
+        matches,
+        truncated: truncated || scan.truncated,
+        scannedFiles: scan.files.length,
+        skippedDirectories: scan.skippedDirectories,
+        skippedSymlinks: scan.skippedSymlinks,
+        ...scan.denied.length > 0 && {
+          denied: scan.denied.slice(0, limits.maxSearchResults).map(({ relative, kind }) => ({ path: relative, kind })),
+          deniedTruncated: scan.deniedTruncated || scan.denied.length > limits.maxSearchResults
+        },
+        ...input.include && scan.files.length === 0 && rejectedByInclude > 0 && {
+          hint: `The anchored include pattern \`${input.include}\` rejected all ${rejectedByInclude} ${rejectedByInclude === 1 ? "file" : "files"} the scan reached. \`*\` does not cross \`/\`; use a pattern such as \`**/*.ts\` for matching files in subdirectories.`
+        }
+      };
+    }
+  });
+  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 realpath4(config.root);
+      const relative = boundedCodingRelativePath(root, input.path, limits.maxPathBytes);
+      await authorizeCodingPathChain(config, relative);
+      const parent = await openContainedParent(root, relative).catch((error) => refuseMissingCodingPath(error, relative));
+      try {
+        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: read.mode
+            });
+          }
+          return {
+            path: relative,
+            baseSha256,
+            sha256: resultSha256,
+            replacements,
+            bytes,
+            applied: !input.dryRun
+          };
+        });
+      } finally {
+        await parent.handle.close();
+      }
+    }
+  });
+  return [search, edit];
+}
+
+// src/agent-runtime/coding-tool-shell.ts
+import { realpath as realpath5, stat } from "node:fs/promises";
+
+// src/agent-runtime/coding-shell-process.ts
+import { spawn } from "node:child_process";
+async function runCodingShell(input) {
+  const preview = (data, budget) => {
+    if (data.byteLength <= budget) {
+      return { data, headBytes: data.byteLength, tailBytes: 0, omittedBytes: 0 };
+    }
+    const headEnd = utf8AlignedEnd(data, 0, Math.ceil(budget / 2));
+    const tailStart = Math.max(headEnd, utf8AlignedStart(data, data.byteLength - Math.floor(budget / 2), data.byteLength));
+    const tailBytes = data.byteLength - tailStart;
+    return {
+      data: Buffer.concat([data.subarray(0, headEnd), data.subarray(tailStart)]),
+      headBytes: headEnd,
+      tailBytes,
+      omittedBytes: data.byteLength - headEnd - tailBytes
+    };
+  };
+  const retainedPreview = (data) => {
+    const end = utf8AlignedEnd(data, 0, data.byteLength);
+    return {
+      data: data.subarray(0, end),
+      headBytes: end,
+      tailBytes: 0,
+      omittedBytes: data.byteLength - end
+    };
+  };
+  const stdoutHeader = Buffer.from(`--- stdout ---
+`);
+  const stderrHeader = Buffer.from(`
+--- stderr ---
+`);
+  const artifactPayloadLimit = input.maxArtifactBytes - stdoutHeader.byteLength - stderrHeader.byteLength;
+  if (input.artifacts && artifactPayloadLimit < 0)
+    throw new Error("maxArtifactBytes is smaller than the shell artifact envelope");
+  if (input.signal?.aborted) {
+    return ShellOutputSchema.parse({
+      executable: input.executableName,
+      exitCode: null,
+      signal: null,
+      stdout: "",
+      stderr: "",
+      outcome: "cancelled"
+    });
+  }
+  return await new Promise((resolve, reject) => {
+    const ownsProcessGroup = process.platform !== "win32";
+    const child = input.spawn ? input.spawn() : spawn(input.executable, input.args, {
+      cwd: input.cwd,
+      env: input.environment,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: ownsProcessGroup
+    });
+    const stdout = [];
+    const stderr = [];
+    const artifactStdout = [];
+    const artifactStderr = [];
+    let retained = 0;
+    let artifactBytes = 0;
+    let outcome = "exited";
+    let settled = false;
+    let settlementTimer;
+    const cancel = () => terminate("cancelled");
+    const cleanup = () => {
+      clearTimeout(timer);
+      if (settlementTimer)
+        clearTimeout(settlementTimer);
+      input.signal?.removeEventListener("abort", cancel);
+    };
+    const persistAndResolve = async (exitCode, signal) => {
+      if (settled)
+        return;
+      settled = true;
+      cleanup();
+      try {
+        const hasArtifact = input.artifacts && artifactBytes > input.maxOutputBytes;
+        const completeStdout = Buffer.concat(artifactStdout);
+        const completeStderr = Buffer.concat(artifactStderr);
+        const artifactData = hasArtifact ? Buffer.concat([stdoutHeader, completeStdout, stderrHeader, completeStderr]) : undefined;
+        const stdoutBudget = completeStderr.byteLength === 0 ? input.maxOutputBytes : Math.ceil(input.maxOutputBytes / 2);
+        const stderrBudget = completeStdout.byteLength === 0 ? input.maxOutputBytes : Math.floor(input.maxOutputBytes / 2);
+        const stdoutPreview = hasArtifact ? preview(completeStdout, stdoutBudget) : retainedPreview(Buffer.concat(stdout));
+        const stderrPreview = hasArtifact ? preview(completeStderr, stderrBudget) : retainedPreview(Buffer.concat(stderr));
+        const persisted = hasArtifact ? await input.artifacts?.write({
+          mediaType: "text/plain; charset=utf-8",
+          data: artifactData ?? new Uint8Array,
+          ...input.authorization && { authorization: input.authorization }
+        }) : undefined;
+        resolve(ShellOutputSchema.parse({
+          executable: input.executableName,
+          exitCode,
+          signal,
+          stdout: stdoutPreview.data.toString("utf8"),
+          stderr: stderrPreview.data.toString("utf8"),
+          outcome,
+          ...persisted && {
+            artifact: {
+              reference: persisted.reference,
+              bytes: artifactData?.byteLength ?? 0,
+              truncated: outcome === "output-limit",
+              headBytes: stdoutPreview.headBytes + stderrPreview.headBytes,
+              tailBytes: stdoutPreview.tailBytes + stderrPreview.tailBytes,
+              omittedBytes: stdoutPreview.omittedBytes + stderrPreview.omittedBytes
+            }
+          }
+        }));
+      } catch (error) {
+        reject(error);
+      }
+    };
+    const killOwnedProcessGroup = () => {
+      if (!ownsProcessGroup || child.pid === undefined)
+        return false;
+      try {
+        process.kill(-child.pid, "SIGKILL");
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    const boundStreamSettlement = () => {
+      if (settlementTimer)
+        return;
+      settlementTimer = setTimeout(() => {
+        child.stdout.destroy();
+        child.stderr.destroy();
+        persistAndResolve(child.exitCode, child.signalCode);
+      }, input.terminationGraceMs);
+    };
+    const terminate = (reason) => {
+      if (settled || outcome !== "exited")
+        return;
+      outcome = reason;
+      if (!killOwnedProcessGroup())
+        child.kill("SIGKILL");
+      boundStreamSettlement();
+    };
+    const timer = setTimeout(() => terminate("timeout"), input.timeoutMs);
+    timer.unref();
+    const retain = (target, artifactTarget, chunk) => {
+      const remaining = Math.max(0, input.maxOutputBytes - retained);
+      if (remaining > 0) {
+        const kept = chunk.subarray(0, remaining);
+        target.push(kept);
+        retained += kept.byteLength;
+      }
+      if (input.artifacts) {
+        const artifactRemaining = Math.max(0, artifactPayloadLimit - artifactBytes);
+        if (artifactRemaining > 0) {
+          const kept = chunk.subarray(0, artifactRemaining);
+          artifactTarget.push(kept);
+          artifactBytes += kept.byteLength;
+        }
+        if (chunk.byteLength > artifactRemaining)
+          terminate("output-limit");
+      } else if (chunk.byteLength > remaining)
+        terminate("output-limit");
+    };
+    child.stdout.on("data", (chunk) => retain(stdout, artifactStdout, Buffer.from(chunk)));
+    child.stderr.on("data", (chunk) => retain(stderr, artifactStderr, Buffer.from(chunk)));
+    child.on("error", (error) => {
+      if (settled)
+        return;
+      settled = true;
+      cleanup();
+      reject(error);
+    });
+    child.on("exit", (exitCode, signal) => {
+      if (outcome === "exited")
+        killOwnedProcessGroup();
+      boundStreamSettlement();
+      if (child.stdout.destroyed && child.stderr.destroyed) {
+        persistAndResolve(exitCode, signal);
+      }
+    });
+    child.on("close", (exitCode, signal) => void persistAndResolve(exitCode, signal));
+    input.signal?.addEventListener("abort", cancel, { once: true });
+    if (input.signal?.aborted)
+      cancel();
+  });
+}
+
+// src/agent-runtime/coding-tool-shell.ts
+function createShellCodingTool(config, limits) {
+  const executables = config.executables ?? {};
+  const executableNames = Object.keys(executables).sort();
+  return defineRuntimeTool({
+    name: "run_command",
+    description: "Run a finite host-declared executable with bounded arguments, time and output.",
+    identity: { serviceName: "coding", action: "shell", method: "POST" },
+    input: createShellInputSchema(executableNames),
+    output: ShellOutputSchema,
+    transports: ["AGENT"],
+    handler: async ({ input, signal }) => {
+      if (input.args.length > limits.maxShellArguments) {
+        throw new Error("Coding tool shell arguments exceed maxShellArguments");
+      }
+      const argumentBytes = input.args.reduce((total, argument) => total + Buffer.byteLength(argument), 0);
+      if (argumentBytes > limits.maxShellArgumentBytes) {
+        throw new Error("Coding tool shell arguments exceed maxShellArgumentBytes");
+      }
+      const executable = executables[input.executable];
+      if (!executable)
+        throw new Error("Coding tool executable is not declared");
+      const root = await realpath5(config.root);
+      const cwd = await existingCodingPath(root, input.cwd === "." ? "." : boundedCodingRelativePath(root, input.cwd, limits.maxPathBytes), limits.maxPathBytes);
+      if (!(await stat(cwd.absolute)).isDirectory()) {
+        throw new Error("Coding tool cwd is not a directory");
+      }
+      const shellAuthorization = {
+        operation: "shell",
+        executable: input.executable,
+        args: input.args,
+        cwd: cwd.relative
+      };
+      await authorizeCodingTool(config, shellAuthorization);
+      let executablePath = executable;
+      let executableArgs = input.args;
+      let environment = config.environment ?? {};
+      if (config.sandbox) {
+        const grade = await probeAgentProcessSandbox(config.sandbox.adapter);
+        if (grade.grade === "unavailable") {
+          codingRefusal("SANDBOX_UNAVAILABLE", "The configured process sandbox is unavailable", {
+            details: { reason: grade.reason }
+          });
+        }
+        const missing = missingSandboxRestrictions(grade, config.sandbox.required);
+        if (missing.length > 0) {
+          codingRefusal("SANDBOX_INSUFFICIENT", "The process sandbox lacks required restrictions", {
+            details: { missing, grade: grade.grade }
+          });
+        }
+        try {
+          const prepared = await config.sandbox.adapter.prepare({
+            required: config.sandbox.required,
+            executable,
+            args: input.args,
+            cwd: cwd.absolute,
+            environment
+          });
+          executablePath = prepared.executable;
+          executableArgs = [...prepared.args];
+          environment = prepared.environment ?? environment;
+        } catch (error) {
+          const refreshed = await probeAgentProcessSandbox(config.sandbox.adapter, {
+            refresh: true
+          });
+          codingRefusal("SANDBOX_UNAVAILABLE", "The process sandbox failed while preparing a command", {
+            details: {
+              grade: refreshed.grade,
+              reason: error instanceof Error ? error.message : "unknown sandbox error"
+            }
+          });
+        }
+      }
+      return runCodingShell({
+        ...config.sandbox?.adapter.spawn && {
+          spawn: () => {
+            const adapter = config.sandbox?.adapter;
+            if (!adapter?.spawn)
+              throw new Error("Sandbox launcher is unavailable");
+            return adapter.spawn({
+              executable: executablePath,
+              args: executableArgs,
+              cwd: cwd.absolute,
+              environment
+            });
+          }
+        },
+        executableName: input.executable,
+        executable: executablePath,
+        args: executableArgs,
+        cwd: cwd.absolute,
+        environment,
+        ...signal && { signal },
+        timeoutMs: limits.shellTimeoutMs,
+        terminationGraceMs: limits.shellTerminationGraceMs,
+        maxOutputBytes: limits.maxShellOutputBytes,
+        maxArtifactBytes: limits.maxArtifactBytes,
+        ...config.artifacts && { artifacts: config.artifacts },
+        authorization: shellAuthorization
+      });
+    }
+  });
+}
+
+// src/agent-runtime/coding-tools.ts
+var AGENT_CODING_TOOL_NAMES = {
+  editFile: "edit_file",
+  glob: "glob",
+  listDirectory: "list_directory",
+  readFile: "read_file",
+  readOutput: "read_output",
+  searchOutput: "search_output",
+  runCommand: "run_command",
+  searchFiles: "search_files",
+  writeFile: "write_file"
+};
+function createAgentCodingTools(config) {
+  if (!path4.isAbsolute(config.root))
+    throw new Error("Coding tool root must be absolute");
+  for (const executable of Object.values(config.executables ?? {})) {
+    if (!path4.isAbsolute(executable)) {
+      throw new Error("Coding tool executables must be absolute paths");
+    }
+  }
+  const limits = resolveCodingToolLimits(config.limits);
+  const artifactTools = [];
+  if (config.artifacts) {
+    const artifacts = config.artifacts;
+    artifactTools.push(defineRuntimeTool({
+      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: z4.object({
+        reference: z4.string().min(1),
+        offset: z4.int().nonnegative().default(0),
+        maxBytes: z4.int().positive().optional()
+      }).strict(),
+      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 }) => {
+        const maxBytes = Math.min(input.maxBytes ?? limits.maxReadBytes, limits.maxReadBytes);
+        await authorizeCodingTool(config, {
+          operation: "artifact-read",
+          reference: input.reference,
+          offset: input.offset,
+          maxBytes
+        });
+        const originAuthorization = await artifacts.authorization?.(input.reference);
+        if (originAuthorization)
+          await authorizeCodingTool(config, originAuthorization);
+        const result = await artifacts.read({
+          reference: input.reference,
+          offset: input.offset,
+          maxBytes
+        });
+        if (result.data.byteLength > maxBytes)
+          throw new Error("Coding artifact store exceeded the requested byte budget");
+        if (result.totalBytes !== undefined && result.totalBytes < input.offset + result.data.byteLength) {
+          throw new Error("Coding artifact store returned inconsistent totalBytes");
+        }
+        return {
+          reference: input.reference,
+          offset: input.offset,
+          text: new TextDecoder("utf-8", { fatal: true }).decode(result.data),
+          bytes: result.data.byteLength,
+          ...result.totalBytes !== undefined && { totalBytes: result.totalBytes }
+        };
+      }
+    }));
+    if (artifacts.search) {
+      const search = artifacts.search;
+      artifactTools.push(defineRuntimeTool({
+        name: AGENT_CODING_TOOL_NAMES.searchOutput,
+        description: "Search a durable spilled output without loading it into context.",
+        identity: { serviceName: "coding", action: "search-artifact", method: "POST" },
+        input: z4.object({
+          reference: z4.string().min(1),
+          query: z4.string().min(1),
+          maxMatches: z4.int().positive().max(limits.maxSearchResults).default(20)
+        }).strict(),
+        output: z4.object({
+          reference: z4.string(),
+          matches: z4.array(z4.object({ line: z4.int().positive(), text: z4.string() }))
+        }).strict(),
+        transports: ["AGENT"],
+        handler: async ({ input }) => {
+          await authorizeCodingTool(config, {
+            operation: "artifact-search",
+            reference: input.reference,
+            query: input.query,
+            maxMatches: input.maxMatches
+          });
+          const originAuthorization = await artifacts.authorization?.(input.reference);
+          if (originAuthorization)
+            await authorizeCodingTool(config, originAuthorization);
+          return {
+            reference: input.reference,
+            matches: [
+              ...await search({
+                reference: input.reference,
+                query: input.query,
+                maxMatches: input.maxMatches
+              })
+            ]
+          };
+        }
+      }));
+    }
+  }
+  const commandTools = Object.keys(config.executables ?? {}).length ? [createShellCodingTool(config, limits)] : [];
+  return [
+    ...createFileCodingTools(config, limits),
+    ...createListingCodingTools(config, limits),
+    ...createSearchAndPatchCodingTools(config, limits),
+    ...commandTools,
+    ...artifactTools
+  ];
+}
+
+export { codingRefusal, AgentCodingToolLimitsSchema, AgentCodingToolAuthorizationSchema, AgentCodingToolPathAuthorizationSchema, createAgentCodingTools };