indusagi-coding-agent 0.1.22 → 0.1.24

package/dist/core/tools/edit.js

@@ -1,18 +1,235 @@
+/**
+ * Edit Tool - Precise text replacement with fuzzy matching and diff output
+ *
+ * @module core/tools/edit
+ * @description
+ * Implements the edit tool for the agent. Replaces text in files with:
+ * - Fuzzy matching (handles minor whitespace variations)
+ * - Unified diff output (shows changes)
+ * - Line ending preservation (CRLF, LF)
+ * - BOM handling (UTF-8 with BOM)
+ *
+ * Based on text editing patterns from Anthropic's Claude API (claude-opus model).
+ * Fuzzy matching inspired by Ruby's string-similarity algorithms.
+ * Refactored for precise agent code modification.
+ * - Remote execution support (SSH, containers)
+ * - Exact character-level matching
+ *
+ * ## Tool Interface
+ *
+ * **Input Parameters:**
+ * - `path` (required): File to edit
+ * - `oldText` (required): Text to find (must match exactly or fuzzily)
+ * - `newText` (required): Replacement text
+ *
+ * **Output:**
+ * - Unified diff showing changes
+ * - Line number of first change (for editor navigation)
+ * - Error if pattern not found
+ *
+ * **Error Behavior:**
+ * - Pattern not found → Tool error "Pattern not found"
+ * - File not found → Tool error "ENOENT: no such file"
+ * - Permission denied → Tool error "EACCES: permission denied"
+ * - Multiple matches → Tool error "Ambiguous match" (if fuzzy enabled)
+ *
+ * ## Usage in Agent
+ *
+ * The agent uses this tool to:
+ * - Refactor code (rename functions, update logic)
+ * - Fix bugs (change implementations)
+ * - Update configuration
+ * - Modify test cases
+ * - Apply patches
+ *
+ * ## Matching Algorithm
+ *
+ * **Exact Matching (default):**
+ * - Finds exact string match
+ * - Case-sensitive
+ * - Whitespace-sensitive
+ *
+ * **Fuzzy Matching (when enabled):**
+ * - Normalizes whitespace
+ * - Handles line ending differences
+ * - Finds similar strings (for minor variations)
+ * - Reports ambiguity if multiple matches
+ *
+ * ## Features
+ *
+ * **Line Ending Preservation:**
+ * - Detects file's line ending (CRLF or LF)
+ * - Preserves in replaced content
+ * - Handles mixed line endings gracefully
+ *
+ * **Normalization:**
+ * - Strips BOM if present (UTF-8 with BOM)
+ * - Normalizes to LF internally
+ * - Restores original format on write
+ *
+ * **Diff Output:**
+ * - Unified diff format
+ * - Shows context lines
+ * - Indicates changed lines
+ * - Line numbers for navigation
+ *
+ * **Unicode Support:**
+ * - Handles UTF-8 correctly
+ * - Preserves multibyte characters
+ * - BOM aware
+ *
+ * ## Security
+ *
+ * **Path validation:**
+ * - All paths resolved relative to cwd
+ * - No path traversal
+ * - Directory traversal prevented
+ *
+ * **Text matching:**
+ * - Pattern matching is literal (not regex)
+ * - No code execution via replacement
+ * - No template substitution
+ *
+ * **File safety:**
+ * - Read-write permission check
+ * - Atomic write (no partial files)
+ * - Error on read failures
+ *
+ * ## Customization
+ *
+ * **Fuzzy Matching:**
+ * ```typescript
+ * const tool = createEditTool(cwd, {
+ *   fuzzyMatch: true, // Enable fuzzy matching
+ * });
+ * ```
+ *
+ * **Remote Execution (SSH):**
+ * ```typescript
+ * const sshTool = createEditTool(cwd, {
+ *   operations: {
+ *     readFile: (path) => sshExec(`cat ${path}`),
+ *     writeFile: (path, content) => sshExec(`cat > ${path}`, content),
+ *     access: (path) => sshExec(`test -r -w ${path}`),
+ *   },
+ * });
+ * ```
+ *
+ * ## Examples
+ *
+ * ### Simple replacement
+ * ```typescript
+ * // Agent calls: edit {
+ * //   path: "main.ts",
+ * //   oldText: "const x = 1;",
+ * //   newText: "const x = 2;"
+ * // }
+ * ```
+ *
+ * ### Multi-line replacement
+ * ```typescript
+ * // Agent calls: edit {
+ * //   path: "server.ts",
+ * //   oldText: "app.listen(3000);\nconsole.log('Ready');",
+ * //   newText: "app.listen(process.env.PORT || 3000);\nconsole.log(`Listening on port ${port}`);"
+ * // }
+ * ```
+ *
+ * ## Attribution
+ *
+ * Based on: indusagi-agent edit tool
+ * Modifications:
+ * - Added fuzzy matching option
+ * - Added unified diff output
+ * - Added line ending preservation
+ * - Added custom operations interface
+ * - Improved error messages
+ */
 import { Type } from "@sinclair/typebox";
 import { constants } from "fs";
 import { access as fsAccess, readFile as fsReadFile, writeFile as fsWriteFile } from "fs/promises";
 import { detectLineEnding, fuzzyFindText, generateDiffString, normalizeForFuzzyMatch, normalizeToLF, restoreLineEndings, stripBom, } from "./edit-diff.js";
 import { resolveToCwd } from "./path-utils.js";
