@theokit/sdk-tools 0.14.0 → 0.15.1

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { CustomTool, ConfigurationError } from '@theokit/sdk';
-import { InteractiveProvider } from '@theokit/sdk/interactive';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
+import { SandboxProvider } from '@theokit/sdk/sandbox';
+import { InteractiveProvider } from '@theokit/sdk/interactive';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -89,6 +90,9 @@ declare function createSessionArtifactStore(options: SessionArtifactStoreOptions
 interface CreateEditFileToolOptions {
     /** Absolute path to the project root. Every edit is gated against this boundary. */
     projectRoot: string;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the read + `.bak` backup +
+     *  write go through the backend (surface-agnostic); omitted ⇒ the local `fs` path (byte-identical). */
+    filesystem?: FilesystemProvider;
 }
 declare function createEditFileTool(opts: CreateEditFileToolOptions): CustomTool;
 
@@ -134,6 +138,9 @@ interface CreateGitDiffToolOptions {
     projectRoot: string;
     timeoutMs?: number;
     maxStdoutBytes?: number;
+    /** Optional injected execution backend (`@theokit/sdk/sandbox`) — when provided, `git diff` runs via
+     *  `SandboxBackend.execute` (surface-agnostic); omitted ⇒ the local `git` child process (unchanged). */
+    sandbox?: SandboxProvider;
 }
 declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 
@@ -151,6 +158,9 @@ declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 interface CreateGlobToolOptions {
     /** Absolute path to the project root. */
     projectRoot: string;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the walk reads through the
+     *  backend (Local/remote), so the tool is surface-agnostic; omitted ⇒ the local `readdir` (unchanged). */
+    filesystem?: FilesystemProvider;
 }
 declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
 
@@ -734,6 +744,9 @@ interface CreateSearchTextToolOptions {
     maxMatches?: number;
     /** Skip files larger than this (bytes). Default 1 MB. */
     maxFileSize?: number;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the recursive walk reads
+     *  through the backend (surface-agnostic); omitted ⇒ the local `readdir`/`readFile` walk (unchanged). */
+    filesystem?: FilesystemProvider;
 }
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 
@@ -760,6 +773,14 @@ interface CreateShellToolOptions {
      * guardrail, not a sandbox.
      */
     allowCatastrophic?: boolean;
+    /**
+     * Optional injected execution backend (`@theokit/sdk/sandbox`) — a backend or a per-request resolver.
+     * When provided, the command runs via `SandboxBackend.execute` (Local/Docker/E2B) so the tool is
+     * surface-agnostic (a cluster/desktop host runs it in the sandbox, not the local host); omitted ⇒ the
+     * local `/bin/sh -c` child process (byte-identical to before). The catastrophic-command guard runs
+     * before either path.
+     */
+    sandbox?: SandboxProvider;
 }
 declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { CustomTool, ConfigurationError } from '@theokit/sdk';
-import { InteractiveProvider } from '@theokit/sdk/interactive';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
+import { SandboxProvider } from '@theokit/sdk/sandbox';
+import { InteractiveProvider } from '@theokit/sdk/interactive';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -89,6 +90,9 @@ declare function createSessionArtifactStore(options: SessionArtifactStoreOptions
 interface CreateEditFileToolOptions {
     /** Absolute path to the project root. Every edit is gated against this boundary. */
     projectRoot: string;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the read + `.bak` backup +
+     *  write go through the backend (surface-agnostic); omitted ⇒ the local `fs` path (byte-identical). */
+    filesystem?: FilesystemProvider;
 }
 declare function createEditFileTool(opts: CreateEditFileToolOptions): CustomTool;
 
@@ -134,6 +138,9 @@ interface CreateGitDiffToolOptions {
     projectRoot: string;
     timeoutMs?: number;
     maxStdoutBytes?: number;
+    /** Optional injected execution backend (`@theokit/sdk/sandbox`) — when provided, `git diff` runs via
+     *  `SandboxBackend.execute` (surface-agnostic); omitted ⇒ the local `git` child process (unchanged). */
+    sandbox?: SandboxProvider;
 }
 declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 
@@ -151,6 +158,9 @@ declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 interface CreateGlobToolOptions {
     /** Absolute path to the project root. */
     projectRoot: string;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the walk reads through the
+     *  backend (Local/remote), so the tool is surface-agnostic; omitted ⇒ the local `readdir` (unchanged). */
+    filesystem?: FilesystemProvider;
 }
 declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
 
@@ -734,6 +744,9 @@ interface CreateSearchTextToolOptions {
     maxMatches?: number;
     /** Skip files larger than this (bytes). Default 1 MB. */
     maxFileSize?: number;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the recursive walk reads
+     *  through the backend (surface-agnostic); omitted ⇒ the local `readdir`/`readFile` walk (unchanged). */
+    filesystem?: FilesystemProvider;
 }
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 
@@ -760,6 +773,14 @@ interface CreateShellToolOptions {
      * guardrail, not a sandbox.
      */
     allowCatastrophic?: boolean;
+    /**
+     * Optional injected execution backend (`@theokit/sdk/sandbox`) — a backend or a per-request resolver.
+     * When provided, the command runs via `SandboxBackend.execute` (Local/Docker/E2B) so the tool is
+     * surface-agnostic (a cluster/desktop host runs it in the sandbox, not the local host); omitted ⇒ the
+     * local `/bin/sh -c` child process (byte-identical to before). The catastrophic-command guard runs
+     * before either path.
+     */
+    sandbox?: SandboxProvider;
 }
 declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
 

package/dist/index.js

@@ -5,11 +5,12 @@ import { z } from 'zod';
 import { existsSync, statSync, mkdirSync, writeFileSync, realpathSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'fs';
 import { safeFilenameForId, safePathJoin as safePathJoin$1 } from '@theokit/sdk/path-safety';
 import { replaceFileAtomic } from '@theokit/sdk/persistence';
+import { resolveFilesystem, FileNotFoundError, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError } from '@theokit/sdk/filesystem';
 import { spawn } from 'child_process';
+import { resolveSandbox } from '@theokit/sdk/sandbox';
 import { resolveInteractive, InteractiveUnavailableError, NoSuchSessionError } from '@theokit/sdk/interactive';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
-import { resolveFilesystem, FileNotFoundError, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError } from '@theokit/sdk/filesystem';
 
 // src/apply-patch.ts
 var PathTraversalError = class extends ConfigurationError {
@@ -348,8 +349,82 @@ ${find}`);
 }
 
 // src/edit-file.ts
+function computeEdit(content, old_string, new_string) {
+  const exactIdx = content.indexOf(old_string);
+  if (exactIdx !== -1) {
+    return {
+      ok: true,
+      result: content.slice(0, exactIdx) + new_string + content.slice(exactIdx + old_string.length)
+    };
+  }
+  const normalizedContent = normalizeWhitespace(content);
+  const normalizedOld = normalizeWhitespace(old_string);
+  const normalizedIdx = normalizedContent.indexOf(normalizedOld);
+  if (normalizedIdx !== -1) {
+    const span = findOriginalSpan(content, normalizedContent, normalizedIdx, normalizedOld.length);
+    return {
+      ok: true,
+      result: content.slice(0, span.start) + new_string + content.slice(span.end)
+    };
+  }
+  try {
+    return { ok: true, result: replaceUnique(content, old_string, new_string) };
+  } catch (err) {
+    if (err instanceof ContextMatchError) return { ok: false, error: "no_match" };
+    throw err;
+  }
+}
+async function editViaBackend(filesystem, ctx, path, old_string, new_string) {
+  const backend = await resolveFilesystem(filesystem, ctx ?? {});
+  let content;
+  try {
+    content = await backend.readFile(path);
+  } catch (err) {
+    if (err instanceof FileNotFoundError) {
+      return JSON.stringify({ ok: false, error: "not_found", path });
+    }
+    throw err;
+  }
+  const outcome = computeEdit(content, old_string, new_string);
+  if (!outcome.ok) return JSON.stringify({ ok: false, error: "no_match", path });
+  await backend.writeFile(`${path}.bak`, content);
+  await backend.writeFile(path, outcome.result);
+  return JSON.stringify({ ok: true, replacements: 1 });
+}
+async function editViaLocal(projectRoot, path, old_string, new_string) {
+  const absolutePath = safePathJoin(projectRoot, path);
+  let content;
+  try {
+    content = await readFile(absolutePath, "utf-8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      return JSON.stringify({ ok: false, error: "not_found", path });
+    }
+    throw err;
+  }
+  const outcome = computeEdit(content, old_string, new_string);
+  if (!outcome.ok) return JSON.stringify({ ok: false, error: "no_match", path });
+  await copyFile(absolutePath, `${absolutePath}.bak`);
+  await writeFile(absolutePath, outcome.result, "utf-8");
+  return JSON.stringify({ ok: true, replacements: 1 });
+}
+function editScopeError(path, projectRoot) {
+  if (isForbiddenPath(path)) {
+    return JSON.stringify({ ok: false, error: "forbidden_path", path });
+  }
+  try {
+    assertNoSymlinkEscape(safePathJoin(projectRoot, path), projectRoot);
+    return null;
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+}
 function createEditFileTool(opts) {
-  const { projectRoot } = opts;
+  const { projectRoot, filesystem } = opts;
   return 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 }.",
@@ -358,67 +433,13 @@ function createEditFileTool(opts) {
       old_string: z.string().min(1).describe("String to find in the file."),
       new_string: z.string().describe("Replacement string.")
     }),
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: unified diff parsing is inherently complex
-    handler: async ({ path, old_string, new_string }) => {
+    handler: async ({ path, old_string, new_string }, ctx) => {
       if (old_string === new_string) {
         return JSON.stringify({ ok: false, error: "no_change", path });
       }
-      if (isForbiddenPath(path)) {
-        return JSON.stringify({ ok: false, error: "forbidden_path", path });
-      }
-      let absolutePath;
-      try {
-        absolutePath = safePathJoin(projectRoot, path);
-        assertNoSymlinkEscape(absolutePath, projectRoot);
-      } catch (err) {
-        if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-          return JSON.stringify({ ok: false, error: "path_traversal", path });
-        }
-        throw err;
-      }
-      let content;
-      try {
-        content = await readFile(absolutePath, "utf-8");
-      } catch (err) {
-        const e = err;
-        if (e.code === "ENOENT") {
-          return JSON.stringify({ ok: false, error: "not_found", path });
-        }
-        throw err;
-      }
-      const exactIdx = content.indexOf(old_string);
-      if (exactIdx !== -1) {
-        await copyFile(absolutePath, `${absolutePath}.bak`);
-        const result = content.slice(0, exactIdx) + new_string + content.slice(exactIdx + old_string.length);
-        await writeFile(absolutePath, result, "utf-8");
-        return JSON.stringify({ ok: true, replacements: 1 });
-      }
-      const normalizedContent = normalizeWhitespace(content);
-      const normalizedOld = normalizeWhitespace(old_string);
-      const normalizedIdx = normalizedContent.indexOf(normalizedOld);
-      if (normalizedIdx !== -1) {
-        const span = findOriginalSpan(
-          content,
-          normalizedContent,
-          normalizedIdx,
-          normalizedOld.length
-        );
-        await copyFile(absolutePath, `${absolutePath}.bak`);
-        const result = content.slice(0, span.start) + new_string + content.slice(span.end);
-        await writeFile(absolutePath, result, "utf-8");
-        return JSON.stringify({ ok: true, replacements: 1 });
-      }
-      try {
-        const result = replaceUnique(content, old_string, new_string);
-        await copyFile(absolutePath, `${absolutePath}.bak`);
-        await writeFile(absolutePath, result, "utf-8");
-        return JSON.stringify({ ok: true, replacements: 1 });
-      } catch (err) {
-        if (err instanceof ContextMatchError) {
-          return JSON.stringify({ ok: false, error: "no_match", path });
-        }
-        throw err;
-      }
+      const scopeErr = editScopeError(path, projectRoot);
+      if (scopeErr !== null) return scopeErr;
+      return filesystem !== void 0 ? editViaBackend(filesystem, ctx, path, old_string, new_string) : editViaLocal(projectRoot, path, old_string, new_string);
     }
   });
 }
@@ -531,11 +552,27 @@ function attachChildSettlers(child, gate, onClose, onError, resolve2) {
 // src/git-diff.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_STDOUT_BYTES = 5 * 1024 * 1024;
+function shq(arg) {
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+async function diffViaSandbox(sandbox, ctx, cached, path, projectRoot, timeoutMs) {
+  const scopeCheck = checkPathScope(path, projectRoot);
+  if (scopeCheck !== null) return scopeCheck;
+  const command = ["git", ...buildDiffArgs(cached, path)].map(shq).join(" ");
+  const backend = await resolveSandbox(sandbox, ctx ?? {});
+  const r = await backend.execute(command, { timeoutMs });
+  if (r.timedOut) return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
+  if (r.exitCode !== 0) {
+    return /not a git repository/i.test(r.stderr) ? JSON.stringify({ ok: false, error: "not_a_repo" }) : JSON.stringify({ ok: false, error: "git_failed", stderr: r.stderr });
+  }
+  return JSON.stringify({ ok: true, diff: r.stdout, truncated: false });
+}
 function createGitDiffTool(opts) {
   const {
     projectRoot,
     timeoutMs = DEFAULT_TIMEOUT_MS,
-    maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES
+    maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES,
+    sandbox
   } = opts;
   return Tool.create({
     name: "git_diff",
@@ -544,7 +581,10 @@ function createGitDiffTool(opts) {
       path: z.string().optional().describe("Optional project-relative file or dir scope."),
       cached: z.boolean().optional().describe("If true, show staged changes (git diff --cached). Default false.")
     }),
-    handler: async ({ path, cached }) => {
+    handler: async ({ path, cached }, ctx) => {
+      if (sandbox !== void 0) {
+        return diffViaSandbox(sandbox, ctx, cached, path, projectRoot, timeoutMs);
+      }
       if (!existsSync(join(projectRoot, ".git"))) {
         return JSON.stringify({ ok: false, error: "not_a_repo" });
       }
@@ -617,8 +657,9 @@ function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
   });
 }
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
+var MAX_BACKEND_WALK_DEPTH = 64;
 function createGlobTool(opts) {
-  const { projectRoot } = opts;
+  const { projectRoot, filesystem } = opts;
   return 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 }.",
@@ -626,20 +667,18 @@ function createGlobTool(opts) {
       pattern: z.string().min(1).describe("Glob pattern (e.g. '**/*.ts', 'src/**/*.json')."),
       cwd: z.string().optional().describe("Project-relative subdirectory to search from.")
     }),
-    handler: async ({ pattern, cwd }) => {
-      let searchRoot = projectRoot;
-      if (cwd) {
-        try {
-          searchRoot = safePathJoin(projectRoot, cwd);
-          assertNoSymlinkEscape(searchRoot, projectRoot);
-        } catch (err) {
-          if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-            return JSON.stringify({ ok: false, error: "path_traversal", path: cwd });
-          }
-          throw err;
-        }
-      }
+    handler: async ({ pattern, cwd }, ctx) => {
+      const scopeErr = globScopeError(cwd, projectRoot);
+      if (scopeErr !== null) return scopeErr;
       const regex = globToRegex(pattern);
+      if (filesystem !== void 0) {
+        const backend = await resolveFilesystem(filesystem, ctx ?? {});
+        const searchRel = cwd ?? "";
+        const found = [];
+        await walkDirBackend(backend, searchRel, searchRel, regex, found, 0);
+        return JSON.stringify({ ok: true, files: found.sort(), count: found.length });
+      }
+      const searchRoot = cwd ? safePathJoin(projectRoot, cwd) : projectRoot;
       const files = [];
       await walkDir(searchRoot, searchRoot, regex, files);
       const relativePaths = files.map((f) => relative(projectRoot, f)).sort();
@@ -647,6 +686,18 @@ function createGlobTool(opts) {
     }
   });
 }
+function globScopeError(cwd, projectRoot) {
+  if (!cwd) return null;
+  try {
+    assertNoSymlinkEscape(safePathJoin(projectRoot, cwd), projectRoot);
+    return null;
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path: cwd });
+    }
+    throw err;
+  }
+}
 async function walkDir(base, dir, pattern, results) {
   let entries;
   try {
@@ -665,6 +716,34 @@ async function walkDir(base, dir, pattern, results) {
     }
   }
 }
+async function walkDirBackend(backend, base, dir, pattern, results, depth) {
+  if (depth > MAX_BACKEND_WALK_DEPTH) return;
+  let names;
+  try {
+    names = await backend.list(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    await walkBackendEntry(backend, base, dir, name, pattern, results, depth);
+  }
+}
+async function walkBackendEntry(backend, base, dir, name, pattern, results, depth) {
+  if (DEFAULT_EXCLUDES.has(name)) return;
+  const fullRel = dir === "" ? name : `${dir}/${name}`;
+  const relPath = base === "" ? fullRel : relative(base, fullRel);
+  let st;
+  try {
+    st = await backend.stat(fullRel);
+  } catch {
+    return;
+  }
+  if (st.isDirectory) {
+    await walkDirBackend(backend, base, fullRel, pattern, results, depth + 1);
+  } else if (st.isFile && pattern.test(relPath)) {
+    results.push(fullRel);
+  }
+}
 function globToRegex(pattern) {
   let regexStr = "";
   let i = 0;
@@ -1732,11 +1811,13 @@ var DEFAULT_MAX_MATCHES = 100;
 var DEFAULT_MAX_FILE_SIZE = 1024 * 1024;
 var BINARY_PROBE_BYTES2 = 8 * 1024;
 var PREVIEW_MAX = 200;
+var MAX_BACKEND_WALK_DEPTH2 = 64;
 function createSearchTextTool(opts) {
   const {
     projectRoot,
     maxMatches = DEFAULT_MAX_MATCHES,
-    maxFileSize = DEFAULT_MAX_FILE_SIZE
+    maxFileSize = DEFAULT_MAX_FILE_SIZE,
+    filesystem
   } = opts;
   return Tool.create({
     name: "search_text",
@@ -1745,9 +1826,7 @@ function createSearchTextTool(opts) {
       query: z.string().min(1).describe("Literal text to search for. Case-sensitive."),
       path: z.string().optional().describe("Optional project-relative directory to scope the search.")
     }),
-    handler: async ({ query, path }) => {
-      const scope = resolveSearchScope(path, projectRoot);
-      if ("error" in scope) return scope.error;
+    handler: async ({ query, path }, ctx) => {
       const state = {
         matches: [],
         totalMatches: 0,
@@ -1757,6 +1836,20 @@ function createSearchTextTool(opts) {
         maxFileSize,
         projectRoot
       };
+      if (filesystem !== void 0) {
+        const scopeRel = resolveScopeRel(path, projectRoot);
+        if ("error" in scopeRel) return scopeRel.error;
+        const backend = await resolveFilesystem(filesystem, ctx ?? {});
+        await walkBackend(backend, scopeRel.rel, state, 0);
+        return JSON.stringify({
+          ok: true,
+          matches: state.matches,
+          truncated: state.truncated,
+          totalMatches: state.totalMatches
+        });
+      }
+      const scope = resolveSearchScope(path, projectRoot);
+      if ("error" in scope) return scope.error;
       await walk(scope.scopeAbs, state);
       return JSON.stringify({
         ok: true,
@@ -1844,11 +1937,79 @@ async function scanFile(absPath, relPath, state) {
     if (!recordMatch(state, relPath, i + 1, line)) return;
   }
 }
+function resolveScopeRel(path, projectRoot) {
+  const scopeRel = path === void 0 || path === "" || path === "." ? "" : path;
+  if (scopeRel === "") return { rel: "" };
+  try {
+    assertNoSymlinkEscape(safePathJoin(projectRoot, scopeRel), projectRoot);
+    return { rel: scopeRel };
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return { error: JSON.stringify({ ok: false, error: "path_traversal", path }) };
+    }
+    throw err;
+  }
+}
+async function walkBackend(backend, dirRel, state, depth) {
+  if (state.truncated) return;
+  if (depth > MAX_BACKEND_WALK_DEPTH2) return;
+  let names;
+  try {
+    names = await backend.list(dirRel);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (state.truncated) return;
+    await handleBackendEntry(backend, dirRel, name, state, depth);
+  }
+}
+async function handleBackendEntry(backend, dirRel, name, state, depth) {
+  const entryRel = dirRel === "" ? name : `${dirRel}/${name}`;
+  if (isForbiddenPath(entryRel)) return;
+  let st;
+  try {
+    st = await backend.stat(entryRel);
+  } catch {
+    return;
+  }
+  if (st.isDirectory) {
+    await walkBackend(backend, entryRel, state, depth + 1);
+  } else if (st.isFile) {
+    await scanFileBackend(backend, entryRel, st.size, state);
+  }
+}
+async function scanFileBackend(backend, relPath, size, state) {
+  if (size > state.maxFileSize) return;
+  let content;
+  try {
+    content = await backend.readFile(relPath);
+  } catch {
+    return;
+  }
+  if (content.slice(0, BINARY_PROBE_BYTES2).includes("\0")) return;
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.includes(state.query)) continue;
+    if (!recordMatch(state, relPath, i + 1, line)) return;
+  }
+}
 var DEFAULT_TIMEOUT_MS3 = 3e4;
 var MAX_TIMEOUT_MS = 3e5;
 var MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+async function execViaSandbox(sandbox, ctx, command, timeoutMs) {
+  const backend = await resolveSandbox(sandbox, ctx ?? {});
+  const r = await backend.execute(command, { timeoutMs });
+  return r.timedOut ? JSON.stringify({ ok: false, error: "timeout", timeout_ms: timeoutMs }) : JSON.stringify({ ok: true, stdout: r.stdout, stderr: r.stderr, exit_code: r.exitCode });
+}
 function createShellTool(opts) {
-  const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3, allowCatastrophic = false } = opts;
+  const {
+    projectRoot,
+    defaultTimeoutMs = DEFAULT_TIMEOUT_MS3,
+    allowCatastrophic = false,
+    sandbox
+  } = opts;
   return 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 }.",
@@ -1856,7 +2017,7 @@ function createShellTool(opts) {
       command: z.string().min(1).describe("Shell command to execute."),
       timeout_ms: z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
     }),
-    handler: async ({ command, timeout_ms }) => {
+    handler: async ({ command, timeout_ms }, ctx) => {
       if (!allowCatastrophic) {
         const reason = catastrophicShellReason(command);
         if (reason) {
@@ -1865,8 +2026,8 @@ function createShellTool(opts) {
         }
       }
       const timeoutMs = Math.min(timeout_ms ?? defaultTimeoutMs, MAX_TIMEOUT_MS);
-      const result = await runShell(projectRoot, command, timeoutMs);
-      return result;
+      if (sandbox !== void 0) return execViaSandbox(sandbox, ctx, command, timeoutMs);
+      return runShell(projectRoot, command, timeoutMs);
     }
   });
 }