Class ToolHandler

src/mcp/tools.ts:1908–8566

 * Other projects are opened on-demand and cached for performance.
 */
export class ToolHandler {
  // Cache of opened CodeGraph instances for cross-project queries, keyed by the
  // CANONICAL (realpath) index root. Map insertion order doubles as LRU order:
  // a hit re-inserts, and `MAX_CACHED_PROJECTS` bounds the size (#1835).
  private projectCache: Map<string, CodeGraph> = new Map();
  // When each cached root was last handed to a call, and the one timer that
  // releases the oldest once it has been idle long enough (#2087).
  private projectUsedAt: Map<string, number> = new Map();
  private idleReleaseTimer: NodeJS.Timeout | null = null;
  // Engine hook that watches + catches up an explicit project (null for the
  // CLI and worker-thread handlers, which never own a watcher).
  private projectLifecycle: ProjectLifecycle | null = null;
  // Every concurrent call shares its project's pending catch-up promise.
  private projectGates: Map<CodeGraph, Promise<void>> = new Map();
  private activeCalls = 0;
  private closing = false;
  private pendingCloses = 0;
  private closeWaiters: Array<() => void> = [];
  // The directory the server last searched for a default project. Surfaced in
  // the "not initialized" error so users can see why detection missed.
  private defaultProjectHint: string | null = null;
  // Indexed sub-projects the engine's bounded down-scan saw below the search
  // base when no default project resolved (#1607). Listed in the "not
  // initialized" error so the fact is reachable through the protocol, not just
  // the host's stderr capture. Engine-maintained (initial resolve + throttled
  // retry) — tool calls themselves never scan.
  private knownSubprojects: string[] = [];
  private knownSubprojectsBase: string | null = null;
  // Why the default project failed to open, when that is worth telling the
  // agent instead of "no project loaded" — today only the Windows/WSL
  // shared-index error (#995). Engine-maintained; cleared by a successful open.
  private defaultOpenFailure: WslSharedIndexError | null = null;
  // Per-start-path cache of the git worktree/index mismatch (issue #155). The
  // mismatch is a fixed property of (where the request came from → which
  // .codegraph/ it resolves to), so the up-to-two `git rev-parse` spawns run
  // once and every later tool call reuses the result — never shelling out to
  // git on the hot path. `undefined` = not computed yet; `null` = no mismatch.
  private worktreeMismatchCache: Map<string, WorktreeIndexMismatch | null> = new Map();
  // Per-(projectPath, index root) cache of the different git repository the
  // path sits in below that root, if any (#2110) — the git half of
  // `uncoveredNestedRepo`, memoized like the mismatch above.
  private nestedRepoCache: Map<string, NestedRepository | null> = new Map();
  // Gate that the MCP engine pokes after `cg.open()` so the first tool call
  // blocks on the post-open filesystem reconcile (catch-up sync). Without
  // this, a tool call that races past `catchUpSync()` serves rows for files
  // that were deleted (or edited) while no MCP server was running — and the
  // per-file staleness banner can't help, because `getPendingFiles()` is
  // populated by the watcher, not by catch-up. The wait is time-boxed
  // (see {@link resolveCatchUpGateTimeoutMs}) so a minutes-long reconcile on a
  // huge repo can't hang a call (#905); cleared when the reconcile settles.
  private catchUpGate: Promise<void> | null = null;
  // Engine hook fired when `freshen` reopened a replaced database (#1902), so
  // the engine can reconcile the new file with a catch-up sync.
  private onDatabaseReopened: ((cg: CodeGraph) => void) | null = null;
  // Optional worker-thread pool for off-loop read-tool dispatch. When ready +
  // healthy, heavy reads leave the main loop free for the MCP transport.
  private queryPool: QueryPool | null = null;