@octocodeai/octocode-core 16.2.1 → 16.4.0

package/dist/resources/tools/localGetFileContent.js

@@ -1 +1 @@
-import{z as e}from"zod";import{buildObject as t,charLength as n,charOffset as a,intRange as i,lineNumber as s,MAX_CONTEXT_LINES as r,metaFields as o,validateFileContentExtractionMode as l}from"./_toolkit.js";export const localGetFileContent={name:"localGetFileContent",description:'Read a local file or region. Start with minify:"symbols" on any unknown file before reading slices.\nChoose one extraction mode — mutually exclusive: matchString (find all occurrences, returns matchRanges) | startLine/endLine (line range — both required together) | fullContent (entire file, small files only) | default (first charLength chars from line 1).\nPick minify by goal (see the minify field): "symbols" to orient, "standard" to read, "none" to quote/match whitespace.\nOutput signals: isPartial:true → check hints[] for next charOffset value (emitted as \'charOffset=N\'); matchRanges[i]={start,end} (1-based line numbers) → use matchRanges[0].start as lineHint for lspGetSemantics; warnings[] → redacted content, auto-pagination, or symbols-fallback messages.\nevidence.answerReady:true means content returned — stop calling (check isPartial separately for pagination state).\nNext: lspGetSemantics(uri=path, symbolName, lineHint=matchRanges[0].start) for semantics; localSearchCode before reading if the symbol location is unknown. Batch up to 5 files per call: queries:[{path:f1,...},{path:f2,...}].',schema:{path:"File to read (absolute or workspace-relative). For directories, use localViewStructure.",fullContent:"Returns the whole file. Reserve for small files; for large ones use matchString or startLine/endLine. Mutually exclusive with both.",matchString:'Anchor text (or regex) to locate; all occurrences come back as merged slices, with matchRanges[i]={start,end} as 1-based line numbers — pass matchRanges[0].start as lineHint to lspGetSemantics. Case-insensitive unless matchStringCaseSensitive:true; regex when matchStringIsRegex:true. Mutually exclusive with startLine/endLine and fullContent; ignored when minify:"symbols".',matchStringIsRegex:"Treats matchString as a regex — use for flexible anchors like function signatures, imports, or JSDoc tags.",matchStringCaseSensitive:"Makes matchString matching case-sensitive (case-insensitive otherwise).",startLine:"First line of the range. Required together with endLine — sending only one is an error. Mutually exclusive with fullContent and matchString.",endLine:"Last line of the range; must be >= startLine. Required together with startLine. Mutually exclusive with fullContent and matchString.",contextLines:"Extra source lines around each matchString hit. Raise to capture a full function body without a follow-up read.",charOffset:"Continuation offset for the next page; take it from hints[] ('charOffset=N') — do not compute it yourself.",charLength:"Page size in characters. Auto-paginates when unset; set it explicitly for normal source files.",minify:'"symbols": structural skeleton with line numbers in the gutter — much smaller. Use for orientation on any unknown file before reading details. matchString and charLength are ignored in symbols mode. "standard": strips comments and blank lines. "none": exact raw text — use when quoting or matching whitespace precisely.'}};export const FetchContentQuerySchema=t(localGetFileContent.schema,{...o,path:e.string(),fullContent:e.boolean().optional(),matchString:e.string().optional(),matchStringIsRegex:e.boolean().optional(),matchStringCaseSensitive:e.boolean().optional(),startLine:s(),endLine:s(),contextLines:i(0,r).default(5),charOffset:a(),charLength:n(),minify:e.enum(["none","standard","symbols"]).default("standard")}).superRefine(l);
+import{z as e}from"zod";import{buildObject as t,charLength as n,charOffset as a,defineTool as i,intRange as s,lineNumber as o,MAX_CONTEXT_LINES as r,metaFields as l,validateFileContentExtractionMode as c}from"./_toolkit.js";export const localGetFileContent=i({name:"localGetFileContent",type:"Local",shortDescription:"Read a local file or a specific region.",instructions:'Best practice: start minify:"symbols" on any unknown file to orient, then read with "standard", or "none" to quote/match whitespace exactly.\nChoose one extraction mode (mutually exclusive): matchString, startLine+endLine, fullContent, or default — see those fields.\nSignals: isPartial:true → next charOffset is in hints[] (\'charOffset=N\'); matchRanges[i]={start,end} are 1-based lines → pass matchRanges[0].start as lineHint to lspGetSemantics; warnings[] → redaction, auto-pagination, or symbols fallback. evidence.answerReady:true means content returned (check isPartial separately).\nNext: lspGetSemantics(uri=path, symbolName, lineHint=matchRanges[0].start) for semantics; localSearchCode first when the symbol\'s location is unknown. Batch files in one queries:[...] call.',schema:{path:"File to read (absolute or workspace-relative). For directories, use localViewStructure.",fullContent:"Returns the whole file. Reserve for small files; for large ones use matchString or startLine/endLine. Mutually exclusive with both.",matchString:'Anchor text (or regex) to locate; all occurrences come back as merged slices, with matchRanges[i]={start,end} as 1-based line numbers — pass matchRanges[0].start as lineHint to lspGetSemantics. Case-insensitive unless matchStringCaseSensitive:true; regex when matchStringIsRegex:true. Mutually exclusive with startLine/endLine and fullContent; ignored when minify:"symbols".',matchStringIsRegex:"Treats matchString as a regex — use for flexible anchors like function signatures, imports, or JSDoc tags.",matchStringCaseSensitive:"Makes matchString matching case-sensitive (case-insensitive otherwise).",startLine:"First line of the range. Required together with endLine — sending only one is an error. Mutually exclusive with fullContent and matchString.",endLine:"Last line of the range; must be >= startLine. Required together with startLine. Mutually exclusive with fullContent and matchString.",contextLines:"Extra source lines around each matchString hit. Raise to capture a full function body without a follow-up read.",charOffset:"Continuation offset for the next page; take it from hints[] ('charOffset=N') — do not compute it yourself.",charLength:"Page size in characters. Auto-paginates when unset; set it explicitly for normal source files.",minify:'"symbols": structural skeleton with line numbers in the gutter — much smaller. Use this first to orient on any unknown file before reading its body. matchString and charLength are ignored in symbols mode. "standard": strips comments and blank lines. "none": exact raw text — use when quoting or matching whitespace precisely.'}});export const FetchContentQuerySchema=t(localGetFileContent.schema,{...l,path:e.string(),fullContent:e.boolean().optional(),matchString:e.string().optional(),matchStringIsRegex:e.boolean().optional(),matchStringCaseSensitive:e.boolean().optional(),startLine:o(),endLine:o(),contextLines:s(0,r).default(5),charOffset:a(),charLength:n(),minify:e.enum(["none","standard","symbols"]).default("standard")}).superRefine(c);

