import type { NormalizedAiUsage } from './usage.js';
export type AiOperation = 'generate' | 'embed' | 'rerank' | 'moderate' | 'transcribe' | 'synthesize' | 'other';
export type AiFinishReason = 'stop' | 'length' | 'tool_call' | 'content_filter' | 'error' | 'cancelled' | 'unknown';
export type AiScalar = string | number | boolean | null;
export interface AiPayloadDescriptor {
    schemaVersion: number;
    sha256: string;
    /** Protected payload reference. Raw payload bytes never enter ledger metadata. */
    ref?: string;
}
export interface AiPriceSnapshot {
    currency: string;
    source: string;
    version: string;
    estimatedCostNanos?: number;
    settledCostNanos?: number;
}
export interface AiRetryAndRateLimit {
    retryCount?: number;
    retryAfterMs?: number;
    limit?: number;
    remaining?: number;
    resetAt?: Date;
}
export interface AiProviderExtension {
    schemaVersion: number;
    fields: Record<string, AiScalar>;
}
export interface StartAiInvocation {
    invocationId?: string;
    idempotencyKey?: string;
    providerFamily: string;
    modelIdentifier: string;
    modelRevision?: string;
    operation: AiOperation;
    prompt: AiPayloadDescriptor;
    parameters: AiPayloadDescriptor;
    promptTemplateId?: string;
    promptTemplateVersion?: string;
    toolDefinitions?: {
        version: string;
        sha256: string;
    };
    providerExtension?: AiProviderExtension;
    startedAt?: Date;
}
export interface CompleteAiInvocation {
    response?: AiPayloadDescriptor;
    finishReason?: AiFinishReason;
    usage?: NormalizedAiUsage;
    price?: AiPriceSnapshot;
    latencyMs?: number;
    retry?: AiRetryAndRateLimit;
    providerExtension?: AiProviderExtension;
    completedAt?: Date;
}
export interface StartAiToolEffect {
    toolCallId: string;
    toolName: string;
    toolVersion: string;
    arguments: AiPayloadDescriptor;
    requestedAt?: Date;
}
export interface CompleteAiToolEffect {
    result?: AiPayloadDescriptor;
    completedAt?: Date;
}
export type AiInvocationTransitionStatus = 'started' | 'succeeded' | 'failed' | 'outcome_unknown';
export type AiToolEffectTransitionStatus = 'requested' | 'succeeded' | 'failed' | 'outcome_unknown';
export interface AiInvocationTransitionRecord {
    schemaVersion: 1;
    invocationId: string;
    idempotencyKey: string;
    status: AiInvocationTransitionStatus;
    providerFamily: string;
    modelIdentifier: string;
    modelRevision?: string;
    operation: AiOperation;
    promptTemplateId?: string;
    promptTemplateVersion?: string;
    prompt: AiPayloadDescriptor;
    parameters: AiPayloadDescriptor;
    response?: AiPayloadDescriptor;
    finishReason?: AiFinishReason;
    usage: NormalizedAiUsage;
    price?: AiPriceSnapshot;
    latencyMs?: number;
    retry: AiRetryAndRateLimit;
    toolDefinitions?: {
        version: string;
        sha256: string;
    };
    providerExtension?: AiProviderExtension;
    startedAt: Date;
    completedAt?: Date;
}
export interface AiToolEffectTransitionRecord {
    invocationId: string;
    toolCallId: string;
    toolName: string;
    toolVersion: string;
    status: AiToolEffectTransitionStatus;
    arguments: AiPayloadDescriptor;
    result?: AiPayloadDescriptor;
    requestedAt: Date;
    completedAt?: Date;
}
export interface AiMutationSender {
    recordInvocation(record: AiInvocationTransitionRecord, transitionEventId: string, transitionIdempotencyKey: string): Promise<void>;
    recordToolEffect(record: AiToolEffectTransitionRecord, transitionEventId: string, transitionIdempotencyKey: string): Promise<void>;
}
export declare function beginAiInvocation(input: StartAiInvocation, sender: AiMutationSender, newId: () => string): Promise<AiInvocationHandle>;
export declare class AiInvocationHandle {
    private readonly started;
    private readonly sender;
    private readonly newId;
    private terminal;
    constructor(started: AiInvocationTransitionRecord, sender: AiMutationSender, newId: () => string);
    get invocationId(): string;
    succeed(outcome?: CompleteAiInvocation): Promise<void>;
    fail(outcome?: CompleteAiInvocation): Promise<void>;
    markOutcomeUnknown(outcome?: CompleteAiInvocation): Promise<void>;
    startToolEffect(input: StartAiToolEffect): Promise<AiToolEffectHandle>;
    private finish;
}
export declare class AiToolEffectHandle {
    private readonly requested;
    private readonly sender;
    private readonly newId;
    private terminal;
    constructor(requested: AiToolEffectTransitionRecord, sender: AiMutationSender, newId: () => string);
    succeed(outcome?: CompleteAiToolEffect): Promise<void>;
    fail(outcome?: CompleteAiToolEffect): Promise<void>;
    markOutcomeUnknown(outcome?: CompleteAiToolEffect): Promise<void>;
    private finish;
}