@octocodeai/octocode-tools-core 16.6.2 → 17.0.1

package/dist/tools/local_ripgrep/rankingProfile.d.ts

@@ -15,99 +15,20 @@
  * Not rigid: profiles are declarative tables, all weights live in one policy
  * object, new languages register by adding a profile. AST/LSP signals (Phase
  * 2/3) layer on top without changing this contract.
+ *
+ * This file is a thin barrel: the implementation lives in `rankingProfile/`,
+ * split by concern —
+ *  - `rankingProfile/rankingProfiles.ts`: profile data/config (language
+ *    tables, path-role regexes, `selectProfile`/`classifyPathRole`).
+ *  - `rankingProfile/rankingScoring.ts`: the scoring engine (`bestLineScore`,
+ *    `pathAffinityScore`, `candidateTermRarityScore`, `scoreFileWithRarity`).
+ *  - `rankingProfile/rankingResults.ts`: `rankFiles`/`RankResult` plus the
+ *    lexical helpers (`lexicalCategoryOf`, `isIndexInsideString`, etc.).
+ * Re-exported here so no other module needs to change its import path.
  */
-import type { LocalSearchCodeFile } from '@octocodeai/octocode-core/types';
-export type RankingProfileId = 'typescript' | 'javascript' | 'rust' | 'python' | 'go' | 'java' | 'scala' | 'markdown' | 'json' | 'yaml' | 'generic';
-/** TS-level result orderings. `relevance` is the language-aware scorer. */
-export type RankSort = 'relevance' | 'matchCount' | 'path' | 'created' | 'modified' | 'accessed';
-export declare const RANKING_PROFILE_IDS: readonly ["typescript", "javascript", "rust", "python", "go", "java", "scala", "markdown", "json", "yaml", "generic"];
-type PathRole = 'source' | 'test' | 'docs' | 'config' | 'generated' | 'fixture' | 'unknown';
-/**
- * All ranking weights in one place. Tuning happens here and in the golden
- * fixtures, never scattered across the scorer. Values are deliberately
- * integer-ish and additive so a score can be read back from its reasons.
- */
-export declare const RANK_WEIGHTS: {
-    readonly exactWholeWord: 6;
-    readonly exactCaseInsensitive: 3;
-    readonly substring: 1;
-    readonly declarationLine: 8;
-    readonly exportLine: 4;
-    readonly importLine: 3;
-    readonly configKeyLine: 4;
-    readonly headingLine: 4;
-    readonly commentOrStringPenalty: -2;
-    readonly pathUnderQuery: 4;
-    readonly pathSegmentToken: 3;
-    readonly extMatchesLangType: 2;
-    readonly sourceDir: 1.5;
-    readonly lowSignalPathPenalty: -5;
-    readonly rareQueryTokenScale: 2;
-    readonly rareQueryTokenCap: 3;
-    readonly matchCountScale: 1.5;
-    readonly matchCountCap: 6;
-};
-/**
- * Bound on how many files get full scoring before pagination. The engine text
- * path returns the entire result set unbounded (no global file/match cap), so
- * for broad terms in a large monorepo we must not score O(total files). When
- * the cap bites we deterministically prefilter (matchCount desc, path asc)
- * before scoring, and the builder surfaces a `truncated`-style note.
- */
-export declare const RANK_CANDIDATE_CAP = 2000;
-interface RankingProfile {
-    id: RankingProfileId;
-    extensions: readonly string[];
-    /** Lines that declare/define a symbol named like the query — highest signal. */
-    declaration: readonly RegExp[];
-    /** Exported/public surface. */
-    export: readonly RegExp[];
-    /** Import/use lines. */
-    import: readonly RegExp[];
-}
-/** Deterministic profile selection from query langType then file extension. */
-export declare function selectProfile(path: string, langType?: string, override?: RankingProfileId | 'auto'): RankingProfile;
-export declare function classifyPathRole(path: string): PathRole;
-export interface RankContext {
-    /** Validated, sanitized search base path (query.path). */
-    queryPath?: string;
-    /** The literal keyword/pattern, used for whole-word / token / path checks. */
-    keyword?: string;
-    langType?: string;
-    caseSensitive?: boolean;
-    wholeWord?: boolean;
-    /** Profile override from query.rankingProfile. */
-    profileOverride?: RankingProfileId | 'auto';
-    /** True when the user explicitly searched into a low-signal/test/docs area. */
-    explicitLowSignal?: boolean;
-}
-export interface FileScore {
-    score: number;
-    profile: RankingProfileId;
-    pathRole: PathRole;
-    reasons: string[];
-}
-/** Score one file. Pure and deterministic. */
-export declare function scoreFile(file: LocalSearchCodeFile, ctx: RankContext): FileScore;
-export interface RankResult {
-    files: LocalSearchCodeFile[];
-    /** Per-path debug info, only populated when debug is requested. */
-    debug?: Map<string, FileScore>;
-    /** Number of files dropped by the candidate cap before scoring (0 if none). */
-    cappedCandidates: number;
-}
-/**
- * Rank files by the requested sort mode. `relevance` is the language-aware
- * scorer (default); `matchCount` and `path` are deterministic escape hatches;
- * filesystem sorts (created/modified/accessed) preserve the engine's order.
- */
-export declare function rankFiles(files: LocalSearchCodeFile[], sort: RankSort, ctx: RankContext, opts?: {
-    debug?: boolean;
-    candidateCap?: number;
-}): RankResult;
-/** True when the query path explicitly targets a low-signal area, so the
- * scorer should not penalize generated/test/docs/fixture roles. Uses anchored
- * path-segment matching (not substring) so `latest/`, `contest/`, `manifest/`
- * do NOT count as low-signal. */
-export declare function isLowSignalQueryPath(path: string | undefined): boolean;
-export {};
+export type { RankingProfileId, RankSort, PathRole, RankingProfile, } from './rankingProfile/rankingProfiles.js';
+export { RANKING_PROFILE_IDS, RANK_WEIGHTS, RANK_CANDIDATE_CAP, COMMENT_LINE, HEADING_LINE, LOW_SIGNAL_PATH, EXT_RE, fileExtension, selectProfile, classifyPathRole, isLowSignalQueryPath, } from './rankingProfile/rankingProfiles.js';
+export type { RankContext, FileScore, } from './rankingProfile/rankingScoring.js';
+export { buildCandidateTermRarity, scoreFileWithRarity, scoreFile, } from './rankingProfile/rankingScoring.js';
+export type { RankResult } from './rankingProfile/rankingResults.js';
+export { rankFiles, matchesAny, escapeRegex, isPlainIdentifierKeyword, matchedLineOf, lexicalCategoryOf, isIndexInsideString, } from './rankingProfile/rankingResults.js';

