/**
 * Boolean hints the stream-wrapper layer reads to decide which
 * provider-specific wrappers to apply. Pure data; no function references
 * so adapter files stay dependency-free.
 */
export interface ProviderStreamHints {
    /** Apply OpenRouter app-attribution headers wrapper. */
    openrouterHeaders?: boolean;
    /** Enable Z.AI tool_stream wrapper (subject to user opt-out via params.tool_stream=false). */
    zaiToolStream?: boolean;
}
/**
 * Boolean hints the transcript-policy layer reads to combine with model-id
 * substring checks. Each hint says "this provider's catalog is associated
 * with the named model family or routing pattern." The transcript-policy
 * code combines the hint with substring checks to decide whether the
 * full sanitization treatment applies.
 */
export interface ProviderTranscriptHints {
    /** All models from this provider should be treated as Gemma-family (e.g., redsand). */
    defaultToGemma?: boolean;
    /** All models from this provider should be treated as Mistral-family. */
    defaultToMistral?: boolean;
    /**
     * This provider may route Gemini-family models via id substring (e.g.,
     * openrouter, opencode). The transcript-policy code combines this with
     * `modelId.includes("gemini")` to decide whether thought-signature
     * sanitization applies.
     */
    routesGeminiVariants?: boolean;
    /**
     * This provider may host Claude-family models with malformed thinking
     * signatures (github-copilot's Claude endpoints). The transcript-policy
     * code combines this with `modelId.includes("claude")` to decide
     * whether to drop thinking blocks at send-time.
     */
    hostsCopilotClaude?: boolean;
}
export interface ProviderAdapter {
    /** Canonical provider key (lowercase). */
    readonly id: string;
    /** Alternative names that resolve to this adapter (e.g., "z-ai" → "zai"). */
    readonly aliases?: readonly string[];
    /**
     * Returns true if the given model id (case-insensitive) is in this
     * provider's "modern/live" catalog — i.e. one of the models that smoke
     * tests + the live-model filter consider current.
     *
     * Default behavior (when not overridden) is `() => false`.
     */
    isLiveModel(id: string): boolean;
    /**
     * Substrings used by meta-providers (openrouter, opencode) to detect
     * when a routed model is "modern" by virtue of matching some other
     * provider's catalog. Optional — only set this on first-party providers
     * whose models can show up under a meta-provider routing prefix.
     */
    readonly modernModelSubstrings?: readonly string[];
    /**
     * Provider-specific stream wrapper hints. Returns data only; the
     * stream-wrapper layer (extra-params.ts) reads these flags and applies
     * the corresponding wrapper functions. Default: no hints.
     */
    streamHints?(): ProviderStreamHints;
    /**
     * Normalize a model id to the form this provider's API expects. Default
     * (when not overridden) returns the input unchanged. Used by
     * `normalizeModelRef` in model-selection.ts to apply per-provider id
     * alias maps (e.g., anthropic "opus-4.6" → "claude-opus-4-6").
     */
    normalizeModelId?(id: string): string;
    /**
     * Optional provider re-routing. Returns the canonical provider key the
     * given model should actually be routed through, or undefined to keep
     * the current provider. Used for cases like openai/gpt-5.3-codex auto-
     * routing to the openai-codex provider.
     */
    routeToProvider?(modelId: string): string | undefined;
    /**
     * Provider-specific transcript-policy hints. The transcript-policy
     * layer combines these with model-id substring checks to decide
     * sanitization behavior. Default: no hints.
     */
    transcriptHints?(): ProviderTranscriptHints;
    /**
     * True if this provider's OAuth flow needs a `projectId` packed into
     * the resulting API-key blob. Used by `auth-profiles/oauth.ts`.
     * Default: false.
     */
    oauthNeedsProjectId?(): boolean;
    /**
     * Sibling providers whose OAuth credentials would conflict with this
     * provider's API key auth (e.g., openai conflicts with openai-codex
     * OAuth — the user can't use openai/* via API key while openai-codex
     * is OAuth-authed). Returns provider keys, or empty/undefined if none.
     * Used by `model-auth.ts` to surface a clear error.
     */
    conflictingOAuthProviders?(): readonly string[];
    /**
     * If defined, transforms a raw API-key into a runtime API-key (e.g.,
     * github-copilot exchanges a GitHub PAT for a Copilot session token).
     * Used by `pi-embedded-runner/compact.ts` and other call sites that
     * load API keys at run time.
     */
    resolveRuntimeApiKey?(rawApiKey: string): Promise<string>;
    /**
     * The id of this provider's model that supports image input, when the
     * provider has a single such variant (e.g., minimax → "MiniMax-VL-01").
     * `image-tool.helpers.ts` uses this to detect whether a configured
     * model entry is the image-capable one. Default: undefined.
     */
    readonly imageInputModelId?: string;
}
