import { type LLMModelUsage } from '../../LLMService.typedefs';
import { type LLMTraceMetadata } from '../../utilities/llmTracing';
/**
 * One model round of an agent tool loop, as its provider observed it.
 *
 * `input` is the provider-native message array the round was sent with. Each
 * provider keeps its own representation, so a round carries whatever that
 * provider actually assembled — system instructions included — rather than a
 * shared message shape none of them speaks.
 */
interface LLMAgentRoundBase {
    input: unknown;
    metadata?: LLMTraceMetadata;
    /**
     * The round's own token usage. Providers that report usage per call fill it
     * on every round; one that only totals a run leaves it unset until the last
     * round, which then carries the run total.
     */
    usage?: LLMModelUsage;
    /** Epoch milliseconds stamped immediately before the provider call. */
    startedAt: number;
}
interface LLMSuccessfulAgentRound extends LLMAgentRoundBase {
    output: unknown;
    error?: never;
    isError?: false;
}
interface LLMFailedAgentRound extends LLMAgentRoundBase {
    output?: never;
    error: unknown;
    isError: true;
}
export type LLMAgentRound = LLMSuccessfulAgentRound | LLMFailedAgentRound;
/**
 * What one round's response contributes to its generation. Produced by the
 * provider because only the provider knows which part of its response is the
 * assistant output and where that response reports its usage.
 */
export interface LLMAgentRoundOutcome {
    output: unknown;
    usage?: LLMModelUsage;
}
export interface LLMAgentRoundSpec<ProviderResponse> {
    input: unknown;
    metadata?: LLMTraceMetadata;
    call: () => Promise<ProviderResponse>;
    describeOutcome: (response: ProviderResponse) => LLMAgentRoundOutcome;
}
/** Emits the generation observation of a single agent round. */
export type LLMAgentRoundWriter = (round: LLMAgentRound) => void;
export type LLMAgentRoundStartedListener = () => void;
export {};