@theokit/sdk-tools 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -671,6 +671,18 @@ interface CreateReadFileToolOptions {
      * identical current behavior (multi-tenant / per-request roots).
      */
     filesystem?: FilesystemProvider;
+    /**
+     * M17 — render a `cat -n`-style numbered view (`<n>\t<line>`) instead of raw content, so the model can
+     * cite / edit by line number (Codex / Claude-Code read idiom). Default `false` ⇒ raw content (unchanged).
+     */
+    lineNumbers?: boolean;
+    /**
+     * M17 — opt-in "reads-anywhere" (Codex read-only sandbox): honor an ABSOLUTE `path` outside `projectRoot`
+     * instead of rejecting it as traversal. The `isForbiddenPath` secret guard STILL fires first, so `.env`/
+     * `.git`/lock files remain blocked. Default `false` ⇒ absolute paths rejected (unchanged). Opt-in only —
+     * this widens the read boundary to the whole filesystem; enable only for a trusted local agent.
+     */
+    allowAbsolute?: boolean;
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
@@ -768,6 +780,12 @@ interface CreateSearchTextToolOptions {
     /** 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;
+    /** M17 — treat `query` as a JavaScript RegExp instead of a literal substring (grep semantics). An
+     *  invalid pattern returns `{ ok: false, error: 'invalid_regex' }`. Default `false` ⇒ literal (unchanged). */
+    regex?: boolean;
+    /** M17 — opt-in "reads-anywhere": honor an ABSOLUTE `path` scope outside `projectRoot` (Codex read-only
+     *  sandbox). Forbidden dirs are still skipped. Default `false` ⇒ absolute scope rejected (unchanged). */
+    allowAbsolute?: boolean;
 }
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 

package/dist/index.d.ts

@@ -671,6 +671,18 @@ interface CreateReadFileToolOptions {
      * identical current behavior (multi-tenant / per-request roots).
      */
     filesystem?: FilesystemProvider;
+    /**
+     * M17 — render a `cat -n`-style numbered view (`<n>\t<line>`) instead of raw content, so the model can
+     * cite / edit by line number (Codex / Claude-Code read idiom). Default `false` ⇒ raw content (unchanged).
+     */
+    lineNumbers?: boolean;
+    /**
+     * M17 — opt-in "reads-anywhere" (Codex read-only sandbox): honor an ABSOLUTE `path` outside `projectRoot`
+     * instead of rejecting it as traversal. The `isForbiddenPath` secret guard STILL fires first, so `.env`/
+     * `.git`/lock files remain blocked. Default `false` ⇒ absolute paths rejected (unchanged). Opt-in only —
+     * this widens the read boundary to the whole filesystem; enable only for a trusted local agent.
+     */
+    allowAbsolute?: boolean;
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
@@ -768,6 +780,12 @@ interface CreateSearchTextToolOptions {
     /** 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;
+    /** M17 — treat `query` as a JavaScript RegExp instead of a literal substring (grep semantics). An
+     *  invalid pattern returns `{ ok: false, error: 'invalid_regex' }`. Default `false` ⇒ literal (unchanged). */
+    regex?: boolean;
+    /** M17 — opt-in "reads-anywhere": honor an ABSOLUTE `path` scope outside `projectRoot` (Codex read-only
+     *  sandbox). Forbidden dirs are still skipped. Default `false` ⇒ absolute scope rejected (unchanged). */
+    allowAbsolute?: boolean;
 }
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 

package/dist/index.js

@@ -1,5 +1,5 @@
 import { readFile, copyFile, mkdir, writeFile, readdir, open, stat } from 'fs/promises';
-import { dirname, join, relative, resolve, sep } from 'path';
+import { dirname, join, relative, isAbsolute, resolve, sep } from 'path';
 import { Tool, ConfigurationError } from '@theokit/sdk';
 import { z } from 'zod';
 import { existsSync, statSync, mkdirSync, writeFileSync, realpathSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'fs';
@@ -1577,23 +1577,53 @@ function createQuestionTool(opts) {
 }
 var MAX_FILE_SIZE = 5 * 1024 * 1024;
 var BINARY_PROBE_BYTES = 8 * 1024;
+var SENSITIVE_SEGMENTS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
+function isForbiddenAtAnyDepth(path) {
+  const segs = path.replace(/\\/g, "/").split("/").filter(Boolean);
+  return segs.some((s) => {
+    if (s === ".env.example") return false;
+    return SENSITIVE_SEGMENTS.has(s) || /^\.env\./.test(s);
+  });
+}
+function forbiddenReadError(path, allowAbsolute) {
+  if (isForbiddenPath(path)) {
+    return JSON.stringify({ ok: false, error: "forbidden_path", path });
+  }
+  if (allowAbsolute && isAbsolute(path) && isForbiddenAtAnyDepth(path)) {
+    return JSON.stringify({ ok: false, error: "forbidden_path", path });
+  }
+  return null;
+}
+function renderView(content, opts) {
+  const paginated = opts.offset !== void 0 || opts.limit !== void 0;
+  if (!opts.lineNumbers && !paginated) return content;
+  const lines = content.split("\n");
+  const start = Math.max(1, opts.offset ?? 1);
+  const end = opts.limit !== void 0 ? Math.min(lines.length, start - 1 + opts.limit) : lines.length;
+  const slice = lines.slice(start - 1, end);
+  return opts.lineNumbers ? slice.map((l, i) => `${start + i}	${l}`).join("\n") : slice.join("\n");
+}
 function createReadFileTool(opts) {
-  const { projectRoot, readTracker, filesystem } = opts;
+  const { projectRoot, readTracker, filesystem, lineNumbers, allowAbsolute } = opts;
+  const numbered = lineNumbers === true ? " Returns a cat -n numbered view (`<n>\\t<line>`)." : "";
+  const abs = allowAbsolute === true ? " Absolute paths outside the project are honored." : "";
   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 }.",
+    description: "Read a 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." + numbered + abs + " By default returns the whole file; use the optional offset (1-based first line) + limit to page through a large file, or search_text to locate a symbol. Refuses 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.")
+      path: z.string().min(1).describe("File path (project-relative; absolute when allowed)."),
+      offset: z.number().int().min(1).optional().describe("1-based first line to read (default 1)."),
+      limit: z.number().int().min(1).optional().describe("Max number of lines to read (default: all).")
     }),
