import type { OrchestratorConfig, ThinkingLevel } from "../src/core/config.js";
import type { McpCompletionCandidate } from "./routing.js";
import { type McpProviderDefiniteFailureCode, type McpProviderUncertainFailureCode } from "./failureCodes.js";
export type ModelRole = "planner" | "judge";
export interface CompletionRequest {
    config: OrchestratorConfig;
    role: ModelRole;
    prompt: string;
    signal?: AbortSignal;
}
export interface RoutedCompletionRequest extends CompletionRequest {
    candidates: readonly McpCompletionCandidate[];
    /** Frozen before the first durable attempt reservation or provider call. */
    routingDecision?: RoutedCompletionDecision;
    /** Reject candidate output before accepting it, allowing an eligible fallback. */
    validateText?: (text: string) => void;
    /** Called before each paid provider attempt. Callback failures stop fallback. */
    beforeAttempt?: (attempt: RoutedCompletionAttempt) => void | Promise<void>;
    /** Called after each provider attempt. Callback failures stop fallback. */
    afterAttempt?: (result: RoutedCompletionAttemptResult) => void | Promise<void>;
}
export interface RoutedCompletionAttempt {
    attempt: number;
    /** Stable, server-derived identity for the exact paid provider request. */
    providerRequestRef: string;
    routingDecision: RoutedCompletionDecision;
    identity: {
        provider: string;
        model: string;
        family?: string;
    };
    thinking: ThinkingLevel;
    requestedOutputTokens?: number;
    estimatedCostUsd?: number;
}
export type RoutedCompletionAttemptResult = (RoutedCompletionAttempt & {
    outcome: "succeeded";
}) | (RoutedCompletionAttempt & {
    outcome: "failed";
    failureCode: McpProviderDefiniteFailureCode;
}) | (RoutedCompletionAttempt & {
    outcome: "unknown";
    failureCode: McpProviderUncertainFailureCode;
});
export interface RoutedCompletionResult {
    text: string;
    selectedIndex: number;
    fallbackHistory: Array<{
        identity: string;
        reason: McpProviderDefiniteFailureCode;
    }>;
}
export interface RoutedCompletionDecision {
    decisionId: string;
    policyVersion: string;
    policyDigest: string;
    configDigest: string;
    candidatesDigest: string;
}
export declare function completeWithRole({ config, role, prompt, signal }: CompletionRequest): Promise<string>;
export declare function completeRouted({ config, role, prompt, signal, candidates, routingDecision: suppliedRoutingDecision, validateText, beforeAttempt, afterAttempt, }: RoutedCompletionRequest): Promise<RoutedCompletionResult>;
/** Freeze non-secret routing authority before any provider-attempt callback. */
export declare function freezeRoutingDecision(config: OrchestratorConfig, candidates: readonly McpCompletionCandidate[], policyVersion: string, decisionId: string): RoutedCompletionDecision;
/**
 * Hash only canonical, non-secret inputs that determine a provider call. The
 * reference is intentionally independent from the client mutation request ID:
 * one mutation may contain several paid fallback attempts.
 */
export declare function providerRequestReference(config: OrchestratorConfig, role: ModelRole, prompt: string, candidate: McpCompletionCandidate, attempt: number): string;