@semalt-ai/code 1.8.5 → 1.20.0

package/lib/tool_specs.js

@@ -50,7 +50,11 @@ const TOOL_SPECS = {
   },
 
   read_file: {
-    description: 'Read a UTF-8 text file and return its full contents.',
+    description: 'Read a UTF-8 text file. Paginated: by default returns the first ~2000 lines; '
+      + 'if the file is longer the result ends with a [PARTIAL] notice giving the total line count '
+      + 'and the start_line for the next page. Use start_line/end_line to read a specific slice '
+      + '(also capped to ~2000 lines). Set show_line_numbers=true when you need line numbers to '
+      + 'target an edit_file call (off by default — keeps content copyable for replace_in_file and cheaper).',
     parameters: {
       type: 'object',
       properties: {
@@ -58,6 +62,39 @@ const TOOL_SPECS = {
           type: 'string',
           description: 'Absolute or relative path to the file to read',
         },
+        start_line: {
+          type: 'integer',
+          description: 'First line to read (1-based, inclusive). Omit to start at line 1.',
+        },
+        end_line: {
+          type: 'integer',
+          description: 'Last line to read (1-based, inclusive). Omit to read to the line cap. '
+            + 'A range wider than the line cap is still capped — page with start_line.',
+        },
+        show_line_numbers: {
+          type: 'boolean',
+          description: 'Prefix each line with its 1-based line number (aligned with edit_file). '
+            + 'Default false. Turn on when you intend to edit by line number.',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  view_image: {
+    description: 'Load a LOCAL image file (PNG, JPEG, GIF, or WebP) into YOUR OWN vision context so you can '
+      + 'analyze it — read text/diagrams in it, inspect a screenshot, compare a mockup, etc. The image is made '
+      + 'visible to YOU (the model) for the next turn; it is NOT displayed to the user, so never say "take a look" '
+      + 'or otherwise refer to the image as something the user can see. To analyze an image that lives at a URL, '
+      + 'first use `download <url>` to save it to the working directory, then call view_image on the saved path. '
+      + 'Unsupported formats, oversized files (image_max_bytes), or missing paths return a clear error, not a crash.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to a local image file (PNG/JPEG/GIF/WebP) to load into vision context',
+        },
       },
       required: ['path'],
     },
@@ -228,7 +265,7 @@ const TOOL_SPECS = {
   },
 
   edit_file: {
-    description: 'Replace the contents of a single line in a file, identified by 1-based line number.',
+    description: 'Replace a single line, or a contiguous range of lines, in a file by 1-based line number. With end_line set, lines line..end_line are replaced wholesale by content (which may itself span multiple lines) — a regex-free way to swap a block: read the slice with read_file (start_line/end_line + show_line_numbers), then replace that exact range. For large block edits this and a literal replace_in_file are the two supported paths.',
     parameters: {
       type: 'object',
       properties: {
@@ -238,12 +275,17 @@ const TOOL_SPECS = {
         },
         line: {
           type: 'integer',
-          description: '1-based line number of the line to replace',
+          description: '1-based line number of the (first) line to replace',
+          minimum: 1,
+        },
+        end_line: {
+          type: 'integer',
+          description: 'Optional 1-based last line of the range to replace (inclusive). Omit for a single-line edit. Must be >= line and within the file.',
           minimum: 1,
         },
         content: {
           type: 'string',
-          description: 'New text for the target line; trailing newline is added automatically when the file is rejoined',
+          description: 'New text for the target line or range; may contain newlines to expand a range into several lines. Trailing newline is added automatically when the file is rejoined.',
           default: '',
         },
       },
@@ -289,8 +331,72 @@ const TOOL_SPECS = {
     },
   },
 
+  grep: {
+    description: 'Search file contents by regular expression across the working tree and return the actual matches (file:line:text), so you can navigate to the relevant lines and read only a slice instead of whole files. Honors .gitignore, skips binary files and node_modules/.git. Prefers ripgrep when available with an identical pure-Node fallback. output_mode selects what is returned: "content" (default) gives file:line:text per match ("show me the lines"); "files_with_matches" gives just the unique file paths ("which files contain this"); "count" gives per-file and total match counts ("how many") — count/files_with_matches return almost nothing, so prefer them when you do not need the line text. Results are bounded by head_limit (default 100); when more matches exist than are shown, a truncation notice tells you how many were omitted — narrow the pattern, switch to count/files_with_matches, or raise head_limit.',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: {
+          type: 'string',
+          description: 'Regular expression to search for (matched per line)',
+        },
+        path: {
+          type: 'string',
+          description: 'Optional search target: a FILE path (search just that file — absolute or relative, like search_in_file), a DIRECTORY path (search recursively under it), or a GLOB filter limiting which files in the working tree are searched, e.g. "*.js" or "src/**/*.ts". A path that is neither an existing file nor directory is treated as a glob. If a supplied path/glob matches nothing to search, grep returns a diagnostic error rather than a silent zero-match result.',
+        },
+        ignore_case: {
+          type: 'boolean',
+          description: 'Case-insensitive match when true',
+          default: false,
+        },
+        output_mode: {
+          type: 'string',
+          enum: ['content', 'files_with_matches', 'count'],
+          description: 'What to return: "content" = file:line:text per match (default); "files_with_matches" = unique file paths only; "count" = match counts per file and total. Use count/files_with_matches when you only need how many / which files.',
+          default: 'content',
+        },
+        head_limit: {
+          type: 'integer',
+          description: 'Maximum number of results to serialize into context (default 100): match lines in content mode, files in files_with_matches/count mode. Excess is omitted with a truncation notice.',
+        },
+        offset: {
+          type: 'integer',
+          description: 'Number of results to skip before serializing (for paging through a large match set). Default 0.',
+        },
+      },
+      required: ['pattern'],
+    },
+  },
+
+  glob: {
+    description: 'List files matching a glob pattern (relative paths). Skips node_modules/.git and hidden entries. The file list is bounded by head_limit (default 100); when more files match than are shown, a truncation notice reports how many were omitted — narrow the glob or raise head_limit.',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: {
+          type: 'string',
+          description: 'Glob pattern such as "*.ts" or "src/**/*.js"; matches the basename when it has no slash, otherwise the relative path',
+        },
+        path: {
+          type: 'string',
+          description: 'Base directory to search from; defaults to the current working directory',
+          default: '.',
+        },
+        head_limit: {
+          type: 'integer',
+          description: 'Maximum number of file paths to serialize into context (default 100). Excess is omitted with a truncation notice.',
+        },
+        offset: {
+          type: 'integer',
+          description: 'Number of file paths to skip before serializing (for paging). Default 0.',
+        },
+      },
+      required: ['pattern'],
+    },
+  },
+
   replace_in_file: {
-    description: 'Regex-replace occurrences of a pattern in a file; returns the number of replacements made.',
+    description: 'Exact string replacement in a file (Claude Code Edit model). The search text is matched LITERALLY by default — byte-for-byte, NO regex — so paste the exact verbatim code, including all whitespace and indentation, even if it contains ( ) { } . [ ] $ etc. The match must be UNIQUE: if the search string is not found the call ERRORS and the file is unchanged; if it appears more than once the call ERRORS (asking you to add surrounding context) unless you set replace_all:true. Returns the honest number of replacements made. Set regex:true to interpret the search as a JavaScript regular expression instead (bounded: long or backtracking-prone regexes are rejected). For block edits by line number, see line-range edit_file.',
     parameters: {
       type: 'object',
       properties: {
@@ -300,16 +406,26 @@ const TOOL_SPECS = {
         },
         search: {
           type: 'string',
-          description: 'JavaScript regular-expression pattern to search for',
+          description: 'Exact text to find. Matched literally (verbatim, no regex) unless regex:true is set. Include enough surrounding context that it appears EXACTLY ONCE in the file, or set replace_all:true.',
         },
         replace: {
           type: 'string',
-          description: 'Replacement string; supports the standard $1, $2, $& back-references',
+          description: 'Replacement string. In literal mode (default) it is inserted as raw text. In regex mode it supports the standard $1, $2, $& back-references.',
           default: '',
         },
+        replace_all: {
+          type: 'boolean',
+          description: 'Replace ALL occurrences instead of requiring a unique match. Without this, matching more than one occurrence is an error. The result reports the actual number replaced.',
+          default: false,
+        },
+        regex: {
+          type: 'boolean',
+          description: 'Opt into regex mode: interpret search as a JavaScript regular expression (bounded by a length cap + nested-quantifier guard). Default false = literal exact match. The uniqueness guard still applies in regex mode (use the g flag or replace_all to replace multiple).',
+          default: false,
+        },
         flags: {
           type: 'string',
-          description: 'Regex flags, any combination of g/i/m/s/u/y; the "g" flag is added automatically if omitted',
+          description: 'Regex flags (only meaningful with regex:true), any combination of g/i/m/s/u/y. Without "g" (and without replace_all) the match must be unique.',
           default: '',
         },
       },
@@ -384,7 +500,7 @@ const TOOL_SPECS = {
   },
 
   http_get: {
-    description: 'Perform an HTTP GET and return the response status code and body, truncated to a configured byte cap.',
+    description: 'Fetch a web page. The `mode` parameter selects how much processing to apply: "summarized" (default) runs the page through Readability + Markdown conversion and a secondary-model summary so only a compact result enters context — use it for find/answer tasks; "extracted" returns the extracted main-content Markdown without the summary — use it to read an article/doc verbatim or grab an exact snippet/quote; "raw" bypasses extraction entirely and returns the ORIGINAL fetched HTML/content (token-capped) — use it to analyze a page\'s HTML/CSS/JavaScript/markup/structure, which extraction destroys. Plain-text/JSON responses pass through unchanged in summarized/extracted modes. Optionally pass intent to focus the summary. The deprecated booleans summarize=false and raw=true are aliases for mode="extracted". DATA EXTRACTION: to pull SPECIFIC VALUES out of a page (hex colors, version strings, URLs, IDs, counts), do NOT use http_get — use `download` (or sandboxed `curl`) to save the page to the working directory, then `grep` it (e.g. `grep -oiE \'#[0-9a-f]{6}\'` for hex colors) so only the matching lines enter context, not the whole page. Reserve mode="raw" for when you actually need to read the markup structure; it loads the entire (token-capped) page and is expensive for simple value extraction. For SPA / asset-heavy sites the values often live in linked assets (e.g. /_nuxt/*.css or *.js, bundled stylesheets) rather than the top-level HTML — download+grep those asset URLs.',
     parameters: {
       type: 'object',
       properties: {
@@ -392,11 +508,46 @@ const TOOL_SPECS = {
           type: 'string',
           description: 'HTTP or HTTPS URL to fetch',
         },
+        mode: {
+          type: 'string',
+          enum: ['summarized', 'extracted', 'raw'],
+          description: 'How to process the page. "summarized" (default): extract main content, convert to Markdown, then summarize with a secondary model — for find/answer tasks. "extracted": extracted Markdown of the main content, no summary — for reading a doc/article verbatim or an exact snippet. "raw": the original fetched HTML/content, token-capped, NO extraction — for analyzing the page\'s HTML/CSS/JS/structure.',
+        },
+        summarize: {
+          type: 'boolean',
+          description: 'DEPRECATED alias (prefer mode). false ≡ mode="extracted" (extracted Markdown, no summary). An explicit mode wins over this.',
+        },
+        raw: {
+          type: 'boolean',
+          description: 'DEPRECATED alias (prefer mode). true ≡ mode="extracted". NOTE: this does NOT return raw HTML — use mode="raw" for the original markup. An explicit mode wins over this.',
+        },
+        intent: {
+          type: 'string',
+          description: 'Why you are fetching this page; focuses the summary on answering it.',
+        },
       },
       required: ['url'],
     },
   },
 
+  web_search: {
+    description: 'Search the web and return a compact list of candidate results — each with a title, url, and snippet. Use this to FIND relevant pages when you do not already know the URL, instead of guessing URLs. IMPORTANT: this returns only short snippets, NOT page content. Read the snippets, pick the single most relevant result (or the few that matter), and then fetch ONLY those with http_get to read them — use http_get mode="summarized" for reading/answering and mode="raw" only for analyzing markup. Do NOT fetch every result; that wastes context. Optional count caps how many results to return (the backend clamps it).',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'The search query.',
+        },
+        count: {
+          type: 'integer',
+          description: 'Optional maximum number of results to return (clamped by the backend; defaults to the backend default).',
+        },
+      },
+      required: ['query'],
+    },
+  },
+
   ask_user: {
     description: 'Prompt the interactive user for input and return their answer; auto-answers "y" in non-TTY mode.',
     parameters: {
@@ -462,6 +613,109 @@ const TOOL_SPECS = {
     },
   },
 
+  // ──────────────────────────────────────────────────────────────────
+  // Native git tools (Task 5.1). Implemented by shelling out to `git`
+  // through the same sandbox + deny-list chokepoint as <shell>, but they
+  // parse output into structured results. Read-only: git_status, git_diff,
+  // git_log (and the LIST ops of git_branch / git_worktree). Mutating:
+  // git_add, git_commit, git_branch (create/delete), git_checkout,
+  // git_worktree (add/remove). NOTE: git operations are NOT reversible via
+  // /rewind — checkpoints (Task 4.3) snapshot file-tool mutations only.
+  // ──────────────────────────────────────────────────────────────────
+
+  git_status: {
+    description: 'Show the working-tree status as structured lists of staged, unstaged, and untracked files plus the current branch. Read-only.',
+    parameters: { type: 'object', properties: {}, required: [] },
+  },
+
+  git_diff: {
+    description: 'Show changes as a structured diff (files, hunks, +/- counts). Defaults to unstaged changes; set staged=true for the staged (index) diff. Read-only.',
+    parameters: {
+      type: 'object',
+      properties: {
+        staged: { type: 'boolean', description: 'Diff the staged (index) changes instead of the working tree', default: false },
+        path: { type: 'string', description: 'Optional path to limit the diff to' },
+      },
+      required: [],
+    },
+  },
+
+  git_log: {
+    description: 'List recent commits as structured records (hash, author, email, date, subject). Read-only.',
+    parameters: {
+      type: 'object',
+      properties: {
+        count: { type: 'integer', description: 'Maximum number of commits to return (default 20)', minimum: 1, default: 20 },
+        path: { type: 'string', description: 'Optional path to limit history to' },
+      },
+      required: [],
+    },
+  },
+
+  git_add: {
+    description: 'Stage changes for commit. Provide `paths` (one or more files) or set all=true to stage everything. Mutating — requires approval.',
+    parameters: {
+      type: 'object',
+      properties: {
+        paths: { type: 'string', description: 'File path(s) to stage; space-separated for multiple' },
+        all: { type: 'boolean', description: 'Stage all changes (git add -A)', default: false },
+      },
+      required: [],
+    },
+  },
+
+  git_commit: {
+    description: 'Create a commit with the given message and return the new commit hash and branch. The message is required and must be non-empty (the tool never invents one). Mutating — requires approval. NOTE: a commit is not reversible via /rewind.',
+    parameters: {
+      type: 'object',
+      properties: {
+        message: { type: 'string', description: 'Commit message (required, non-empty)' },
+        all: { type: 'boolean', description: 'Automatically stage modified/deleted tracked files before committing (git commit -a)', default: false },
+      },
+      required: ['message'],
+    },
+  },
+
+  git_branch: {
+    description: 'List branches (no name — read-only) or create/delete a branch (name given — mutating). Set delete=true to delete (force=true for -D). Branch creation/deletion is not reversible via /rewind.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Branch name to create or delete; omit to list branches' },
+        delete: { type: 'boolean', description: 'Delete the named branch instead of creating it', default: false },
+        force: { type: 'boolean', description: 'Force the operation (e.g. delete an unmerged branch with -D)', default: false },
+      },
+      required: [],
+    },
+  },
+
+  git_checkout: {
+    description: 'Switch to a branch or ref (set create=true to create and switch with -b). Mutating — requires approval. WARNING: checkout can overwrite or discard uncommitted changes in the working tree, and those changes are NOT recoverable via /rewind (checkpoints snapshot file-tool mutations only, not git operations).',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Branch or ref to switch to' },
+        create: { type: 'boolean', description: 'Create the branch and switch to it (git checkout -b)', default: false },
+        force: { type: 'boolean', description: 'Force checkout, discarding local changes (git checkout -f)', default: false },
+      },
+      required: ['name'],
+    },
+  },
+
+  git_worktree: {
+    description: 'Manage linked worktrees for running parallel agents in isolated working trees. op=list (read-only) lists worktrees; op=add creates one (optionally on a new `branch`); op=remove deletes one (force=true to override). add/remove are mutating and not reversible via /rewind.',
+    parameters: {
+      type: 'object',
+      properties: {
+        op: { type: 'string', description: 'Operation: list | add | remove', enum: ['list', 'add', 'remove'], default: 'list' },
+        path: { type: 'string', description: 'Worktree directory path (required for add/remove)' },
+        branch: { type: 'string', description: 'For add: create and check out this new branch in the worktree' },
+        force: { type: 'boolean', description: 'For remove: remove even with local changes', default: false },
+      },
+      required: [],
+    },
+  },
+
   // ──────────────────────────────────────────────────────────────────
   // Parser-wrapper tags. These are XML envelopes that carry other tool
   // calls; they are not invocable tools themselves. Entries exist only