Method handleExplore

src/mcp/tools.ts:3254–5980

* Handle codegraph_explore — deep exploration in a single call * * Strategy: find relevant symbols via graph traversal, group by file, * then read contiguous file sections covering all symbols per file. * This replaces multiple codegraph_node + Read calls. * * Output size is adapti

(args: Record<string, unknown>)

   * tax on small projects while earning its keep on large ones.
   */
  private async handleExplore(args: Record<string, unknown>): Promise<ToolResult> {
    const rawQuery = this.validateString(args.query, 'query');
    if (typeof rawQuery !== 'string') return rawQuery;
    // One normalization point so the flow-builder, relevance search, and
    // ranking all see the same canonical spelling (Erlang `mod:fn/arity`).
    const query = normalizeQuerySpelling(rawQuery);

    const cg = this.getCodeGraph(args.projectPath as string | undefined);
    const projectRoot = cg.getProjectRoot();

    // Resolve adaptive output budget from project size. Falls back to the
    // largest-tier defaults if stats aren't available, which preserves
    // pre-#185 behavior for callers that hit the rare stats failure.
    let budget: ExploreOutputBudget;
    let indexedFileCount = -1;
    try {
      indexedFileCount = cg.getStats().fileCount;
      budget = getExploreOutputBudget(indexedFileCount);
    } catch {
      budget = getExploreOutputBudget(Infinity);
    }
    const maxFiles = clamp((args.maxFiles as number) || budget.defaultMaxFiles, 1, 20);

    // File paths named in the query become PINNED files: guaranteed admission,
    // top of the rank order, funded first — and their span is REMOVED from the
    // matching query. Runs on the RAW query (normalizeQuerySpelling strips
    // `/digits` tails, which would mangle numeric path segments). Without this,
    // a SvelteKit path like `runs/[runId]/+page.svelte` was shredded by the
    // seeding tokenizer (splits on brackets → `runId` seeded as a "named
    // symbol") and by FTS (`page`/`runs` fragments admitted every sibling
    // `+page.svelte`), starving the very files the agent asked for.
    let pinnedFiles: string[] = [];
    let unresolvedPathSpans: string[] = [];
    let matchQuery = query;
    if (queryMightContainPaths(rawQuery)) {
      try {
        const extraction = extractQueryPaths(
          rawQuery,
          cg.getFiles().map((f) => f.path),
          { maxPins: maxFiles },
        );
        if (extraction.pinnedFiles.length > 0 || extraction.unresolvedPathSpans.length > 0) {
          pinnedFiles = extraction.pinnedFiles;
          unresolvedPathSpans = extraction.unresolvedPathSpans;
          matchQuery = normalizeQuerySpelling(extraction.strippedQuery);
        }
      } catch { /* path pinning must never fail an explore call */ }
    }
    const pinnedSet = new Set(pinnedFiles);
    const pinnedOrder = new Map(pinnedFiles.map((p, i) => [p, i]));

    // Per-file allocation diagnostic (CG-4). `null` unless CODEGRAPH_EXPLORE_DEBUG
    // is set — every `diag?.` below is then a no-op and the response is
    // byte-identical. It only OBSERVES: it must never feed back into rendering.
    const diag = ExploreDiagnostics.start(query, projectRoot, budget, maxFiles, indexedFileCount);

    // What this session has already been served for THIS project (CG-17), and
    // whether this call may act on it (CG-18). Dedup is off on the session's