package/dist/tools/local_ripgrep/ripgrepResultBuilder/buildResult.d.ts

@@ -0,0 +1,10 @@
+import type { LocalSearchCodeFile } from '@octocodeai/octocode-core/types';
+import type { LocalSearchCodeToolResult } from '@octocodeai/octocode-core/extra-types';
+import type { SearchStats } from '../../../utils/core/types.js';
+import type { RipgrepQuery } from '../scheme.js';
+export type LocalSearchEngine = 'rg' | 'structural';
+export declare function buildSearchResult(parsedFiles: LocalSearchCodeFile[], configuredQuery: RipgrepQuery, searchEngine: LocalSearchEngine, warnings: string[], stats?: SearchStats): Promise<LocalSearchCodeToolResult>;
+export declare function finalizeRipgrepResult(result: LocalSearchCodeToolResult, _query: RipgrepQuery, _totals: {
+    totalMatches: number;
+    totalFiles: number;
+}): LocalSearchCodeToolResult;

package/dist/tools/local_ripgrep/ripgrepResultBuilder/searchNext.d.ts

@@ -0,0 +1,46 @@
+import type { LocalSearchCodeFile } from '@octocodeai/octocode-core/types';
+import type { RipgrepQuery } from '../scheme.js';
+import type { LocalSearchEngine } from './buildResult.js';
+type NextToolName = 'localGetFileContent' | 'lspGetSemantics' | 'localSearchCode';
+type NextConfidence = 'exact' | 'heuristic';
+type SearchNextCall = {
+    tool: NextToolName;
+    query: Record<string, unknown>;
+    why: string;
+    confidence?: NextConfidence;
+};
+export type SearchNextMap = {
+    fetch?: SearchNextCall;
+    lspDefinition?: SearchNextCall;
+    lspReferences?: SearchNextCall;
+    nextPage?: SearchNextCall;
+    nextMatchPage?: SearchNextCall;
+};
+type FlowMatch = {
+    line?: number;
+    endLine?: number;
+    value?: string;
+    metavars?: Record<string, string[]>;
+    metavarRanges?: Record<string, Array<{
+        line: number;
+    }>>;
+};
+export declare function buildSearchNextMap(files: LocalSearchCodeFile[], query: RipgrepQuery, searchEngine: LocalSearchEngine, options: {
+    isFileListMode: boolean;
+    currentPage: number;
+    totalFilePages: number;
+    matchPage: number;
+    matchesPerPage: number;
+    hasFileWithMoreMatches: boolean;
+}): SearchNextMap;
+export type InferredLspSymbol = {
+    symbol: string;
+    /**
+     * Precise capture line from `metavarRanges` (structural search only).
+     * Undefined when the search engine doesn't carry per-capture ranges — the
+     * caller falls back to the match's own start line.
+     */
+    line?: number;
+};
+export declare function inferLspSymbolName(match: FlowMatch | undefined, query: RipgrepQuery, searchEngine: LocalSearchEngine): InferredLspSymbol | undefined;
+export {};

