@theokit/sdk-tools 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- 6dc0e26: Add `withShellExitGuidance` — a guidance wrapper for `shell_exec` soft failures.
+
+  `injectGuidance`/`withDefaultGuidance` inject an actionable `guidance` hint only on `{ ok:false, error }` results (by design). But `shell_exec` returns `{ ok:true, exit_code }` — a non-zero `exit_code` is a SOFT failure (the tool ran, the command failed) that the ok:false-only injector does not cover. `withShellExitGuidance(tool)` wraps `shell_exec` so a `{ ok:true, exit_code≠0 }` result gains a `guidance` hint ("The command exited N. Read the stderr above, fix the cause, then retry."). ADDITIVE, IDEMPOTENT, NEVER-THROW; a no-op for any other tool, for `exit_code 0`, and for non-JSON output. Composes after `withDefaultGuidance` (disjoint domains — no double-injection). Lets consumers drop app-side shell-exit guidance reimplementations.
+
+## 0.4.0
+
+### Minor Changes
+
+- bd10da3: SOTA default descriptions for the 9 built-in tools (`read_file`/`write_file`/`edit_file`/`glob_files`/`search_text`/`shell_exec`/`todolist`/`web_fetch`/`web_search`).
+
+  Each tool's default `description` is upgraded from terse mechanics-only copy to rich, behavior-accurate ACI copy (preconditions, when-to-prefer-which-tool, return shape) — the Agent-Computer Interface the model reads to choose tools, which measurably improves tool-selection. Every claim is verified against the tool's own handler (e.g. `search_text` is described as LITERAL + CASE-SENSITIVE because it matches via `line.includes`; `web_fetch` is described as SSRF-guarded because `screenedFetch` defaults `allowPrivateHosts: false`), so the description lives next to the implementation it describes and cannot drift. Descriptions are generalized (no app-specific cross-tool references). `edit_file` now also ENFORCES the documented `old_string !== new_string` precondition (a no-op edit returns `{ ok: false, error: "no_change" }` instead of a misleading `replacements: 1`), so the description matches behavior. Otherwise no API change: same factory signatures, same return shapes; only the default description string changed. Consumers no longer need to override these descriptions app-side — `withDescription` remains for genuine per-consumer customization. Added `tests/sota-descriptions.test.ts` asserting each description's load-bearing behavioral phrases.
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -268,7 +268,7 @@ function createEditFileTool(opts) {
   const { projectRoot } = opts;
   return sdk.defineTool({
     name: "edit_file",
-    description: "Replace the first occurrence of old_string with new_string in a project-relative file. Falls back to whitespace-normalized matching when the exact match fails. Creates a .bak backup before editing. Returns { ok, replacements } or { ok: false, error }.",
+    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({
       path: zod.z.string().min(1).describe("Project-relative file path."),
       old_string: zod.z.string().min(1).describe("String to find in the file."),
@@ -276,6 +276,9 @@ function createEditFileTool(opts) {
     }),
     // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: unified diff parsing is inherently complex
     handler: async ({ path, old_string, new_string }) => {
+      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 });
       }
@@ -524,7 +527,7 @@ function createGlobTool(opts) {
   const { projectRoot } = opts;
   return sdk.defineTool({
     name: "glob_files",
-    description: "List project files matching a glob-like pattern. Excludes node_modules, .git, dist, .theo by default. Returns relative paths. Pattern supports * and ** wildcards. Returns { ok, files } or { ok: false, error }.",
+    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.")
@@ -1026,6 +1029,28 @@ function withToolResultGuidance(tool, guidance) {
 function withDefaultGuidance(tool) {
   return withToolResultGuidance(tool, DEFAULT_TOOL_GUIDANCE);
 }
+function withShellExitGuidance(tool) {
+  if (tool.name !== "shell_exec") return tool;
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: async (input) => {
+      const out = await tool.handler(input);
+      let parsed;
+      try {
+        parsed = JSON.parse(out);
+      } catch {
+        return out;
+      }
+      if (isRecord(parsed) && parsed.ok === true && typeof parsed.exit_code === "number" && parsed.exit_code !== 0 && !("guidance" in parsed)) {
+        const guidance = `The command exited ${parsed.exit_code}. Read the stderr above, fix the cause, then retry.`;
+        return JSON.stringify({ ...parsed, guidance });
+      }
+      return out;
+    }
+  };
+}
 var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
   const { projectRoot, max = DEFAULT_MAX_ENTRIES } = opts;
@@ -1211,7 +1236,7 @@ function createReadFileTool(opts) {
   const { projectRoot } = opts;
   return sdk.defineTool({
     name: "read_file",
-    description: "Read a single project-relative text file as UTF-8. Refuses paths that escape the project root, are in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files), or contain a null byte in the first 8 KB (binary file). Returns { ok, content } or { ok: false, error }.",
+    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.")
     }),
@@ -1401,7 +1426,7 @@ function createSearchTextTool(opts) {
   } = opts;
   return sdk.defineTool({
     name: "search_text",
-    description: `Search the project tree for a literal text query. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB. Returns up to ${String(maxMatches)} matches as { file, line, preview }. Use 'path' to scope the search to a subdirectory.`,
+    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({
       query: zod.z.string().min(1).describe("Literal text to search for. Case-sensitive."),
       path: zod.z.string().optional().describe("Optional project-relative directory to scope the search.")
@@ -1512,7 +1537,7 @@ function createShellTool(opts) {
   const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3, allowCatastrophic = false } = opts;
   return sdk.defineTool({
     name: "shell_exec",
-    description: "Execute a shell command in the project directory. Returns stdout, stderr, and exit code. Default timeout 30s, max 5 minutes. Output capped at 5 MB. Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
+    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({
       command: zod.z.string().min(1).describe("Shell command to execute."),
       timeout_ms: zod.z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
@@ -1690,7 +1715,7 @@ ${done}/${items.length} done | ${inProg} in progress | ${pending} pending`);
   };
   return {
     name: "todolist",
-    description: "Track multi-step task progress. Actions: 'add' (create task with title), 'complete' (mark done by id), 'in_progress' (mark started by id), 'remove' (delete by id), 'list' (show all), 'clear_completed' (remove done items). Returns { ok, items, items_summary } (items = structured array; items_summary = formatted text).",
+    description: "Create and maintain a structured task list for the current session \u2014 tracks progress and keeps a multi-step plan visible across turns. Use it proactively when the work has 3+ steps or the user gave multiple tasks; skip it for a single trivial step. Keep exactly ONE item 'in_progress' at a time, and mark 'complete' only after the work is actually done. Actions: 'add' (create with title), 'in_progress' (mark started by id), 'complete' (mark done by id), 'remove' (delete by id), 'list' (show all), 'clear_completed' (remove done items). Returns { ok, items, items_summary } (items = structured array; items_summary = formatted text).",
     inputSchema: {
       type: "object",
       properties: {
@@ -1746,7 +1771,7 @@ function createWebFetchTool(opts) {
   const allowPrivateHosts = opts?.allowPrivateHosts ?? false;
   return sdk.defineTool({
     name: "web_fetch",
-    description: "Fetch content from a URL via HTTP/HTTPS. Rejects non-http(s) URLs. Response body capped at 1 MB. Returns { ok, content, status_code } or { ok: false, error }.",
+    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).")
@@ -1827,7 +1852,7 @@ function createWebSearchTool(opts) {
   const { search, defaultMaxResults = 5 } = opts;
   return sdk.defineTool({
     name: "web_search",
-    description: "Search the web for a query. Returns a list of results with title, URL, and snippet. The search provider is injected by the consumer. Returns { ok, results } or { ok: false, error }.",
+    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).")
@@ -1885,7 +1910,7 @@ function createWriteFileTool(opts) {
   const { projectRoot } = opts;
   return sdk.defineTool({
     name: "write_file",
-    description: "Write UTF-8 content to a project-relative file. Creates parent directories recursively. Refuses paths that escape the project root, sensitive files (.env, .git/, node_modules/, .theo/, lock files), and binary-file overwrites. Returns { ok, path, bytes } or { ok: false, error }.",
+    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 project root, sensitive files (.env, .git/, node_modules/, .theo/, lock files), and 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.")
@@ -1975,6 +2000,7 @@ exports.todoItemsToPlanNodes = todoItemsToPlanNodes;
 exports.truncateOutput = truncateOutput;
 exports.withDefaultGuidance = withDefaultGuidance;
 exports.withDescription = withDescription;
+exports.withShellExitGuidance = withShellExitGuidance;
 exports.withToolResultGuidance = withToolResultGuidance;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map