import type { InterpreterContext } from "../interpreter/types.js";
import type { ExecResult, Observation } from "../types.js";
/**
 * AgTrace - Agent Observability Layer
 *
 * Provides rich metadata and suggestions for command failures.
 */
export declare class AgTrace {
    /**
     * Analyze a command execution failure and generate observations.
     *
     * AgTrace is the FALLBACK channel (A3): it regex-scrapes English stderr
     * for failures that the source could not emit a typed observation for
     * (e.g. WASM/external commands). Observations the SOURCE already emitted
     * are passed via `existing` so AgTrace can DEDUP/GATE and avoid producing
     * a duplicate for the same failure. Scraped observations are lower
     * confidence (0.5) than source-emitted ones (1.0).
     */
    static analyze(ctx: InterpreterContext, command: string, args: string[], result: ExecResult, existing?: readonly Observation[]): Promise<Observation[]>;
    /**
     * Combine source-emitted observations with AgTrace's fresh (fallback)
     * observations into a single deduplicated list (A3).
     *
     * Dedup/merge rules, applied immutably (always new objects/arrays):
     *  - A fresh observation that ENRICHES an existing one (same `type` AND same
     *    `path`) is MERGED into it: the existing observation gains the fresh
     *    `suggestions` (unioned) and keeps its higher source `confidence`. This
     *    keeps exactly one observation per failure while preserving the
     *    actionable fix (e.g. a case-insensitive "Correct the casing" hint).
     *  - A fresh observation with no matching existing one is appended.
     *
     * @param existing - Source-emitted (high-confidence) observations.
     * @param fresh - AgTrace fallback observations from {@link AgTrace.analyze}.
     */
    static combineObservations(existing: readonly Observation[], fresh: readonly Observation[]): Observation[];
    /**
     * Analyze a caught error during execution.
     */
    static analyzeError(error: Error): Observation;
    /**
     * Get a command typo suggestion using Levenshtein distance.
     *
     * Public so source emitters (e.g. command-not-found in builtin-dispatch)
     * can attach the same "did you mean" candidate to a typed Observation at
     * the source, instead of relying on AgTrace's stderr regex pass.
     *
     * @param command - The unresolved command name.
     * @param candidates - Candidate command names to match against.
     * @returns The closest match within the typo threshold, or null.
     */
    static suggestCommand(command: string, candidates: readonly string[]): string | null;
    /**
     * Get a command typo suggestion from the interpreter's registered commands.
     */
    private static getCommandSuggestion;
    /**
     * Investigates why a path failed (e.g. parent doesn't exist).
     */
    private static analyzePathFailure;
    /**
     * Damerau-Levenshtein distance (simple version)
     */
    private static levenshtein;
}