package/dist/tools/local_ripgrep/ripgrepResultBuilder.d.ts

@@ -1,18 +1,2 @@
-import type { LocalSearchCodeFile } from '@octocodeai/octocode-core/types';
-import type { LocalSearchCodeToolResult } from '@octocodeai/octocode-core/extra-types';
-import type { SearchStats } from '../../utils/core/types.js';
-import type { RipgrepQuery } from './scheme.js';
-export type LocalSearchEngine = 'rg' | 'structural';
-type FlowMatch = {
-    line?: number;
-    endLine?: number;
-    value?: string;
-    metavars?: Record<string, string[]>;
-};
-export declare function buildSearchResult(parsedFiles: LocalSearchCodeFile[], configuredQuery: RipgrepQuery, searchEngine: LocalSearchEngine, warnings: string[], stats?: SearchStats): Promise<LocalSearchCodeToolResult>;
-export declare function finalizeRipgrepResult(result: LocalSearchCodeToolResult, _query: RipgrepQuery, _totals: {
-    totalMatches: number;
-    totalFiles: number;
-}): LocalSearchCodeToolResult;
-export declare function inferLspSymbolName(match: FlowMatch | undefined, query: RipgrepQuery, searchEngine: LocalSearchEngine): string | undefined;
-export {};
+export * from './ripgrepResultBuilder/buildResult.js';
+export * from './ripgrepResultBuilder/searchNext.js';

package/dist/tools/local_ripgrep/scheme.d.ts

@@ -78,3 +78,173 @@ export declare const LocalRipgrepBulkQuerySchema: z.ZodObject<{
     responseCharLength: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
     queries: z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
 }, z.core.$strip>;
