stitchkit 0.68.11 → 0.69.0

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

@@ -0,0 +1,706 @@
+import {
+  readContainedUtf8File,
+  scanContainedFiles
+} from "./index-v3dpzpjw.js";
+import {
+  defineRuntimeTool
+} from "./index-wwst0td5.js";
+import"./index-22by16v6.js";
+import"./index-cby4ar3v.js";
+import"./index-qyrqwr4c.js";
+
+// src/agent-runtime/coding-tools.ts
+import path3 from "node:path";
+import { z as z3 } from "zod";
+
+// 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(),
+  maxSearchResults: z.int().positive(),
+  maxSearchFiles: z.int().positive(),
+  maxSearchDepth: z.int().nonnegative(),
+  shellTimeoutMs: 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()
+  }).strict(),
+  z.object({
+    operation: z.literal("search"),
+    query: z.string().min(1),
+    mode: z.enum(["path", "content"])
+  }).strict(),
+  z.object({
+    operation: z.literal("patch"),
+    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("artifact-read"),
+    reference: z.string().min(1),
+    offset: z.int().nonnegative(),
+    maxBytes: 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 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() }).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()
+  }).strict().optional()
+}).strict();
+var DEFAULT_LIMITS = {
+  maxPathBytes: 4096,
+  maxReadBytes: 262144,
+  maxWriteBytes: 262144,
+  maxShellArguments: 128,
+  maxShellArgumentBytes: 65536,
+  maxShellOutputBytes: 262144,
+  maxArtifactBytes: 4194304,
+  maxSearchResults: 100,
+  maxSearchFiles: 1e4,
+  maxSearchDepth: 32,
+  shellTimeoutMs: 30000
+};
+function resolveCodingToolLimits(input) {
+  return AgentCodingToolLimitsSchema.parse({ ...DEFAULT_LIMITS, ...input });
+}
+
+// src/agent-runtime/coding-tool-files.ts
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath as realpath2, stat, writeFile as writeFile2 } from "node:fs/promises";
+
+// src/agent-runtime/coding-tool-paths.ts
+import { lstat, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+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");
+  }
+  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");
+  return resolved;
+}
+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 writableCodingPath(root, requested, maxPathBytes) {
+  const candidate = inputPath(root, requested, maxPathBytes);
+  const parent = await realpath(path.dirname(candidate));
+  if (!within(root, parent))
+    throw new Error("Coding tool parent resolves outside its root");
+  const target = path.join(parent, path.basename(candidate));
+  const metadata = await lstat(target).catch((error) => {
+    if (error.code === "ENOENT")
+      return null;
+    throw error;
+  });
+  if (metadata?.isSymbolicLink())
+    throw new Error("Coding tools do not write through symlinks");
+  return { absolute: target, relative: path.relative(root, target) || "." };
+}
+async function editableCodingPath(root, requested, maxPathBytes) {
+  const candidate = inputPath(root, requested, maxPathBytes);
+  const metadata = await lstat(candidate);
+  if (metadata.isSymbolicLink())
+    throw new Error("Coding tools do not edit symlinks");
+  const resolved = await realpath(candidate);
+  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))
+    throw new Error("Coding tool permission denied");
+}
+async function atomicCodingReplace(target, content, mode) {
+  const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, content, { flag: "wx", ...mode !== undefined && { mode } });
+    await rename(temporary, target);
+  } catch (error) {
+    await unlink(temporary).catch(() => {
+      return;
+    });
+    throw error;
+  }
+}
+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-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 target = await existingCodingPath(root, input.path, limits.maxPathBytes);
+      await authorizeCodingTool(config, { operation: "read", path: target.relative });
+      const maximum = Math.min(input.maxBytes ?? limits.maxReadBytes, limits.maxReadBytes);
+      const handle = await open(target.absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+      let selected;
+      let size;
+      let sha256;
+      try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile())
+          throw new Error("Coding read path is not a regular file");
+        size = metadata.size;
+        const length = Math.min(maximum, 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);
+        sha256 = await digestFile(handle, size);
+      } finally {
+        await handle.close();
+      }
+      const text = new TextDecoder("utf-8", { fatal: true }).decode(selected);
+      const end = input.offset + selected.byteLength;
+      const truncated = end < size;
+      return {
+        path: target.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 target = await writableCodingPath(root, input.path, limits.maxPathBytes);
+      const bytes = Buffer.byteLength(input.content);
+      if (bytes > limits.maxWriteBytes)
+        throw new Error("Coding tool write exceeds maxWriteBytes");
+      await authorizeCodingTool(config, {
+        operation: "write",
+        path: target.relative,
+        bytes,
+        overwrite: input.overwrite
+      });
+      if (input.overwrite) {
+        const current = await stat(target.absolute).catch(() => null);
+        await atomicCodingReplace(target.absolute, input.content, current?.mode);
+      } else {
+        await writeFile2(target.absolute, input.content, { flag: "wx" });
+      }
+      return { path: target.relative, bytes };
+    }
+  });
+  return [read, write];
+}
+
+// src/agent-runtime/coding-tool-search-patch.ts
+import { createHash as createHash2 } from "node:crypto";
+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 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()),
+  truncated: z2.boolean(),
+  scannedFiles: z2.int().nonnegative(),
+  skippedDirectories: z2.int().nonnegative(),
+  skippedSymlinks: 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)
+}).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()
+}).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 realpath3(config.root);
+      const excluded = new Set(config.search?.excludeDirectories ?? DEFAULT_EXCLUDED_DIRECTORIES);
+      const scan = await scanContainedFiles({
+        root,
+        maxDepth: limits.maxSearchDepth,
+        maxFiles: limits.maxSearchFiles,
+        symlinks: "skip",
+        excludeDirectory: (relative) => relative.split(path2.sep).some((segment) => excluded.has(segment))
+      });
+      const matches = [];
+      let truncated = false;
+      for (const file of scan.files) {
+        if (input.mode === "path") {
+          if (file.relative.includes(input.query))
+            matches.push({ path: file.relative });
+        } else {
+          let text;
+          try {
+            text = (await readContainedUtf8File(file.absolute, limits.maxReadBytes)).text;
+          } catch {
+            continue;
+          }
+          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;
+            }
+          }
+        }
+        if (matches.length >= limits.maxSearchResults) {
+          truncated = true;
+          break;
+        }
+      }
+      return {
+        matches,
+        truncated: truncated || scan.truncated,
+        scannedFiles: scan.files.length,
+        skippedDirectories: scan.skippedDirectories,
+        skippedSymlinks: scan.skippedSymlinks
+      };
+    }
+  });
+  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,
+    transports: ["AGENT"],
+    handler: async ({ input }) => {
+      const root = await realpath3(config.root);
+      const target = await editableCodingPath(root, input.path, limits.maxPathBytes);
+      const read = await readContainedUtf8File(target.absolute, limits.maxWriteBytes);
+      const source = read.text;
+      const baseSha256 = sha256(source);
+      if (baseSha256 !== input.baseSha256)
+        throw new Error("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: target.relative,
+        baseSha256,
+        resultSha256,
+        resultBytes: bytes,
+        replacements,
+        dryRun: input.dryRun
+      });
+      if (!input.dryRun) {
+        await withCodingPathLock(target.absolute, async () => {
+          const current = await readContainedUtf8File(target.absolute, limits.maxWriteBytes);
+          if (sha256(current.text) !== baseSha256)
+            throw new Error("Coding patch base digest became stale before apply");
+          await atomicCodingReplace(target.absolute, changed, current.mode);
+        });
+      }
+      return {
+        path: target.relative,
+        baseSha256,
+        resultSha256,
+        replacements,
+        bytes,
+        applied: !input.dryRun
+      };
+    }
+  });
+  return [search, patch];
+}
+
+// src/agent-runtime/coding-tool-shell.ts
+import { spawn } from "node:child_process";
+import { realpath as realpath4, stat as stat2 } from "node:fs/promises";
+async function runShell(input) {
+  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");
+  return await new Promise((resolve, reject) => {
+    const child = spawn(input.executable, input.args, {
+      cwd: input.cwd,
+      env: input.environment,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdout = [];
+    const stderr = [];
+    const artifactStdout = [];
+    const artifactStderr = [];
+    let retained = 0;
+    let artifactBytes = 0;
+    let outcome = "exited";
+    let settled = false;
+    const terminate = (reason) => {
+      if (settled || outcome !== "exited")
+        return;
+      outcome = reason;
+      child.kill("SIGKILL");
+    };
+    const timer = setTimeout(() => terminate("timeout"), input.timeoutMs);
+    timer.unref();
+    const cancel = () => terminate("cancelled");
+    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, chunk));
+    child.stderr.on("data", (chunk) => retain(stderr, artifactStderr, chunk));
+    child.on("error", (error) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      input.signal?.removeEventListener("abort", cancel);
+      reject(error);
+    });
+    child.on("close", async (exitCode, signal) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      input.signal?.removeEventListener("abort", cancel);
+      try {
+        const hasArtifact = input.artifacts && artifactBytes > input.maxOutputBytes;
+        const artifactData = hasArtifact ? Buffer.concat([stdoutHeader, ...artifactStdout, stderrHeader, ...artifactStderr]) : undefined;
+        const persisted = hasArtifact ? await input.artifacts?.write({
+          mediaType: "text/plain; charset=utf-8",
+          data: artifactData ?? new Uint8Array
+        }) : undefined;
+        resolve(ShellOutputSchema.parse({
+          executable: input.executableName,
+          exitCode,
+          signal,
+          stdout: Buffer.concat(stdout).toString("utf8"),
+          stderr: Buffer.concat(stderr).toString("utf8"),
+          outcome,
+          ...persisted && {
+            artifact: {
+              reference: persisted.reference,
+              bytes: artifactData?.byteLength ?? 0,
+              truncated: outcome === "output-limit"
+            }
+          }
+        }));
+      } catch (error) {
+        reject(error);
+      }
+    });
+    input.signal?.addEventListener("abort", cancel, { once: true });
+    if (input.signal?.aborted)
+      cancel();
+  });
+}
+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 realpath4(config.root);
+      const cwd = await existingCodingPath(root, input.cwd, limits.maxPathBytes);
+      if (!(await stat2(cwd.absolute)).isDirectory()) {
+        throw new Error("Coding tool cwd is not a directory");
+      }
+      await authorizeCodingTool(config, {
+        operation: "shell",
+        executable: input.executable,
+        args: input.args,
+        cwd: cwd.relative
+      });
+      return runShell({
+        executableName: input.executable,
+        executable,
+        args: input.args,
+        cwd: cwd.absolute,
+        environment: config.environment ?? {},
+        ...signal && { signal },
+        timeoutMs: limits.shellTimeoutMs,
+        maxOutputBytes: limits.maxShellOutputBytes,
+        maxArtifactBytes: limits.maxArtifactBytes,
+        ...config.artifacts && { artifacts: config.artifacts }
+      });
+    }
+  });
+}
+
+// src/agent-runtime/coding-tools.ts
+var AGENT_CODING_TOOL_NAMES = {
+  applyPatch: "apply_patch",
+  readFile: "read_file",
+  readOutput: "read_output",
+  runCommand: "run_command",
+  searchFiles: "search_files",
+  writeFile: "write_file"
+};
+function createAgentCodingTools(config) {
+  if (!path3.isAbsolute(config.root))
+    throw new Error("Coding tool root must be absolute");
+  for (const executable of Object.values(config.executables ?? {})) {
+    if (!path3.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: z3.object({
+        reference: z3.string().min(1),
+        offset: z3.int().nonnegative().default(0),
+        maxBytes: z3.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()
+      }).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 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 }
+        };
+      }
+    }));
+  }
+  const commandTools = Object.keys(config.executables ?? {}).length ? [createShellCodingTool(config, limits)] : [];
+  return [
+    ...createFileCodingTools(config, limits),
+    ...createSearchAndPatchCodingTools(config, limits),
+    ...commandTools,
+    ...artifactTools
+  ];
+}
+export {
+  AgentCodingToolAuthorizationSchema,
+  AgentCodingToolLimitsSchema,
+  createAgentCodingTools
+};