/** Provider-neutral generation, budgets, schema gates, and retry policy. */
import { type JsonValue } from "../core/contracts.ts";
import { type ContextRequestV1 } from "../memory/context.ts";
export type ProviderOperation = "contract" | "context" | "patch" | "repair";
export type ProviderMessageRole = "system" | "user" | "assistant" | "tool";
export interface ProviderToolCallV1 {
    /** Provider call identity. The host supplies a deterministic one when omitted. */
    id: string;
    name: string;
    arguments: Readonly<Record<string, JsonValue>>;
}
export interface ProviderMessageV1 {
    role: ProviderMessageRole;
    content: string;
    name?: string;
    /** Present only on an assistant turn that requested host tools. */
    toolCalls?: readonly ProviderToolCallV1[];
    /** Associates one tool result with the assistant request that caused it. */
    toolCallId?: string;
}
export type JsonSchemaV1 = Readonly<Record<string, JsonValue>>;
export interface ProviderToolDefinitionV1 {
    name: string;
    description: string;
    inputSchema: JsonSchemaV1;
}
export interface ProviderCapabilitiesV1 {
    /** False means prompts/tools carry the schema; local validation is still mandatory. */
    nativeStructuredOutput: boolean;
    toolCalling: boolean;
    cancellation: boolean;
    tokenCounting: "exact" | "estimated" | "unavailable";
    usageReporting: boolean;
    remote: boolean;
    maxContextTokens?: number;
}
export interface ProviderGenerationRequestV1 {
    operation: ProviderOperation;
    model: string;
    messages: ProviderMessageV1[];
    /**
     * `structured` asks the provider for JSON matching responseSchema. `text`
     * returns assistant text unchanged so the host can construct the artifact.
     */
    responseMode?: "structured" | "text";
    responseSchema: JsonSchemaV1;
    tools?: ProviderToolDefinitionV1[];
    timeoutMs: number;
    maxOutputTokens: number;
    temperature?: number;
    signal?: AbortSignal;
}
export interface ProviderRequestUsageV1 {
    inputTokens: number;
    outputTokens: number;
    costUsd?: number;
}
export type ProviderFinishReason = "stop" | "tool_call" | "length" | "refusal" | "other";
export interface ProviderGenerationResultV1 {
    output: unknown;
    resolvedModelId: string;
    requestId: string;
    usage: ProviderRequestUsageV1;
    finishReason: ProviderFinishReason;
}
export interface ProviderAdapter {
    readonly name: string;
    readonly capabilities: Readonly<ProviderCapabilitiesV1>;
    /**
     * Conservative upper bound for one request. Remote adapters must implement
     * this so the host can reserve spend before any bytes leave the machine.
     */
    maximumRequestCostUsd?(request: ProviderGenerationRequestV1): number;
    generate(request: ProviderGenerationRequestV1): Promise<ProviderGenerationResultV1>;
}
export declare const CONTEXT_REQUEST_TOOL: Readonly<ProviderToolDefinitionV1>;
/**
 * Terminal coding tool for a host-resolved source selection. The model submits
 * replacement text, while the host retains ownership of path authorization,
 * byte offsets, stale checks, candidate validation, and the eventual write.
 */
