@theokit/sdk-tools 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.9.1
+
+### Patch Changes
+
+- 9dc221b: SE31 gap closure — wire the read-side file factories to the optional `filesystem` backend. `createReadFileTool` and `createListDirTool` now accept the same optional `filesystem` provider as `createWriteFileTool`, so a per-request / multi-tenant root isolates READS and LISTINGS too (previously only writes routed through the backend). Omitted ⇒ identical current behavior (local process fs). `createGlobTool` / `createSearchTextTool` remain on local fs in v1 — they need recursive traversal the minimal non-recursive `FilesystemBackend` seam does not expose (deferred follow-up).
+
+## 0.9.0
+
+### Minor Changes
+
+- 3af329f: **SE31 — `Filesystem` provider seam (`@theokit/sdk/filesystem`).**
+
+  A pluggable filesystem _storage_ provider, the storage-side twin of `@theokit/sdk/sandbox`. `FilesystemBackend` is an abstract class with four methods (`readFile` / `writeFile` / `stat` / `list`), an `exists()` derived on the base, a boundary `basePath`, a `readOnly` flag, structured `stat().mtimeMs` (the read-before-write oracle for SE32), and typed errors (`FileNotFoundError` / `FilesystemSecurityError` / `FilesystemReadOnlyError` / `StaleFileError`). `LocalFilesystem` is the local-process implementation, boundary-enforced by reusing the core path-guard (traversal + symlink escape → `FilesystemSecurityError`). `FilesystemProvider` + `resolveFilesystem` support a per-request resolver `(ctx) => FilesystemBackend` for multi-tenant roots.
+
+  Unlike `SandboxBackend` (whose file ops shell out via `execute`, require command execution, and give no structured `stat`), a `FilesystemBackend` serves a filesystem-only workspace with no sandbox — see ADR 0011 for why file ops are NOT routed through `SandboxBackend`. `@theokit/sdk-tools`' `createWriteFileTool` now accepts an optional `filesystem` backend (writes route through it; omitted ⇒ identical local-`projectRoot` behavior). This is the backend seam, NOT a bundled `Workspace` and NOT a new toolset — bring-your-own-tools stands; `mounts`/FUSE, S3/GCS, and LSP remain out of core. From the Mastra Workspaces comparison (SDK Evolution roadmap SE31).
+
+- 84df83a: **SE32 — read-before-write safety (`requireReadBeforeWrite` + `ReadTracker`).**
+
+  An opt-in guard on `createWriteFileTool` that refuses to blindly overwrite a file the agent has not seen. A per-run `ReadTracker` (exported from `@theokit/sdk-tools`) records each file's mtime when `createReadFileTool` reads it; when `createWriteFileTool` is created with `{ requireReadBeforeWrite: true, readTracker }`, a write is refused with `read_required` if the existing file was never read, or `stale_file` if it changed on disk since it was read. A NEW file writes freely (nothing to clobber). Default OFF — omitting the flag preserves current behavior exactly.
+
+  Works on both the local `projectRoot` path and the SE31 `filesystem` backend path (the backend also gets `expectedMtime` forwarded so it re-checks at write time — TOCTOU defense). The tracker is deliberately per-instance, not a global singleton, so state never leaks across runs. `edit_file` already has implicit read-before-write safety via `old_string` content matching, so the guard targets the blind-overwrite path (`write_file`). Mirrors Mastra Workspaces' read-before-write (`FileReadRequiredError` / `StaleFileError`). From the Mastra Workspaces comparison (SDK Evolution roadmap SE32).
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -10,6 +10,7 @@ var pathSafety = require('@theokit/sdk/path-safety');
 var child_process = require('child_process');
 var promises$1 = require('dns/promises');
 var net = require('net');
