/** A `MockAi` — the optional injected interface `makeTestContext` accepts.
 *  Structurally compatible with `@voltro/testing`'s `MockAi` (no hard dep
 *  in either direction). */
export declare interface MockAi {
    readonly generate?: (...args: ReadonlyArray<unknown>) => unknown;
    readonly generateObject?: (...args: ReadonlyArray<unknown>) => unknown;
    /** Recorded model calls (prompt + tool names), for assertions. */
    readonly calls: ReadonlyArray<{
        readonly prompt: unknown;
        readonly tools: ReadonlyArray<string>;
    }>;
    /** Restore the previous provider override. */
    reset(): void;
}

/**
 * Build a `MockAi` value AND install the provider override, so
 * `makeTestContext({ ai: mockAi({...}) })` covers both the injected `ctx.ai`
 * path and the free-function (`generateText`/`streamText`) path.
 */
export declare const mockAi: (fixture?: MockAiFixture) => MockAi;

/** The fixture shape `useMockAi` / `mockAi` accept. Every field is optional;
 *  supply only what the test under exercise needs. */
export declare interface MockAiFixture {
    /** Canned `generateText` / `ctx.ai.generate` output. */
    readonly generate?: {
        readonly text: string;
    };
    /** Canned `generateObject` / `ctx.ai.generateObject` output. */
    readonly generateObject?: {
        readonly object: unknown;
    };
    /** `streamText` word/chunk sequence (drives token deltas + the free
     *  `generateText` mock text on the first turn). */
    readonly stream?: ReadonlyArray<string>;
    /** Scripted tool-call → text turns for the SDK tool loop. Each turn is one
     *  `doStream`/`doGenerate` call. Takes precedence over `stream`. */
    readonly turns?: ReadonlyArray<MockTurn>;
    /** Mock model id reported on the override. Default `'mock'`. */
    readonly model?: string;
}

/** A scripted inline file the mock model emits on a turn (usually an image).
 *  `data` is base64 (a short ascii string works for assertions). */
declare interface MockFile {
    readonly mediaType: string;
    readonly data: string;
}

/** A consumable sequence of model turns, plus a recorder for asserting on
 *  what the model was asked. Each `doGenerate`/`doStream` advances the
 *  cursor by one turn; running past the end repeats the last turn's text
 *  (or empties) so a loop that over-steps doesn't hang. */
declare class MockScript {
    private readonly turns;
    private cursor;
    readonly calls: Array<{
        readonly prompt: unknown;
        readonly tools: ReadonlyArray<string>;
    }>;
    constructor(turns: ReadonlyArray<MockTurn>);
    record(prompt: unknown, tools: ReadonlyArray<string>): void;
    next(): MockTurn;
    reset(): void;
}

/** A scripted citation the mock model emits on a turn (RAG grounding). */
declare interface MockSource {
    readonly sourceType?: 'url' | 'document';
    readonly id?: string;
    readonly url?: string;
    readonly title?: string;
    readonly mediaType?: string;
    readonly filename?: string;
}

/** A scripted tool call the mock model emits on a turn. */
declare interface MockToolCall {
    readonly name: string;
    readonly input: unknown;
}

/** One model turn. A turn can carry text (streamed word-by-word), scripted
 *  tool calls (which trigger the SDK's tool loop), cited sources, inline files,
 *  or an error. A turn with tool calls + no text drives one LLM↔tool
 *  round-trip. */
declare interface MockTurn {
    readonly text?: string;
    /** Reasoning ("thinking") the mock streams before the answer text. */
    readonly reasoning?: string;
    readonly toolCalls?: ReadonlyArray<MockToolCall>;
    readonly sources?: ReadonlyArray<MockSource>;
    readonly files?: ReadonlyArray<MockFile>;
    readonly error?: {
        readonly message: string;
    };
}

/**
 * A test helper: a function that throws the first `n` times it's called, then
 * returns `value`. For exercising retry paths (`Effect.retry`, the SDK's
 * tool-output retry) deterministically.
 *
 * ```ts
 * const flaky = throwNTimes(2, 'ok')
 * flaky() // throws
 * flaky() // throws
 * flaky() // 'ok'
 * ```
 */
export declare const throwNTimes: <T>(n: number, value: T, error?: (attempt: number) => unknown) => (() => T);

/**
 * Install a mock provider override for the duration of a test. Returns the
 * recorded `calls` array (model prompt + tool names) + a `reset()` that
 * restores the previous override. Use in `beforeEach` + `reset()` in
 * `afterEach`.
 */
export declare const useMockAi: (fixture: MockAiFixture) => {
    readonly calls: MockScript["calls"];
    reset(): void;
};

export { }