@theokit/sdk-tools 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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 {
@@ -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);
@@ -1264,7 +1269,7 @@ function createQuestionTool(opts) {
 var MAX_FILE_SIZE = 5 * 1024 * 1024;
 var BINARY_PROBE_BYTES = 8 * 1024;
 function createReadFileTool(opts) {
-  const { projectRoot } = opts;
+  const { projectRoot, readTracker } = opts;
   return sdk.defineTool({
     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 }.",
@@ -1280,7 +1285,11 @@ function createReadFileTool(opts) {
       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();
       }
@@ -1311,7 +1320,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 +1335,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 +1348,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) {
@@ -1970,38 +2000,111 @@ function createGenericHttpSearchAdapter(opts = {}) {
 }
 var BINARY_PROBE_BYTES3 = 8 * 1024;
 function createWriteFileTool(opts) {
-  const { projectRoot } = opts;
+  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.defineTool({
     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 +2129,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;