/**
 * @octomil/browser — Browser request router
 *
 * Resolves routing decisions for production request paths. Consumes planner
 * outputs (or defaults) and decides between:
 *
 * 1. `sdk_runtime` (local) — true in-browser execution via WebGPU or WASM
 * 2. `external_endpoint` (local) — explicitly configured outside-the-browser server
 * 3. `hosted_gateway` (cloud) — Octomil cloud inference
 *
 * Fallback chain:
 *   WebGPU → WASM (local engine fallback)
 *   → cloud (only when policy allows)
 *
 * Hard constraints:
 * - Browser downloads model artifacts only when planner selects sdk_runtime
 * - external_endpoint is ONLY used when explicitly configured via localEndpoint
 * - No silent background downloads — user must opt in to local execution
 * - Tree-shakeable: no side effects on import
 *
 * For streaming requests: no fallback after first chunk emitted.
 */
import { type AttemptLoopResult, type CandidatePlan, type EndpointChecker, type RuntimeChecker, type ArtifactChecker, type OutputQualityEvaluator, type RouteAttempt } from "../attempt-runner.js";
import { type ModelRef } from "./model-ref.js";
import { type BrowserRouteEvent } from "./route-event.js";
import type { RouteMetadata } from "../../_generated/runtime_planner_types.js";
export type { RouteMetadata } from "../../_generated/runtime_planner_types.js";
/**
 * Input context for a routing decision. Callers populate this before
 * calling `BrowserRequestRouter.resolve()`.
 */
export interface BrowserRoutingContext {
    /** Model identifier or reference (e.g. "phi-4", "@app/translator/chat", "deploy_abc") */
    model: string;
    /** The capability being invoked (e.g. "chat", "embeddings", "transcriptions") */
    capability: string;
    /** Whether this is a streaming request */
    streaming: boolean;
    /**
     * Explicit localhost serve URL if the user has configured one.
     * Only used for `external_endpoint` mode — not for in-browser sdk_runtime.
     */
    localEndpoint?: string;
    /** Cached planner result from the server (candidates + policy) */
    cachedPlan?: PlannerResult;
    /** Routing policy override (if any) */
    routingPolicy?: string;
}
/**
 * Structured planner output from the server.
 * A subset of the full planner response — only what the router needs.
 */
export interface PlannerResult {
    candidates: CandidatePlan[];
    fallbackAllowed: boolean;
    policy: string;
}
/**
 * The resolved routing decision, including the endpoint to call,
 * metadata, and the attempt loop result.
 */
export interface BrowserRoutingDecision<T = unknown> {
    /** Final locality: "local" or "cloud", null if no route was selected */
    locality: "local" | "cloud" | null;
    /** Execution mode, null if no route was selected */
    mode: "sdk_runtime" | "hosted_gateway" | "external_endpoint" | null;
    /** The endpoint URL to send the request to (null for sdk_runtime) */
    endpoint: string | null;
    /** For sdk_runtime: the execution provider that was selected */
    executionProvider: "webgpu" | "wasm" | null;
    /** For sdk_runtime: the engine being used */
    engine: string | null;
    /** For sdk_runtime: artifact info for model loading */
    artifact: CandidatePlan["artifact"] | null;
    /** Contract-generated route metadata for attaching to the response. */
    routeMetadata: RouteMetadata;
    /** The plan used to make this decision */
    plan: PlannerResult;
    /** The raw attempt loop result from the BrowserAttemptRunner */
    attemptResult: AttemptLoopResult<T>;
    /** Parsed model reference */
    modelRef: ModelRef;
    /** Telemetry-safe route event */
    routeEvent: BrowserRouteEvent;
}
export declare class FetchEndpointChecker implements EndpointChecker {
    private readonly timeoutMs;
    constructor(timeoutMs?: number);
    check(endpoint: string): Promise<{
        available: boolean;
        reasonCode?: string;
    }>;
}
export declare class BrowserRequestRouter {
    private readonly serverUrl;
    private readonly endpointChecker;
    private readonly runtimeChecker;
    private readonly artifactChecker;
    constructor(opts: {
        serverUrl: string;
        endpointChecker?: EndpointChecker;
        runtimeChecker?: RuntimeChecker | null;
        artifactChecker?: ArtifactChecker | null;
    });
    /**
     * Resolve a routing decision for the given context.
     *
     * This is the main entry point for production request paths.
     */
    resolve(ctx: BrowserRoutingContext): Promise<BrowserRoutingDecision>;
    /**
     * Resolve and execute a routing decision for product request paths.
     *
     * Unlike resolve(), this keeps actual inference inside the attempt loop so
     * post-inference output-quality gates can trigger fallback before a
     * non-streaming response is returned. For streaming requests, callers must
     * expose firstOutputEmitted so the runner can lock out fallback after output.
     */
    resolveWithInference<T>(ctx: BrowserRoutingContext, executeCandidate: (candidate: CandidatePlan, attempt: RouteAttempt) => Promise<T> | T, opts?: {
        outputQualityEvaluator?: OutputQualityEvaluator | null;
        firstOutputEmitted?: () => boolean;
    }): Promise<BrowserRoutingDecision<T>>;
    private decisionFromAttemptResult;
    /**
     * Build a default plan when no cached server plan is available.
     *
     * Default behavior depends on configuration:
     * - If runtimeChecker is available: try local sdk_runtime (WebGPU then WASM)
     * - If localEndpoint is configured: try external_endpoint
     * - Always include cloud as final candidate
     */
    private defaultPlan;
    private buildRouteMetadata;
    private buildRouteEvent;
}
//# sourceMappingURL=request-router.d.ts.map