+var filesystem = require('@theokit/sdk/filesystem');
 
 // src/apply-patch.ts
 var PathTraversalError = class extends sdk.ConfigurationError {
@@ -104,7 +105,7 @@ function isForbiddenPath(input) {
 // src/apply-patch.ts
 function createApplyPatchTool(opts) {
   const { projectRoot } = opts;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "apply_patch",
     description: "Apply a unified diff patch to project files. Each file in the diff is security-checked against the project root. Creates .bak backups before modifying. Returns { ok, files_patched } or { ok: false, error }.",
     inputSchema: zod.z.object({
@@ -266,7 +267,7 @@ function createSessionArtifactStore(options) {
 }
 function createEditFileTool(opts) {
   const { projectRoot } = opts;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "edit_file",
     description: "Make an exact string replacement in a project-relative file. Replaces the FIRST occurrence of old_string with new_string (a whitespace-normalized fallback is attempted if the exact match fails) and writes a .bak backup first. Read the file first so old_string matches the on-disk text exactly; include enough surrounding context to make it unique \u2014 only the first match is replaced, so a too-short old_string can edit the wrong location. old_string must be non-empty and differ from new_string; to change every occurrence, call edit_file repeatedly. Returns { ok, replacements } or { ok: false, error }.",
     inputSchema: zod.z.object({
@@ -443,7 +444,7 @@ function createGitDiffTool(opts) {
     timeoutMs = DEFAULT_TIMEOUT_MS,
     maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES
   } = opts;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "git_diff",
     description: "Return the unified diff of the project's working tree (or staged changes when cached=true). Scoped to a single file when 'path' is provided. Requires the project to be a git repository. Returns { ok, diff, truncated? } or { ok: false, error }.",
     inputSchema: zod.z.object({
@@ -525,7 +526,7 @@ function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
 function createGlobTool(opts) {
   const { projectRoot } = opts;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "glob_files",
     description: "Find files by glob pattern across the project \u2014 fast at any repo size. Use glob_files when you know the filename SHAPE; use search_text when you know the file CONTENT; use read_file when you know the exact path. The pattern supports * and ** wildcards (e.g. '**/*.ts', 'src/**/*.json'); node_modules/.git/dist/.theo are excluded and results are relative paths. Returns { ok, files } or { ok: false, error }.",
     inputSchema: zod.z.object({
@@ -1054,7 +1055,10 @@ function withToolResultGuidance(tool, guidance) {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
-    handler: async (input) => injectGuidance(await tool.handler(input), guidance)
+    handler: async (input) => {
+      const out = await tool.handler(input);
+      return typeof out === "string" ? injectGuidance(out, guidance) : out;
+    }
   };
 }
 function withDefaultGuidance(tool) {
@@ -1068,6 +1072,7 @@ function withShellExitGuidance(tool) {
     inputSchema: tool.inputSchema,
     handler: async (input) => {
       const out = await tool.handler(input);
+      if (typeof out !== "string") return out;
       let parsed;
       try {
         parsed = JSON.parse(out);
@@ -1084,26 +1089,61 @@ function withShellExitGuidance(tool) {
 }
 var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
-  const { projectRoot, max = DEFAULT_MAX_ENTRIES } = opts;
-  return sdk.defineTool({
+  const { projectRoot, max = DEFAULT_MAX_ENTRIES, filesystem: filesystem$1 } = opts;
+  return sdk.Tool.create({
     name: "list_dir",
     description: `Return the direct entries of a project-relative directory. Refuses paths outside the project root or in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files). Caps at ${String(max)} entries by default; result carries truncated + totalCount.`,
     inputSchema: zod.z.object({
       path: zod.z.string().min(1).describe("Project-relative directory path. Use '.' for root.")
     }),
-    handler: async ({ path }) => {
+    handler: async ({ path }, ctx) => {
       const relative2 = path === "" || path === "." ? "." : path;
       if (relative2 !== "." && isForbiddenPath(relative2)) {
         return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
-      const boundary = resolveDirBoundary(relative2, projectRoot, path);
-      if ("error" in boundary) return boundary.error;
-      const readResult = await readDirSafe(boundary.absolutePath, path);
-      if ("error" in readResult) return readResult.error;
-      return formatListing(readResult.dirents, max);
+      if (filesystem$1) {
+        const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
+        return listViaBackend(backend, relative2, path, max);
+      }
+      return listViaLocalFs(projectRoot, relative2, path, max);
     }
   });
 }
+async function listViaLocalFs(projectRoot, relative2, originalPath, max) {
+  const boundary = resolveDirBoundary(relative2, projectRoot, originalPath);
+  if ("error" in boundary) return boundary.error;
+  const readResult = await readDirSafe(boundary.absolutePath, originalPath);
+  if ("error" in readResult) return readResult.error;
+  return formatListing(readResult.dirents, max);
+}
+async function listViaBackend(backend, relative2, originalPath, max) {
+  let names;
+  try {
+    names = await backend.list(relative2);
+  } catch (err) {
+    if (err instanceof filesystem.FileNotFoundError) {
+      return JSON.stringify({ ok: false, error: "not_found", path: originalPath });
+    }
+    if (err instanceof filesystem.FilesystemSecurityError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path: originalPath });
+    }
+    throw err;
+  }
+  const totalCount = names.length;
+  const windowed = names.slice(0, max);
+  const entries = await Promise.all(
+    windowed.map(async (name) => {
+      const child = relative2 === "." ? name : `${relative2}/${name}`;
+      let type = "file";
+      try {
+        type = (await backend.stat(child)).isDirectory ? "directory" : "file";
+      } catch {
+      }
+      return { name, type };
+    })
+  );
+  return JSON.stringify({ ok: true, entries, truncated: totalCount > max, totalCount });
+}
 function resolveDirBoundary(relative2, projectRoot, originalPath) {
   try {
     const absolutePath = relative2 === "." ? projectRoot : safePathJoin(projectRoot, relative2);
@@ -1264,29 +1304,65 @@ function createQuestionTool(opts) {
 var MAX_FILE_SIZE = 5 * 1024 * 1024;
 var BINARY_PROBE_BYTES = 8 * 1024;
 function createReadFileTool(opts) {
-  const { projectRoot } = opts;
-  return sdk.defineTool({
+  const { projectRoot, readTracker, filesystem: filesystem$1 } = opts;
+  return sdk.Tool.create({
     name: "read_file",
     description: "Read a project-relative text file as UTF-8. ALWAYS read a file before you edit it (edit_file) or overwrite it (write_file), so your old_string / new content matches the real bytes exactly. Returns the WHOLE file (there is no offset or line-range parameter); to locate a symbol inside a large file, use search_text instead of re-reading. Refuses paths that escape the project root, sensitive files (.env, .git/, node_modules/, .theo/, lock files), and binary files (null byte in the first 8 KB); caps at 5 MB. Returns { ok, content, size } or { ok: false, error }.",
     inputSchema: zod.z.object({
       path: zod.z.string().min(1).describe("Project-relative file path.")
     }),
-    handler: async ({ path }) => {
+    handler: async ({ path }, ctx) => {
       if (isForbiddenPath(path)) {
         return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
+      if (filesystem$1) {
+        const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
+        return readViaBackend(backend, path, (mtimeMs) => readTracker?.record(path, mtimeMs));
+      }
       const boundary = resolveBoundary(path, projectRoot);
       if ("error" in boundary) return boundary.error;
       const opened = await openHandleSafe(boundary.absolutePath, path);
       if ("error" in opened) return opened.error;
       try {
-        return await readContent(opened.handle, path);
+        return await readContent(
+          opened.handle,
+          path,
+          (mtimeMs) => readTracker?.record(path, mtimeMs)
+        );
       } finally {
         await opened.handle.close();
       }
     }
   });
 }
+async function readViaBackend(backend, path, onRead) {
+  try {
+    const stat2 = await backend.stat(path);
+    if (stat2.size > MAX_FILE_SIZE) {
+      return JSON.stringify({
+        ok: false,
+        error: "too_large",
+        path,
+        size: stat2.size,
+        limit: MAX_FILE_SIZE
+      });
+    }
+    const content = await backend.readFile(path);
+    if (content.includes("\0")) {
+      return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
+    }
+    onRead?.(stat2.mtimeMs);
+    return JSON.stringify({ ok: true, content, size: stat2.size });
+  } catch (err) {
+    if (err instanceof filesystem.FileNotFoundError) {
+      return JSON.stringify({ ok: false, error: "not_found", path });
+    }
+    if (err instanceof filesystem.FilesystemSecurityError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+}
 function resolveBoundary(path, projectRoot) {
   try {
     const absolutePath = safePathJoin(projectRoot, path);
@@ -1311,7 +1387,7 @@ async function openHandleSafe(absolutePath, path) {
     throw err;
   }
 }
-async function readContent(handle, path) {
+async function readContent(handle, path, onRead) {
   const stat2 = await handle.stat();
   if (stat2.size > MAX_FILE_SIZE) {
     return JSON.stringify({
@@ -1326,6 +1402,7 @@ async function readContent(handle, path) {
     return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
   }
   const content = await handle.readFile({ encoding: "utf-8" });
+  onRead?.(stat2.mtimeMs);
   return JSON.stringify({ ok: true, content, size: stat2.size });
 }
 async function isBinaryProbe(handle, size) {
@@ -1338,6 +1415,26 @@ async function isBinaryProbe(handle, size) {
   }
   return false;
 }
+
+// src/read-tracker.ts
+var ReadTracker = class {
+  seen = /* @__PURE__ */ new Map();
+  /** Record the mtime observed when `path` was read. */
+  record(path, mtimeMs) {
+    this.seen.set(path, mtimeMs);
+  }
+  /** The mtime last recorded for `path`, or `undefined` if never read. */
+  expected(path) {
+    return this.seen.get(path);
+  }
+};
+function evaluateReadBeforeWrite(tracker, path, currentMtimeMs) {
+  if (currentMtimeMs === null) return "ok";
+  const recorded = tracker.expected(path);
+  if (recorded === void 0) return "read_required";
+  if (recorded !== currentMtimeMs) return "stale";
+  return "ok";
+}
 var DEFAULT_TIMEOUT_MS2 = 12e4;
 var DEFAULT_MAX_STDOUT_BYTES2 = 10 * 1024 * 1024;
 function createRunVitestTool(opts) {
@@ -1346,7 +1443,7 @@ function createRunVitestTool(opts) {
     timeoutMs = DEFAULT_TIMEOUT_MS2,
     maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES2
   } = opts;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "run_vitest",
     description: "Run the project's vitest suite, optionally scoped to a file or pattern via 'path'. Returns parsed { ok, summary } or { ok: false, error }. Vitest stdout warnings are stripped \u2014 the parser extracts the trailing JSON report.",
     inputSchema: zod.z.object({
@@ -1455,7 +1552,7 @@ function createSearchTextTool(opts) {
     maxMatches = DEFAULT_MAX_MATCHES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE
   } = opts;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "search_text",
     description: `Search file CONTENTS for a LITERAL, CASE-SENSITIVE query across the project tree (the query is matched as a substring, not a regex). Use search_text when you know the content; use glob_files when you know the filename shape; use read_file when you know the exact path. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB; 'path' scopes the search to a subdirectory. Returns up to ${String(maxMatches)} matches as { file, line, preview } \u2014 cite locations to the user as file:line. Returns { ok, matches } or { ok: false, error }.`,
     inputSchema: zod.z.object({
@@ -1566,7 +1663,7 @@ var MAX_TIMEOUT_MS = 3e5;
 var MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
 function createShellTool(opts) {
   const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3, allowCatastrophic = false } = opts;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "shell_exec",
     description: "Execute a shell command in the project directory. Use this for terminal operations \u2014 running tests, git, package managers, build tools. Do NOT use it for file operations (reading, writing, editing, finding files): prefer the specialized read_file/write_file/edit_file/glob_files/search_text tools, which are path-checked and safer. Only commit, push, or change git state when the user explicitly asks. timeout_ms defaults to 30000 (max 300000); stdout/stderr are capped (~5 MB). Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
     inputSchema: zod.z.object({
@@ -1803,7 +1900,7 @@ function createWebFetchTool(opts) {
   const maxRedirects = opts?.maxRedirects;
   const fetchImpl = opts?.fetchImpl;
   const lookup = opts?.lookup;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "web_fetch",
     description: "Fetch the contents of a URL via HTTP/HTTPS. Use only for URLs the user provided or that you are confident help with the task; never invent or guess URLs. Rejects non-http(s) URLs and is SSRF-guarded by default (private/loopback/link-local/cloud-metadata hosts are refused with an ssrf_blocked error). The response body is capped at 1 MB. Returns { ok, content, status_code, content_type } or { ok: false, error }.",
     inputSchema: zod.z.object({
@@ -1890,7 +1987,7 @@ function createWebFetchTool(opts) {
 }
 function createWebSearchTool(opts) {
   const { search, defaultMaxResults = 5 } = opts;
-  return sdk.defineTool({
+  return sdk.Tool.create({
     name: "web_search",
     description: "Search the web for a query \u2014 use when you need current information beyond the repo or your training cutoff (library docs, an error message, an API). Returns a list of results with title, URL, and snippet; follow up with web_fetch on a promising result to read it in full. The search provider is injected by the consumer. Returns { ok, results } or { ok: false, error }.",
     inputSchema: zod.z.object({
@@ -1970,38 +2067,111 @@ function createGenericHttpSearchAdapter(opts = {}) {
 }
 var BINARY_PROBE_BYTES3 = 8 * 1024;
 function createWriteFileTool(opts) {
-  const { projectRoot } = opts;
-  return sdk.defineTool({
+  const { projectRoot, filesystem: filesystem$1 } = opts;
+  if (opts.requireReadBeforeWrite && !opts.readTracker) {
+    throw new Error(
+      "createWriteFileTool: requireReadBeforeWrite is true but no readTracker was provided \u2014 pass the same ReadTracker instance to createReadFileTool and createWriteFileTool."
+    );
+  }
+  const guard = opts.requireReadBeforeWrite ? opts.readTracker : void 0;
+  return sdk.Tool.create({
     name: "write_file",
-    description: "Write UTF-8 content to a project-relative file, creating parent directories as needed. OVERWRITES any existing file at the path. Prefer editing an existing file with edit_file over rewriting it; use write_file to create a NEW file or fully replace a small one. If the file already exists, read_file it first so you do not discard content you have not seen. Refuses paths that escape the project root, sensitive files (.env, .git/, node_modules/, .theo/, lock files), and binary-file overwrites. Returns { ok, path, bytes } or { ok: false, error }.",
+    description: "Write UTF-8 content to a project-relative file, creating parent directories as needed. OVERWRITES any existing file at the path. Prefer editing an existing file with edit_file over rewriting it; use write_file to create a NEW file or fully replace a small one. If the file already exists, read_file it first so you do not discard content you have not seen. Refuses paths that escape the write root and sensitive files (.env, .git/, node_modules/, .theo/, lock files); the default local root also refuses binary-file overwrites. Returns { ok, path, bytes } or { ok: false, error }.",
     inputSchema: zod.z.object({
       path: zod.z.string().min(1).describe("Project-relative file path."),
       content: zod.z.string().describe("UTF-8 content to write.")
     }),
-    handler: async ({ path: path$1, content }) => {
-      if (isForbiddenPath(path$1)) {
-        return JSON.stringify({ ok: false, error: "forbidden_path", path: path$1 });
-      }
-      let absolutePath;
-      try {
-        absolutePath = safePathJoin(projectRoot, path$1);
-        assertNoSymlinkEscape(absolutePath, projectRoot);
-      } catch (err) {
-        if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-          return JSON.stringify({ ok: false, error: "path_traversal", path: path$1 });
-        }
-        throw err;
+    handler: async ({ path, content }, ctx) => {
+      if (isForbiddenPath(path)) {
+        return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
-      if (await isBinaryFile(absolutePath)) {
-        return JSON.stringify({ ok: false, error: "binary_file", path: path$1 });
+      if (filesystem$1) {
+        const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
+        return writeViaBackend(backend, path, content, guard);
       }
-      await promises.mkdir(path.dirname(absolutePath), { recursive: true });
-      await promises.writeFile(absolutePath, content, "utf-8");
-      const bytes = Buffer.byteLength(content, "utf-8");
-      return JSON.stringify({ ok: true, path: path$1, bytes });
+      return writeViaLocalFs(projectRoot, path, content, guard);
     }
   });
 }
+function readBeforeWriteError(guard, path, currentMtimeMs) {
+  if (!guard) return null;
+  const decision = evaluateReadBeforeWrite(guard, path, currentMtimeMs);
+  if (decision === "read_required")
+    return JSON.stringify({ ok: false, error: "read_required", path });
+  if (decision === "stale") return JSON.stringify({ ok: false, error: "stale_file", path });
+  return null;
+}
+async function writeViaLocalFs(projectRoot, path$1, content, guard) {
+  let absolutePath;
+  try {
+    absolutePath = safePathJoin(projectRoot, path$1);
+    assertNoSymlinkEscape(absolutePath, projectRoot);
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path: path$1 });
+    }
+    throw err;
+  }
+  const rbw = readBeforeWriteError(guard, path$1, await statMtimeOrNull(absolutePath));
+  if (rbw) return rbw;
+  if (await isBinaryFile(absolutePath)) {
+    return JSON.stringify({ ok: false, error: "binary_file", path: path$1 });
+  }
+  await promises.mkdir(path.dirname(absolutePath), { recursive: true });
+  await promises.writeFile(absolutePath, content, "utf-8");
+  const bytes = Buffer.byteLength(content, "utf-8");
+  return JSON.stringify({ ok: true, path: path$1, bytes });
+}
+async function statMtimeOrNull(absolutePath) {
+  try {
+    return (await promises.stat(absolutePath)).mtimeMs;
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+async function backendMtimeOrNull(backend, path) {
+  try {
+    return (await backend.stat(path)).mtimeMs;
+  } catch (err) {
+    if (err instanceof filesystem.FileNotFoundError) return null;
+    throw err;
+  }
+}
+async function writeViaBackend(backend, path, content, guard) {
+  try {
+    let expectedMtime;
+    if (guard) {
+      const current = await backendMtimeOrNull(backend, path);
+      const rbw = readBeforeWriteError(guard, path, current);
+      if (rbw) return rbw;
+      expectedMtime = current ?? void 0;
+    }
+    const stat2 = await backend.writeFile(
+      path,
+      content,
+      expectedMtime !== void 0 ? { expectedMtime } : void 0
+    );
+    return JSON.stringify({ ok: true, path, bytes: stat2.size });
+  } catch (err) {
+    return backendErrorToJson(err, path);
+  }
+}
+function backendErrorToJson(err, path) {
+  if (err instanceof filesystem.FilesystemSecurityError) {
+    return JSON.stringify({ ok: false, error: "path_traversal", path });
+  }
+  if (err instanceof filesystem.FilesystemReadOnlyError) {
+    return JSON.stringify({ ok: false, error: "read_only", path });
+  }
+  if (err instanceof filesystem.StaleFileError) {
+    return JSON.stringify({ ok: false, error: "stale_file", path });
+  }
+  if (err instanceof filesystem.FilesystemError) {
+    return JSON.stringify({ ok: false, error: "write_failed", path });
+  }
+  throw err;
+}
 async function isBinaryFile(absolutePath) {
   let handle;
   try {
@@ -2026,6 +2196,7 @@ async function isBinaryFile(absolutePath) {
 
 exports.CatastrophicCommandError = CatastrophicCommandError;
 exports.DEFAULT_TOOL_GUIDANCE = DEFAULT_TOOL_GUIDANCE;
+exports.ReadTracker = ReadTracker;
 exports.RedirectBlockedError = RedirectBlockedError;
 exports.SsrfBlockedError = SsrfBlockedError;
 exports.buildEnvContext = buildEnvContext;