+export declare const LocalSearchCodeOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            empty: "empty";
+            error: "error";
+        }>>;
+        data: z.ZodObject<{
+            files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                matches: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    line: z.ZodNumber;
+                    endLine: z.ZodOptional<z.ZodNumber>;
+                    value: z.ZodOptional<z.ZodString>;
+                    column: z.ZodOptional<z.ZodNumber>;
+                    endColumn: z.ZodOptional<z.ZodNumber>;
+                    count: z.ZodOptional<z.ZodNumber>;
+                    kind: z.ZodOptional<z.ZodString>;
+                    scoreHint: z.ZodOptional<z.ZodNumber>;
+                    metavars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+                    metavarRanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+                        text: z.ZodString;
+                        line: z.ZodNumber;
+                        column: z.ZodNumber;
+                        endLine: z.ZodNumber;
+                        endColumn: z.ZodNumber;
+                    }, z.core.$strip>>>>;
+                }, z.core.$strip>>>;
+                totalOccurrences: z.ZodOptional<z.ZodNumber>;
+                totalMatchedLines: z.ZodOptional<z.ZodNumber>;
+                totalMatchRows: z.ZodOptional<z.ZodNumber>;
+                returnedMatchRows: z.ZodOptional<z.ZodNumber>;
+                ranking: z.ZodOptional<z.ZodObject<{
+                    score: z.ZodNumber;
+                    profile: z.ZodOptional<z.ZodString>;
+                    pathRole: z.ZodOptional<z.ZodString>;
+                    reasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strip>>;
+                matchPagination: z.ZodOptional<z.ZodObject<{
+                    currentPage: z.ZodNumber;
+                    totalPages: z.ZodNumber;
+                    hasMore: z.ZodBoolean;
+                    nextPage: z.ZodOptional<z.ZodNumber>;
+                    pageSize: z.ZodOptional<z.ZodNumber>;
+                    totalItems: z.ZodOptional<z.ZodNumber>;
+                    perPage: z.ZodOptional<z.ZodNumber>;
+                    totalFound: z.ZodOptional<z.ZodNumber>;
+                    returned: z.ZodOptional<z.ZodNumber>;
+                    reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                    reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                    totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                        exact: "exact";
+                        reported: "reported";
+                        lowerBound: "lowerBound";
+                    }>>;
+                    totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                    totalResults: z.ZodOptional<z.ZodNumber>;
+                    itemsPerPage: z.ZodOptional<z.ZodNumber>;
+                    filesPerPage: z.ZodOptional<z.ZodNumber>;
+                    entriesPerPage: z.ZodOptional<z.ZodNumber>;
+                    matchesPerPage: z.ZodOptional<z.ZodNumber>;
+                    totalFiles: z.ZodOptional<z.ZodNumber>;
+                    totalEntries: z.ZodOptional<z.ZodNumber>;
+                    totalMatches: z.ZodOptional<z.ZodNumber>;
+                    totalFilesFound: z.ZodOptional<z.ZodNumber>;
+                    nextMatchPage: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+                pagination: z.ZodOptional<z.ZodObject<{
+                    currentPage: z.ZodNumber;
+                    totalPages: z.ZodNumber;
+                    hasMore: z.ZodBoolean;
+                    nextPage: z.ZodOptional<z.ZodNumber>;
+                    pageSize: z.ZodOptional<z.ZodNumber>;
+                    totalItems: z.ZodOptional<z.ZodNumber>;
+                    perPage: z.ZodOptional<z.ZodNumber>;
+                    totalFound: z.ZodOptional<z.ZodNumber>;
+                    returned: z.ZodOptional<z.ZodNumber>;
+                    reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                    reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                    totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                        exact: "exact";
+                        reported: "reported";
+                        lowerBound: "lowerBound";
+                    }>>;
+                    totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                    totalResults: z.ZodOptional<z.ZodNumber>;
+                    itemsPerPage: z.ZodOptional<z.ZodNumber>;
+                    filesPerPage: z.ZodOptional<z.ZodNumber>;
+                    entriesPerPage: z.ZodOptional<z.ZodNumber>;
+                    matchesPerPage: z.ZodOptional<z.ZodNumber>;
+                    totalFiles: z.ZodOptional<z.ZodNumber>;
+                    totalEntries: z.ZodOptional<z.ZodNumber>;
+                    totalMatches: z.ZodOptional<z.ZodNumber>;
+                    totalFilesFound: z.ZodOptional<z.ZodNumber>;
+                    nextMatchPage: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+                next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    tool: z.ZodString;
+                    query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    why: z.ZodOptional<z.ZodString>;
+                    confidence: z.ZodOptional<z.ZodEnum<{
+                        exact: "exact";
+                        heuristic: "heuristic";
+                    }>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>>;
+            summary: z.ZodOptional<z.ZodString>;
+            searchEngine: z.ZodOptional<z.ZodString>;
+            stats: z.ZodOptional<z.ZodObject<{
+                totalOccurrences: z.ZodOptional<z.ZodNumber>;
+                matchedLines: z.ZodOptional<z.ZodNumber>;
+                filesMatched: z.ZodOptional<z.ZodNumber>;
+                filesSearched: z.ZodOptional<z.ZodNumber>;
+                bytesSearched: z.ZodOptional<z.ZodNumber>;
+                searchTime: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            pagination: z.ZodOptional<z.ZodObject<{
+                currentPage: z.ZodNumber;
+                totalPages: z.ZodNumber;
+                hasMore: z.ZodBoolean;
+                nextPage: z.ZodOptional<z.ZodNumber>;
+                pageSize: z.ZodOptional<z.ZodNumber>;
+                totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
+                filesPerPage: z.ZodOptional<z.ZodNumber>;
+                entriesPerPage: z.ZodOptional<z.ZodNumber>;
+                matchesPerPage: z.ZodOptional<z.ZodNumber>;
+                totalFiles: z.ZodOptional<z.ZodNumber>;
+                totalEntries: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                totalFilesFound: z.ZodOptional<z.ZodNumber>;
+                nextMatchPage: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                tool: z.ZodString;
+                query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                why: z.ZodOptional<z.ZodString>;
+                confidence: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    heuristic: "heuristic";
+                }>>;
+            }, z.core.$strip>>>;
+            warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    base: z.ZodOptional<z.ZodString>;
+    shared: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    responsePagination: z.ZodOptional<z.ZodObject<{
+        currentPage: z.ZodNumber;
+        totalPages: z.ZodNumber;
+        hasMore: z.ZodBoolean;
+        charOffset: z.ZodNumber;
+        charLength: z.ZodNumber;
+        totalChars: z.ZodNumber;
+        nextCharOffset: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LocalSearchCodeOutput = z.infer<typeof LocalSearchCodeOutputSchema>;

package/dist/tools/local_view_structure/scheme.d.ts

@@ -31,3 +31,86 @@ export declare const LocalViewStructureBulkQuerySchema: z.ZodObject<{
     responseCharLength: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
     queries: z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
 }, z.core.$strip>;
+export declare const LocalViewStructureOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            empty: "empty";
+            error: "error";
+        }>>;
+        data: z.ZodObject<{
+            path: z.ZodOptional<z.ZodString>;
+            entries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
+                type: z.ZodEnum<{
+                    file: "file";
+                    link: "link";
+                    directory: "directory";
+                    dir: "dir";
+                    symlink: "symlink";
+                }>;
+                path: z.ZodOptional<z.ZodString>;
+                depth: z.ZodOptional<z.ZodNumber>;
+                size: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                sizeBytes: z.ZodOptional<z.ZodNumber>;
+                modified: z.ZodOptional<z.ZodString>;
+                permissions: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            folders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            summary: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+            pagination: z.ZodOptional<z.ZodObject<{
+                currentPage: z.ZodNumber;
+                totalPages: z.ZodNumber;
+                hasMore: z.ZodBoolean;
+                nextPage: z.ZodOptional<z.ZodNumber>;
+                pageSize: z.ZodOptional<z.ZodNumber>;
+                totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
+                filesPerPage: z.ZodOptional<z.ZodNumber>;
+                entriesPerPage: z.ZodOptional<z.ZodNumber>;
+                matchesPerPage: z.ZodOptional<z.ZodNumber>;
+                totalFiles: z.ZodOptional<z.ZodNumber>;
+                totalEntries: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                totalFilesFound: z.ZodOptional<z.ZodNumber>;
+                nextMatchPage: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                tool: z.ZodString;
+                query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                why: z.ZodOptional<z.ZodString>;
+                confidence: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    heuristic: "heuristic";
+                }>>;
+            }, z.core.$strip>>>;
+            warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    base: z.ZodOptional<z.ZodString>;
+    shared: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    responsePagination: z.ZodOptional<z.ZodObject<{
+        currentPage: z.ZodNumber;
+        totalPages: z.ZodNumber;
+        hasMore: z.ZodBoolean;
+        charOffset: z.ZodNumber;
+        charLength: z.ZodNumber;
+        totalChars: z.ZodNumber;
+        nextCharOffset: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LocalViewStructureOutput = z.infer<typeof LocalViewStructureOutputSchema>;

package/dist/tools/lsp/semantic_content/scheme.d.ts

@@ -95,11 +95,11 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
                 foundAtLine: z.ZodNumber;
                 orderHint: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
-            lsp: z.ZodObject<{
+            lsp: z.ZodOptional<z.ZodObject<{
                 serverAvailable: z.ZodOptional<z.ZodBoolean>;
                 provider: z.ZodOptional<z.ZodString>;
                 source: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>;
+            }, z.core.$strip>>;
             payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"definition">;
                 locations: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
@@ -356,13 +356,37 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
             pagination: z.ZodOptional<z.ZodObject<{
                 currentPage: z.ZodNumber;
                 totalPages: z.ZodNumber;
-                totalResults: z.ZodNumber;
                 hasMore: z.ZodBoolean;
-                itemsPerPage: z.ZodNumber;
                 nextPage: z.ZodOptional<z.ZodNumber>;
+                pageSize: z.ZodOptional<z.ZodNumber>;
+                totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             summary: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                tool: z.ZodString;
+                query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                why: z.ZodOptional<z.ZodString>;
+                confidence: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    heuristic: "heuristic";
+                }>>;
+            }, z.core.$strip>>>;
+            hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
@@ -386,11 +410,11 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
                 foundAtLine: z.ZodNumber;
                 orderHint: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
-            lsp: z.ZodObject<{
+            lsp: z.ZodOptional<z.ZodObject<{
                 serverAvailable: z.ZodOptional<z.ZodBoolean>;
                 provider: z.ZodOptional<z.ZodString>;
                 source: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>;
+            }, z.core.$strip>>;
             payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"definition">;
                 locations: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
@@ -647,13 +671,37 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
             pagination: z.ZodOptional<z.ZodObject<{
                 currentPage: z.ZodNumber;
                 totalPages: z.ZodNumber;
-                totalResults: z.ZodNumber;
                 hasMore: z.ZodBoolean;
-                itemsPerPage: z.ZodNumber;
                 nextPage: z.ZodOptional<z.ZodNumber>;
+                pageSize: z.ZodOptional<z.ZodNumber>;
+                totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             summary: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                tool: z.ZodString;
+                query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                why: z.ZodOptional<z.ZodString>;
+                confidence: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    heuristic: "heuristic";
+                }>>;
+            }, z.core.$strip>>>;
+            hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;

package/dist/tools/lsp/semantic_content/semanticAnchored.d.ts

@@ -0,0 +1,7 @@
+import { acquirePooledClient } from '@octocodeai/octocode-engine/lsp/manager';
+import type { SymbolAnchor } from '../shared/resolveSymbolAnchor.js';
+import type { LspSemanticEnvelope, SymbolAnchoredSemanticQuery } from '../shared/semanticTypes.js';
+declare const CONSUMER_SCOPED_TYPES: ReadonlySet<string>;
+export { CONSUMER_SCOPED_TYPES };
+export declare function warmLikelyConsumers(client: NonNullable<Awaited<ReturnType<typeof acquirePooledClient>>>, anchor: SymbolAnchor, workspaceRoot: string): Promise<void>;
+export declare function dispatchAnchoredSemantic(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, client: NonNullable<Awaited<ReturnType<typeof acquirePooledClient>>>): Promise<LspSemanticEnvelope>;

package/dist/tools/lsp/semantic_content/semanticEnvelopes/callEnvelopes.d.ts

@@ -0,0 +1,5 @@
+import { acquirePooledClient } from '@octocodeai/octocode-engine/lsp/manager';
+import { type LspSemanticEnvelope, type SymbolAnchoredSemanticQuery } from '../../shared/semanticTypes.js';
+import type { SymbolAnchor } from '../../shared/resolveSymbolAnchor.js';
+export declare function callsEnvelope(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, client: NonNullable<Awaited<ReturnType<typeof acquirePooledClient>>>): Promise<LspSemanticEnvelope>;
+export declare function typeHierarchyEnvelope(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, client: NonNullable<Awaited<ReturnType<typeof acquirePooledClient>>>): Promise<LspSemanticEnvelope>;

package/dist/tools/lsp/semantic_content/semanticEnvelopes/envelopeHelpers.d.ts

@@ -0,0 +1,20 @@
+import { type LspGetSemanticsQuery, type LspSemanticEnvelope, type SemanticEmptyCategory, type SemanticContentType } from '../../shared/semanticTypes.js';
+import type { SymbolAnchor } from '../../shared/resolveSymbolAnchor.js';
+export declare const DEFAULT_SYMBOLS_PER_PAGE = 40;
+export declare const DEFAULT_LOCATIONS_PER_PAGE = 40;
+export declare const DEFAULT_CALLS_PER_PAGE = 10;
+export type PaginationInfo = {
+    currentPage: number;
+    totalPages: number;
+    totalResults: number;
+    hasMore: boolean;
+    itemsPerPage: number;
+    nextPage?: number;
+};
+export declare function emptyCategoryForReason(type: SemanticContentType, reason: string): SemanticEmptyCategory;
+export declare function failedAnchorEnvelope(query: LspGetSemanticsQuery, reason: string): LspSemanticEnvelope;
+export declare function emptyEnvelope(type: SemanticContentType, anchor: SymbolAnchor, reason: string, serverAvailable?: boolean): LspSemanticEnvelope;
+export declare function paginateItems<T>(items: readonly T[], requestedPage: number, requestedItemsPerPage: number): {
+    pageItems: T[];
+    pagination: PaginationInfo;
+};

package/dist/tools/lsp/semantic_content/semanticEnvelopes/locationEnvelopes.d.ts

@@ -0,0 +1,13 @@
+import type { LSPRange, ReferenceLocation, ReferencesByFile, CodeSnippet } from '@octocodeai/octocode-engine/lsp/types';
+import { type LspSemanticEnvelope, type SymbolAnchoredSemanticQuery } from '../../shared/semanticTypes.js';
+import type { SymbolAnchor } from '../../shared/resolveSymbolAnchor.js';
+export declare function locationsEnvelope(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, kind: 'definition' | 'typeDefinition' | 'implementation', provider: string, locations: CodeSnippet[]): LspSemanticEnvelope;
+export declare function referencesEnvelope(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, locations: CodeSnippet[]): LspSemanticEnvelope;
+export declare function hoverEnvelope(_query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, hover: unknown): Promise<LspSemanticEnvelope>;
+export declare function buildReferencesByFile(locations: readonly ReferenceLocation[]): ReferencesByFile[];
+export declare function normalizeHover(hover: unknown): {
+    markdown?: string;
+    text?: string;
+    range?: LSPRange;
+};
+export declare function stringifyHoverPart(part: unknown): string;

package/dist/tools/lsp/semantic_content/semanticEnvelopes.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_SYMBOLS_PER_PAGE, DEFAULT_LOCATIONS_PER_PAGE, DEFAULT_CALLS_PER_PAGE, type PaginationInfo, emptyCategoryForReason, failedAnchorEnvelope, emptyEnvelope, paginateItems, } from './semanticEnvelopes/envelopeHelpers.js';
+export { locationsEnvelope, referencesEnvelope, hoverEnvelope, buildReferencesByFile, normalizeHover, stringifyHoverPart, } from './semanticEnvelopes/locationEnvelopes.js';
+export { callsEnvelope, typeHierarchyEnvelope, } from './semanticEnvelopes/callEnvelopes.js';

package/dist/tools/lsp/semantic_content/semanticFileOps/anchor.d.ts

@@ -0,0 +1,24 @@
+import type { SemanticContentType, WorkspaceSymbolSemanticQuery } from '../../shared/semanticTypes.js';
+export declare function isNativeJsTsFile(uri: string): boolean;
+/**
+ * Throw when a real language server cannot answer a semantic operation. We do
+ * NOT fabricate a syntactic/same-file stand-in: a faked answer is worse than an
+ * honest failure because the agent would trust it. The thrown ToolError is
+ * routed by the execution boundary into the standard `status:"error"` envelope
+ * (errorCode `lspServerUnavailable`), and the message directs the agent to text
+ * search instead. documentSymbols/structural search keep their tree-sitter path
+ * and never reach here.
+ */
+export declare function throwLspUnavailable(uri: string, op: SemanticContentType): never;
+export declare function toLocalPath(value: string, workspaceRoot: string): string;
+export declare function workspaceSymbolAnchorExtensions(): string[];
+export declare function workspaceSymbolAnchorIncludeGlobs(): string[];
+export declare function findWorkspaceSymbolAnchorByName(query: WorkspaceSymbolSemanticQuery, workspaceRoot: string): Promise<string | undefined>;
+export declare function resolveWorkspaceSymbolAnchor(query: WorkspaceSymbolSemanticQuery, workspaceRoot: string): Promise<string>;
+export declare function lspErrorMessage(error: unknown): string;
+/**
+ * Native JS/TS document symbols via oxc, parsed into the LSP `DocumentSymbol[]`
+ * shape. Returns `null` when oxc declines the input so the caller can fall back
+ * to the "no symbols" empty state.
+ */
+export declare function nativeDocumentSymbols(uri: string, content: string): unknown[] | null;