-    handler: async ({ path }, ctx) => {
-      if (isForbiddenPath(path)) {
-        return JSON.stringify({ ok: false, error: "forbidden_path", path });
-      }
+    handler: async ({ path, offset, limit }, ctx) => {
+      const forbidden = forbiddenReadError(path, allowAbsolute === true);
+      if (forbidden !== null) return forbidden;
+      const view = { lineNumbers, offset, limit };
       if (filesystem) {
         const backend = await resolveFilesystem(filesystem, ctx ?? {});
-        return readViaBackend(backend, path, (mtimeMs) => readTracker?.record(path, mtimeMs));
+        return readViaBackend(backend, path, view, (mtimeMs) => readTracker?.record(path, mtimeMs));
       }
-      const boundary = resolveBoundary(path, projectRoot);
+      const boundary = resolveBoundary(path, projectRoot, allowAbsolute === true);
       if ("error" in boundary) return boundary.error;
       const opened = await openHandleSafe(boundary.absolutePath, path);
       if ("error" in opened) return opened.error;
@@ -1601,6 +1631,7 @@ function createReadFileTool(opts) {
         return await readContent(
           opened.handle,
           path,
+          view,
           (mtimeMs) => readTracker?.record(path, mtimeMs)
         );
       } finally {
@@ -1609,7 +1640,7 @@ function createReadFileTool(opts) {
     }
   });
 }
