@theokit/sdk-tools 0.23.0 → 0.24.0

package/dist/index.cjs

@@ -227,8 +227,8 @@ ${chunk.oldLines.join("\n")}`
 function createApplyPatchTool(opts) {
   const { projectRoot } = opts;
   return sdk.Tool.create({
-    name: "apply_patch",
-    description: "Apply a Codex-style V4A patch. The patch is `*** Begin Patch` \u2026 `*** End Patch` wrapping one or more hunks: `*** Add File: <path>` (then `+`lines), `*** Delete File: <path>`, or `*** Update File: <path>` (optional `*** Move to: <path>`) with `@@`-anchored `+` (add) / `-` (remove) / ` ` (context) lines. Read a file first so your context/removed lines match. Applied atomically \u2014 a mismatch anywhere aborts the whole patch with zero writes; each path is security-checked. Returns { ok, files_patched } or { ok: false, error }.",
+    name: opts.name ?? "apply_patch",
+    description: opts.description ?? "Apply a Codex-style V4A patch. The patch is `*** Begin Patch` \u2026 `*** End Patch` wrapping one or more hunks: `*** Add File: <path>` (then `+`lines), `*** Delete File: <path>`, or `*** Update File: <path>` (optional `*** Move to: <path>`) with `@@`-anchored `+` (add) / `-` (remove) / ` ` (context) lines. Read a file first so your context/removed lines match. Applied atomically \u2014 a mismatch anywhere aborts the whole patch with zero writes; each path is security-checked. Returns { ok, files_patched } or { ok: false, error }.",
     inputSchema: zod.z.object({
       patch: zod.z.string().min(1).describe("V4A patch: *** Begin Patch \u2026 *** End Patch.")
     }),
@@ -429,8 +429,8 @@ function formatInTimezone(now, tz) {
 function createCurrentTimeTool(opts = {}) {
   const clock = opts.clock ?? (() => /* @__PURE__ */ new Date());
   return sdk.Tool.create({
-    name: "current_time",
-    description: "Get the current date and time. Returns { current_time, iso, timezone } as a JSON string, where current_time is 'YYYY-MM-DD HH:MM:SS <timezone>' and iso is the ISO-8601 instant. Pass an optional IANA timezone (e.g. 'America/Sao_Paulo', 'Europe/Lisbon'); defaults to UTC. Never state the date or time from memory \u2014 always call this. Returns { ok: false, error: 'invalid_timezone' } for an unknown timezone.",
+    name: opts.name ?? "current_time",
+    description: opts.description ?? "Get the current date and time. Returns { current_time, iso, timezone } as a JSON string, where current_time is 'YYYY-MM-DD HH:MM:SS <timezone>' and iso is the ISO-8601 instant. Pass an optional IANA timezone (e.g. 'America/Sao_Paulo', 'Europe/Lisbon'); defaults to UTC. Never state the date or time from memory \u2014 always call this. Returns { ok: false, error: 'invalid_timezone' } for an unknown timezone.",
     inputSchema: zod.z.object({
       timezone: zod.z.string().optional().describe("IANA timezone, e.g. 'America/Sao_Paulo' or 'Europe/Lisbon'. Defaults to UTC.")
     }),
@@ -720,6 +720,9 @@ function attachChildSettlers(child, gate, onClose, onError, resolve) {
 }
 
 // src/internal/git-exec.ts
+function shq(arg) {
+  return `'${arg.replaceAll("'", `'\\''`)}'`;
+}
 function formatGitResult(result, timeoutMs) {
   if (result.kind === "timeout") {
     return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
@@ -801,9 +804,6 @@ function ehProibidoEmQualquerProfundidade(path) {
 // 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$1, ctx, cached, path, projectRoot, timeoutMs) {
   const scopeCheck = checkPathScope(path, projectRoot);
   if (scopeCheck !== null) return scopeCheck;
@@ -824,8 +824,8 @@ function createGitDiffTool(opts) {
     sandbox
   } = opts;
   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 }.",
+    name: opts.name ?? "git_diff",
+    description: opts.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({
       path: zod.z.string().optional().describe("Optional project-relative file or dir scope."),
       cached: zod.z.boolean().optional().describe("If true, show staged changes (git diff --cached). Default false.")
@@ -859,7 +859,7 @@ function createGitStatusTool(opts) {
     inputSchema: zod.z.object({
       path: zod.z.string().optional().describe("Optional project-relative path to scope the status report.")
     }),
-    handler: async ({ path: path$1 }) => {
+    handler: async ({ path: path$1 }, ctx) => {
       if (!fs.existsSync(path.join(projectRoot, ".git"))) {
         return JSON.stringify({ ok: false, error: "not_a_repo" });
       }
@@ -868,18 +868,31 @@ function createGitStatusTool(opts) {
       const args = ["status", "--porcelain=v1"];
       if (opts.includeBranch !== false) args.push("-b");
       if (path$1 !== void 0 && path$1 !== "") args.push("--", path$1);
+      if (opts.sandbox !== void 0) {
+        return statusViaSandbox(opts.sandbox, ctx, args, timeoutMs);
+      }
       const result = await runGitProcess(projectRoot, args, timeoutMs, maxStdoutBytes);
       return formatGitResult(result, timeoutMs);
     }
   });
 }
+async function statusViaSandbox(sandbox$1, ctx, args, timeoutMs) {
+  const command = ["git", ...args].map(shq).join(" ");
+  const backend = await sandbox.resolveSandbox(sandbox$1, 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 });
+}
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
 var MAX_BACKEND_WALK_DEPTH = 64;
 function createGlobTool(opts) {
   const { projectRoot, filesystem: filesystem$1 } = opts;
   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 }.",
+    name: opts.name ?? "glob_files",
+    description: opts.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({
       pattern: zod.z.string().min(1).describe("Glob pattern (e.g. '**/*.ts', 'src/**/*.json')."),
       cwd: zod.z.string().optional().describe("Project-relative subdirectory to search from.")
@@ -998,8 +1011,8 @@ function toErrorJson(err) {
 function createInteractiveShellTool(opts) {
   const { interactive: interactive$1 } = opts;
   return sdk.Tool.create({
-    name: "interactive_shell",
-    description: "Start an interactive shell session for a command that PROMPTS for input or is a REPL (python, node, `git rebase -i`, a `read` prompt) \u2014 NOT for one-shot commands (use shell_exec). Returns a session_id; drive it with write_stdin, reading the incremental output each step. Returns { ok, session_id, output } or { ok: false, error }.",
+    name: opts.name ?? "interactive_shell",
+    description: opts.description ?? "Start an interactive shell session for a command that PROMPTS for input or is a REPL (python, node, `git rebase -i`, a `read` prompt) \u2014 NOT for one-shot commands (use shell_exec). Returns a session_id; drive it with write_stdin, reading the incremental output each step. Returns { ok, session_id, output } or { ok: false, error }.",
     inputSchema: zod.z.object({
       command: zod.z.string().min(1).describe("Command to run interactively, e.g. 'python3' or 'bash -i'."),
       yield_time_ms: zod.z.number().int().positive().optional().describe("How long to wait for startup output before returning (clamped by the backend).")
@@ -1703,8 +1716,8 @@ function createPlanModeTool(options) {
   }
   const { artifactStore, artifactId = "plan" } = options;
   return {
-    name: "plan_mode",
-    description: DESCRIPTION,
+    name: options.name ?? "plan_mode",
+    description: options.description ?? DESCRIPTION,
     inputSchema: planModeSchema(true),
     handler: async (input) => {
       if (input.action === "enter") {
@@ -1762,10 +1775,14 @@ function createQuestionTool(opts) {
         setTimeout(() => reject(new Error("timeout")), timeoutMs);
       });
       try {
-        const answer = await Promise.race([askUser(String(input.question ?? "")), timeout]);
+        const answer = await Promise.race([
+          askUser(String(input.question ?? ""), ctx?.threadId),
+          timeout
+        ]);
         return JSON.stringify({ ok: true, answer });
       } catch (err) {
         if (err instanceof Error && err.message === "timeout") {
+          opts.onAbandon?.(ctx?.threadId);
           return JSON.stringify({
             ok: false,
             error: "timeout",
@@ -1810,8 +1827,8 @@ function createReadFileTool(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 sdk.Tool.create({
-    name: "read_file",
-    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 }.",
+    name: opts.name ?? "read_file",
+    description: opts.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: zod.z.object({
       path: zod.z.string().min(1).describe("File path (project-relative; absolute when allowed)."),
       offset: zod.z.number().int().min(1).optional().describe("1-based first line to read (default 1)."),
@@ -1985,8 +2002,8 @@ function createRunVitestTool(opts) {
     maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES2
   } = opts;
   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.",
+    name: opts.name ?? "run_vitest",
+    description: opts.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({
       path: zod.z.string().optional().describe("Optional vitest pattern or file path (project-relative).")
     }),
@@ -2583,8 +2600,8 @@ function createWebFetchTool(opts) {
   const fetchImpl = opts?.fetchImpl;
   const lookup = opts?.lookup;
   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 }.",
+    name: opts?.name ?? "web_fetch",
+    description: opts?.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({
       url: zod.z.string().min(1).describe("URL to fetch (http or https only)."),
       timeout_ms: zod.z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000).")
@@ -2670,8 +2687,8 @@ function createWebFetchTool(opts) {
 function createWebSearchTool(opts) {
   const { search, defaultMaxResults = 5 } = opts;
   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 }.",
+    name: opts.name ?? "web_search",
+    description: opts.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({
       query: zod.z.string().min(1).describe("Search query."),
       max_results: zod.z.number().int().positive().max(20).optional().describe("Maximum results to return (default 5, max 20).")
@@ -2757,8 +2774,8 @@ function createWriteFileTool(opts) {
   }
   const guard = opts.requireReadBeforeWrite ? opts.readTracker : void 0;
   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 }.",
+    name: opts.name ?? "write_file",
+    description: opts.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.")