@theokit/sdk-tools 0.9.0 → 0.9.1

package/dist/index.d.cts

@@ -424,6 +424,13 @@ interface CreateListDirToolOptions {
     projectRoot: string;
     /** Maximum number of entries returned per call. Default 500. */
     max?: number;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver. When provided, listings route through the backend
+     * (its own boundary + `basePath`) instead of the local `projectRoot`; omitted
+     * ⇒ identical current behavior (multi-tenant / per-request roots).
+     */
+    filesystem?: FilesystemProvider;
 }
 declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;
 
@@ -559,6 +566,13 @@ interface CreateReadFileToolOptions {
      * `requireReadBeforeWrite`) can refuse a blind or stale overwrite.
      */
     readTracker?: ReadTracker;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver. When provided, reads route through the backend (its
+     * own boundary + `basePath`) instead of the local `projectRoot`; omitted ⇒
+     * identical current behavior (multi-tenant / per-request roots).
+     */
+    filesystem?: FilesystemProvider;
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 

package/dist/index.d.ts

@@ -424,6 +424,13 @@ interface CreateListDirToolOptions {
     projectRoot: string;
     /** Maximum number of entries returned per call. Default 500. */
     max?: number;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver. When provided, listings route through the backend
+     * (its own boundary + `basePath`) instead of the local `projectRoot`; omitted
+     * ⇒ identical current behavior (multi-tenant / per-request roots).
+     */
+    filesystem?: FilesystemProvider;
 }
 declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;
 
@@ -559,6 +566,13 @@ interface CreateReadFileToolOptions {
      * `requireReadBeforeWrite`) can refuse a blind or stale overwrite.
      */
     readTracker?: ReadTracker;
+    /**
+     * SE31 — optional pluggable filesystem backend (`@theokit/sdk/filesystem`), or
+     * a per-request resolver. When provided, reads route through the backend (its
+     * own boundary + `basePath`) instead of the local `projectRoot`; omitted ⇒
+     * identical current behavior (multi-tenant / per-request roots).
+     */
+    filesystem?: FilesystemProvider;
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 

package/dist/index.js

@@ -1,6 +1,6 @@
 import { readFile, copyFile, mkdir, writeFile, readdir, open, stat } from 'fs/promises';
 import { dirname, join, relative, resolve, sep } from 'path';
-import { defineTool, ConfigurationError } from '@theokit/sdk';
+import { Tool, ConfigurationError } from '@theokit/sdk';
 import { z } from 'zod';
 import { existsSync, statSync, mkdirSync, writeFileSync, realpathSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'fs';
 import { replaceFileAtomic } from '@theokit/sdk/internal/persistence';
@@ -8,7 +8,7 @@ import { safeFilenameForId, safePathJoin as safePathJoin$1 } from '@theokit/sdk/
 import { spawn } from 'child_process';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
-import { resolveFilesystem, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError, FileNotFoundError } from '@theokit/sdk/filesystem';
+import { resolveFilesystem, FileNotFoundError, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError } from '@theokit/sdk/filesystem';
 
 // src/apply-patch.ts
 var PathTraversalError = class extends ConfigurationError {
@@ -103,7 +103,7 @@ function isForbiddenPath(input) {
 // src/apply-patch.ts
 function createApplyPatchTool(opts) {
   const { projectRoot } = opts;
-  return defineTool({
+  return 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: z.object({
@@ -265,7 +265,7 @@ function createSessionArtifactStore(options) {
 }
 function createEditFileTool(opts) {
   const { projectRoot } = opts;
-  return defineTool({
+  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 }.",
     inputSchema: z.object({
@@ -442,7 +442,7 @@ function createGitDiffTool(opts) {
     timeoutMs = DEFAULT_TIMEOUT_MS,
     maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES
   } = opts;
-  return defineTool({
+  return 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: z.object({
@@ -524,7 +524,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 defineTool({
+  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 }.",
     inputSchema: z.object({
@@ -1087,26 +1087,61 @@ function withShellExitGuidance(tool) {
 }
 var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
-  const { projectRoot, max = DEFAULT_MAX_ENTRIES } = opts;
-  return defineTool({
+  const { projectRoot, max = DEFAULT_MAX_ENTRIES, filesystem } = opts;
+  return 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: z.object({
       path: 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) {
+        const backend = await resolveFilesystem(filesystem, 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 FileNotFoundError) {
+      return JSON.stringify({ ok: false, error: "not_found", path: originalPath });
+    }
+    if (err instanceof 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);
@@ -1267,17 +1302,21 @@ function createQuestionTool(opts) {
 var MAX_FILE_SIZE = 5 * 1024 * 1024;
 var BINARY_PROBE_BYTES = 8 * 1024;
 function createReadFileTool(opts) {
-  const { projectRoot, readTracker } = opts;
-  return defineTool({
+  const { projectRoot, readTracker, filesystem } = opts;
+  return 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: z.object({
       path: 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) {
+        const backend = await resolveFilesystem(filesystem, 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);
@@ -1294,6 +1333,34 @@ function createReadFileTool(opts) {
     }
   });
 }
+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 FileNotFoundError) {
+      return JSON.stringify({ ok: false, error: "not_found", path });
+    }
+    if (err instanceof FilesystemSecurityError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+}
 function resolveBoundary(path, projectRoot) {
   try {
     const absolutePath = safePathJoin(projectRoot, path);
@@ -1374,7 +1441,7 @@ function createRunVitestTool(opts) {
     timeoutMs = DEFAULT_TIMEOUT_MS2,
     maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES2
   } = opts;
-  return defineTool({
+  return 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: z.object({
@@ -1483,7 +1550,7 @@ function createSearchTextTool(opts) {
     maxMatches = DEFAULT_MAX_MATCHES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE
   } = opts;
-  return defineTool({
+  return 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: z.object({
@@ -1594,7 +1661,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 defineTool({
+  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 }.",
     inputSchema: z.object({
@@ -1831,7 +1898,7 @@ function createWebFetchTool(opts) {
   const maxRedirects = opts?.maxRedirects;
   const fetchImpl = opts?.fetchImpl;
   const lookup = opts?.lookup;
-  return defineTool({
+  return 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: z.object({
@@ -1918,7 +1985,7 @@ function createWebFetchTool(opts) {
 }
 function createWebSearchTool(opts) {
   const { search, defaultMaxResults = 5 } = opts;
-  return defineTool({
+  return 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: z.object({
@@ -2005,7 +2072,7 @@ function createWriteFileTool(opts) {
     );
   }
   const guard = opts.requireReadBeforeWrite ? opts.readTracker : void 0;
-  return defineTool({
+  return 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 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: z.object({