-async function readViaBackend(backend, path, onRead) {
+async function readViaBackend(backend, path, view, onRead) {
   try {
     const stat2 = await backend.stat(path);
     if (stat2.size > MAX_FILE_SIZE) {
@@ -1621,12 +1652,12 @@ async function readViaBackend(backend, path, onRead) {
         limit: MAX_FILE_SIZE
       });
     }
-    const content = await backend.readFile(path);
-    if (content.includes("\0")) {
+    const raw = await backend.readFile(path);
+    if (raw.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 });
+    return JSON.stringify({ ok: true, content: renderView(raw, view), size: stat2.size });
   } catch (err) {
     if (err instanceof FileNotFoundError) {
       return JSON.stringify({ ok: false, error: "not_found", path });
@@ -1637,7 +1668,10 @@ async function readViaBackend(backend, path, onRead) {
     throw err;
   }
 }
-function resolveBoundary(path, projectRoot) {
+function resolveBoundary(path, projectRoot, allowAbsolute) {
+  if (allowAbsolute && isAbsolute(path)) {
+    return { absolutePath: path };
+  }
   try {
     const absolutePath = safePathJoin(projectRoot, path);
     assertNoSymlinkEscape(absolutePath, projectRoot);
@@ -1661,7 +1695,7 @@ async function openHandleSafe(absolutePath, path) {
     throw err;
   }
 }
-async function readContent(handle, path, onRead) {
+async function readContent(handle, path, view, onRead) {
   const stat2 = await handle.stat();
   if (stat2.size > MAX_FILE_SIZE) {
     return JSON.stringify({
@@ -1675,9 +1709,9 @@ async function readContent(handle, path, onRead) {
   if (await isBinaryProbe(handle, Number(stat2.size))) {
     return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
   }
-  const content = await handle.readFile({ encoding: "utf-8" });
+  const raw = await handle.readFile({ encoding: "utf-8" });
   onRead?.(stat2.mtimeMs);
-  return JSON.stringify({ ok: true, content, size: stat2.size });
+  return JSON.stringify({ ok: true, content: renderView(raw, view), size: stat2.size });
 }
 async function isBinaryProbe(handle, size) {
   const probeLen = Math.min(BINARY_PROBE_BYTES, size);
@@ -1857,27 +1891,36 @@ function createSearchTextTool(opts) {
     projectRoot,
     maxMatches = DEFAULT_MAX_MATCHES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
-    filesystem
+    filesystem,
+    regex = false,
+    allowAbsolute = false
   } = opts;
+  const queryKind = regex ? "a JavaScript REGULAR EXPRESSION" : "LITERAL, CASE-SENSITIVE text";
+  const queryMatch = regex ? "matched as a regex" : "matched as a substring, not a regex";
   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 }.`,
+    description: `Search file CONTENTS for ${queryKind} across the project tree (the query is ${queryMatch}). 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({
-      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.")
+      query: regex ? z.string().min(1).describe("A JavaScript regular expression, e.g. 'function\\\\s+main'.") : z.string().min(1).describe("Literal text to search for. Case-sensitive."),
+      path: z.string().optional().describe(
+        "Optional directory to scope the search (project-relative; absolute when allowed)."
+      )
     }),
     handler: async ({ query, path }, ctx) => {
+      const built = buildMatcher(query, regex);
+      if ("error" in built) return built.error;
+      const matcher = built.matcher;
       const state = {
         matches: [],
         totalMatches: 0,
         truncated: false,
-        query,
+        matcher,
         maxMatches,
         maxFileSize,
         projectRoot
       };
       if (filesystem !== void 0) {
-        const scopeRel = resolveScopeRel(path, projectRoot);
+        const scopeRel = resolveScopeRel(path, projectRoot, allowAbsolute);
         if ("error" in scopeRel) return scopeRel.error;
         const backend = await resolveFilesystem(filesystem, ctx ?? {});
         await walkBackend(backend, scopeRel.rel, state, 0);
@@ -1888,7 +1931,7 @@ function createSearchTextTool(opts) {
           totalMatches: state.totalMatches
         });
       }
-      const scope = resolveSearchScope(path, projectRoot);
+      const scope = resolveSearchScope(path, projectRoot, allowAbsolute);
       if ("error" in scope) return scope.error;
       await walk(scope.scopeAbs, state);
       return JSON.stringify({
@@ -1900,8 +1943,20 @@ function createSearchTextTool(opts) {
     }
   });
 }
-function resolveSearchScope(path, projectRoot) {
+function buildMatcher(query, regex) {
+  if (!regex) return { matcher: (line) => line.includes(query) };
+  try {
+    const re = new RegExp(query);
+    return { matcher: (line) => re.test(line) };
+  } catch {
+    return { error: JSON.stringify({ ok: false, error: "invalid_regex", query }) };
+  }
+}
+function resolveSearchScope(path, projectRoot, allowAbsolute) {
   const scopeRel = path === void 0 || path === "" || path === "." ? "." : path;
+  if (allowAbsolute && isAbsolute(scopeRel)) {
+    return { scopeAbs: scopeRel };
+  }
   try {
     const scopeAbs = scopeRel === "." ? projectRoot : safePathJoin(projectRoot, scopeRel);
     assertNoSymlinkEscape(scopeAbs, projectRoot);
@@ -1973,13 +2028,14 @@ async function scanFile(absPath, relPath, state) {
   const lines = buffer.toString("utf-8").split("\n");
   for (let i = 0; i < lines.length; i += 1) {
     const line = lines[i];
-    if (!line.includes(state.query)) continue;
+    if (!state.matcher(line)) continue;
     if (!recordMatch(state, relPath, i + 1, line)) return;
   }
 }
-function resolveScopeRel(path, projectRoot) {
+function resolveScopeRel(path, projectRoot, allowAbsolute) {
   const scopeRel = path === void 0 || path === "" || path === "." ? "" : path;
   if (scopeRel === "") return { rel: "" };
+  if (allowAbsolute && isAbsolute(scopeRel)) return { rel: scopeRel };
   try {
     assertNoSymlinkEscape(safePathJoin(projectRoot, scopeRel), projectRoot);
     return { rel: scopeRel };
@@ -2031,7 +2087,7 @@ async function scanFileBackend(backend, relPath, size, state) {
   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 (!state.matcher(line)) continue;
     if (!recordMatch(state, relPath, i + 1, line)) return;
   }
 }