/**
 * One provider entry to write into the cortex-controlled `models.json`. cortex uses PI's
 * "Override Built-in Providers" mechanism (docs/models.md §Overriding Built-in Providers):
 * specifying only `baseUrl` redirects all of that provider's traffic to our gateway while
 * keeping PI's built-in model catalog and OAuth/API-key auth resolution from auth.json intact.
 */
export interface ProviderOverride {
    /** PI provider name (e.g. "anthropic", "deepseek", "openai-codex"). */
    name: string;
    /**
     * Path segment appended to the gateway URL. Defaults to `/${name}`.
     * An explicit empty string keeps the gateway URL exact; other values select a non-standard path
     * (e.g. deepseek's anthropic-compat endpoint: `/deepseek/anthropic`).
     */
    basePath?: string;
    /**
     * Per-spawn PI compat flags to write into this provider's models.json entry.
     * Merged ON TOP of PROVIDER_COMPAT_OVERRIDES (explicit wins). Normally unset —
     * the static table covers the known cases.
     */
    compat?: Record<string, unknown>;
    /**
     * Complete provider block for a user-defined provider, written verbatim. PI knows nothing about
     * such a provider, so a `baseUrl`-only override would strip the protocol (`api`) and the model
     * list and leave PI unable to call it. When set, `basePath`/`compat` are ignored — the definition
     * already carries its own gateway `baseUrl`.
     */
    entry?: Record<string, unknown>;
}
export interface WriteProvidersOpts {
    /** Target file path. Required: an implicit host default is exactly the ambient reach §13 A3
     *  forbids, so every caller states where the catalog lands. */
    modelsPath: string;
}
/**
 * Atomic-write models.json with multi-provider baseUrl overrides. Each provider entry has a
 * `baseUrl` pointing to `<gatewayUrl><basePath>`; no apiKey is written so PI resolves credentials
 * from auth.json (or environment variables) per PI's auth resolution order.
 *
 * Called by PIAdapter.spawn() — sole writer of this file, no other code path touches it.
 */
export declare function writeProvidersConfig(providers: ProviderOverride[], gatewayUrl: string, opts: WriteProvidersOpts): void;
/**
 * Compute the set of PI providers whose baseUrl should be overridden to the gateway for a spawn.
 *
 * Design: "route through gateway" and "PI has credentials" are independent concerns. Discovery
 * (`pi --list-models`) only reports providers the user is authenticated to, but a profile may
 * legitimately route a provider through the gateway even without direct PI credentials (the
 * gateway injects managed keys). So the override set is the union of:
 *   - `discovered`        — providers PI reports creds for (credential passthrough via auth.json)
 *   - `currentProvider`   — the provider THIS spawn uses (`--provider`); it MUST be routed, always
 *
 * `gatewayPath`, when set, becomes the current provider's `basePath` (decouples the gateway route
 * from the provider name — e.g. provider "anthropic" landing on "/deepseek-anthropic"). It wins
 * over the default `/<name>` even if the current provider was also discovered.
 */
export declare function buildProviderOverrides(discovered: string[], currentProvider: string | null, gatewayPath?: string | null): ProviderOverride[];
/**
 * Attach user-defined provider definitions to the overrides that name them, so the catalog carries
 * a complete block for each one. Overrides without a definition (PI built-ins) are untouched.
 */
export declare function withCustomEntries(overrides: ProviderOverride[], definitions: Record<string, Record<string, unknown>>): ProviderOverride[];