@octocodeai/octocode-tools-core 16.2.0 → 16.5.1

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

@@ -2,8 +2,8 @@ import { z } from 'zod';
 export declare const LspGetSemanticsQueryDisplaySchema: z.ZodObject<{
     uri: z.ZodString;
     type: z.ZodDefault<z.ZodEnum<{
-        references: "references";
         definition: "definition";
+        references: "references";
         callers: "callers";
         callees: "callees";
         callHierarchy: "callHierarchy";
@@ -34,8 +34,8 @@ export declare const LspGetSemanticsQueryDisplaySchema: 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";
@@ -64,14 +64,13 @@ export declare const LspGetSemanticsQuerySchema: z.ZodObject<{
     reasoning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const BulkLspGetSemanticsQuerySchema: z.ZodObject<{
-    responseCharOffset: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNumber>>;
-    responseCharLength: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNumber>>;
+    responseCharOffset: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
+    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 LspGetSemanticsOutputSchema: z.ZodObject<{
     base: z.ZodOptional<z.ZodString>;
     shared: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-    hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     results: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         id: z.ZodString;
         status: z.ZodLiteral<"empty">;
@@ -283,7 +282,6 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
             }, z.core.$strip>>;
             summary: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
@@ -291,7 +289,6 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
         data: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             error: z.ZodString;
-            hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
@@ -503,7 +500,6 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
             }, z.core.$strip>>;
             summary: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;

package/dist/tools/lsp/shared/callHierarchyTraversal.d.ts

@@ -1,5 +1,5 @@
-import type { LSPClient } from 'octocode-lsp/client';
-import type { CallHierarchyItem, IncomingCall, OutgoingCall } from 'octocode-lsp/types';
+import type { LSPClient } from '@octocodeai/octocode-engine/lsp/client';
+import type { CallHierarchyItem, IncomingCall, OutgoingCall } from '@octocodeai/octocode-engine/lsp/types';
 export type TraversalResult<T> = {
     calls: T[];
     truncatedByDepth: boolean;

package/dist/tools/lsp/shared/semanticTypes.d.ts

@@ -1,4 +1,4 @@
-import type { ExactPosition, LSPRange } from 'octocode-lsp/types';
+import type { ExactPosition, LSPRange } from '@octocodeai/octocode-engine/lsp/types';
 export declare const LSP_GET_SEMANTIC_CONTENT_TOOL_NAME = "lspGetSemantics";
 export declare const SEMANTIC_CONTENT_TYPES: readonly ["definition", "references", "callers", "callees", "callHierarchy", "hover", "documentSymbols", "typeDefinition", "implementation"];
 export type SemanticContentType = (typeof SEMANTIC_CONTENT_TYPES)[number];
@@ -58,6 +58,7 @@ export type CompactLocation = {
 export declare function compactLocation(snippet: {
     uri: string;
     content?: string;
+    range?: LSPRange;
     displayRange?: {
         startLine: number;
         endLine: number;

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

@@ -8,8 +8,8 @@ export declare const NpmSearchQueryLocalSchema: z.ZodObject<{
     reasoning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const NpmSearchBulkQueryLocalSchema: z.ZodObject<{
-    responseCharOffset: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNumber>>;
-    responseCharLength: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNumber>>;
+    responseCharOffset: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
+    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 NpmSearchOutputLocalSchema: z.ZodObject<{
@@ -21,9 +21,10 @@ export declare const NpmSearchOutputLocalSchema: z.ZodObject<{
                 version: z.ZodOptional<z.ZodString>;
                 description: z.ZodOptional<z.ZodString>;
                 license: z.ZodOptional<z.ZodString>;
-                weeklyDownloads: z.ZodOptional<z.ZodNumber>;
+                downloads: z.ZodOptional<z.ZodNumber>;
                 repository: z.ZodOptional<z.ZodString>;
                 repositoryDirectory: z.ZodOptional<z.ZodString>;
+                next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             }, z.core.$loose>>>;
             pagination: z.ZodOptional<z.ZodObject<{
                 currentPage: z.ZodNumber;
@@ -32,14 +33,15 @@ export declare const NpmSearchOutputLocalSchema: z.ZodObject<{
                 totalFound: z.ZodNumber;
                 returned: z.ZodNumber;
                 hasMore: z.ZodBoolean;
+                nextPage: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$loose>>;
         status: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>>;
-    readonly hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    readonly base: z.ZodOptional<z.ZodString>;
-    readonly shared: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-    readonly responsePagination: z.ZodOptional<z.ZodObject<{
+    hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    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;

package/dist/tools/providerMappers.d.ts

@@ -9,6 +9,13 @@ type GitHubCodeSearchQuery = z.infer<typeof GitHubCodeSearchQuerySchema>;
 type LocalFileContentQuery = z.infer<typeof FileContentQueryLocalSchema> & {
     minify: import('../scheme/fields.js').MinifyMode;
 };
+/**
+ * Char-boundary truncation mirroring the Rust engine's `truncate_unicode`:
+ * keeps at most `maxChars` Unicode scalars and appends `...` when it cuts.
+ * Never slices UTF-8 mid-codepoint or mid-token — the single data-layer bound
+ * for GitHub code-search match fragments (the render layer must not re-trim).
+ */
+export declare function truncateSnippetChars(value: string, maxChars?: number): string;
 type GitHubPullRequestSearchQuery = z.infer<typeof GitHubPullRequestSearchQueryLocalSchema>;
 type GitHubReposSearchSingleQuery = z.infer<typeof GitHubReposSearchSingleQuerySchema>;
 type GitHubViewRepoStructureQuery = z.infer<typeof GitHubViewRepoStructureQuerySchema>;
@@ -70,12 +77,14 @@ export interface CodeSearchPagination {
     totalMatchesKind?: 'exact' | 'reported' | 'lowerBound';
     totalMatchesCapped?: boolean;
     hasMore: boolean;
+    nextPage?: number;
     uniqueFileCount?: number;
 }
 export interface CodeSearchFlatResult {
     results: CodeSearchGroupedResult[];
     pagination?: CodeSearchPagination;
     nonExistentScope?: boolean;
+    incompleteResults?: boolean;
 }
 export declare function mapCodeSearchProviderResult(data: CodeSearchResult, query: WithOptionalMeta<GitHubCodeSearchQuery>): CodeSearchFlatResult;
 export declare function mapRepoSearchToolQuery(query: WithOptionalMeta<GitHubReposSearchSingleQuery>): {
@@ -130,6 +139,14 @@ export declare function mapPullRequestToolQuery(query: PartialPRQuery): {
     interactions: string;
     draft: boolean;
     match: ("comments" | "title" | "body")[];
+    milestone: string;
+    language: string;
+    checks: "pending" | "success" | "failure";
+    review: "none" | "required" | "approved" | "changes_requested";
+    locked: boolean;
+    visibility: "public" | "private";
+    teamMentions: string;
+    project: string;
     archived: boolean | undefined;
     content: unknown;
     reviewMode: "summary" | "full";
@@ -230,6 +247,7 @@ export declare function mapPullRequestProviderResultData(data: ProviderPullReque
     }[];
     resultData: Record<string, unknown>;
     pagination: {
+        nextPage?: number;
         hasMore: boolean;
         uniqueFileCount?: number;
         totalMatchesCapped?: boolean;
@@ -251,6 +269,7 @@ export declare function mapFileContentToolQuery(query: LocalFileContentQuery): {
     matchString: string;
     contextLines: number;
     fullContent: boolean;
+    forceRefresh: boolean;
     charOffset: number;
     charLength: number;
     minify: "none" | "standard" | "symbols";

package/dist/tools/toolMetadata/proxies.d.ts

@@ -2,9 +2,3 @@ export { TOOL_NAMES } from './names.js';
 export { DESCRIPTIONS } from './descriptions.js';
 export { isToolInMetadata } from './metadataPresence.js';
 export { BASE_SCHEMA } from './baseSchema.js';
-type HintsMap = Record<string, readonly string[]>;
-export declare const TOOL_HINTS: Record<string, HintsMap>;
-export declare const GENERIC_ERROR_HINTS: readonly string[];
-export declare function getToolHintsSync(toolName: string, status: string): readonly string[];
-export declare function getDynamicHints(toolName: string, key: string): readonly string[];
-export declare function getGenericErrorHintsSync(): readonly string[];

package/dist/tools/utils.d.ts

@@ -1,20 +1,16 @@
 import type { ToolErrorResult, ToolSuccessResult, ToolInvocationCallback } from '../types/toolResults.js';
-import type { HintContext } from '../types/metadata.js';
 import type { ProviderResponse } from '../providers/types.js';
-import { createErrorResult } from '../utils/response/error.js';
-export { createErrorResult };
+import { createErrorResult, safeParseOrError } from '../utils/response/error.js';
+export { createErrorResult, safeParseOrError };
 export declare function invokeCallbackSafely(callback: ToolInvocationCallback | undefined, toolName: string, queries: unknown[]): Promise<void>;
 interface SuccessResultOptions {
-    hintContext?: HintContext;
-    prefixHints?: string[];
-    extraHints?: string[];
     rawResponse?: unknown;
 }
 export declare function createSuccessResult<T extends object>(_query: {
     mainResearchGoal?: string;
     researchGoal?: string;
     reasoning?: string;
-}, data: T, hasContent: boolean, toolName: string, options?: SuccessResultOptions): ToolSuccessResult & T;
+}, data: T, hasContent: boolean, _toolName: string, options?: SuccessResultOptions): ToolSuccessResult & T;
 export declare function handleProviderError(apiResult: ProviderResponse<unknown>, query: {
     mainResearchGoal?: string;
     researchGoal?: string;

package/dist/types/bulk.d.ts

@@ -26,7 +26,6 @@ export interface ResponsePaginationInfo {
 export interface BulkResponseConfig<TQuery = object, TOutput extends Record<string, unknown> = Record<string, unknown>> {
     toolName: string;
     keysPriority?: string[];
-    peerHints?: boolean;
     concurrency?: number;
     minQueryTimeoutMs?: number;
     responsePagination?: BulkResponsePagination;
@@ -34,7 +33,6 @@ export interface BulkResponseConfig<TQuery = object, TOutput extends Record<stri
 }
 export interface BulkToolResponse {
     results: FlatQueryResult[];
-    hints?: string[];
     base?: string;
     shared?: Record<string, string | number | boolean>;
     responsePagination?: ResponsePaginationInfo;

package/dist/types/execution.d.ts

@@ -1,5 +1,4 @@
 import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
-import type { HintContext } from './metadata.js';
 export type WithOptionalMeta<T> = Partial<T>;
 export interface ToolExecutionArgs<TQuery> {
     queries: TQuery[];
@@ -7,5 +6,5 @@ export interface ToolExecutionArgs<TQuery> {
     responseCharLength?: number;
     authInfo?: AuthInfo;
     sessionId?: string;
-    hintContext?: HintContext;
+    hintContext?: Record<string, unknown>;
 }

package/dist/types/toolResults.d.ts

@@ -2,7 +2,6 @@ import type { GitHubAPIError } from '../github/githubAPI.js';
 export type QueryStatus = 'empty' | 'error';
 interface ToolResult {
     status?: QueryStatus;
-    hints?: string[];
     [key: string]: unknown;
 }
 export interface ToolErrorResult extends ToolResult {
@@ -16,6 +15,8 @@ export interface PaginationInfo {
     currentPage: number;
     totalPages: number;
     hasMore: boolean;
+    nextPage?: number;
+    nextMatchPage?: number;
     charOffset?: number;
     charLength?: number;
     totalChars?: number;
@@ -41,7 +42,6 @@ export interface ProcessedBulkResult {
     data?: Record<string, unknown>;
     error?: string | GitHubAPIError;
     status?: QueryStatus;
-    hints?: readonly string[] | string[];
     [key: string]: unknown;
 }
 export interface FlatQueryResult {
@@ -55,7 +55,6 @@ export interface QueryError {
 }
 export interface StructuredToolResponse {
     data?: unknown;
-    hints?: string[];
     instructions?: string;
     [key: string]: unknown;
 }

package/dist/utils/contextUtils.d.ts

@@ -1,5 +1,5 @@
-import type * as NativeContextUtils from '@octocodeai/octocode-context-utils';
-export type { ExtractMatchingLinesOptions, ExtractMatchingLinesResult, FilterPatchOptions, FileSystemEntry, FileSystemQueryOptions, FileSystemQueryResult, MinifyResult, JsonInput, RipgrepParseOptions, RipgrepParseResult, SliceContentOptions, SliceContentResult, StructuralMatch, YamlConversionConfig, } from '@octocodeai/octocode-context-utils';
+import type * as NativeContextUtils from '@octocodeai/octocode-engine';
+export type { BinaryInspectInfo, BinaryStrings, ExtractMatchingLinesOptions, ExtractMatchingLinesResult, FilterPatchOptions, FileSystemEntry, FileSystemQueryOptions, FileSystemQueryResult, MinifyResult, JsonInput, RipgrepParseOptions, RipgrepParseResult, RipgrepSearchOptions, SliceContentOptions, SliceContentResult, StructuralMatch, YamlConversionConfig, } from '@octocodeai/octocode-engine';
 type NativeContextUtilsModule = typeof NativeContextUtils;
 type NativeLoader = () => NativeContextUtilsModule;
 export declare class ContextUtilsLoadError extends Error {
@@ -16,10 +16,43 @@ export declare const contextUtils: {
     minifyContentResult(content: string, filePath: string): NativeContextUtils.MinifyResult;
     minifyMarkdownCore(content: string): string;
     extractSignatures(content: string, filePath: string): string | null;
+    /**
+     * Native JS/TS document symbols as a JSON `DocumentSymbol[]` string, or null
+     * when oxc declines the input (non-JS/TS, oversized, hard parse failure, or
+     * no symbols). Server-free, syntax-only — no type inference.
+     */
+    extractJsSymbols(content: string, filePath: string): string | null;
+    /**
+     * Native in-file references as a JSON `Range[]` (declaration first), or null
+     * when oxc declines the input or the cursor is not on a resolvable binding.
+     * Same-file only, syntax-only — no type inference, no cross-file resolution.
+     */
+    findInFileReferences(content: string, filePath: string, line: number, character: number): string | null;
+    /**
+     * Canonical lowercase extensions (no leading dot) the native oxc JS/TS path
+     * handles. Source of truth lives in the engine — gate native dispatch on this.
+     */
+    getSupportedJsTsExtensions(): string[];
     structuralSearch(content: string, filePath: string, pattern?: string | null, rule?: string | null): NativeContextUtils.StructuralMatch[];
+    structuralSearchFiles(options: NativeContextUtils.StructuralSearchFilesOptions): NativeContextUtils.StructuralSearchFilesResult;
+    getSupportedStructuralExtensions(): string[];
+    /**
+     * Native binary inspection (format lane). Parses an executable / object /
+     * archive and returns identity + symbols/imports/exports/sections/deps.
+     * Degrades to magic-byte identity on malformed input; only unreadable or
+     * oversized files throw.
+     */
+    inspectBinaryNative(path: string): NativeContextUtils.BinaryInspectInfo;
+    /**
+     * Native strings extraction — printable ASCII + UTF-16 (LE/BE) runs of at
+     * least `minLength`, longest-first, optionally hex offset-prefixed.
+     */
+    extractBinaryStringsNative(path: string, minLength: number, includeOffsets: boolean, scanOffset?: number): NativeContextUtils.BinaryStrings;
+    validateRipgrepPattern(pattern: string, fixedString?: boolean | null, perlRegex?: boolean | null): NativeContextUtils.RipgrepPatternValidationResult;
     getSemanticBoundaryOffsets(content: string, filePath: string): number[];
     jsonToYamlString(jsonObject: NativeContextUtils.JsonInput, config?: NativeContextUtils.YamlConversionConfig | null): string;
     parseRipgrepJson(stdout: string, options?: NativeContextUtils.RipgrepParseOptions | null): NativeContextUtils.RipgrepParseResult;
+    searchRipgrep(options: NativeContextUtils.RipgrepSearchOptions): Promise<NativeContextUtils.RipgrepParseResult>;
     queryFileSystem(options: NativeContextUtils.FileSystemQueryOptions): NativeContextUtils.FileSystemQueryResult;
     extractMatchingLines(content: string, pattern: string, options?: NativeContextUtils.ExtractMatchingLinesOptions | null): NativeContextUtils.ExtractMatchingLinesResult;
     filterPatch(patch: string, options?: NativeContextUtils.FilterPatchOptions | null): string;

package/dist/utils/core/lines.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Split `content` into its text lines, handling LF and CRLF endings.
+ *
+ * A line is a maximal run of characters terminated by a newline or by EOF. A
+ * single trailing newline terminates the last line; it does not start a new
+ * empty one, so `"a\nb\n"` yields `["a", "b"]`, not `["a", "b", ""]`. A plain
+ * `split('\n')` gets this wrong by emitting a trailing empty segment for
+ * newline-terminated text. A genuine blank final line (`"a\n\n"`) is preserved
+ * — only the single terminator is dropped.
+ */
+export declare function splitLines(content: string): string[];
+/**
+ * Number of text lines in `content`. Equals `splitLines(content).length`; see
+ * {@link splitLines} for how trailing newlines are handled.
+ */
+export declare function countLines(content: string): number;

package/dist/utils/core/types.d.ts

@@ -3,6 +3,8 @@ export interface ExecResult {
     stdout: string;
     stderr: string;
     success: boolean;
+    /** True when output hit maxOutputSize and stdout is the partial prefix. */
+    truncated?: boolean;
 }
 export interface ExecOptions {
     cwd?: string;
@@ -10,11 +12,19 @@ export interface ExecOptions {
     env?: Record<string, string>;
     maxOutputSize?: number;
     toolName?: string;
+    /**
+     * When true, an output-size overflow returns the partial stdout flagged
+     * `truncated` instead of throwing. For commands (e.g. `strings` on a huge
+     * binary) where a bounded prefix is still useful.
+     */
+    tolerateOutputLimit?: boolean;
 }
 export interface PaginationInfo {
     currentPage: number;
     totalPages: number;
     hasMore: boolean;
+    nextPage?: number;
+    nextMatchPage?: number;
     charOffset?: number;
     charLength?: number;
     totalChars?: number;

package/dist/utils/file/filters.d.ts

@@ -1,11 +1,2 @@
-export declare const IGNORED_FOLDER_NAMES: string[];
-export declare const IGNORED_FILE_NAMES: string[];
-export declare const IGNORED_FILE_EXTENSIONS: string[];
-export declare function shouldIgnoreDir(folderName: string): boolean;
-export declare function shouldIgnoreFile(filePath: string): boolean;
-interface GetExtensionOptions {
-    lowercase?: boolean;
-    fallback?: string;
-}
-export declare function getExtension(filePath: string, options?: GetExtensionOptions): string;
-export {};
+export { DISCOVERY_IGNORED_FILE_EXTENSIONS as IGNORED_FILE_EXTENSIONS, DISCOVERY_IGNORED_FILE_NAMES as IGNORED_FILE_NAMES, DISCOVERY_IGNORED_FOLDER_NAMES as IGNORED_FOLDER_NAMES, getDiscoveryExtension as getExtension, shouldIgnoreDiscoveryDir as shouldIgnoreDir, shouldIgnoreDiscoveryFile as shouldIgnoreFile, } from '@octocodeai/octocode-engine/security';
+export type { DiscoveryExtensionOptions as GetExtensionOptions } from '@octocodeai/octocode-engine/security';

package/dist/utils/parsers/diff.d.ts

@@ -1,2 +1,20 @@
+/** Max diff lines carried in a {@link DiffPreview} before the rest are summarized. */
+export declare const DIFF_PREVIEW_MAX_LINES = 20;
+/**
+ * A render-ready slice of a patch: the first {@link DIFF_PREVIEW_MAX_LINES}
+ * lines plus a count of how many were withheld. Consumers (e.g. the CLI) only
+ * colorize `lines` and print `moreCount` — they do no splitting or counting, so
+ * the trailing-newline off-by-one lives in exactly one place.
+ */
+export interface DiffPreview {
+    lines: string[];
+    moreCount: number;
+}
+/**
+ * Build a {@link DiffPreview} from a raw patch string. Splitting is newline-safe
+ * via {@link splitLines}, so a patch that ends in a newline neither inflates
+ * `moreCount` nor surfaces a phantom blank line.
+ */
+export declare function buildDiffPreview(patch: string | undefined, maxLines?: number): DiffPreview;
 export declare function filterPatch(patch: string, additions?: number[], deletions?: number[]): string;
 export declare function trimDiffContext(patch: string): string;

package/dist/utils/ranking/evidenceRanker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Tier 2 — cross-source evidence fusion for code-research results.
+ *
+ * Raw LSP, structural-search, and code-search scores are not comparable. This
+ * layer normalizes hits into `EvidenceItem`s, merges them into `EvidenceBundle`s
+ * (one per useful target), fuses incomparable per-source ranks with weighted
+ * Reciprocal Rank Fusion, reranks by task intent, diversifies, budgets for
+ * tokens, and explains every result. See `.octocode/RANKING-ARCHITECTURE.md`.
+ *
+ * Determinism: no clock, no randomness. Sort is total via explicit
+ * tie-breakers. Weak evidence is penalized but never silently dropped.
+ */
+export interface Range {
+    startLine: number;
+    endLine?: number;
+}
+export type EvidenceSource = 'lsp' | 'structural' | 'codeSearch' | 'fileGraph' | 'signature' | 'contentView' | 'recentEdit' | 'testSignal' | 'diagnostic';
+export type EvidenceStatus = 'ok' | 'partial' | 'fallback' | 'ambiguous' | 'unsupported' | 'parserFailed' | 'truncated' | 'stale';
+export type EvidenceIntent = 'definition' | 'reference' | 'callsite' | 'declaration' | 'implementation' | 'test' | 'config' | 'doc' | 'schema' | 'route' | 'error' | 'unknown';
+export type EvidenceConfidence = 'high' | 'medium' | 'low';
+/** A measurement that can be mapped to a source weight (e.g. LSP fallback kind). */
+export type EvidenceQuality = 'exact' | 'detailed' | 'nearLineFallback' | 'wholeFileFallback' | 'partialAst' | 'fallbackText' | 'comment' | 'broadRegex';
+export interface EvidenceItem {
+    id: string;
+    source: EvidenceSource;
+    /** 1-based rank within this item's own source list (for RRF). */
+    sourceRank: number;
+    sourceScore?: number;
+    status: EvidenceStatus;
+    confidence: EvidenceConfidence;
+    intent: EvidenceIntent;
+    quality?: EvidenceQuality;
+    path: string;
+    range?: Range;
+    symbol?: string;
+    languageId?: string;
+    textPreview?: string;
+    tokenCost?: number;
+    reasons: string[];
+}
+export interface EvidenceBundle {
+    id: string;
+    target: {
+        path: string;
+        range?: Range;
+        symbol?: string;
+        languageId?: string;
+    };
+    primaryIntent: EvidenceIntent;
+    contributors: EvidenceItem[];
+    fusedScore: number;
+    finalScore: number;
+    confidence: EvidenceConfidence;
+    status: EvidenceStatus;
+    tokenCost: number;
+    reasons: string[];
+    warnings: string[];
+}
+export interface RankedEvidenceGroups {
+    mustRead: EvidenceBundle[];
+    supporting: EvidenceBundle[];
+    maybe: EvidenceBundle[];
+    weakOrSkipped: EvidenceBundle[];
+}
+export type RankTask = 'definition' | 'references' | 'edit' | 'explain' | 'security' | 'test' | 'generic';
+export interface RankEvidenceOptions {
+    task: RankTask;
+    seed?: {
+        path?: string;
+        range?: Range;
+        symbol?: string;
+        query?: string;
+    };
+    tokenBudget?: number;
+    maxBundles?: number;
+    includeWeak?: boolean;
+}
+export interface RankEvidenceResult {
+    groups: RankedEvidenceGroups;
+    allBundles: EvidenceBundle[];
+    scorerVersion: string;
+}
+export declare const SCORER_VERSION = "tier2-rrf-1";
+export declare function bundleEvidence(items: EvidenceItem[]): EvidenceBundle[];
+/** Rank a flat list of normalized evidence items into explained groups. */
+export declare function rankEvidence(items: EvidenceItem[], options: RankEvidenceOptions): RankEvidenceResult;

package/dist/utils/response/error.d.ts

@@ -5,16 +5,50 @@ export interface UnifiedErrorResult {
     status: 'error';
     error?: string | GitHubAPIError;
     errorCode?: string;
-    hints?: string[];
     [key: string]: unknown;
 }
 interface CreateErrorResultOptions {
     toolName?: string;
-    hintContext?: Record<string, unknown>;
     extra?: Record<string, unknown>;
-    customHints?: string[];
-    hintSourceError?: GitHubAPIError;
     rawResponse?: unknown;
 }
 export declare function createErrorResult(error: unknown, _query: PartialBaseQuery, options?: CreateErrorResultOptions): UnifiedErrorResult;
+/**
+ * Minimal shape of the parts of a Zod schema this helper relies on, kept
+ * version-agnostic so it does not couple to a specific Zod release.
+ */
+interface SafeParseableSchema<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+        error?: never;
+    } | {
+        success: false;
+        data?: never;
+        error: {
+            issues: Array<{
+                message: string;
+            }>;
+        };
+    };
+}
+export type SafeParseOutcome<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: UnifiedErrorResult;
+};
+/**
+ * Validate `input` against `schema`, returning either the parsed data or a
+ * structured {@link UnifiedErrorResult} built via {@link createErrorResult}.
+ *
+ * Replaces the per-tool `safeParse → issues.map(...).join('; ') →
+ * createErrorResult('Validation error: …')` block. Pass `prefix: false` to
+ * omit the "Validation error: " prefix (github_fetch_content parity).
+ */
+export declare function safeParseOrError<T>(schema: SafeParseableSchema<T>, query: PartialBaseQuery, options?: {
+    toolName?: string;
+    prefix?: boolean;
+}): SafeParseOutcome<T>;
 export {};

package/dist/utils/response/groupedFinalizer.d.ts

@@ -27,11 +27,9 @@ export declare function paginateGroupsCharWindow<TGroup, TItem>({ groups, getIte
     groups: TGroup[];
     pagination: CharPagination;
 };
-export declare function dedupeHints(hints: readonly string[]): string[];
 export declare function collectFlatErrors(results: readonly FlatQueryResult[]): Array<{
     id: string;
     error: string;
-    hints?: string[];
 }>;
 export declare function formatFinalizedResponse<T extends Record<string, unknown>>(responseData: T, keysPriority: readonly string[], isError?: boolean): BulkFinalizerOutput<T>;
 export {};