export declare const SELECTED_CODE_EDIT_TOOL: Readonly<ProviderToolDefinitionV1>;
export declare const COMPILER_CONTEXT_TOOLS: readonly ProviderToolDefinitionV1[];
export type ProviderErrorCode = "timeout" | "rate_limit" | "server" | "authentication" | "refusal" | "schema" | "safety" | "budget" | "cancelled" | "configuration" | "network" | "internal";
export declare class ProviderError extends Error {
    readonly code: ProviderErrorCode;
    readonly options: {
        statusCode?: number;
        requestId?: string;
        cause?: unknown;
    };
    readonly retryable: boolean;
    constructor(code: ProviderErrorCode, message: string, options?: {
        statusCode?: number;
        requestId?: string;
        cause?: unknown;
    });
}
/** Normalize SDK/HTTP errors without treating arbitrary network failures as retry-safe. */
export declare function normalizeProviderError(error: unknown): ProviderError;
export interface ProviderBudgetLimitsV1 {
    maxInputTokens: number;
    maxOutputTokens: number;
    maxRequests: number;
    maxRepairs: number;
    maxCostUsd: number;
    maxElapsedMs: number;
}
export interface ProviderBudgetUsageV1 {
    inputTokens: number;
    outputTokens: number;
    requests: number;
    repairs: number;
    costUsd: number;
    elapsedMs: number;
}
export interface ProviderRequestReservationV1 {
    readonly inputTokens: number;
    readonly outputTokens: number;
    readonly maximumCostUsd: number;
}
export declare const DEFAULT_PROVIDER_BUDGETS: Readonly<ProviderBudgetLimitsV1>;
export declare class ProviderBudgetTracker {
    #private;
    readonly limits: Readonly<ProviderBudgetLimitsV1>;
    constructor(limits?: ProviderBudgetLimitsV1, clock?: () => number);
    assertCanRequest(estimatedInputTokens: number, maximumOutputTokens: number): void;
    beginRequest(conservativeInputTokens: number, maximumOutputTokens: number, maximumCostUsd: number): ProviderRequestReservationV1;
    cancelRequest(reservation: ProviderRequestReservationV1): void;
    recordUsage(usage: ProviderRequestUsageV1, reservation?: ProviderRequestReservationV1): void;
    /** Count a failed attempt even when the provider returned no usage data. */
    recordFailedRequest(reservation?: ProviderRequestReservationV1): void;
    recordRepair(): void;
    get usage(): ProviderBudgetUsageV1;
    get remainingOutputTokens(): number;
    get remainingRequests(): number;
    get remainingElapsedMs(): number;
}
export declare function estimateProviderInputTokens(request: ProviderGenerationRequestV1): number;
/**
 * A tokenizer-independent upper bound for byte-level model tokenizers. It is
 * intentionally pessimistic and includes host/API framing headroom.
 */
export declare function conservativeProviderInputTokenUpperBound(request: ProviderGenerationRequestV1): number;
export interface GenerateValidatedOptions {
    budget?: ProviderBudgetTracker;
    /** Runs after pessimistic budget charging and before network transmission. */
    onBeforeRequest?: () => void | Promise<void>;
}
/**
 * Gets model output and accepts it only once the host has validated it against
 * the required code-artifact schema. Native JSON Schema support may improve what
 * comes back, but it never replaces this local validator.
 */
export declare function generateValidated<T>(adapter: ProviderAdapter, request: ProviderGenerationRequestV1, validator: (value: unknown) => T, options?: GenerateValidatedOptions): Promise<{
    value: T;
    result: ProviderGenerationResultV1;
}>;
export interface RetryProviderOptions {
    maxRetries?: number;
    maxElapsedMs: number;
    signal?: AbortSignal;
    backoffMs?: (retry: number, error: ProviderError) => number;
    onRetry?: (retry: number, error: ProviderError) => void | Promise<void>;
    clock?: () => number;
}
/** Retry only timeout, rate-limit, and 5xx failures; never more than twice. */
export declare function withProviderRetries<T>(operation: (attempt: number) => Promise<T>, options: RetryProviderOptions): Promise<T>;
export interface DeterministicMockOutput {
    output: unknown;
    usage?: ProviderRequestUsageV1;
    finishReason?: ProviderFinishReason;
    requestId?: string;
}
export type DeterministicMockStep = DeterministicMockOutput | Error | ((request: ProviderGenerationRequestV1, sequence: number) => DeterministicMockOutput | Promise<DeterministicMockOutput>);
/** A no-network provider for deterministic unit/integration and CI runs. */
export declare class DeterministicMockProvider implements ProviderAdapter {
    #private;
    readonly name = "mock";
    readonly capabilities: Readonly<ProviderCapabilitiesV1>;
    constructor(options: {
        resolvedModelId?: string;
        steps: readonly DeterministicMockStep[];
        nativeStructuredOutput?: boolean;
    });
    generate(request: ProviderGenerationRequestV1): Promise<ProviderGenerationResultV1>;
}
/** Type-only convenience for providers that surface context tool arguments. */
export type CompilerContextToolOutput = ContextRequestV1;
//# sourceMappingURL=provider.d.ts.map