agentool 1.0.0 → 1.1.1

package/dist/{chunk-FV2R5FFQ.cjs → chunk-LNAR3NJQ.cjs}

@@ -1,12 +1,50 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
 
+
+
+
+var _chunkBIAODQ2Pcjs = require('./chunk-BIAODQ2P.cjs');
+
+
 var _chunkQZ5GS6HWcjs = require('./chunk-QZ5GS6HW.cjs');
 
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
+
 // src/memory/index.ts
 var _ai = require('ai');
 var _zod = require('zod');
-var _promises = require('fs/promises');
 var _path = require('path');
+
+// src/memory/prompt.ts
+function getPrompt() {
+  return `File-based key-value memory store for persisting notes, context, or any text data across conversations.
+
+Entries are stored as individual .md files in the memory directory.
+
+## Operations
+- **write**: Store content under a key (creates or overwrites)
+- **read**: Retrieve content by key
+- **list**: List all stored keys
+- **delete**: Remove a key and its content
+
+## When to Use
+- To persist information that should survive across conversations or sessions
+- To store user preferences, project notes, or context summaries
+- To keep a running log of decisions, findings, or important details
+
+## When NOT to Use
+- For temporary data within a single conversation \u2014 just keep it in context
+- For structured task tracking \u2014 use the task management tools instead
+
+## Usage Guidelines
+- Keys are sanitized to prevent path traversal (no ../ allowed)
+- The \`key\` parameter is required for read, write, and delete operations
+- The \`content\` parameter is required for write operations
+- Use descriptive key names for easy discovery (e.g., "user-preferences", "project-architecture")`;
+}
+
+// src/memory/index.ts
 function sanitizeKey(key) {
   if (!key || key.trim() === "") {
     return { err: "Error [memory]: Key must not be empty." };
@@ -24,7 +62,7 @@ function createMemory(config = {}) {
   const cwd = _nullishCoalesce(config.cwd, () => ( process.cwd()));
   const memoryDir = _nullishCoalesce(config.memoryDir, () => ( _path.join.call(void 0, cwd, ".agentool", "memory")));
   return _ai.tool.call(void 0, {
-    description: "File-based key-value memory store. Use this to persist notes, context, or any text data across conversations. Supports write, read, list, and delete operations.",
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
     inputSchema: _zod.z.object({
       action: _zod.z.enum(["read", "write", "list", "delete"]).describe(
         "The operation to perform: read, write, list, or delete"
@@ -55,7 +93,7 @@ function createMemory(config = {}) {
             return `Error [memory]: Unknown action "${String(action)}".`;
         }
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
         return `Error [memory]: ${msg}`;
       }
     }
@@ -65,20 +103,19 @@ async function writeEntry(dir, key, content) {
   if (!content && content !== "") {
     return "Error [memory]: Content is required for write action.";
   }
-  await _promises.mkdir.call(void 0, dir, { recursive: true });
-  await _promises.writeFile.call(void 0, _path.join.call(void 0, dir, `${key}.md`), content, "utf-8");
+  await _chunkBIAODQ2Pcjs.writeTextContent.call(void 0, _path.join.call(void 0, dir, `${key}.md`), content);
   return `Saved memory "${key}".`;
 }
 async function readEntry(dir, key) {
   try {
-    return await _promises.readFile.call(void 0, _path.join.call(void 0, dir, `${key}.md`), "utf-8");
+    return await _chunkBIAODQ2Pcjs.readTextContent.call(void 0, _path.join.call(void 0, dir, `${key}.md`));
   } catch (e) {
     return `Error [memory]: Key "${key}" not found.`;
   }
 }
 async function listKeys(dir) {
   try {
-    const files = await _promises.readdir.call(void 0, dir);
+    const files = await _chunkBIAODQ2Pcjs.listDirectory.call(void 0, dir);
     const keys = files.filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
     if (keys.length === 0) return "No memory entries found.";
     return keys.join("\n");
@@ -88,7 +125,7 @@ async function listKeys(dir) {
 }
 async function deleteEntry(dir, key) {
   try {
-    await _promises.unlink.call(void 0, _path.join.call(void 0, dir, `${key}.md`));
+    await _chunkBIAODQ2Pcjs.removeFile.call(void 0, _path.join.call(void 0, dir, `${key}.md`));
     return `Deleted memory "${key}".`;
   } catch (e3) {
     return `Error [memory]: Key "${key}" not found.`;
@@ -99,4 +136,5 @@ var memory = createMemory();
 
 
 
-exports.createMemory = createMemory; exports.memory = memory;
+
+exports.getPrompt = getPrompt; exports.createMemory = createMemory; exports.memory = memory;

package/dist/chunk-M74OQYNK.js

@@ -0,0 +1,69 @@
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
+
+// src/sleep/index.ts
+import { tool, zodSchema } from "ai";
+import { z } from "zod";
+
+// src/sleep/prompt.ts
+function getPrompt(config = {}) {
+  const maxDuration = config.maxDuration ?? 3e5;
+  const maxSec = maxDuration / 1e3;
+  return `Pause execution for a specified duration. Maximum duration: ${maxSec} seconds (${maxDuration}ms).
+
+## When to Use
+- When rate-limited by an external API and need to wait before retrying
+- When waiting for an external process to complete
+- Prefer this over shell sleep commands \u2014 it doesn't hold a shell process
+
+## When NOT to Use
+- Don't sleep between commands that can run immediately \u2014 just run them
+- Don't retry failing commands in a sleep loop \u2014 diagnose the root cause first
+- Avoid long sleeps that block the user \u2014 keep durations short when possible
+
+## Usage Guidelines
+- Durations exceeding the maximum are automatically clamped to ${maxDuration}ms
+- Provide a \`reason\` parameter to document why the sleep is needed
+- Each sleep costs an API turn \u2014 use judiciously`;
+}
+
+// src/sleep/index.ts
+function createSleep(config = {}) {
+  const maxDuration = config.maxDuration ?? 3e5;
+  return tool({
+    description: config.description ?? getPrompt(config),
+    inputSchema: zodSchema(
+      z.object({
+        durationMs: z.number().describe("Duration to sleep in milliseconds"),
+        reason: z.string().optional().describe("Optional reason for the sleep")
+      })
+    ),
+    execute: async ({ durationMs, reason }) => {
+      try {
+        const clamped = Math.max(0, Math.min(durationMs, maxDuration));
+        const start = Date.now();
+        await new Promise((resolve) => setTimeout(resolve, clamped));
+        const elapsed = Date.now() - start;
+        const parts = [`Slept for ${elapsed}ms`];
+        if (reason) parts.push(`Reason: ${reason}`);
+        if (clamped !== durationMs) {
+          parts.push(
+            `(clamped from ${durationMs}ms to ${clamped}ms, max: ${maxDuration}ms)`
+          );
+        }
+        return parts.join(". ");
+      } catch (error) {
+        const message = extractErrorMessage(error);
+        return `Sleep failed: ${message}`;
+      }
+    }
+  });
+}
+var sleep = createSleep();
+
+export {
+  getPrompt,
+  createSleep,
+  sleep
+};

package/dist/{chunk-IMZQ7ELK.cjs → chunk-NQIV6LBH.cjs}

@@ -1,10 +1,45 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }// src/lsp/index.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+
+var _chunkBIAODQ2Pcjs = require('./chunk-BIAODQ2P.cjs');
+
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
+
+// src/lsp/index.ts
 var _ai = require('ai');
 var _zod = require('zod');
 var _child_process = require('child_process');
-var _promises = require('fs/promises');
 var _url = require('url');
 var _path = require('path');
+
+// src/lsp/prompt.ts
+function getPrompt() {
+  return `Interact with Language Server Protocol (LSP) servers to get code intelligence features.
+
+## Supported Operations
+- **goToDefinition**: Find where a symbol is defined
+- **findReferences**: Find all references to a symbol
+- **hover**: Get hover information (documentation, type info) for a symbol
+- **documentSymbol**: Get all symbols (functions, classes, variables) in a document
+- **workspaceSymbol**: Search for symbols across the entire workspace
+- **goToImplementation**: Find implementations of an interface or abstract method
+- **prepareCallHierarchy**: Get call hierarchy item at a position
+- **incomingCalls**: Find all functions/methods that call the function at a position
+- **outgoingCalls**: Find all functions/methods called by the function at a position
+
+## When to Use
+- To navigate code: find definitions, references, implementations
+- To understand code structure: list symbols in a file or workspace
+- To analyze call graphs: trace incoming/outgoing calls
+
+## Usage Guidelines
+- All operations require \`filePath\`, \`line\`, and \`character\` parameters
+- Line and character are **1-based** (as shown in editors), not 0-based
+- An LSP server must be configured for the file's language via \`servers\` config
+- Operations that don't need a position (documentSymbol, workspaceSymbol) still require filePath`;
+}
+
+// src/lsp/index.ts
 var nextId = 1;
 function encodeJsonRpc(msg) {
   const body = JSON.stringify(msg);
@@ -39,13 +74,14 @@ function operationToMethod(operation) {
     documentSymbol: "textDocument/documentSymbol",
     workspaceSymbol: "workspace/symbol",
     goToImplementation: "textDocument/implementation",
+    prepareCallHierarchy: "textDocument/prepareCallHierarchy",
     incomingCalls: "textDocument/prepareCallHierarchy",
     outgoingCalls: "textDocument/prepareCallHierarchy"
   };
   return _nullishCoalesce(map[operation], () => ( operation));
 }
-function buildRequestParams(op, uri, line, char, query) {
-  if (op === "workspaceSymbol") return { query: _nullishCoalesce(query, () => ( "")) };
+function buildRequestParams(op, uri, line, char) {
+  if (op === "workspaceSymbol") return { query: "" };
   const td = { uri };
   if (op === "documentSymbol") return { textDocument: td };
   const pos = { line, character: char };
@@ -122,13 +158,13 @@ async function executeLspOperation(serverConfig, params, timeoutMs) {
     const rpc = (id) => Promise.race([waitForResponse(proc, id, timeoutMs), spawnError]);
     await rpc(initId);
     sendNotification(proc, "initialized", {});
-    const content = await _promises.readFile.call(void 0, absolutePath, "utf-8");
+    const content = await _chunkBIAODQ2Pcjs.readTextContent.call(void 0, absolutePath);
     const langId = _path.extname.call(void 0, absolutePath).replace(".", "") || "plaintext";
     sendNotification(proc, "textDocument/didOpen", {
       textDocument: { uri, languageId: langId, version: 1, text: content }
     });
     const method = operationToMethod(params.operation);
-    const reqParams = buildRequestParams(params.operation, uri, _nullishCoalesce(params.line, () => ( 0)), _nullishCoalesce(params.character, () => ( 0)), params.query);
+    const reqParams = buildRequestParams(params.operation, uri, _nullishCoalesce(params.line, () => ( 0)), _nullishCoalesce(params.character, () => ( 0)));
     let response = await rpc(sendRequest(proc, method, reqParams));
     if (response.error) return `Error [lsp]: Server error: ${response.error.message} (code ${response.error.code})`;
     if ((params.operation === "incomingCalls" || params.operation === "outgoingCalls") && Array.isArray(response.result) && response.result.length > 0) {
@@ -150,21 +186,21 @@ var LSP_OPERATIONS = [
   "documentSymbol",
   "workspaceSymbol",
   "goToImplementation",
+  "prepareCallHierarchy",
   "incomingCalls",
   "outgoingCalls"
 ];
 function createLsp(config = {}) {
   const timeoutMs = _nullishCoalesce(config.timeout, () => ( 3e4));
   return _ai.tool.call(void 0, {
-    description: "Perform language server operations like go-to-definition, find-references, and hover. Requires LSP server configuration. Supports 8 operations: goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, incomingCalls, outgoingCalls.",
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
     inputSchema: _zod.z.object({
       operation: _zod.z.enum(LSP_OPERATIONS).describe("The LSP operation to perform"),
       filePath: _zod.z.string().describe("Path to the file"),
-      line: _zod.z.number().optional().describe("Line number (0-indexed)"),
-      character: _zod.z.number().optional().describe("Character offset (0-indexed)"),
-      query: _zod.z.string().optional().describe("Search query for workspaceSymbol")
+      line: _zod.z.number().int().positive().describe("The line number (1-based, as shown in editors)"),
+      character: _zod.z.number().int().positive().describe("The character offset (1-based, as shown in editors)")
     }),
-    execute: async ({ operation, filePath, line, character, query }) => {
+    execute: async ({ operation, filePath, line, character }) => {
       if (!config.servers || Object.keys(config.servers).length === 0) {
         return 'Error [lsp]: No LSP servers configured. Provide server configuration via createLsp({ servers: { ".ts": { command: "typescript-language-server", args: ["--stdio"] } } })';
       }
@@ -177,11 +213,11 @@ function createLsp(config = {}) {
       try {
         return await executeLspOperation(
           serverConfig,
-          { operation, filePath, line, character, query, cwd: _nullishCoalesce(config.cwd, () => ( process.cwd())) },
+          { operation, filePath, line: line - 1, character: character - 1, cwd: _nullishCoalesce(config.cwd, () => ( process.cwd())) },
           timeoutMs
         );
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
         return `Error [lsp]: ${operation} failed for ${filePath}: ${msg}`;
       }
     }
@@ -193,4 +229,5 @@ var lsp = createLsp();
 
 
 
-exports.executeLspOperation = executeLspOperation; exports.createLsp = createLsp; exports.lsp = lsp;
+
+exports.getPrompt = getPrompt; exports.executeLspOperation = executeLspOperation; exports.createLsp = createLsp; exports.lsp = lsp;

package/dist/chunk-NTGDU5X3.js

@@ -0,0 +1,67 @@
+import {
+  pathExists,
+  writeTextContent
+} from "./chunk-PWBVB6MN.js";
+import {
+  expandPath
+} from "./chunk-I3ONDY7P.js";
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
+
+// src/write/index.ts
+import { tool } from "ai";
+import { z } from "zod";
+
+// src/write/prompt.ts
+function getPrompt() {
+  return `Write text content to a file, creating parent directories as needed. If the file already exists it is overwritten entirely.
+
+Supports absolute paths, relative paths, and tilde (~) expansion.
+
+## When to Use
+- To create new files that don't exist yet
+- To completely rewrite an existing file's content
+- When the changes are so extensive that targeted editing would be impractical
+
+## When NOT to Use
+- To make small, targeted changes to an existing file \u2014 use the file editing tool instead (it only changes what you specify and is less error-prone)
+- Prefer the editing tool for modifications; reserve this tool for creating new files or complete rewrites
+
+## Usage Guidelines
+- This tool overwrites the entire file \u2014 make sure you include all desired content, not just the changes
+- Parent directories are created automatically if they don't exist
+- Read the existing file first before overwriting it, so you don't accidentally lose content`;
+}
+
+// src/write/index.ts
+function createWrite(config = {}) {
+  const cwd = config.cwd ?? process.cwd();
+  return tool({
+    description: config.description ?? getPrompt(),
+    inputSchema: z.object({
+      file_path: z.string().describe("The absolute path to the file to write (must be absolute, not relative)"),
+      content: z.string().describe("Text content to write to the file")
+    }),
+    execute: async ({ file_path, content }) => {
+      try {
+        const absolutePath = expandPath(file_path, cwd);
+        const existed = await pathExists(absolutePath);
+        await writeTextContent(absolutePath, content);
+        const bytes = Buffer.byteLength(content, "utf-8");
+        const verb = existed ? "Updated" : "Created";
+        return `${verb} file: ${absolutePath} (${bytes} bytes)`;
+      } catch (error) {
+        const message = extractErrorMessage(error);
+        return `Error [write]: Failed to write file: ${message}`;
+      }
+    }
+  });
+}
+var write = createWrite();
+
+export {
+  getPrompt,
+  createWrite,
+  write
+};

package/dist/{chunk-ONBH74ZV.cjs → chunk-OYLTQJXT.cjs}

@@ -1,14 +1,18 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
+var _chunkBIAODQ2Pcjs = require('./chunk-BIAODQ2P.cjs');
+
+
 var _chunkQZ5GS6HWcjs = require('./chunk-QZ5GS6HW.cjs');
 
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
+
 // src/diff/index.ts
-var _promises = require('fs/promises');
 var _ai = require('ai');
 var _zod = require('zod');
 
 // src/shared/diff.ts
-
 var _diff = require('diff');
 function diffStrings(oldContent, newContent, options) {
   if (oldContent === newContent) {
@@ -29,8 +33,8 @@ function diffStrings(oldContent, newContent, options) {
 }
 async function diffFiles(oldFilePath, newFilePath, options) {
   const [oldContent, newContent] = await Promise.all([
-    _promises.readFile.call(void 0, oldFilePath, "utf-8"),
-    _promises.readFile.call(void 0, newFilePath, "utf-8")
+    _chunkBIAODQ2Pcjs.readTextContent.call(void 0, oldFilePath),
+    _chunkBIAODQ2Pcjs.readTextContent.call(void 0, newFilePath)
   ]);
   return diffStrings(oldContent, newContent, {
     ...options,
@@ -39,11 +43,30 @@ async function diffFiles(oldFilePath, newFilePath, options) {
   });
 }
 
+// src/diff/prompt.ts
+function getPrompt() {
+  return `Generate a unified diff between two files or two strings.
+
+Supports three modes:
+1. **Two file paths**: \`file_path\` + \`other_file_path\` \u2014 compares the contents of both files
+2. **Two strings**: \`old_content\` + \`new_content\` \u2014 compares the provided strings directly
+3. **File + string**: \`file_path\` + \`old_content\` or \`new_content\` \u2014 compares a file against provided content
+
+## When to Use
+- To preview what changes would look like before making edits
+- To compare two versions of a file or text
+- To generate a diff for review or documentation purposes
+
+## When NOT to Use
+- To actually apply changes to a file \u2014 use the file editing tool instead
+- To read file contents \u2014 use the file reading tool instead`;
+}
+
 // src/diff/index.ts
 function createDiff(config = {}) {
   const cwd = _nullishCoalesce(config.cwd, () => ( process.cwd()));
   return _ai.tool.call(void 0, {
-    description: "Generate a unified diff between two files or two strings. Provide file_path + other_file_path to compare files, or old_content + new_content to compare strings. You can also provide file_path with old_content or new_content to compare a file against provided content.",
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
     inputSchema: _zod.z.object({
       file_path: _zod.z.string().optional().describe("Path to the first file (absolute or relative to cwd)"),
       other_file_path: _zod.z.string().optional().describe("Path to the second file (absolute or relative to cwd)"),
@@ -62,7 +85,7 @@ function createDiff(config = {}) {
         }
         if (file_path && (old_content !== void 0 || new_content !== void 0)) {
           const resolvedPath = _chunkQZ5GS6HWcjs.expandPath.call(void 0, file_path, cwd);
-          const fileContent = await _promises.readFile.call(void 0, resolvedPath, "utf-8");
+          const fileContent = await _chunkBIAODQ2Pcjs.readTextContent.call(void 0, resolvedPath);
           if (old_content !== void 0) {
             return diffStrings(old_content, fileContent, {
               oldLabel: "provided",
@@ -76,7 +99,7 @@ function createDiff(config = {}) {
         }
         return "Error [diff]: Insufficient parameters. Provide either: (1) file_path + other_file_path, (2) old_content + new_content, or (3) file_path + old_content/new_content.";
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
         return `Error [diff]: ${msg}`;
       }
     }
@@ -87,4 +110,5 @@ var diff = createDiff();
 
 
 
-exports.createDiff = createDiff; exports.diff = diff;
+
+exports.getPrompt = getPrompt; exports.createDiff = createDiff; exports.diff = diff;

package/dist/{chunk-6PQLFDGT.js → chunk-PWBVB6MN.js}

@@ -1,6 +1,6 @@
 // src/shared/file.ts
 import { createReadStream } from "fs";
-import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { mkdir, readFile, readdir, stat, unlink, writeFile } from "fs/promises";
 import { dirname } from "path";
 var FAST_PATH_MAX_SIZE = 10 * 1024 * 1024;
 function addLineNumbers({
@@ -25,6 +25,18 @@ async function pathExists(path) {
     return false;
   }
 }
+async function readTextContent(filePath) {
+  return readFile(filePath, "utf-8");
+}
+async function listDirectory(dirPath) {
+  return readdir(dirPath);
+}
+async function removeFile(filePath) {
+  await unlink(filePath);
+}
+async function getFileStats(filePath) {
+  return stat(filePath);
+}
 async function readFileInRange(filePath, offset = 0, maxLines) {
   const stats = await stat(filePath);
   if (stats.isDirectory()) {
@@ -113,5 +125,9 @@ export {
   addLineNumbers,
   writeTextContent,
   pathExists,
+  readTextContent,
+  listDirectory,
+  removeFile,
+  getFileStats,
   readFileInRange
 };

package/dist/{chunk-QEJV2KZ4.cjs → chunk-RIGL3JTS.cjs}

@@ -3,13 +3,48 @@
 var _chunkMIYA7TNRcjs = require('./chunk-MIYA7TNR.cjs');
 
 
+var _chunkBIAODQ2Pcjs = require('./chunk-BIAODQ2P.cjs');
+
+
 
 var _chunkQZ5GS6HWcjs = require('./chunk-QZ5GS6HW.cjs');
 
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
+
 // src/grep/index.ts
-var _promises = require('fs/promises');
 var _ai = require('ai');
 var _zod = require('zod');
+
+// src/grep/prompt.ts
+function getPrompt() {
+  return `Search file contents using ripgrep. Supports regex patterns, context lines, and multiple output modes.
+
+## When to Use
+- To find where a function, variable, string, or pattern is used across files
+- To search for specific code patterns, error messages, or configuration values
+- To count occurrences of a pattern across a codebase
+
+## When NOT to Use
+- To find files by name/extension \u2014 use the dedicated file search tool instead
+- To read a specific file \u2014 use the file reading tool instead
+- Don't use shell commands (grep, rg) for content search when this tool is available
+
+## Output Modes
+- \`files_with_matches\` (default): Returns file paths containing matches, sorted by modification time. Best for discovering which files contain a pattern.
+- \`content\`: Returns matching lines with optional context. Supports \`-A\` (after), \`-B\` (before), \`-C\` (context) for surrounding lines and \`-n\` for line numbers (default: true).
+- \`count\`: Returns match counts per file with totals.
+
+## Usage Guidelines
+- Uses ripgrep regex syntax (not grep). Literal braces need escaping: use \`interface\\{\\}\` to find \`interface{}\`
+- Filter files with the \`glob\` parameter (e.g., "*.js", "*.{ts,tsx}") or \`type\` parameter (e.g., "js", "py")
+- Default head_limit is 250 entries. Pass \`head_limit: 0\` for unlimited (use sparingly \u2014 large results waste context)
+- Use \`offset\` to paginate through large result sets
+- Enable \`multiline: true\` for patterns that span lines (e.g., \`struct \\{[\\s\\S]*?field\`)
+- Use \`-i: true\` for case-insensitive search`;
+}
+
+// src/grep/index.ts
 var VCS_DIRS = [".git", ".svn", ".hg", ".bzr", ".jj", ".sl"];
 var DEFAULT_HEAD_LIMIT = 250;
 function applyHeadLimit(items, limit, offset = 0) {
@@ -48,22 +83,22 @@ function parseGlobPatterns(globFilter) {
 function createGrep(config = {}) {
   const cwd = _nullishCoalesce(config.cwd, () => ( process.cwd()));
   return _ai.tool.call(void 0, {
-    description: 'Search file contents using ripgrep. Supports regex patterns, context lines, and three output modes: "content" (matching lines), "files_with_matches" (file paths), and "count" (match counts).',
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
     inputSchema: _zod.z.object({
-      pattern: _zod.z.string().describe("Regex pattern to search for"),
-      path: _zod.z.string().optional().describe("File or directory to search in"),
-      glob: _zod.z.string().optional().describe('Glob pattern to filter files (e.g. "*.js")'),
-      output_mode: _zod.z.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode. Defaults to "files_with_matches".'),
-      "-B": _zod.z.number().optional().describe("Lines of context before each match"),
-      "-A": _zod.z.number().optional().describe("Lines of context after each match"),
-      "-C": _zod.z.number().optional().describe("Lines of context around each match"),
-      context: _zod.z.number().optional().describe("Context lines (alias for -C)"),
-      "-n": _zod.z.boolean().optional().describe("Show line numbers (content mode, default true)"),
-      "-i": _zod.z.boolean().optional().describe("Case insensitive search"),
-      type: _zod.z.string().optional().describe('File type filter (e.g. "js", "py")'),
-      head_limit: _zod.z.number().optional().describe("Max entries. Default 250, 0 = unlimited."),
-      offset: _zod.z.number().optional().describe("Skip first N entries. Default 0."),
-      multiline: _zod.z.boolean().optional().describe("Enable multiline matching")
+      pattern: _zod.z.string().describe("The regular expression pattern to search for in file contents"),
+      path: _zod.z.string().optional().describe("File or directory to search in (rg PATH). Defaults to current working directory."),
+      glob: _zod.z.string().optional().describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}") - maps to rg --glob'),
+      output_mode: _zod.z.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode: "content" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), "files_with_matches" shows file paths (supports head_limit), "count" shows match counts (supports head_limit). Defaults to "files_with_matches".'),
+      "-B": _zod.z.number().optional().describe('Number of lines to show before each match (rg -B). Requires output_mode: "content", ignored otherwise.'),
+      "-A": _zod.z.number().optional().describe('Number of lines to show after each match (rg -A). Requires output_mode: "content", ignored otherwise.'),
+      "-C": _zod.z.number().optional().describe("Alias for context."),
+      context: _zod.z.number().optional().describe('Number of lines to show before and after each match (rg -C). Requires output_mode: "content", ignored otherwise.'),
+      "-n": _zod.z.boolean().optional().describe('Show line numbers in output (rg -n). Requires output_mode: "content", ignored otherwise. Defaults to true.'),
+      "-i": _zod.z.boolean().optional().describe("Case insensitive search (rg -i)"),
+      type: _zod.z.string().optional().describe("File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types."),
+      head_limit: _zod.z.number().optional().describe('Limit output to first N lines/entries, equivalent to "| head -N". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). Defaults to 250 when unspecified. Pass 0 for unlimited (use sparingly \u2014 large result sets waste context).'),
+      offset: _zod.z.number().optional().describe('Skip first N lines/entries before applying head_limit, equivalent to "| tail -n +N | head -N". Works across all output modes. Defaults to 0.'),
+      multiline: _zod.z.boolean().optional().describe("Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false.")
     }),
     execute: async (input) => {
       try {
@@ -132,7 +167,7 @@ function createGrep(config = {}) {
 
 Total: ${totalMatches} matches in ${fileCount} files` + truncationSuffix(appliedLimit2, offset);
         }
-        const stats = await Promise.allSettled(results.map((f) => _promises.stat.call(void 0, f)));
+        const stats = await Promise.allSettled(results.map((f) => _chunkBIAODQ2Pcjs.getFileStats.call(void 0, f)));
         const sorted = results.map((fp, i) => {
           const r = stats[i];
           const mt = r.status === "fulfilled" ? _nullishCoalesce(r.value.mtimeMs, () => ( 0)) : 0;
@@ -145,7 +180,7 @@ Total: ${totalMatches} matches in ${fileCount} files` + truncationSuffix(applied
         const relative = items.map((f) => _chunkQZ5GS6HWcjs.toRelativePath.call(void 0, f, cwd));
         return relative.join("\n") + truncationSuffix(appliedLimit, offset);
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
         return `Error [grep]: Failed to search: ${msg}`;
       }
     }
@@ -156,4 +191,5 @@ var grep = createGrep();
 
 
 
-exports.createGrep = createGrep; exports.grep = grep;
+
+exports.getPrompt = getPrompt; exports.createGrep = createGrep; exports.grep = grep;