/**
 * plan-turn-tools.ts — Query parser + main handler for plan/turn routing.
 *
 * Parser (Task 6):
 *   - Normalisation (lowercase, trim, 1000-char cap)
 *   - Multi-intent split on "and / or / ; / &&" with surrounding whitespace
 *   - File ref extraction (extensions: ts/tsx/js/jsx/py/go/rs/php/kt/sql)
 *   - Symbol ref extraction (cross-referenced against index.symbols)
 *   - Vague detection (short query with no domain keywords)
 *
 * Handler (Task 7) — `planTurn`:
 *   1. Guards against missing index → returns structured error
 *   2. Parses query via parseQuery
 *   3. Checks negative evidence → returns STOP_AND_REPORT_GAP early
 *   4. Builds ranker context (usage freq, framework tools, embeddings)
 *   5. Runs rankTools per intent, merges results
 *   6. Dedups against session.queries (top-3 retained)
 *   7. Collects hidden tool names for reveal_required[]
 *   8. Populates metadata flags (stale_index, framework_mismatch, cold_start…)
 */
import { type ToolRecommendation } from "../search/tool-ranker.js";
import type { CodeIndex } from "../types.js";
export interface ParsedQuery {
    original: string;
    normalized: string;
    truncated: boolean;
    intents: string[];
    file_refs: string[];
    symbol_refs: string[];
    is_vague: boolean;
}
export declare function parseQuery(raw: string, index: CodeIndex): ParsedQuery;
export interface SymbolRecommendation {
    name: string;
    file: string;
    line: number;
    kind: string;
    score: number;
}
export interface FileRecommendation {
    path: string;
    score: number;
    reason: string;
}
export interface GapAnalysis {
    action: "STOP_AND_REPORT_GAP";
    prior_query: string;
    prior_result_count: number;
    suggestion: string;
}
export interface PlanTurnMetadata {
    intents_detected: number;
    bm25_candidates: number;
    embedding_available: boolean;
    session_queries_seen: number;
    duration_ms: number;
    truncated?: boolean;
    vague_query?: boolean;
    stale_index?: boolean;
    low_discrimination?: boolean;
    framework_mismatch?: boolean;
    cold_start?: boolean;
    unindexed?: boolean;
}
export interface PlanTurnResult {
    query: string;
    truncated: boolean;
    confidence: number;
    tools: ToolRecommendation[];
    symbols: SymbolRecommendation[];
    files: FileRecommendation[];
    reveal_required: string[];
    already_used: string[];
    gap_analysis?: GapAnalysis;
    framework_context?: string;
    metadata: PlanTurnMetadata;
}
/** Test-only reset of module caches. */
export declare function _resetPlanTurnCaches(): void;
/**
 * Return the current `git rev-parse HEAD` SHA for `repoRoot`, or `null` if the
 * directory isn't a git checkout / git isn't available / spawn times out.
 *
 * Synchronous + bounded (timeout 1500ms) because `plan_turn` is the front-door
 * routing tool — p99 budget is a few hundred ms. Real-world cost on warm git
 * caches is ~5–15 ms. Failures are silent on purpose; the caller falls back
 * to the time-based stale check.
 */
export declare function safeReadGitHead(repoRoot: string): string | null;
/**
 * Decide whether the in-memory index has drifted from the live repository.
 *
 * Source-of-truth priority:
 *   1. `git rev-parse HEAD` vs registry's `last_git_commit` — definitive when
 *      both are available; flips true iff the HEAD has moved.
 *   2. Time-based fallback (24 h) — only when git is unavailable, so we don't
 *      go fully silent on non-git repos or after `git` spawn failures.
 *
 * Notably we no longer flip true after 5 min of agent idle — that was the
 * historical behavior and produced false positives in read-mostly sessions
 * (audits, plans, explorations) where the index was perfectly in sync.
 */
export declare function isStaleIndex(index: CodeIndex, lastGitCommit: string | undefined): boolean;
export declare function planTurn(repo: string, query: string, options?: {
    max_results?: number;
    skip_session?: boolean;
}): Promise<PlanTurnResult>;
/**
 * Format a PlanTurnResult as a human-readable markdown-style string.
 * Edge-case: if no tools, injects a discover_tools fallback.
 */
export declare function formatPlanTurnResult(result: PlanTurnResult): string;
//# sourceMappingURL=plan-turn-tools.d.ts.map