package/dist/resources/tools/localSearchCode.d.ts

@@ -33,8 +33,8 @@ export declare const RipgrepQuerySchema: z.ZodObject<{
     multilineDotall: z.ZodOptional<z.ZodBoolean>;
     sort: z.ZodDefault<z.ZodEnum<{
         path: "path";
-        modified: "modified";
         created: "created";
+        modified: "modified";
         accessed: "accessed";
     }>>;
     sortReverse: z.ZodOptional<z.ZodBoolean>;

package/dist/resources/tools/localSearchCode.js

@@ -1 +1 @@
-import{z as e}from"zod";import{buildObject as t,contextLines as a,DEFAULT_MATCH_CONTENT_LENGTH as s,intRange as i,MAX_MATCH_CONTENT_LENGTH as n,MAX_PAGE_NUMBER as o,metaFields as l,optionalPageNumber as r,pageNumber as c,StringArray as u}from"./_toolkit.js";export const localSearchCode={name:"localSearchCode",description:'Local code/text search for file+line.\nChoose mode first: "paginated" returns snippets; "discovery" returns file paths only — cheapest orientation; "detailed" returns expanded context per match.\nFor count-only output use countLinesPerFile:true or countMatchesPerFile:true — do NOT use mode:"count" (does not exist).\nOutput signal: searchEngine flags when a reduced-capability fallback ran — perlRegex features are dropped and countMatchesPerFile becomes line-count semantics.\nPage only on hasMore; use matchPage for more matches in one file; narrow include/exclude/path before paging noisy results.\nBatch: pass up to 5 {keywords, path} objects in one call — e.g. search same keyword across multiple directories simultaneously.\nevidence.answerReady:true means at least one result exists; check pagination.hasMore separately before deciding to stop.\nPair with lspGetSemantics for semantic navigation — matches[0].line feeds directly as lineHint for definition, references, and call hierarchy.\nmode:"structural" (+ pattern OR rule): AST/shape queries regex can\'t express and that aren\'t symbol-identity questions — e.g. eval($X) call sites excluding comments/strings, or async fns lacking try/catch. pattern is a code-shaped query (foo($X), console.log($$$ARGS)); rule is a YAML relational/composite blob (not/inside/has/all/any). Returns node ranges; matches[].line still feeds lspGetSemantics lineHint. keywords is ignored in this mode.\nNext: localGetFileContent(path, matchString=keyword) to read context; lspGetSemantics(uri=files[0].path, symbolName, lineHint=matches[0].line) for semantics; localViewStructure if root unknown; localFindFiles when searching by filename or metadata.',schema:{keywords:"The search pattern (text or regex). Set fixedString:true for a literal match, or perlRegex:true for advanced regex features (lookaheads, backreferences).",path:"File or directory to search (absolute paths are safest).",mode:'"paginated": matches with snippets. "discovery": file paths only — cheapest, for orienting before you read. "detailed": snippets with surrounding context, for deep reading without a follow-up read. "structural": AST/shape search (set pattern OR rule) for queries regex can\'t express. For counts only, set countLinesPerFile or countMatchesPerFile.',pattern:'mode:"structural" only. An ast-grep code-shaped pattern. Metavariables: $X matches a single node (captured), $$$ARGS matches a list of nodes. E.g. eval($X) / console.log($$$) / oldApi.foo($X). Matches code structure, so comments and strings never false-positive. Mutually exclusive with rule.',rule:'mode:"structural" only. A YAML relational/composite ast-grep rule blob for what plain patterns can\'t express — negation and parent/child relations (not/inside/has/all/any). E.g. "rule:\\n  pattern: await $C\\n  inside:\\n    kind: for_statement\\n    stopBy: end". NOTE: relational sub-rules need stopBy: end to walk all ancestors/descendants, else they silently match nothing. Mutually exclusive with pattern.',fixedString:"Literal match (disables regex). Mutually exclusive with perlRegex.",perlRegex:"Advanced regex (lookaheads, backreferences). Mutually exclusive with fixedString.",caseInsensitive:"Case-insensitive matching. Mutually exclusive with caseSensitive.",caseSensitive:"Case-sensitive matching. Mutually exclusive with caseInsensitive.",wholeWord:"Matches whole words only.",invertMatch:"Returns non-matching lines. To list files lacking the pattern, use filesWithoutMatch instead.",include:"Globs of files to search, e.g. '*.ts', 'src/**/*.tsx'. Only files matching any glob are searched.",exclude:"Globs of files to skip, e.g. '*.min.js', 'dist/**'.",excludeDir:"Directory names to skip entirely (e.g. 'node_modules', 'dist', '.git') — faster than exclude globs for whole directories.",noIgnore:"Searches files normally hidden by .gitignore/.ignore.",hidden:"Includes hidden (dot) files.",filesOnly:"Returns matching file paths without line content. Mutually exclusive with filesWithoutMatch.",filesWithoutMatch:"Returns files that do NOT contain the pattern — useful to find files missing a required import or header. Mutually exclusive with filesOnly.",contextLines:"Lines of context around each match. Pair with mode:'detailed' for self-contained snippets.",matchContentLength:"Characters kept per match snippet. Raise for minified code or JSON, or when truncation hides matches.",maxMatchesPerFile:"Caps matches per file and sets the per-file page size; when a file has more, file.pagination.hasMore appears — page it with matchPage. No effect in filesOnly/count modes.",maxFiles:"Caps how many matched files are returned.",multiline:"Lets a match span lines. Add multilineDotall to let . cross newlines.",multilineDotall:"Lets . match newlines too. Requires multiline:true.",sort:"Order results by path, modified time, access time, or creation time.",sortReverse:"Reverses the sort (e.g. sort:'modified' + sortReverse:true = oldest first).",langType:"Language filter (ts, js, py, go, rust, …) — more precise than include globs.",countLinesPerFile:"Returns the count of matching lines per file instead of content — good for orientation (which files have the most hits). Mutually exclusive with countMatchesPerFile.",countMatchesPerFile:"Returns the total match count per file (counts multiple hits on one line). Mutually exclusive with countLinesPerFile.",matchPage:"Page within one file's matches; pair with maxMatchesPerFile to walk a noisy file.",itemsPerPage:"Files per page.",page:"Result page."}};export const RipgrepQuerySchema=t(localSearchCode.schema,{...l,keywords:e.string().optional(),path:e.string(),mode:e.enum(["paginated","discovery","detailed","structural"]).default("paginated"),pattern:e.string().optional(),rule:e.string().optional(),fixedString:e.boolean().optional(),perlRegex:e.boolean().optional(),caseInsensitive:e.boolean().optional(),caseSensitive:e.boolean().optional(),wholeWord:e.boolean().optional(),invertMatch:e.boolean().optional(),include:u,exclude:u,excludeDir:u,noIgnore:e.boolean().optional(),hidden:e.boolean().optional(),filesOnly:e.boolean().optional(),filesWithoutMatch:e.boolean().optional(),contextLines:a(),matchContentLength:i(1,n).default(s),maxMatchesPerFile:i(1,n).optional(),maxFiles:i(1,n).optional(),multiline:e.boolean().optional(),multilineDotall:e.boolean().optional(),sort:e.enum(["path","modified","accessed","created"]).default("path"),sortReverse:e.boolean().optional(),langType:e.string().optional(),countLinesPerFile:e.boolean().optional(),countMatchesPerFile:e.boolean().optional(),matchPage:r(),itemsPerPage:i(1,o).optional(),page:c()}).superRefine((e,t)=>{if("structural"===e.mode){e.pattern||e.rule||t.addIssue({code:"custom",message:'mode:"structural" requires `pattern` (a code-shaped query) or `rule` (a YAML relational rule).',path:["pattern"]}),e.pattern&&e.rule&&t.addIssue({code:"custom",message:"`pattern` and `rule` are mutually exclusive.",path:["rule"]});for(const a of["fixedString","perlRegex","wholeWord","invertMatch","multiline","multilineDotall"])e[a]&&t.addIssue({code:"custom",message:`\`${a}\` is not valid with mode:"structural".`,path:[a]})}else(e.pattern||e.rule)&&t.addIssue({code:"custom",message:'`pattern`/`rule` require mode:"structural".',path:[e.pattern?"pattern":"rule"]}),e.keywords||t.addIssue({code:"custom",message:'`keywords` is required unless mode:"structural".',path:["keywords"]});e.filesOnly&&e.filesWithoutMatch&&t.addIssue({code:"custom",message:"filesOnly and filesWithoutMatch are mutually exclusive.",path:["filesWithoutMatch"]}),e.fixedString&&e.perlRegex&&t.addIssue({code:"custom",message:"fixedString and perlRegex are mutually exclusive.",path:["perlRegex"]}),e.caseSensitive&&e.caseInsensitive&&t.addIssue({code:"custom",message:"caseSensitive and caseInsensitive are mutually exclusive.",path:["caseInsensitive"]}),e.multilineDotall&&!e.multiline&&t.addIssue({code:"custom",message:"multilineDotall requires multiline=true.",path:["multilineDotall"]}),e.countLinesPerFile&&e.countMatchesPerFile&&t.addIssue({code:"custom",message:"countLinesPerFile and countMatchesPerFile are mutually exclusive.",path:["countMatchesPerFile"]})});
+import{z as e}from"zod";import{buildObject as t,contextLines as a,DEFAULT_MATCH_CONTENT_LENGTH as s,defineTool as i,intRange as o,MAX_MATCH_COUNT as n,MAX_MATCH_CONTENT_LENGTH as l,MAX_SEARCH_ITEMS_PER_PAGE as r,metaFields as c,optionalPageNumber as u,pageNumber as d,StringArray as h}from"./_toolkit.js";export const localSearchCode=i({name:"localSearchCode",type:"Local",shortDescription:"Search local files for text, regex, or AST patterns to find file and line.",instructions:'Pick a mode: "discovery" (paths only, cheapest orientation), "paginated" (snippets), "detailed" (snippets + context). For counts use countLinesPerFile/countMatchesPerFile — there is no mode:"count".\nmode:"structural" (set pattern OR rule) handles AST/shape queries regex can\'t express — e.g. eval($X) call sites, async fns lacking try/catch. keywords is ignored there; matches[].line still works as a lineHint.\nBest practice: narrow with include/exclude/excludeDir/langType before paging noisy results; page only when hasMore, and use matchPage to walk one file\'s matches.\nSignals: searchEngine flags a reduced-capability fallback (perlRegex dropped, countMatchesPerFile becomes line counts). evidence.answerReady:true means ≥1 result — still check pagination.hasMore before stopping.\nNext: localGetFileContent(path, matchString=keyword) to read; lspGetSemantics(uri=files[0].path, symbolName, lineHint=matches[0].line) for semantics; localViewStructure if root unknown; localFindFiles to search by filename/metadata.',schema:{keywords:"The search pattern (text or regex). Set fixedString:true for a literal match, or perlRegex:true for advanced regex features (lookaheads, backreferences).",path:"File or directory to search (absolute paths are safest).",mode:'"paginated": matches with snippets. "discovery": file paths only — cheapest, for orienting before you read. "detailed": snippets with surrounding context, for deep reading without a follow-up read. "structural": AST/shape search (set pattern OR rule) for queries regex can\'t express. For counts only, set countLinesPerFile or countMatchesPerFile.',pattern:'mode:"structural" only. An ast-grep code-shaped pattern. Metavariables: $X matches a single node (captured), $$$ARGS matches a list of nodes. E.g. eval($X) / console.log($$$) / oldApi.foo($X). Matches code structure, so comments and strings never false-positive. Mutually exclusive with rule.',rule:'mode:"structural" only. A YAML relational/composite ast-grep rule blob for what plain patterns can\'t express — negation and parent/child relations (not/inside/has/all/any). E.g. "rule:\\n  pattern: await $C\\n  inside:\\n    kind: for_statement\\n    stopBy: end". NOTE: relational sub-rules need stopBy: end to walk all ancestors/descendants, else they silently match nothing. Mutually exclusive with pattern.',fixedString:"Literal match (disables regex). Mutually exclusive with perlRegex.",perlRegex:"Advanced regex (lookaheads, backreferences). Mutually exclusive with fixedString.",caseInsensitive:"Case-insensitive matching. Mutually exclusive with caseSensitive.",caseSensitive:"Case-sensitive matching. Mutually exclusive with caseInsensitive.",wholeWord:"Matches whole words only.",invertMatch:"Returns non-matching lines. To list files lacking the pattern, use filesWithoutMatch instead.",include:"Globs of files to search, e.g. '*.ts', 'src/**/*.tsx'. Only files matching any glob are searched.",exclude:"Globs of files to skip, e.g. '*.min.js', 'dist/**'.",excludeDir:"Directory names to skip entirely (e.g. 'node_modules', 'dist', '.git') — faster than exclude globs for whole directories.",noIgnore:"Searches files normally hidden by .gitignore/.ignore.",hidden:"Includes hidden (dot) files.",filesOnly:"Returns matching file paths without line content. Mutually exclusive with filesWithoutMatch.",filesWithoutMatch:"Returns files that do NOT contain the pattern — useful to find files missing a required import or header. Mutually exclusive with filesOnly.",contextLines:"Lines of context around each match. Pair with mode:'detailed' for self-contained snippets.",matchContentLength:"Characters kept per match snippet. Raise for minified code or JSON, or when truncation hides matches.",maxMatchesPerFile:"Caps matches per file and sets the per-file page size; when a file has more, file.pagination.hasMore appears — page it with matchPage. No effect in filesOnly/count modes.",maxFiles:"Caps how many matched files are returned.",multiline:"Lets a match span lines. Add multilineDotall to let . cross newlines.",multilineDotall:"Lets . match newlines too. Requires multiline:true.",sort:"Order results by path, modified time, access time, or creation time.",sortReverse:"Reverses the sort (e.g. sort:'modified' + sortReverse:true = oldest first).",langType:"Language filter (ts, js, py, go, rust, …) — more precise than include globs.",countLinesPerFile:"Returns the count of matching lines per file instead of content — good for orientation (which files have the most hits). Mutually exclusive with countMatchesPerFile.",countMatchesPerFile:"Returns the total match count per file (counts multiple hits on one line). Mutually exclusive with countLinesPerFile.",matchPage:"Page within one file's matches; pair with maxMatchesPerFile to walk a noisy file.",itemsPerPage:"Files per page.",page:"Result page."}});export const RipgrepQuerySchema=t(localSearchCode.schema,{...c,keywords:e.string().optional(),path:e.string(),mode:e.enum(["paginated","discovery","detailed","structural"]).default("paginated"),pattern:e.string().optional(),rule:e.string().optional(),fixedString:e.boolean().optional(),perlRegex:e.boolean().optional(),caseInsensitive:e.boolean().optional(),caseSensitive:e.boolean().optional(),wholeWord:e.boolean().optional(),invertMatch:e.boolean().optional(),include:h,exclude:h,excludeDir:h,noIgnore:e.boolean().optional(),hidden:e.boolean().optional(),filesOnly:e.boolean().optional(),filesWithoutMatch:e.boolean().optional(),contextLines:a(),matchContentLength:o(1,l).default(s),maxMatchesPerFile:o(1,n).optional(),maxFiles:o(1,n).optional(),multiline:e.boolean().optional(),multilineDotall:e.boolean().optional(),sort:e.enum(["path","modified","accessed","created"]).default("path"),sortReverse:e.boolean().optional(),langType:e.string().optional(),countLinesPerFile:e.boolean().optional(),countMatchesPerFile:e.boolean().optional(),matchPage:u(),itemsPerPage:o(1,r).optional(),page:d()}).superRefine((e,t)=>{if("structural"===e.mode){e.pattern||e.rule||t.addIssue({code:"custom",message:'mode:"structural" requires `pattern` (a code-shaped query) or `rule` (a YAML relational rule).',path:["pattern"]}),e.pattern&&e.rule&&t.addIssue({code:"custom",message:"`pattern` and `rule` are mutually exclusive.",path:["rule"]});for(const a of["fixedString","perlRegex","wholeWord","invertMatch","multiline","multilineDotall"])e[a]&&t.addIssue({code:"custom",message:`\`${a}\` is not valid with mode:"structural".`,path:[a]})}else(e.pattern||e.rule)&&t.addIssue({code:"custom",message:'`pattern`/`rule` require mode:"structural".',path:[e.pattern?"pattern":"rule"]}),e.keywords||t.addIssue({code:"custom",message:'`keywords` is required unless mode:"structural".',path:["keywords"]});e.filesOnly&&e.filesWithoutMatch&&t.addIssue({code:"custom",message:"filesOnly and filesWithoutMatch are mutually exclusive.",path:["filesWithoutMatch"]}),e.fixedString&&e.perlRegex&&t.addIssue({code:"custom",message:"fixedString and perlRegex are mutually exclusive.",path:["perlRegex"]}),e.caseSensitive&&e.caseInsensitive&&t.addIssue({code:"custom",message:"caseSensitive and caseInsensitive are mutually exclusive.",path:["caseInsensitive"]}),e.multilineDotall&&!e.multiline&&t.addIssue({code:"custom",message:"multilineDotall requires multiline=true.",path:["multilineDotall"]}),e.countLinesPerFile&&e.countMatchesPerFile&&t.addIssue({code:"custom",message:"countLinesPerFile and countMatchesPerFile are mutually exclusive.",path:["countMatchesPerFile"]})});

package/dist/resources/tools/localViewStructure.js

@@ -1 +1 @@
-import{z as e}from"zod";import{buildObject as t,intRange as i,MAX_LOCAL_DEPTH as o,MAX_LOCAL_ITEMS_PER_PAGE as s,MAX_LOCAL_LIMIT as n,metaFields as a,pageNumber as r,StringArray as l}from"./_toolkit.js";export const localViewStructure={name:"localViewStructure",description:'Browse a local directory tree. Returns files[], folders[], and links[] (symlinks) at each level. When details:true or showFileLastModified:true, switches to entries[] objects with size, permissions, and timestamps.\nUse this to map a directory before searching. Use localFindFiles when you need metadata (size, modified date) or filename patterns. Use localSearchCode(mode:"discovery") to find which files contain a pattern.\nMutual exclusion: filesOnly and directoriesOnly cannot both be true.\nBulk: queries:[{path:d1},{path:d2}] to browse multiple directories in one call (max 5).\nPaginate with page=N when pagination.hasMore is true.\nNext: localGetFileContent(path), localSearchCode, lspGetSemantics after localSearchCode gives uri/symbolName/lineHint.',schema:{path:"Directory to browse (absolute or workspace-relative). Defaults to the workspace root.",details:"Returns per-entry objects with size, permissions, and dates (structured entries[] output).",hidden:"Includes hidden (dot) files and directories, e.g. .env, .git, .github.",sortBy:"Ordering. 'name': A–Z. 'size': by bytes. 'time': by last-modified (implicitly enables showFileLastModified). 'extension': grouped by file type.",reverse:"Reverses the sort (e.g. sortBy:'time' + reverse:true = oldest first).",pattern:"Name filter — a glob (e.g. '*.ts') or plain substring; only matching entries are returned. For regex, use localFindFiles.",directoriesOnly:"Returns directories only. Mutually exclusive with filesOnly.",filesOnly:"Returns files only. Mutually exclusive with directoriesOnly.",recursive:"Descends into subdirectories (top level only when off). When on without maxDepth, depth is capped automatically; set maxDepth to control cost.",extensions:"Extension whitelist, without dots, e.g. ['ts', 'tsx', 'js']. Only matching files are returned; directories always appear.",maxDepth:"Recursion depth when recursive is on (0 = immediate children). Start shallow on large monorepos, then drill in.",limit:"Caps how many entries are discovered before pagination — guards against huge scans. Distinct from page size.",showFileLastModified:"Adds last-modified timestamps per file. Independent of details. Use to spot recently changed files without switching to localFindFiles.",page:"Result page.",itemsPerPage:"Entries per page."}};export const ViewStructureQuerySchema=t(localViewStructure.schema,{...a,path:e.string(),details:e.boolean().optional(),hidden:e.boolean().optional(),sortBy:e.enum(["name","size","time","extension"]).default("name"),reverse:e.boolean().optional(),pattern:e.string().optional(),directoriesOnly:e.boolean().optional(),filesOnly:e.boolean().optional(),recursive:e.boolean().optional(),extensions:l,maxDepth:i(0,o).optional(),limit:i(1,n).optional(),showFileLastModified:e.boolean().optional(),page:r(),itemsPerPage:i(1,s).optional()}).superRefine((e,t)=>{e.filesOnly&&e.directoriesOnly&&t.addIssue({code:"custom",message:"filesOnly and directoriesOnly are mutually exclusive.",path:["directoriesOnly"]})});
+import{z as e}from"zod";import{buildObject as t,defineTool as i,intRange as o,MAX_LOCAL_DEPTH as s,MAX_LOCAL_ITEMS_PER_PAGE as r,MAX_LOCAL_LIMIT as a,metaFields as n,pageNumber as l,StringArray as d}from"./_toolkit.js";export const localViewStructure=i({name:"localViewStructure",type:"Local",shortDescription:"Browse a local directory tree.",instructions:'Returns files[], folders[], links[]; details:true or showFileLastModified:true switches to entries[] with size, permissions, timestamps.\nBest practice: map a directory here before searching. Use localFindFiles instead when you need metadata or filename patterns, and localSearchCode(mode:"discovery") to find which files contain a pattern.\nPaginate with page=N while pagination.hasMore; batch multiple paths in one queries:[...] call.\nNext: localGetFileContent(path) to read; localSearchCode to search; lspGetSemantics once localSearchCode gives uri/symbolName/lineHint.',schema:{path:"Directory to browse (absolute or workspace-relative). Defaults to the workspace root.",details:"Returns per-entry objects with size, permissions, and dates (structured entries[] output).",hidden:"Includes hidden (dot) files and directories, e.g. .env, .git, .github.",sortBy:"Ordering. 'name': A–Z. 'size': by bytes. 'time': by last-modified (implicitly enables showFileLastModified). 'extension': grouped by file type.",reverse:"Reverses the sort (e.g. sortBy:'time' + reverse:true = oldest first).",pattern:"Name filter — a glob (e.g. '*.ts') or plain substring; only matching entries are returned. For regex, use localFindFiles.",directoriesOnly:"Returns directories only. Mutually exclusive with filesOnly.",filesOnly:"Returns files only. Mutually exclusive with directoriesOnly.",recursive:"Descends into subdirectories (top level only when off). When on without maxDepth, depth is capped automatically; set maxDepth to control cost.",extensions:"Extension whitelist, without dots, e.g. ['ts', 'tsx', 'js']. Only matching files are returned; directories always appear.",maxDepth:"Recursion depth when recursive is on (0 = immediate children). Start shallow on large monorepos, then drill in.",limit:"Caps how many entries are discovered before pagination — guards against huge scans. Distinct from page size.",showFileLastModified:"Adds last-modified timestamps per file. Independent of details. Use to spot recently changed files without switching to localFindFiles.",page:"Result page.",itemsPerPage:"Entries per page."}});export const ViewStructureQuerySchema=t(localViewStructure.schema,{...n,path:e.string(),details:e.boolean().optional(),hidden:e.boolean().optional(),sortBy:e.enum(["name","size","time","extension"]).default("name"),reverse:e.boolean().optional(),pattern:e.string().optional(),directoriesOnly:e.boolean().optional(),filesOnly:e.boolean().optional(),recursive:e.boolean().optional(),extensions:d,maxDepth:o(0,s).optional(),limit:o(1,a).optional(),showFileLastModified:e.boolean().optional(),page:l(),itemsPerPage:o(1,r).optional()}).superRefine((e,t)=>{e.filesOnly&&e.directoriesOnly&&t.addIssue({code:"custom",message:"filesOnly and directoriesOnly are mutually exclusive.",path:["directoriesOnly"]})});

package/dist/resources/tools/lspGetSemantics.d.ts

@@ -48,8 +48,8 @@ export declare const LSPCallHierarchyQuerySchema: z.ZodObject<{
 export declare const LspGetSemanticsQuerySchema: z.ZodObject<{
     uri: z.ZodString;
     type: z.ZodDefault<z.ZodEnum<{
-        references: "references";
         definition: "definition";
+        references: "references";
         callers: "callers";
         callees: "callees";
         callHierarchy: "callHierarchy";

package/dist/resources/tools/lspGetSemantics.js

@@ -1 +1 @@
-import{z as e}from"zod";import{buildObject as t,contextLines as n,intRange as o,MAX_LINE_NUMBER as i,MAX_LOCAL_DEPTH as l,MAX_ORDER_HINT as a,MAX_PR_ITEMS_PER_PAGE as s,metaFields as r,pageNumber as c}from"./_toolkit.js";export const lspGetSemantics={name:"lspGetSemantics",description:"Typed LSP queries for semantic navigation (default type: definition).\nPrerequisites: all types except documentSymbols require symbolName + lineHint. lineHint must come from a real localSearchCode match (matches[0].line) — never guess. A wrong lineHint causes silent empty results. If lineHint is unknown: run documentSymbols (uri only) or localSearchCode first.\nType routing: documentSymbols=file outline (uri only); hover=signature+JSDoc; definition=jump to decl; typeDefinition=generic types; implementation=abstract member impl (member name, not class); references=same-package usages (bounded by the language server's open files, NOT cross-package — zero results does NOT mean unused, try callers); callers=cross-package incoming calls (TS/JS/Go/Rust only — Python/C++ use references instead); callees=outgoing calls; callHierarchy=both.\nToken efficiency: format:\"compact\" on callers/callees/callHierarchy → significantly fewer tokens. groupByFile:true on references → per-file summary with lines[] (each is a valid lineHint for follow-up calls). contextLines=3–10 on callers/callees embeds source context, reducing follow-up localGetFileContent calls.\nLanguage tiers — Tier 1 all types: TS/JS/Go/Rust. Tier 2 no callHierarchy: Python/C++. Tier 3 documentSymbols+hover+definition only: Shell/HTML/CSS/YAML/TOML.\nOutput signal: resolvedSymbol.foundAtLine confirms which line LSP resolved — if far from lineHint, re-run localSearchCode to get an accurate anchor. payload.kind='empty' means LSP returned no results (symbolNotFound → re-anchor with localSearchCode; serverUnavailable → fall back to localSearchCode). In callers/callees results, each ranges[].line is the lineHint for the next lspGetSemantics call on that symbol.\nevidence.answerReady:true — stop calling.\nNext: localGetFileContent(startLine/endLine) to read the definition; lspGetSemantics(callers) for impact analysis. Batch: up to 5 queries per call — combine definition+hover or definition+callers in one request.",schema:{uri:"Target source file as an absolute path or file:/// URI.",type:"Which query to run — see the type-routing list in the description.",symbolName:"Exact identifier sitting at lineHint — bare name only, no parentheses or type annotations (e.g. 'fetchPRDetail', not 'fetchPRDetail()'). Case-sensitive, must match the token exactly. Required for every type except documentSymbols.",lineHint:"Line where symbolName appears. Must come from a real localSearchCode match (matches[0].line) — never guess; a wrong value silently returns nothing. Required for every type except documentSymbols.",orderHint:"Disambiguates when symbolName occurs multiple times on lineHint (e.g. overloads, chained calls) — increment if you get the wrong symbol.",depth:"Recursion depth for callHierarchy/callers/callees — immediate calls only unless raised. Raise for full chains; pair high depth on hot symbols with format:'compact' to limit size.",includeDeclaration:"references: whether to include the symbol's own declaration. Set false to get only usages, not the definition site.",groupByFile:"references: returns a per-file summary (path + count + all line numbers in lines[]) instead of per-location rows — ideal for blast radius; each line is a valid lineHint for follow-ups.",page:"Result page for documentSymbols and call-flow results.",itemsPerPage:"Items per page (symbol/location lists get a larger page than call-flow results).",contextLines:"Source lines around each call site in callers/callees/callHierarchy (locations only unless set). Raise to embed calling context and skip a follow-up localGetFileContent.",format:'"structured": typed objects with full location metadata. "compact": line-oriented strings, far fewer tokens. Prefer "compact" for navigation; use "structured" only when parsing locations programmatically.',workspaceRoot:"Overrides the LSP workspace root (absolute path). Omit to auto-resolve from uri; needed only when the server spans multiple roots."}};const m={...r,uri:e.string(),symbolName:e.string(),lineHint:o(1,i),orderHint:o(0,a).default(0)};export const LSPGotoDefinitionQuerySchema=t(lspGetSemantics.schema,{...m,contextLines:n()});export const LSPFindReferencesQuerySchema=t(lspGetSemantics.schema,{...m,includeDeclaration:e.boolean().optional(),contextLines:n(),itemsPerPage:o(1,s).optional(),page:c(),groupByFile:e.boolean().optional()});export const LSPCallHierarchyQuerySchema=t(lspGetSemantics.schema,{...m,direction:e.enum(["incoming","outgoing"]),depth:o(0,l).optional(),contextLines:n(),itemsPerPage:o(1,s).optional(),page:c()});export const LspGetSemanticsQuerySchema=t(lspGetSemantics.schema,{...r,uri:e.string(),type:e.enum(["definition","references","callers","callees","callHierarchy","hover","documentSymbols","typeDefinition","implementation"]).default("definition"),symbolName:e.string().min(1).optional(),lineHint:o(1,i).optional(),orderHint:o(0,a).default(0),depth:o(0,l).optional(),includeDeclaration:e.boolean().default(!0),groupByFile:e.boolean().optional(),page:c(),itemsPerPage:o(1,s).optional(),contextLines:n(),format:e.enum(["structured","compact"]).default("structured"),workspaceRoot:e.string().optional()}).superRefine((e,t)=>{"documentSymbols"!==e.type&&(e.symbolName||t.addIssue({code:"custom",path:["symbolName"],message:"symbolName is required unless type is documentSymbols"}),Number.isInteger(e.lineHint)||t.addIssue({code:"custom",path:["lineHint"],message:"lineHint is required unless type is documentSymbols"}))});
+import{z as e}from"zod";import{buildObject as t,contextLines as o,defineTool as n,intRange as i,MAX_LINE_NUMBER as a,MAX_LSP_DEPTH as s,MAX_LSP_ITEMS_PER_PAGE as l,MAX_ORDER_HINT as r,metaFields as c,pageNumber as m}from"./_toolkit.js";export const lspGetSemantics=n({name:"lspGetSemantics",type:"Local",shortDescription:"Run LSP semantic queries — definitions, references, call hierarchy, symbols.",instructions:'Default type is definition. Every type except documentSymbols needs symbolName + lineHint, and lineHint MUST come from a real localSearchCode match (matches[0].line) — a guessed line silently returns nothing. No lineHint yet? Run documentSymbols (uri only) or localSearchCode first.\nType routing: documentSymbols=file outline; hover=signature+docs; definition=declaration; typeDefinition=generic type; implementation=abstract member impl; references=same-package usages (NOT cross-package — zero ≠ unused; try callers); callers=cross-package incoming calls; callees=outgoing; callHierarchy=both.\nCapability varies by language server: TS/JS/Go/Rust usually support all; Python/C++ often lack callHierarchy/callers/callees (use references). An unsupported type isn\'t rejected — payload.kind=\'empty\' (serverUnavailable) means "not supported here", not "no results"; re-route, don\'t conclude absence.\nBest practice: format:"compact" on call queries and groupByFile:true on references cut tokens sharply; contextLines embeds source so you skip a follow-up read.\nSignals: resolvedSymbol.foundAtLine confirms the resolved line (far from lineHint → re-anchor via localSearchCode); each ranges[].line is the next lineHint.\nNext: localGetFileContent(startLine/endLine) to read a definition; lspGetSemantics(callers) for impact. Batch related queries (definition+hover, definition+callers) in one call.',schema:{uri:"Target source file as an absolute path or file:/// URI.",type:"Which query to run — see the type-routing list in the instructions.",symbolName:"Exact identifier sitting at lineHint — bare name only, no parentheses or type annotations (e.g. 'fetchPRDetail', not 'fetchPRDetail()'). Case-sensitive, must match the token exactly. Required for every type except documentSymbols.",lineHint:"Line where symbolName appears. Must come from a real localSearchCode match (matches[0].line) — never guess; a wrong value silently returns nothing. Required for every type except documentSymbols.",orderHint:"Disambiguates when symbolName occurs multiple times on lineHint (e.g. overloads, chained calls) — increment if you get the wrong symbol.",depth:"Recursion depth for callHierarchy/callers/callees — immediate calls only unless raised. Raise for full chains; pair high depth on hot symbols with format:'compact' to limit size.",includeDeclaration:"references: whether to include the symbol's own declaration. Set false to get only usages, not the definition site.",groupByFile:"references: returns a per-file summary (path + count + all line numbers in lines[]) instead of per-location rows — ideal for blast radius; each line is a valid lineHint for follow-ups.",page:"Result page for documentSymbols and call-flow results.",itemsPerPage:"Items per page (symbol/location lists get a larger page than call-flow results).",contextLines:"Source lines around each call site in callers/callees/callHierarchy (locations only unless set). Raise to embed calling context and skip a follow-up localGetFileContent.",format:'"structured": typed objects with full location metadata. "compact": line-oriented strings, far fewer tokens. Prefer "compact" for navigation; use "structured" only when parsing locations programmatically.',workspaceRoot:"Overrides the LSP workspace root (absolute path). Omit to auto-resolve from uri; needed only when the server spans multiple roots."}});const u={...c,uri:e.string(),symbolName:e.string(),lineHint:i(1,a),orderHint:i(0,r).default(0)};export const LSPGotoDefinitionQuerySchema=t(lspGetSemantics.schema,{...u,contextLines:o()});export const LSPFindReferencesQuerySchema=t(lspGetSemantics.schema,{...u,includeDeclaration:e.boolean().optional(),contextLines:o(),itemsPerPage:i(1,l).optional(),page:m(),groupByFile:e.boolean().optional()});export const LSPCallHierarchyQuerySchema=t(lspGetSemantics.schema,{...u,direction:e.enum(["incoming","outgoing"]).describe('Call direction: "incoming" (who calls this symbol) or "outgoing" (what this symbol calls).'),depth:i(0,s).optional(),contextLines:o(),itemsPerPage:i(1,l).optional(),page:m()});export const LspGetSemanticsQuerySchema=t(lspGetSemantics.schema,{...c,uri:e.string(),type:e.enum(["definition","references","callers","callees","callHierarchy","hover","documentSymbols","typeDefinition","implementation"]).default("definition"),symbolName:e.string().min(1).optional(),lineHint:i(1,a).optional(),orderHint:i(0,r).default(0),depth:i(0,s).optional(),includeDeclaration:e.boolean().default(!0),groupByFile:e.boolean().optional(),page:m(),itemsPerPage:i(1,l).optional(),contextLines:o(),format:e.enum(["structured","compact"]).default("structured"),workspaceRoot:e.string().optional()}).superRefine((e,t)=>{"documentSymbols"!==e.type&&(e.symbolName||t.addIssue({code:"custom",path:["symbolName"],message:"symbolName is required unless type is documentSymbols"}),Number.isInteger(e.lineHint)||t.addIssue({code:"custom",path:["lineHint"],message:"lineHint is required unless type is documentSymbols"}))});

package/dist/resources/tools/npmSearch.js

@@ -1 +1 @@
-import{z as e}from"zod";import{buildObject as r,metaFields as t,pageNumber as a}from"./_toolkit.js";export const npmSearch={name:"npmSearch",description:'npm package lookup and keyword search. Returns package metadata and source repository handoff.\nExact package name (e.g. "react", "@octokit/rest") returns one rich result with version, description, keywords, and repository owner/repo for GitHub handoff.\nKeyword query (e.g. "http client typescript") returns lean results — paginate with page; pagination.hasMore and totalFound available in output.\nWhen owner+repo is present in the result, pass directly to ghViewRepoStructure or ghSearchCode. If a repositoryDirectory path follows owner/repo in the result, pass it as path= to ghViewRepoStructure to scope the tree to the package subdirectory.\nSkip if owner/repo is already known — go directly to ghViewRepoStructure.\nBatch up to 5 packages in one call: queries:[{packageName:"react"},{packageName:"lodash"}].\nNext: ghViewRepoStructure or ghSearchCode when owner/repo exists; ghSearchRepos when owner/repo is absent or non-GitHub.',schema:{packageName:"An exact npm package name or a keyword query. An exact name (e.g. 'react', '@octokit/rest') returns one rich result, or empty if it doesn't exist (check spelling before assuming it's private). A keyword query returns a lean list. Scoped packages need the full scope: '@octokit/rest', not 'rest'.",page:"Page for keyword results; exact-name lookups always return page 1. Paginate while pagination.hasMore."}};export const NpmPackageQuerySchema=r(npmSearch.schema,{...t,packageName:e.string(),page:a()});
+import{z as e}from"zod";import{buildObject as r,defineTool as t,metaFields as o,pageNumber as a}from"./_toolkit.js";export const npmSearch=t({name:"npmSearch",type:"NPM",shortDescription:"Look up npm packages and find their source repositories.",instructions:"An exact package name returns one rich result (version, keywords, repository owner/repo); a keyword query returns a lean list — paginate with page while pagination.hasMore.\nBest practice: skip this tool when owner/repo is already known — go straight to ghViewRepoStructure. Use it mainly to resolve a package to its source repo.\nWhen the result has owner/repo, hand off to ghViewRepoStructure or ghSearchCode; if a repositoryDirectory is present, pass it as path= to scope the tree to the package subdirectory.\nBatch multiple packages in one queries:[...] call.\nNext: ghViewRepoStructure/ghSearchCode when owner/repo exists; ghSearchRepos when it's absent or non-GitHub.",schema:{packageName:"An exact npm package name or a keyword query. An exact name (e.g. 'react', '@octokit/rest') returns one rich result, or empty if it doesn't exist (check spelling before assuming it's private). A keyword query returns a lean list. Scoped packages need the full scope: '@octokit/rest', not 'rest'.",page:"Page for keyword results; exact-name lookups always return page 1. Paginate while pagination.hasMore."}});export const NpmPackageQuerySchema=r(npmSearch.schema,{...o,packageName:e.string(),page:a()});

package/dist/schemas/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-import { RipgrepQuerySchema } from "./index.js";
+import { RipgrepQuerySchema } from "../schemas.js";
 type RuntimeRipgrepQuery = z.infer<typeof RipgrepQuerySchema>;
 export interface RipgrepValidationResult {
     isValid: boolean;