/**
 * VCR — Record and replay LLM/agent interactions for testing
 *
 * Provides a VCR (Video Cassette Recorder) pattern for capturing
 * agent execution calls and replaying them deterministically in tests.
 *
 * Modes:
 *   - `record` — Intercepts calls, forwards to real handler, saves cassette
 *   - `replay` — Matches calls to recorded cassettes, returns saved results
 *   - `passthrough` — Disabled, all calls go to real handler
 *
 * Features:
 *   - Cassettes stored as JSON files
 *   - Request matching by agent ID + action + params hash
 *   - Configurable matching strictness
 *   - Call ordering enforcement (optional)
 *   - Missing cassette detection with helpful errors
 *
 * Usage:
 *   const vcr = new AgentVCR({ mode: 'record', cassettePath: './fixtures' });
 *   const result = await vcr.execute('agent-1', payload, realHandler);
 *   await vcr.save('my-test'); // Saves cassette to ./fixtures/my-test.json
 *
 *   // Later in tests:
 *   const vcr2 = new AgentVCR({ mode: 'replay', cassettePath: './fixtures' });
 *   await vcr2.load('my-test');
 *   const result2 = await vcr2.execute('agent-1', payload); // Returns recorded result
 *
 * @module AgentVCR
 * @version 1.0.0
 */
/** VCR operating mode */
export type VCRMode = 'record' | 'replay' | 'passthrough';
/** A single recorded interaction */
export interface VCRInteraction {
    /** Request fingerprint for matching */
    fingerprint: string;
    /** Agent ID */
    agentId: string;
    /** Action/instruction */
    action: string;
    /** Params hash (for matching) */
    paramsHash: string;
    /** Full request payload (for debugging) */
    request: Record<string, unknown>;
    /** Recorded response */
    response: Record<string, unknown>;
    /** When this was recorded */
    recordedAt: number;
    /** Execution duration in ms */
    durationMs: number;
}
/** A cassette file — collection of recorded interactions */
export interface VCRCassette {
    /** Cassette name */
    name: string;
    /** When the cassette was created */
    createdAt: number;
    /** Recorded interactions */
    interactions: VCRInteraction[];
    /** Metadata */
    metadata?: Record<string, unknown>;
}
/** VCR configuration */
export interface VCRConfig {
    /** Operating mode */
    mode: VCRMode;
    /** Directory for cassette files */
    cassettePath: string;
    /** Match strictness: 'exact' matches full params, 'fuzzy' matches agent+action only */
    matchMode?: 'exact' | 'fuzzy';
    /** Whether to enforce call ordering in replay (default: false) */
    ordered?: boolean;
    /** Whether to throw on missing cassette in replay (default: true) */
    throwOnMissing?: boolean;
}
/** Real execution handler — wraps the actual agent call */
export type VCRHandler = (agentId: string, payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
/** Match result for debugging */
export interface VCRMatchResult {
    matched: boolean;
    fingerprint: string;
    candidates: number;
    bestMatch?: VCRInteraction;
}
/**
 * Agent VCR — Record and replay agent execution calls.
 *
 * In `record` mode, calls are forwarded to the real handler and saved.
 * In `replay` mode, calls are matched to saved cassettes.
 */
export declare class AgentVCR {
    private cassette;
    private replayIndex;
    private readonly config;
    constructor(config: VCRConfig);
    /** Get current mode */
    get mode(): VCRMode;
    /** Set mode at runtime */
    setMode(mode: VCRMode): void;
    /**
     * Execute an agent call through the VCR.
     *
     * @param agentId - The agent to call
     * @param payload - The request payload
     * @param handler - Real handler (required in record/passthrough mode)
     */
    execute(agentId: string, payload: Record<string, unknown>, handler?: VCRHandler): Promise<Record<string, unknown>>;
    /**
     * Load a cassette from disk.
     */
    load(name: string): Promise<VCRCassette>;
    /**
     * Save the current recording as a named cassette.
     */
    save(name: string): Promise<void>;
    /** Get the current cassette */
    getCassette(): VCRCassette | null;
    /** Reset the VCR (clear cassette and replay index) */
    reset(): void;
    /** Get number of recorded interactions */
    get interactionCount(): number;
    /**
     * Try to match a request to a recorded interaction.
     * Useful for debugging match failures.
     */
    findMatch(agentId: string, payload: Record<string, unknown>): VCRMatchResult;
    private recordExecution;
    private replayExecution;
    private computeFingerprint;
    private hashParams;
}
//# sourceMappingURL=agent-vcr.d.ts.map