@octocodeai/octocode-tools-core 18.1.2 → 18.2.0

package/dist/tools/providerMappers/pullRequests.d.ts

@@ -27,12 +27,11 @@ export declare function mapPullRequestToolQuery(query: PartialPRQuery): {
     comments: string;
     reactions: string;
     draft: boolean;
-    match: ("title" | "body" | "comments")[];
-    checks: "success" | "failure" | "pending";
-    review: "none" | "approved" | "changes_requested" | "required";
+    match: ("body" | "title" | "comments")[];
+    checks: "success" | "pending" | "failure";
+    review: "none" | "required" | "approved" | "changes_requested";
     archived: boolean | undefined;
     content: unknown;
-    reviewMode: "full" | "summary";
     filePage: number;
     commentPage: number;
     commitPage: number;
@@ -43,8 +42,7 @@ export declare function mapPullRequestToolQuery(query: PartialPRQuery): {
     page: number;
     charOffset: number;
     charLength: number;
-    mainResearchGoal: string;
-    researchGoal: string;
+    goal: string;
     reasoning: string;
 };
 export declare function mapPullRequestProviderResultData(data: ProviderPullRequestSearchResult, options?: {
@@ -64,6 +62,8 @@ export declare function mapPullRequestProviderResultData(data: ProviderPullReque
             inlineComments: number;
             discussionComments: number;
             commenters: string[];
+            commenterCount: number;
+            commentersTruncated?: true;
             latestCommentAt?: string;
             themes: string[];
         };

package/dist/tools/providerMappers/repoSearch.d.ts

@@ -1,6 +1,6 @@
 import type { RepoSearchResult as ProviderRepoSearchResult } from '../../providers/types.js';
 import type { z } from 'zod';
-import type { GitHubReposSearchSingleQuerySchema } from '@octocodeai/octocode-core/schemas';
+import type { GitHubReposSearchSingleQuerySchema } from '../../toolContract/schemas.js';
 import type { GitHubRepositoryOutput } from '@octocodeai/octocode-core/extra-types';
 import type { WithOptionalMeta } from '../../types/execution.js';
 type GitHubReposSearchSingleQuery = z.infer<typeof GitHubReposSearchSingleQuerySchema>;
@@ -9,17 +9,20 @@ export declare function mapRepoSearchToolQuery(query: WithOptionalMeta<GitHubRep
     topics: string[];
     owner: string;
     stars: string;
+    size: string | undefined;
+    created: string | undefined;
     updated: string;
     language: string;
     archived: boolean | undefined;
     visibility: "public" | "private" | undefined;
     license: string | undefined;
-    match: ("description" | "name" | "readme")[];
+    forks: string | undefined;
+    goodFirstIssues: string | undefined;
+    match: ("name" | "description" | "readme")[];
     sort: "updated" | "best-match" | "stars" | "forks" | "help-wanted-issues";
     limit: number | undefined;
     page: number;
-    mainResearchGoal: string;
-    researchGoal: string;
+    goal: string;
     reasoning: string;
 };
 export declare function mapRepoSearchProviderRepositories(repositories: ProviderRepoSearchResult['repositories']): GitHubRepositoryOutput[];

package/dist/tools/providerMappers/repoStructure.d.ts

@@ -1,6 +1,6 @@
 import type { RepoStructureResult as ProviderRepoStructureResult } from '../../providers/types.js';
 import type { z } from 'zod';
-import type { GitHubViewRepoStructureQuerySchema } from '@octocodeai/octocode-core/schemas';
+import type { GitHubViewRepoStructureQuerySchema } from '../../toolContract/schemas.js';
 import type { WithOptionalMeta } from '../../types/execution.js';
 type GitHubViewRepoStructureQuery = z.infer<typeof GitHubViewRepoStructureQuerySchema>;
 type PartialRepoStructureQuery = WithOptionalMeta<GitHubViewRepoStructureQuery>;
@@ -16,8 +16,7 @@ export declare function mapRepoStructureToolQuery(query: PartialRepoStructureQue
     includeContributors: boolean;
     includeBranches: boolean;
     includeTags: boolean;
-    mainResearchGoal: string;
-    researchGoal: string;
+    goal: string;
     reasoning: string;
 };
 export declare function mapRepoStructureProviderResult(data: ProviderRepoStructureResult, _query: PartialRepoStructureQuery, filteredStructure: ProviderRepoStructureResult['structure'], resolvedBranch: string): Record<string, unknown>;

package/dist/tools/toolCatalogFactory.d.ts

@@ -1,7 +1,5 @@
-import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import type { ToolNames } from '@octocodeai/octocode-core/types';
+import type { CallToolResult } from '@modelcontextprotocol/server';
 import { type z } from 'zod';
-import { type ToolMetadataGateway } from './toolMetadata/gateway.js';
 export type ToolDirectSecurity = 'basic' | 'remote';
 export interface ToolDirectExecutionConfig {
     schema: z.ZodType;
@@ -10,16 +8,17 @@ export interface ToolDirectExecutionConfig {
     security: ToolDirectSecurity;
     requiresServerRuntime?: boolean;
     requiresProviders?: boolean;
+    /** Outer security boundary for tools whose own bounded operation may exceed
+     * the shared 60-second default (for example a shallow repository clone). */
+    timeoutMs?: number;
 }
 export interface ToolConfig {
     name: string;
+    title: string;
     description: string;
     isDefault: boolean;
     isLocal: boolean;
     isClone?: boolean;
     type: 'search' | 'content' | 'history' | 'debug';
-    skipMetadataCheck?: boolean;
     direct: ToolDirectExecutionConfig;
 }
-export declare const getDescription: (toolName: string, gateway?: Pick<ToolMetadataGateway, "getDescription">) => string;
-export declare function createTool(gateway: ToolMetadataGateway, nameKey: keyof ToolNames, config: Omit<ToolConfig, 'name' | 'description'>): ToolConfig;

package/dist/tools/toolConfig.d.ts

@@ -1,25 +1,14 @@
-import { DEFAULT_TOOL_METADATA_GATEWAY, type ToolMetadataGateway } from './toolMetadata/gateway.js';
-import { getDescription, type ToolConfig, type ToolDirectExecutionConfig, type ToolDirectSecurity } from './toolCatalogFactory.js';
-export type { ToolMetadataGateway };
-export { DEFAULT_TOOL_METADATA_GATEWAY };
-export { getDescription };
+import { type ToolConfig, type ToolDirectExecutionConfig, type ToolDirectSecurity } from './toolCatalogFactory.js';
 export type { ToolConfig, ToolDirectExecutionConfig, ToolDirectSecurity };
 export type { ToolInvocationCallback } from '../types/toolResults.js';
-export declare const GITHUB_SEARCH_CODE: ToolConfig;
+export declare const GITHUB_SEARCH: ToolConfig;
 export declare const GITHUB_FETCH_CONTENT: ToolConfig;
-export declare const GITHUB_VIEW_REPO_STRUCTURE: ToolConfig;
-export declare const GITHUB_SEARCH_REPOSITORIES: ToolConfig;
-export declare const GITHUB_PULL_REQUESTS: ToolConfig;
-export declare const GITHUB_ISSUES: ToolConfig;
-export declare const GITHUB_COMMITS: ToolConfig;
-export declare const GITHUB_RELEASES: ToolConfig;
-export declare const GITHUB_DISCUSSIONS: ToolConfig;
+export declare const GITHUB_SEARCH_HISTORY: ToolConfig;
+export declare const GITHUB_GET_HISTORY_ITEM: ToolConfig;
 export declare const PACKAGE_SEARCH: ToolConfig;
 export declare const GITHUB_CLONE_REPO: ToolConfig;
-export declare const LOCAL_RIPGREP: ToolConfig;
-export declare const LOCAL_VIEW_STRUCTURE: ToolConfig;
-export declare const LOCAL_FIND_FILES: ToolConfig;
-export declare const LOCAL_FIND_DEAD_CODE: ToolConfig;
+export declare const LOCAL_SEARCH: ToolConfig;
+export declare const LOCAL_ANALYZE_GRAPH: ToolConfig;
 export declare const LOCAL_FETCH_CONTENT: ToolConfig;
 export declare const LSP_GET_SEMANTIC_CONTENT: ToolConfig;
 export declare const ALL_TOOLS: ToolConfig[];

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

@@ -1,2 +1 @@
-import type { CompleteMetadata } from '@octocodeai/octocode-core/types';
-export declare const BASE_SCHEMA: CompleteMetadata["baseSchema"];
+export { baseSchemaDescriptions as BASE_SCHEMA } from '../../toolContract/schemas.js';

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

@@ -1 +1 @@
-export declare const DESCRIPTIONS: Record<string, string>;
+export { PUBLIC_TOOL_DESCRIPTIONS, PUBLIC_TOOL_DESCRIPTIONS as DESCRIPTIONS, } from '../../toolContract/descriptions.js';

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

@@ -1,2 +1,18 @@
-import type { CompleteMetadata } from '@octocodeai/octocode-core/types';
-export declare const TOOL_NAMES: CompleteMetadata["toolNames"];
+export declare const TOOL_NAMES: {
+    readonly LOCAL_SEARCH: "localSearch";
+    readonly GITHUB_SEARCH_CODE: "github.code";
+    readonly GITHUB_VIEW_REPO_STRUCTURE: "github.tree";
+    readonly GITHUB_SEARCH_REPOSITORIES: "github.repositories";
+    readonly LOCAL_RIPGREP: "local.text";
+    readonly LOCAL_VIEW_STRUCTURE: "local.tree";
+    readonly LOCAL_FIND_FILES: "local.files";
+    readonly GITHUB_SEARCH: "ghSearch";
+    readonly GITHUB_FETCH_CONTENT: "ghGetFileContent";
+    readonly PACKAGE_SEARCH: "npmSearch";
+    readonly GITHUB_CLONE_REPO: "ghCloneRepo";
+    readonly LOCAL_FETCH_CONTENT: "localGetFileContent";
+    readonly LOCAL_ANALYZE_GRAPH: "localAnalyzeGraph";
+    readonly LSP_GET_SEMANTIC_CONTENT: "lspGetSemantics";
+    readonly GITHUB_SEARCH_HISTORY: "ghSearchHistory";
+    readonly GITHUB_GET_HISTORY_ITEM: "ghGetHistoryItem";
+};

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

@@ -1,5 +1,5 @@
-import type { CompleteMetadata } from '@octocodeai/octocode-core/types';
-export declare function loadToolContent(): Promise<CompleteMetadata>;
+import type { LocalCompleteMetadata } from '../../toolContract/types.js';
+export declare function loadToolContent(): Promise<LocalCompleteMetadata>;
 export declare function initializeToolMetadata(): Promise<void>;
-export declare function getMetadataOrNull(): CompleteMetadata | null;
+export declare function getMetadataOrNull(): LocalCompleteMetadata | null;
 export declare function _resetMetadataState(): void;

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

@@ -1,2 +1,2 @@
-import type { ToolNames } from '@octocodeai/octocode-core/types';
+import type { ToolNames } from '../../toolContract/input/types/index.js';
 export type ToolName = ToolNames[keyof ToolNames];

package/dist/tools/toolNames.d.ts

@@ -1,5 +1,18 @@
-export declare const STATIC_TOOL_NAMES: import("@octocodeai/octocode-core/types").ToolNames;
+export declare const LOCAL_ANALYZE_GRAPH_TOOL_NAME: "localAnalyzeGraph";
+export declare const LOCAL_SEARCH_TOOL_NAME = "localSearch";
+export declare const GITHUB_SEARCH_TOOL_NAME: "ghSearch";
+export declare const GITHUB_SEARCH_HISTORY_TOOL_NAME = "ghSearchHistory";
+export declare const GITHUB_GET_HISTORY_ITEM_TOOL_NAME = "ghGetHistoryItem";
+export declare const STATIC_TOOL_NAMES: {
+    readonly GITHUB_SEARCH: "ghSearch";
+    readonly GITHUB_FETCH_CONTENT: "ghGetFileContent";
+    readonly PACKAGE_SEARCH: "npmSearch";
+    readonly GITHUB_CLONE_REPO: "ghCloneRepo";
+    readonly LOCAL_FETCH_CONTENT: "localGetFileContent";
+    readonly LOCAL_ANALYZE_GRAPH: "localAnalyzeGraph";
+    readonly LSP_GET_SEMANTIC_CONTENT: "lspGetSemantics";
+    readonly GITHUB_SEARCH_HISTORY: "ghSearchHistory";
+    readonly GITHUB_GET_HISTORY_ITEM: "ghGetHistoryItem";
+};
 export declare const LSP_GET_SEMANTICS_TOOL_NAME: "lspGetSemantics";
-export declare function isReleasesEnabled(env?: NodeJS.ProcessEnv): boolean;
-export declare function isDiscussionsEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function isLocalTool(toolName: string): boolean;

package/dist/tools/toolSchemaImports.d.ts

@@ -1,15 +1,16 @@
 export { CloneRepoQueryLocalSchema, BulkCloneRepoLocalSchema, } from './github_clone_repo/scheme.js';
 export { FileContentQueryLocalSchema, FileContentBulkQueryLocalSchema, } from './github_fetch_content/scheme.js';
+export { GitHubSearchQuerySchema, GitHubSearchBulkQuerySchema, } from './github_search/scheme.js';
 export { GitHubCodeSearchQueryLocalSchema, GitHubCodeSearchBulkQueryLocalSchema, } from './github_search_code/scheme.js';
 export { GitHubPullRequestSearchQueryLocalSchema, GitHubPullRequestSearchBulkQueryLocalSchema, } from './github_search_pull_requests/scheme.js';
-export { SearchPullRequestsLocalSchema, SearchPullRequestsBulkLocalSchema, SearchIssuesLocalSchema, SearchIssuesBulkLocalSchema, SearchCommitsLocalSchema, SearchCommitsBulkLocalSchema, ListReleasesLocalSchema, ListReleasesBulkLocalSchema, } from './github_search_pull_requests/splitSchemes.js';
-export { SearchDiscussionsLocalSchema, SearchDiscussionsBulkLocalSchema, } from './github_search_discussions/scheme.js';
+export { GitHubSearchHistoryQueryLocalSchema, GitHubSearchHistoryBulkQueryLocalSchema, GitHubGetHistoryItemQueryLocalSchema, GitHubGetHistoryItemBulkQueryLocalSchema, } from './github_search_pull_requests/historySchemes.js';
 export { GitHubReposSearchSingleQueryLocalSchema, GitHubReposSearchBulkQueryLocalSchema, } from './github_search_repos/scheme.js';
 export { GitHubViewRepoStructureQueryLocalSchema, GitHubViewRepoStructureBulkQueryLocalSchema, } from './github_view_repo_structure/scheme.js';
 export { NpmSearchQueryLocalSchema, NpmSearchBulkQueryLocalSchema, } from './package_search/scheme.js';
 export { LocalFetchContentQuerySchema, LocalFetchContentBulkQuerySchema, } from './local_fetch_content/scheme.js';
 export { LocalFindFilesQuerySchema, LocalFindFilesBulkQuerySchema, } from './local_find_files/scheme.js';
-export { LocalFindDeadCodeQuerySchema, LocalFindDeadCodeBulkQuerySchema, } from './local_dead_code/scheme.js';
+export { LocalAnalyzeGraphQuerySchema, LocalAnalyzeGraphBulkQuerySchema, } from './local_analyze_graph/scheme.js';
 export { LocalRipgrepQuerySchema, LocalRipgrepBulkQuerySchema, } from './local_ripgrep/scheme.js';
 export { LocalViewStructureQuerySchema, LocalViewStructureBulkQuerySchema, } from './local_view_structure/scheme.js';
-export { BulkLspGetSemanticsQuerySchema, LspGetSemanticsQueryDisplaySchema, } from './lsp/semantic_content/scheme.js';
+export { LocalSearchQuerySchema, LocalSearchBulkQuerySchema, } from './local_search/scheme.js';
+export { BulkLspGetSemanticsQuerySchema, LspGetSemanticsQuerySchema, } from './lsp/semantic_content/scheme.js';

package/dist/tools/utils.d.ts

@@ -7,17 +7,14 @@ interface SuccessResultOptions {
     rawResponse?: unknown;
 }
 export declare function createSuccessResult<T extends object>(_query: {
-    mainResearchGoal?: string;
-    researchGoal?: string;
+    goal?: string;
     reasoning?: string;
 }, data: T, hasContent: boolean, _toolName: string, options?: SuccessResultOptions): ToolSuccessResult & T;
 export declare function handleProviderError(apiResult: ProviderResponse<unknown>, query: {
-    mainResearchGoal?: string;
-    researchGoal?: string;
+    goal?: string;
     reasoning?: string;
 }): ToolErrorResult;
 export declare function handleCatchError(error: unknown, query: {
-    mainResearchGoal?: string;
-    researchGoal?: string;
+    goal?: string;
     reasoning?: string;
 }, contextMessage?: string, toolName?: string): ToolErrorResult;

package/dist/types/bulk.d.ts

@@ -6,7 +6,12 @@ export interface BulkFinalizerInput<TQuery, TOutput extends Record<string, unkno
 }
 export interface BulkFinalizerOutput<TOutput extends Record<string, unknown> = Record<string, unknown>> {
     structuredContent: TOutput;
-    text: string;
+    /** Rendering priority only. Text is derived once from finalized structured
+     * content so MCP and CLI cannot observe different semantic states. */
+    keysPriority?: readonly string[];
+    /** Optional presentation for copy-sensitive payloads. It receives the final,
+     * reconciled structured value and therefore cannot render stale metadata. */
+    renderText?: (structuredContent: Record<string, unknown>) => string;
     isError?: boolean;
 }
 export type BulkFinalizer<TQuery, TOutput extends Record<string, unknown> = Record<string, unknown>> = (input: BulkFinalizerInput<TQuery, TOutput>) => BulkFinalizerOutput<TOutput>;
@@ -15,6 +20,7 @@ export interface BulkResponsePagination {
     responseCharLength?: number;
 }
 export interface ResponsePaginationInfo {
+    scope: 'content.text';
     currentPage: number;
     totalPages: number;
     hasMore: boolean;
@@ -22,6 +28,10 @@ export interface ResponsePaginationInfo {
     charLength: number;
     totalChars: number;
     nextCharOffset?: number;
+    next?: {
+        tool: string;
+        query: Record<string, unknown>;
+    };
 }
 export interface BulkResponseConfig<TQuery = object, TOutput extends Record<string, unknown> = Record<string, unknown>> {
     toolName: string;

package/dist/types/execution.d.ts

@@ -1,5 +1,10 @@
-import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import type { AuthInfo } from '@modelcontextprotocol/server';
 export type WithOptionalMeta<T> = Partial<T>;
+export interface BaseQueryLocal {
+    goal?: string;
+    reasoning?: string;
+    path?: string;
+}
 export interface ToolExecutionArgs<TQuery> {
     queries: TQuery[];
     responseCharOffset?: number;

package/dist/types/server.d.ts

@@ -3,12 +3,10 @@ export interface ServerConfig {
     version: string;
     githubApiUrl: string;
     toolsToRun?: string[];
-    enableTools?: string[];
     disableTools?: string[];
     timeout: number;
     maxRetries: number;
     enableLocal: boolean;
     enableClone: boolean;
-    outputFormat: 'yaml' | 'json';
     tokenSource: TokenSourceType;
 }

package/dist/types/toolOutput.d.ts

@@ -1,18 +1,17 @@
 /**
  * Hand-written output TYPES for the direct tools.
  *
- * The per-tool zod OUTPUT schemas were removed: the MCP server registers no
- * outputSchema (see octocode-mcp registerBasicTool), so they validated nothing
- * at runtime, duplicated the tool result shapes, and forced every output-shape
- * change to be made in twelve places. Tools keep a plain TypeScript output
- * type instead — one shared envelope generic plus a per-tool `data` interface.
+ * Tools keep one shared TypeScript envelope generic plus a per-tool `data`
+ * interface. MCP advertises the matching broad runtime contract sourced from
+ * @octocodeai/octocode-core, avoiding per-interface schema duplication.
  *
  * INPUT/query schemas are unaffected: those are registered and parsed, so they
  * stay as zod.
  */
-import type { ToolContinuation } from '../scheme/pagination.js';
+import type { ToolResultMeta } from './toolResults.js';
 /** Outermost char-window pagination wrapping a whole bulk response. */
 export interface ResponsePaginationInfo {
+    scope: 'content.text';
     currentPage: number;
     totalPages: number;
     hasMore: boolean;
@@ -23,10 +22,13 @@ export interface ResponsePaginationInfo {
 }
 /** One result row in a bulk tool response. */
 export interface BulkToolResultRow<TData> {
-    id: string;
+    /** Zero-based position of the originating query in the submitted batch. */
+    index: number;
     status?: 'empty' | 'error';
+    /** Present only when the primary response payload was served from cache. */
+    cache?: 1;
+    meta?: ToolResultMeta;
     data: TData;
-    next?: Record<string, ToolContinuation>;
 }
 /** The shared bulk envelope every direct tool returns, parameterized by its per-query `data` payload. */
 export interface BulkToolOutput<TData> {
@@ -34,5 +36,4 @@ export interface BulkToolOutput<TData> {
     base?: string;
     shared?: Record<string, string | number | boolean>;
     responsePagination?: ResponsePaginationInfo;
-    next?: Record<string, ToolContinuation>;
 }

package/dist/types/toolResults.d.ts

@@ -45,10 +45,26 @@ export interface ProcessedBulkResult {
     [key: string]: unknown;
 }
 export interface FlatQueryResult {
-    id: string;
+    /** Zero-based position of the originating query in the submitted batch. */
+    index: number;
+    /** Present only when this query's response was served from cache. */
+    cache?: 1;
     status?: QueryStatus;
+    meta: ToolResultMeta;
     data: Record<string, unknown>;
 }
+export type EvidenceKind = 'exact' | 'lexical' | 'structural' | 'syntactic' | 'semantic' | 'provider';
+export interface ToolResultMeta {
+    evidence: {
+        kind: EvidenceKind;
+        confidence: 'high' | 'medium' | 'low';
+    };
+    diagnostics?: {
+        codes?: string[];
+        hints?: string[];
+        partial?: boolean;
+    };
+}
 export interface QueryError {
     queryIndex: number;
     error: string;

package/dist/utils/contextUtils.d.ts

@@ -1,5 +1,5 @@
 import type * as NativeContextUtils from '@octocodeai/octocode-engine';
-export type { ExtractMatchingLinesOptions, ExtractMatchingLinesResult, FilterPatchOptions, FileSystemEntry, FileSystemQueryOptions, FileSystemQueryResult, GraphFactCapability, GraphFactCall, GraphFactDeclaration, GraphFactEdge, GraphFactExport, GraphFactImport, GraphFacts, LineDiffOp, MinifyResult, JsonInput, RipgrepParseOptions, RipgrepParseResult, RipgrepSearchOptions, SliceContentOptions, SliceContentResult, StructuralMatch, YamlConversionConfig, } from '@octocodeai/octocode-engine';
+export type { ExtractMatchingLinesOptions, ExtractMatchingLinesResult, FilterPatchOptions, FileSystemEntry, FileSystemQueryOptions, FileSystemQueryResult, GraphFactCapability, GraphFactCall, GraphFactDeclaration, GraphFactEdge, GraphFactExport, GraphFactImport, GraphFacts, GraphFactsScanEntry, GraphFactsScanOptions, GraphFactsScanResult, GraphReferenceCount, LineDiffOp, 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 {
@@ -33,6 +33,8 @@ export declare const contextUtils: {
      * declarations/imports/exports, containment, and direct call expressions.
      */
     extractGraphFacts(content: string, filePath: string): string | null;
+    /** Walk, read, and extract graph facts on the native worker pool in one call. */
+    scanGraphFacts(options: NativeContextUtils.GraphFactsScanOptions): Promise<NativeContextUtils.GraphFactsScanResult>;
     /**
      * 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.
@@ -61,7 +63,7 @@ export declare const contextUtils: {
     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;
+    queryFileSystem(options: NativeContextUtils.FileSystemQueryOptions): Promise<NativeContextUtils.FileSystemQueryResult>;
     extractMatchingLines(content: string, pattern: string, options?: NativeContextUtils.ExtractMatchingLinesOptions | null): NativeContextUtils.ExtractMatchingLinesResult;
     filterPatch(patch: string, options?: NativeContextUtils.FilterPatchOptions | null): string;
     computeLineDiff(oldText: string, newText: string): NativeContextUtils.LineDiffOp[];

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

@@ -1,4 +1,4 @@
-import type { BaseQueryLocal } from '@octocodeai/octocode-core/extra-types';
+import type { BaseQueryLocal } from '../../types/execution.js';
 type PartialBaseQueryLocal = Partial<BaseQueryLocal>;
 import { createErrorResult, type UnifiedErrorResult } from '../response/error.js';
 type LocalErrorResult = UnifiedErrorResult;

package/dist/utils/http/cache/conditional.d.ts

@@ -1,4 +1,5 @@
 import NodeCache from 'node-cache';
+import { type CacheRole } from './trace.js';
 /**
  * Soft ETag store: survives primary TTL so a miss can send If-None-Match and
  * recover a 304 without paying a full body download (GitHub authorized 304s
@@ -11,11 +12,15 @@ export type ConditionalFetchResult<T> = {
     /** True when the upstream responded 304 Not Modified. */
     notModified?: boolean;
 };
-export declare function withDataCacheConditional<T>(cacheKey: string, operation: (opts: {
-    ifNoneMatch?: string;
-}) => Promise<ConditionalFetchResult<T>>, options?: {
+interface ConditionalCacheOptions<T> {
     ttl?: number;
     skipCache?: boolean;
     forceRefresh?: boolean;
     shouldCache?: (value: T) => boolean;
-}): Promise<T>;
+    /** Whether a hit supplies the tool response or only supporting metadata. */
+    cacheRole?: CacheRole;
+}
+export declare function withDataCacheConditional<T>(cacheKey: string, operation: (opts: {
+    ifNoneMatch?: string;
+}) => Promise<ConditionalFetchResult<T>>, options?: ConditionalCacheOptions<T>): Promise<T>;
+export {};

package/dist/utils/http/cache/dataCache.d.ts

@@ -1,6 +1,11 @@
-export declare function withDataCache<T>(cacheKey: string, operation: () => Promise<T>, options?: {
+import { type CacheRole } from './trace.js';
+interface DataCacheOptions<T> {
     ttl?: number;
     skipCache?: boolean;
     forceRefresh?: boolean;
     shouldCache?: (value: T) => boolean;
-}): Promise<T>;
+    /** Whether a hit supplies the tool response or only supporting metadata. */
+    cacheRole?: CacheRole;
+}
+export declare function withDataCache<T>(cacheKey: string, operation: () => Promise<T>, options?: DataCacheOptions<T>): Promise<T>;
+export {};

package/dist/utils/http/cache/diskStore.d.ts

@@ -0,0 +1,30 @@
+export interface DiskCacheRead<T> {
+    value: T;
+    etag?: string;
+    state: 'fresh' | 'stale';
+    expiresAt: number;
+}
+declare const diskStats: {
+    hits: number;
+    misses: number;
+    sets: number;
+    errors: number;
+    evictions: number;
+};
+export declare function isDiskCacheEnabled(): boolean;
+export declare function getDiskCacheRoot(octocodeHome?: string): string;
+export declare function getDiskCacheEntryPath(key: string, octocodeHome?: string): string;
+export declare function readDiskCache<T>(key: string, options?: {
+    allowStale?: boolean;
+}): Promise<DiskCacheRead<T> | undefined>;
+export declare function writeDiskCache<T>(key: string, value: T, ttlSeconds: number, options?: {
+    etag?: string;
+    staleTtlSeconds?: number;
+}): Promise<boolean>;
+export declare function sweepDiskCacheIfDue(octocodeHome?: string, now?: number): Promise<number>;
+/** Full response-cache sweep for the already due-gated shared lifecycle. */
+export declare function sweepDiskCacheNow(octocodeHome?: string, now?: number): Promise<number>;
+export declare function clearDiskCache(octocodeHome?: string): Promise<void>;
+export declare function getDiskCacheStats(): Readonly<typeof diskStats>;
+export declare function resetDiskCacheStats(): void;
+export {};

package/dist/utils/http/cache/management.d.ts

@@ -6,4 +6,9 @@ export declare function clearRemoteAPICache(): number;
 export declare function getCacheStats(): CacheStats & {
     hitRate: number;
     cacheSize: number;
+    diskHits: number;
+    diskMisses: number;
+    diskSets: number;
+    diskErrors: number;
+    diskEvictions: number;
 };

package/dist/utils/http/cache/store.d.ts

@@ -19,6 +19,7 @@ export declare const CACHE_TTL_CONFIG: {
 export interface PendingRequest {
     promise: Promise<unknown>;
     startedAt: number;
+    requestId: symbol;
 }
 export declare const pendingRequests: Map<string, PendingRequest>;
 export declare function extractCachePrefix(cacheKey: string): string | undefined;

package/dist/utils/http/cache/trace.d.ts

@@ -0,0 +1,10 @@
+export type CacheRole = 'response' | 'helper';
+/** Trace cache activity for one independently processed bulk query. */
+export declare function traceResponseCache<T>(operation: () => Promise<T>): Promise<{
+    value: T;
+    cacheHit: boolean;
+}>;
+/** Preserve cache nesting so helper-cache hits do not label a fresh response. */
+export declare function runCacheLayer<T>(operation: () => Promise<T>, role?: CacheRole): Promise<T>;
+/** Mark a direct hit or a query's outermost cache layer as its response source. */
+export declare function markResponseCacheHit(): void;

package/dist/utils/http/cache.d.ts

@@ -2,3 +2,4 @@ export * from './cache/key.js';
 export * from './cache/dataCache.js';
 export * from './cache/conditional.js';
 export * from './cache/management.js';
+export * from './cache/diskStore.js';

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

@@ -2,8 +2,7 @@ export interface NpmSearchInput {
     name: string;
     itemsPerPage?: number;
     page?: number;
-    mainResearchGoal?: string;
-    researchGoal?: string;
+    goal?: string;
     reasoning?: string;
 }
 export interface MinimalPackageResult {
@@ -24,7 +23,11 @@ export interface NpmPackageResult {
     typeDefinitions?: string | null;
     packageType?: 'module' | 'commonjs' | 'types-only' | 'unknown';
     exports?: string[];
+    exportsTotal?: number;
+    exportsTruncated?: true;
     bin?: string[];
+    binTotal?: number;
+    binTruncated?: true;
     repositoryDirectory?: string;
     lastPublished?: string;
     owner?: string;

package/dist/utils/pagination/charLimit.d.ts

@@ -1,3 +1 @@
 export declare function getOutputCharLimit(): number;
-export declare const MAX_DEFAULT_OUTPUT_CHAR_LENGTH = 100000;
-export declare function getBulkDefaultCharLength(queryCount: number): number;

package/dist/utils/response/bulk/pagination.d.ts

@@ -3,4 +3,5 @@ export declare function paginateBulkText(text: string, pagination?: BulkResponse
     text: string;
     pagination?: NonNullable<BulkToolResponse['responsePagination']>;
 };
-export declare function appendResponsePagination<T extends Record<string, unknown>>(structuredContent: T, pagination?: NonNullable<BulkToolResponse['responsePagination']>): T;
+export declare function appendResponsePagination<T extends Record<string, unknown>>(structuredContent: T, pagination?: NonNullable<BulkToolResponse['responsePagination']>, next?: NonNullable<BulkToolResponse['responsePagination']>['next']): T;
+export declare function buildResponsePaginationContinuation(toolName: string, queries: object[], request: BulkResponsePagination | undefined, pagination: NonNullable<BulkToolResponse['responsePagination']> | undefined): NonNullable<BulkToolResponse['responsePagination']>['next'] | undefined;

package/dist/utils/response/bulk/paginationDiagnostics.d.ts

@@ -0,0 +1,2 @@
+export declare function isPartialResult(data: Record<string, unknown>): boolean;
+export declare function buildPaginationDiagnosticCodes(data: Record<string, unknown>): string[];

package/dist/utils/response/bulk/queries.d.ts

@@ -8,12 +8,3 @@ export declare function processBulkQueries<TQuery extends object>(queries: Array
     }>;
     errors: QueryError[];
 }>;
-export declare function resolveQueryId<TQuery extends object>(originalQuery: TQuery, queryIndex: number): string;
-/**
- * Resolve one id per query, guaranteed unique within the batch. Everything
- * downstream (finalizer grouping, per-query pagination maps) keys off these
- * ids, so two queries submitted with the same explicit `id` would otherwise
- * silently merge and the second query's pagination would overwrite the first.
- * Collisions get a `#2`, `#3`… suffix in submission order.
- */
-export declare function resolveUniqueQueryIds<TQuery extends object>(queries: readonly TQuery[]): string[];

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

@@ -1,4 +1,5 @@
-import { CallToolResult } from '@modelcontextprotocol/sdk/types';
-import type { ProcessedBulkResult } from '../../../types/toolResults.js';
+import { CallToolResult } from '@modelcontextprotocol/server';
+import type { ProcessedBulkResult, FlatQueryResult } from '../../../types/toolResults.js';
 import type { BulkResponseConfig, BulkResponsePagination } from '../../../types/bulk.js';
 export declare function executeBulkOperation<TQuery extends object, TOutput extends Record<string, unknown> = Record<string, unknown>>(queries: Array<TQuery>, processor: (query: TQuery, index: number) => Promise<ProcessedBulkResult>, config: BulkResponseConfig<TQuery, TOutput>, pagination?: BulkResponsePagination): Promise<CallToolResult>;
+export declare function buildToolResultMeta(toolName: string, query: object, data: Record<string, unknown>, status?: 'empty' | 'error'): FlatQueryResult['meta'];

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

@@ -1,2 +1,2 @@
-export { computeQueryTimeout, resolveQueryId, resolveUniqueQueryIds, } from './bulk/queries.js';
+export { computeQueryTimeout } from './bulk/queries.js';
 export { executeBulkOperation } from './bulk/response.js';

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

@@ -1,3 +1,3 @@
-import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult } from '@modelcontextprotocol/server';
 export declare function sanitizeCallToolResult(result: CallToolResult): CallToolResult;
 export declare function buildToolErrorResult(toolName: string, error: unknown): CallToolResult;