@theokit/sdk-tools 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.10.0
+
+### Minor Changes
+
+- 2606c98: SE37 — Reasoning ergonomics. Ships `ReasoningTools.create()` (`think`/`analyze` scratchpad tools, from `@theokit/sdk` core, re-exported by `@theokit/sdk-tools`) and a lightweight `AgentOptions.reasoning?: boolean` flag. When `reasoning: true`, the agent gets a chain-of-thought preamble prepended to its system prompt AND the reasoning tools auto-attached, turning a non-reasoning model into a reason→act→observe loop using the SAME model (reuses the existing tool loop; no new runtime). Inert (with a one-time warn) when a native reasoning model is configured (`model.params: [{ id: "thinking" }]`) — native reasoning wins, no double-reasoning. Default off; byte-identical behaviour when unset. Validated REAL on OpenRouter: `reasoning: true` drove the `think` tool and answered the "9.11 vs 9.9" trap correctly (9.9).
+
+## 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

package/dist/index.cjs

@@ -105,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({
@@ -267,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({
@@ -444,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({
@@ -526,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({
@@ -1089,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);
@@ -1269,17 +1304,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 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);
@@ -1296,6 +1335,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 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);
@@ -1368,6 +1435,37 @@ function evaluateReadBeforeWrite(tracker, path, currentMtimeMs) {
   if (recorded !== currentMtimeMs) return "stale";
   return "ok";
 }
+var ReasoningTools = class {
+  constructor() {
+  }
+  /** Build the tools. Pass `{ analyze: false }` for `think` only. */
+  static create(opts) {
+    const think = sdk.Tool.create({
+      name: "think",
+      description: "Use this as a scratchpad to think step by step BEFORE answering or acting. Write out your reasoning for one step. Nothing else happens \u2014 it is only your private reasoning space. Call it as many times as you need before the final answer.",
+      inputSchema: zod.z.object({
+        thought: zod.z.string().min(1, "think: `thought` must be a non-empty string.")
+      }),
+      handler: ({ thought }) => thought
+    });
+    if (opts?.analyze === false) return [think];
+    const analyze = sdk.Tool.create({
+      name: "analyze",
+      description: "Analyze the result of a previous step or tool call. State what you looked at, your analysis, and whether to `continue` reasoning, `validate` (double-check) your work, or give the `final_answer`. Use this to catch your own mistakes before answering.",
+      inputSchema: zod.z.object({
+        title: zod.z.string().optional(),
+        result: zod.z.string().min(1, "analyze: `result` must describe what you are analyzing."),
+        analysis: zod.z.string().min(1, "analyze: `analysis` must contain your reasoning."),
+        next_action: zod.z.enum(["continue", "validate", "final_answer"])
+      }),
+      handler: ({ title, result, analysis, next_action }) => `${title ? `# ${title}
+` : ""}Result: ${result}
+Analysis: ${analysis}
+Next: ${next_action}`
+    });
+    return [think, analyze];
+  }
+};
 var DEFAULT_TIMEOUT_MS2 = 12e4;
 var DEFAULT_MAX_STDOUT_BYTES2 = 10 * 1024 * 1024;
 function createRunVitestTool(opts) {
@@ -1376,7 +1474,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({
@@ -1485,7 +1583,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({
@@ -1596,7 +1694,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({
@@ -1833,7 +1931,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({
@@ -1920,7 +2018,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({
@@ -2007,7 +2105,7 @@ function createWriteFileTool(opts) {
     );
   }
   const guard = opts.requireReadBeforeWrite ? opts.readTracker : void 0;
-  return sdk.defineTool({
+  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 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({
@@ -2130,6 +2228,7 @@ async function isBinaryFile(absolutePath) {
 exports.CatastrophicCommandError = CatastrophicCommandError;
 exports.DEFAULT_TOOL_GUIDANCE = DEFAULT_TOOL_GUIDANCE;
 exports.ReadTracker = ReadTracker;
+exports.ReasoningTools = ReasoningTools;
 exports.RedirectBlockedError = RedirectBlockedError;
 exports.SsrfBlockedError = SsrfBlockedError;
 exports.buildEnvContext = buildEnvContext;