+// ============================================================================
+// Schema & Types
+// ============================================================================
+/**
+ * JSON Schema for edit tool parameters
+ * @internal
+ */
 const editSchema = Type.Object({
     path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
     oldText: Type.String({ description: "Exact text to find and replace (must match exactly)" }),
     newText: Type.String({ description: "New text to replace the old text with" }),
 });
+/**
+ * Default edit operations using local filesystem
+ * @internal
+ */
 const defaultEditOperations = {
     readFile: (path) => fsReadFile(path),
     writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
     access: (path) => fsAccess(path, constants.R_OK | constants.W_OK),
 };
+// ============================================================================
+// Tool Factory & Exports
+// ============================================================================
+/**
+ * Create an edit tool with custom configuration
+ *
+ * Creates an AgentTool that can edit files with:
+ * - Exact text replacement
+ * - Fuzzy matching (optional)
+ * - Unified diff output
+ * - Line ending preservation
+ * - Remote execution support
+ *
+ * **Tool Behavior:**
+ * - Resolves paths relative to working directory
+ * - Prevents path traversal
+ * - Finds and replaces exact text
+ * - Preserves file format (line endings, BOM)
+ * - Returns unified diff of changes
+ *
+ * **Tool Parameters:**
+ * - `path` (required): File to edit
+ * - `oldText` (required): Text to find
+ * - `newText` (required): Replacement text
+ *
+ * **Tool Output:**
+ * - Success message with unified diff
+ * - Details: Diff and first changed line number
+ * - Errors: Tool error with message
+ *
+ * **Error Handling:**
+ * - Pattern not found: Tool error "Pattern not found"
+ * - File not found: Tool error "ENOENT: no such file"
+ * - Permission denied: Tool error "EACCES: permission denied"
+ * - Other errors: Tool error with message
+ *
+ * @param cwd - Working directory for relative path resolution
+ *   - All relative paths resolved from this directory
+ *   - Prevents directory traversal attacks
+ *
+ * @param options - Optional configuration
+ *   - operations: Custom file editing backend (default: filesystem)
+ *
+ * @returns AgentTool instance ready to use
+ *
+ * @example
+ * ```typescript
+ * // Basic tool
+ * const tool = createEditTool(process.cwd());
+ *
+ * // With remote backend (SSH)
+ * const remoteTool = createEditTool(cwd, {
+ *   operations: sshOperations,
+ * });
+ * ```
+ *
+ * @see EditToolOptions for detailed configuration
+ * @see EditOperations for custom backend interface
+ */
 export function createEditTool(cwd, options) {
     const ops = options?.operations ?? defaultEditOperations;
     return {
@@ -142,5 +359,26 @@ export function createEditTool(cwd, options) {
     };
 }
 /** Default edit tool using process.cwd() - for backwards compatibility */
+/**
+ * Default edit tool instance
+ *
+ * Pre-created edit tool using current process working directory.
+ * Supports exact text replacement with unified diff output.
+ *
+ * Equivalent to:
+ * ```typescript
+ * const editTool = createEditTool(process.cwd());
+ * ```
+ *
+ * For custom configuration or remote backends, use createEditTool() directly.
+ *
+ * @example
+ * ```typescript
+ * import { editTool } from "./tools/edit.js";
+ * const agent = new Agent({ tools: [editTool] });
+ * ```
+ *
+ * @see createEditTool for custom configuration
+ */
 export const editTool = createEditTool(process.cwd());
 //# sourceMappingURL=edit.js.map

package/dist/core/tools/edit.js.map

@@ -1 +1 @@
-{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../../src/core/tools/edit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,QAAQ,IAAI,UAAU,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,QAAQ,GACR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,iDAAiD,EAAE,CAAC;IACrF,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,qDAAqD,EAAE,CAAC;IAC5F,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,uCAAuC,EAAE,CAAC;CAC9E,CAAC,CAAC;AAsBH,MAAM,qBAAqB,GAAmB;IAC7C,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;IACpC,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC;IACjE,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;CACjE,CAAC;AAOF,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,OAAyB;IACpE,MAAM,GAAG,GAAG,OAAO,EAAE,UAAU,IAAI,qBAAqB,CAAC;IAEzD,OAAO;QACN,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,MAAM;QACb,WAAW,EACV,mIAAmI;QACpI,UAAU,EAAE,UAAU;QACtB,OAAO,EAAE,KAAK,EACb,WAAmB,EACnB,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAsD,EAC9E,MAAoB,EACnB,EAAE;YACH,MAAM,YAAY,GAAG,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAE7C,OAAO,IAAI,OAAO,CAGf,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACtB,2BAA2B;gBAC3B,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;oBACrB,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;oBACvC,OAAO;gBACR,CAAC;gBAED,IAAI,OAAO,GAAG,KAAK,CAAC;gBAEpB,uBAAuB;gBACvB,MAAM,OAAO,GAAG,GAAG,EAAE;oBACpB,OAAO,GAAG,IAAI,CAAC;oBACf,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;gBACxC,CAAC,CAAC;gBAEF,IAAI,MAAM,EAAE,CAAC;oBACZ,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC3D,CAAC;gBAED,6BAA6B;gBAC7B,CAAC,KAAK,IAAI,EAAE;oBACX,IAAI,CAAC;wBACJ,uBAAuB;wBACvB,IAAI,CAAC;4BACJ,MAAM,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;wBAChC,CAAC;wBAAC,MAAM,CAAC;4BACR,IAAI,MAAM,EAAE,CAAC;gCACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;4BAC9C,CAAC;4BACD,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC,CAAC;4BAC7C,OAAO;wBACR,CAAC;wBAED,kCAAkC;wBAClC,IAAI,OAAO,EAAE,CAAC;4BACb,OAAO;wBACR,CAAC;wBAED,gBAAgB;wBAChB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;wBAChD,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;wBAE5C,iCAAiC;wBACjC,IAAI,OAAO,EAAE,CAAC;4BACb,OAAO;wBACR,CAAC;wBAED,yEAAyE;wBACzE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;wBAEpD,MAAM,cAAc,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;wBACjD,MAAM,iBAAiB,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;wBACjD,MAAM,iBAAiB,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;wBACjD,MAAM,iBAAiB,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;wBAEjD,+EAA+E;wBAC/E,MAAM,WAAW,GAAG,aAAa,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,CAAC;wBAExE,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;4BACxB,IAAI,MAAM,EAAE,CAAC;gCACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;4BAC9C,CAAC;4BACD,MAAM,CACL,IAAI,KAAK,CACR,oCAAoC,IAAI,0EAA0E,CAClH,CACD,CAAC;4BACF,OAAO;wBACR,CAAC;wBAED,mEAAmE;wBACnE,MAAM,YAAY,GAAG,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;wBAC/D,MAAM,YAAY,GAAG,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;wBAC/D,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;wBAEhE,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;4BACrB,IAAI,MAAM,EAAE,CAAC;gCACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;4BAC9C,CAAC;4BACD,MAAM,CACL,IAAI,KAAK,CACR,SAAS,WAAW,+BAA+B,IAAI,2EAA2E,CAClI,CACD,CAAC;4BACF,OAAO;wBACR,CAAC;wBAED,kCAAkC;wBAClC,IAAI,OAAO,EAAE,CAAC;4BACb,OAAO;wBACR,CAAC;wBAED,sDAAsD;wBACtD,gFAAgF;wBAChF,MAAM,WAAW,GAAG,WAAW,CAAC,qBAAqB,CAAC;wBACtD,MAAM,UAAU,GACf,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC;4BAC3C,iBAAiB;4BACjB,WAAW,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;wBAEpE,oDAAoD;wBACpD,IAAI,WAAW,KAAK,UAAU,EAAE,CAAC;4BAChC,IAAI,MAAM,EAAE,CAAC;gCACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;4BAC9C,CAAC;4BACD,MAAM,CACL,IAAI,KAAK,CACR,sBAAsB,IAAI,0IAA0I,CACpK,CACD,CAAC;4BACF,OAAO;wBACR,CAAC;wBAED,MAAM,YAAY,GAAG,GAAG,GAAG,kBAAkB,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;wBAC1E,MAAM,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;wBAEhD,iCAAiC;wBACjC,IAAI,OAAO,EAAE,CAAC;4BACb,OAAO;wBACR,CAAC;wBAED,yBAAyB;wBACzB,IAAI,MAAM,EAAE,CAAC;4BACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;wBAC9C,CAAC;wBAED,MAAM,UAAU,GAAG,kBAAkB,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;wBAC/D,OAAO,CAAC;4BACP,OAAO,EAAE;gCACR;oCACC,IAAI,EAAE,MAAM;oCACZ,IAAI,EAAE,iCAAiC,IAAI,GAAG;iCAC9C;6BACD;4BACD,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,gBAAgB,EAAE,UAAU,CAAC,gBAAgB,EAAE;yBACjF,CAAC,CAAC;oBACJ,CAAC;oBAAC,OAAO,KAAU,EAAE,CAAC;wBACrB,yBAAyB;wBACzB,IAAI,MAAM,EAAE,CAAC;4BACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;wBAC9C,CAAC;wBAED,IAAI,CAAC,OAAO,EAAE,CAAC;4BACd,MAAM,CAAC,KAAK,CAAC,CAAC;wBACf,CAAC;oBACF,CAAC;gBACF,CAAC,CAAC,EAAE,CAAC;YACN,CAAC,CAAC,CAAC;QACJ,CAAC;KACD,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC"}
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../../src/core/tools/edit.ts"],"names":[],"mappings":"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"}

package/dist/core/tools/find.d.ts

@@ -1,33 +1,197 @@
+/**
+ * Find Tool - Search for files using glob patterns
+ *
+ * Purpose: Implements find tool for agent to search files using glob patterns.
+ * Searches with glob patterns (*, **, ?, braces), directory scoping, result limiting.
+ *
+ * Input Parameters:
+ * - pattern (required): Glob pattern (e.g., *.ts, src path to json files)
+ * - path (optional): Search directory (default: current directory)
+ * - limit (optional): Max results (default: 1000)
+ *
+ * Output:
+ * - List of matching file paths
+ * - Truncation info if results exceed limit
+ * - Error if pattern invalid
+ *
+ * Features:
+ * - Fast searching using fd if available, falls back to JS glob
+ * - Respects .gitignore by default
+ * - Result limiting prevents OOM
+ * - Path safety: no traversal, validated paths
+ * - Pattern validation: literal matching, not code
+ *
+ * Security:
+ * - Patterns validated for safety
+ * - All paths resolved relative to cwd
+ * - Directory traversal prevented
+ * - Invalid paths caught
+ * - Max 1000 results by default prevents DOS
+ *
+ * Examples:
+ * - Find all TypeScript files: *.ts
+ * - Find JSON recursively: all paths to json files
+ * - Find tests in src: src path test ts
+ * - Exclude node_modules: src without node_modules
+ *
+ * Based on Unix find and Node.js glob library.
+ * Refactored for agent file discovery with pattern filtering.
+ * Modifications: fd support, custom operations, glob patterns, error handling.
+ */
 import type { AgentTool } from "indusagi/agent";
 import { type TruncationResult } from "./truncate.js";
+/**
+ * JSON Schema for find tool parameters
+ * @internal
+ */
 declare const findSchema: import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>;
+/**
+ * Tool-specific details returned with find results
+ */
 export interface FindToolDetails {
+    /** Truncation information if result count exceeded limit */
     truncation?: TruncationResult;
+    /** Number of results if limit was reached */
     resultLimitReached?: number;
 }
 /**
- * Pluggable operations for the find tool.
- * Override these to delegate file search to remote systems (e.g., SSH).
+ * Pluggable interface for file search operations
+ *
+ * Allows custom implementations for:
+ * - Remote file systems (SSH, cloud storage)
+ * - Virtual file systems (in-memory, testing)
+ * - Custom search backends
+ * - Monitoring and logging
  */
 export interface FindOperations {
-    /** Check if path exists */
+    /**
+     * Check if path exists
+     *
+     * @param absolutePath - Full path to check
+     * @returns true if path exists
+     */
     exists: (absolutePath: string) => Promise<boolean> | boolean;
-    /** Find files matching glob pattern. Returns relative paths. */
+    /**
+     * Find files matching glob pattern
+     *
+     * @param pattern - Glob pattern to match
+     * @param cwd - Search root directory
+     * @param options - Search options
+     *   - ignore: Patterns to exclude
+     *   - limit: Max results to return
+     * @returns Array of relative paths matching pattern
+     */
     glob: (pattern: string, cwd: string, options: {
         ignore: string[];
         limit: number;
     }) => Promise<string[]> | string[];
 }
+/**
+ * Configuration options for the find tool
+ */
 export interface FindToolOptions {
-    /** Custom operations for find. Default: local filesystem + fd */
+    /**
+     * Custom operations for file searching
+     *
+     * Default: Local filesystem with fd or glob
+     * Custom: SSH, cloud storage, testing mocks
+     *
+     * @example
+     * ```typescript
+     * const tool = createFindTool(cwd, {
+     *   operations: {
+     *     exists: (path) => sshExec(`test -e ${path}`),
+     *     glob: (pattern, cwd, opts) => sshExec(`find ${cwd} -name ${pattern}`),
+     *   },
+     * });
+     * ```
+     */
     operations?: FindOperations;
 }
+/**
+ * Create a find tool with custom configuration
+ *
+ * Creates an AgentTool that can search for files with:
+ * - Glob pattern matching
+ * - Directory scope limiting
+ * - Result limiting
+ * - Truncation for large results
+ * - Remote execution support
+ * - Fast fd-based search
+ *
+ * **Tool Behavior:**
+ * - Resolves paths relative to working directory
+ * - Prevents path traversal
+ * - Uses fd or glob for searching
+ * - Respects .gitignore
+ * - Limits results (default: 1000)
+ * - Truncates results if too many
+ *
+ * **Tool Parameters:**
+ * - `pattern` (required): Glob pattern (e.g., "*.ts")
+ * - `path` (optional): Search directory (default: cwd)
+ * - `limit` (optional): Max results (default: 1000)
+ *
+ * **Tool Output:**
+ * - List of matching file paths
+ * - Details: Truncation info and limit reached count
+ * - Errors: Tool error with message
+ *
+ * **Error Handling:**
+ * - Invalid directory: Tool error "Path outside working directory"
+ * - Invalid pattern: Tool error "Invalid glob pattern"
+ * - Search errors: Tool error with message
+ *
+ * @param cwd - Working directory for relative path resolution
+ *   - All relative paths resolved from this directory
+ *   - Prevents directory traversal attacks
+ *
+ * @param options - Optional configuration
+ *   - operations: Custom search backend (default: local filesystem)
+ *
+ * @returns AgentTool instance ready to use
+ *
+ * @example
+ * ```typescript
+ * // Basic tool
+ * const tool = createFindTool(process.cwd());
+ *
+ * // With remote backend (SSH)
+ * const remoteTool = createFindTool(cwd, {
+ *   operations: sshOperations,
+ * });
+ * ```
+ *
+ * @see FindToolOptions for detailed configuration
+ * @see FindOperations for custom backend interface
+ */
 export declare function createFindTool(cwd: string, options?: FindToolOptions): AgentTool<typeof findSchema>;
 /** Default find tool using process.cwd() - for backwards compatibility */
+/**
+ * Default find tool instance
+ *
+ * Pre-created find tool using current process working directory.
+ * Supports glob pattern matching with result limiting.
+ *
+ * Equivalent to:
+ * ```typescript
+ * const findTool = createFindTool(process.cwd());
+ * ```
+ *
+ * For custom configuration or remote backends, use createFindTool() directly.
+ *
+ * @example
+ * ```typescript
+ * import { findTool } from "./tools/find.js";
+ * const agent = new Agent({ tools: [findTool] });
+ * ```
+ *
+ * @see createFindTool for custom configuration
+ */
 export declare const findTool: AgentTool<import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;

package/dist/core/tools/find.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/core/tools/find.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQhD,OAAO,EAAiC,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAEnG,QAAA,MAAM,UAAU;;;;EAMd,CAAC;AAIH,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,2BAA2B;IAC3B,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7D,gEAAgE;IAChE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC;CACnH;AAUD,MAAM,WAAW,eAAe;IAC/B,iEAAiE;IACjE,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CA0NnG;AAED,0EAA0E;AAC1E,eAAO,MAAM,QAAQ;;;;QAAgC,CAAC"}
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/core/tools/find.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQhD,OAAO,EAAiC,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAMnG;;;GAGG;AACH,QAAA,MAAM,UAAU;;;;EAMd,CAAC;AAQH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,4DAA4D;IAC5D,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;OAKG;IACH,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAE7D;;;;;;;;;OASG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC;CACnH;AAcD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CA0NnG;AAED,0EAA0E;AAC1E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,QAAQ;;;;QAAgC,CAAC"}

package/dist/core/tools/find.js

@@ -1,3 +1,43 @@
+/**
+ * Find Tool - Search for files using glob patterns
+ *
+ * Purpose: Implements find tool for agent to search files using glob patterns.
+ * Searches with glob patterns (*, **, ?, braces), directory scoping, result limiting.
+ *
+ * Input Parameters:
+ * - pattern (required): Glob pattern (e.g., *.ts, src path to json files)
+ * - path (optional): Search directory (default: current directory)
+ * - limit (optional): Max results (default: 1000)
+ *
+ * Output:
+ * - List of matching file paths
+ * - Truncation info if results exceed limit
+ * - Error if pattern invalid
+ *
+ * Features:
+ * - Fast searching using fd if available, falls back to JS glob
+ * - Respects .gitignore by default
+ * - Result limiting prevents OOM
+ * - Path safety: no traversal, validated paths
+ * - Pattern validation: literal matching, not code
+ *
+ * Security:
+ * - Patterns validated for safety
+ * - All paths resolved relative to cwd
+ * - Directory traversal prevented
+ * - Invalid paths caught
+ * - Max 1000 results by default prevents DOS
+ *
+ * Examples:
+ * - Find all TypeScript files: *.ts
+ * - Find JSON recursively: all paths to json files
+ * - Find tests in src: src path test ts
+ * - Exclude node_modules: src without node_modules
+ *
+ * Based on Unix find and Node.js glob library.
+ * Refactored for agent file discovery with pattern filtering.
+ * Modifications: fd support, custom operations, glob patterns, error handling.
+ */
 import { Type } from "@sinclair/typebox";
 import { spawnSync } from "child_process";
 import { existsSync } from "fs";
@@ -6,6 +46,13 @@ import path from "path";
 import { ensureTool } from "../../utils/tools-manager.js";
 import { resolveToCwd } from "./path-utils.js";
 import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from "./truncate.js";
+// ============================================================================
+// Schema & Types
+// ============================================================================
+/**
+ * JSON Schema for find tool parameters
+ * @internal
+ */
 const findSchema = Type.Object({
     pattern: Type.String({
         description: "Glob pattern to match files, e.g. '*.ts', '**/*.json', or 'src/**/*.spec.ts'",
@@ -13,7 +60,15 @@ const findSchema = Type.Object({
     path: Type.Optional(Type.String({ description: "Directory to search in (default: current directory)" })),
     limit: Type.Optional(Type.Number({ description: "Maximum number of results (default: 1000)" })),
 });
+/**
+ * Default maximum results for find operations
+ * @internal
+ */
 const DEFAULT_LIMIT = 1000;
+/**
+ * Default find operations using local filesystem and glob
+ * @internal
+ */
 const defaultFindOperations = {
     exists: existsSync,
     glob: (_pattern, _searchCwd, _options) => {
@@ -21,6 +76,66 @@ const defaultFindOperations = {
         return [];
     },
 };
+// ============================================================================
+// Tool Factory & Exports
+// ============================================================================
+/**
+ * Create a find tool with custom configuration
+ *
+ * Creates an AgentTool that can search for files with:
+ * - Glob pattern matching
+ * - Directory scope limiting
+ * - Result limiting
+ * - Truncation for large results
+ * - Remote execution support
+ * - Fast fd-based search
+ *
+ * **Tool Behavior:**
+ * - Resolves paths relative to working directory
+ * - Prevents path traversal
+ * - Uses fd or glob for searching
+ * - Respects .gitignore
+ * - Limits results (default: 1000)
+ * - Truncates results if too many
+ *
+ * **Tool Parameters:**
+ * - `pattern` (required): Glob pattern (e.g., "*.ts")
+ * - `path` (optional): Search directory (default: cwd)
+ * - `limit` (optional): Max results (default: 1000)
+ *
+ * **Tool Output:**
+ * - List of matching file paths
+ * - Details: Truncation info and limit reached count
+ * - Errors: Tool error with message
+ *
+ * **Error Handling:**
+ * - Invalid directory: Tool error "Path outside working directory"
+ * - Invalid pattern: Tool error "Invalid glob pattern"
+ * - Search errors: Tool error with message
+ *
+ * @param cwd - Working directory for relative path resolution
+ *   - All relative paths resolved from this directory
+ *   - Prevents directory traversal attacks
+ *
+ * @param options - Optional configuration
+ *   - operations: Custom search backend (default: local filesystem)
+ *
+ * @returns AgentTool instance ready to use
+ *
+ * @example
+ * ```typescript
+ * // Basic tool
+ * const tool = createFindTool(process.cwd());
+ *
+ * // With remote backend (SSH)
+ * const remoteTool = createFindTool(cwd, {
+ *   operations: sshOperations,
+ * });
+ * ```
+ *
+ * @see FindToolOptions for detailed configuration
+ * @see FindOperations for custom backend interface
+ */
 export function createFindTool(cwd, options) {
     const customOps = options?.operations;
     return {
@@ -202,5 +317,26 @@ export function createFindTool(cwd, options) {
     };
 }
 /** Default find tool using process.cwd() - for backwards compatibility */
+/**
+ * Default find tool instance
+ *
+ * Pre-created find tool using current process working directory.
+ * Supports glob pattern matching with result limiting.
+ *
+ * Equivalent to:
+ * ```typescript
+ * const findTool = createFindTool(process.cwd());
+ * ```
+ *
+ * For custom configuration or remote backends, use createFindTool() directly.
+ *
+ * @example
+ * ```typescript
+ * import { findTool } from "./tools/find.js";
+ * const agent = new Agent({ tools: [findTool] });
+ * ```
+ *
+ * @see createFindTool for custom configuration
+ */
 export const findTool = createFindTool(process.cwd());
 //# sourceMappingURL=find.js.map