import type { Driver, DriverStep } from "../drivers/types.js";
import type { ActionTrace, Goal, RecipeStep } from "./types.js";
export interface TracingDriverOptions {
    /** Driver to delegate to — typically `aiDriver` or a `compositeDriver`. */
    inner: Driver;
    /** Goal whose `successCheck` decides when the trace is finalised. */
    goal: Goal;
    /** Fires once when `successCheck` first returns true. */
    onTraceComplete?: (trace: ActionTrace) => Promise<void> | void;
    /**
     * When the AI driver fills a form, the fill *value* is not part of
     * the `ActionResult`. By default we serialise as `"test input"` —
     * the same string the crawler uses — but real form journeys need a
     * caller-provided overrider keyed by selector.
     */
    fillValueFor?: (selector: string, step: DriverStep) => string | undefined;
    /**
     * Per-step screenshot capture. browser-harness doctrine: "after
     * every meaningful action, re-screenshot before assuming it worked."
     * Enable for AI-driver runs where downstream `investigate()` will
     * need visual context to diagnose recipe drift.
     *
     * Paths are absolute. The caller owns disk hygiene (rotating /
     * deleting old runs) — we never clean up automatically.
     */
    screenshots?: {
        /** Output directory. Created if missing. */
        dir: string;
        /** "viewport" (default) or "fullPage". */
        mode?: "viewport" | "fullPage";
        /**
         * Filename strategy. Default: `step-${index}-${kind}.png`.
         * Override when you need a stable, run-scoped naming convention.
         */
        filenameFor?: (stepIndex: number, kind: RecipeStep["kind"]) => string;
    };
}
export interface TracingDriver extends Driver {
    /** Snapshot of the trace as currently accumulated. */
    getTrace(): ActionTrace;
    /** Reset between iterations so the same wrapper can be reused. */
    reset(): void;
}
export declare function tracingDriver(opts: TracingDriverOptions): TracingDriver;
//# sourceMappingURL=tracing-driver.d.ts.map